lo6

AGENTS.md — Guide for AI Coding Agents

This file is read by AI coding agents (Claude Code, Codex, Copilot, Aider, etc.) to understand project conventions, architecture decisions, and contribution patterns.

Project Overview

lo6 is a “Newsroom Operating System” — an Ableton Live for journalists. It orchestrates AI agents for sourcing, research, and drafting while keeping human journalists in creative control through a Human-in-the-Loop architecture with strict source provenance.

Architecture

┌─────────────────────────────────────────────────┐
│               Newsroom Console (Next.js)         │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │  Triage   │ │  Editor   │ │  Signal Exchange │ │
│  │  Board    │ │  Studio   │ │  Dashboard        │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
└──────────────────────┬──────────────────────────┘
                       │ tRPC / REST
┌──────────────────────┴──────────────────────────┐
│             Newsroom Engine (LangGraph.js)       │
│  ┌─────────┐ ┌──────────┐ ┌───────────────────┐ │
│  │ Sourcing │ │ Research  │ │  Drafting Agent   │ │
│  │ Agent    │ │ Agent     │ │                   │ │
│  └─────────┘ └──────────┘ └───────────────────┘ │
└──────────────────────┬──────────────────────────┘
                       │ Prisma
┌──────────────────────┴──────────────────────────┐
│          PostgreSQL (Supabase / Neon)            │
└─────────────────────────────────────────────────┘

Tech Stack (Non-Negotiable)

• Next.js 14+ App Router — NOT Pages Router. Use Server Actions, Server Components, streaming.
• TypeScript strict mode — No any. No @ts-ignore. Zod for runtime validation.
• LangChain.js + LangGraph.js — Agents are LangGraph state machine nodes. NOT Python/LangChain.py.
• Prisma ORM — NOT raw SQL or Drizzle. Schema in prisma/schema.prisma.
• Shadcn/UI components — NOT MUI, NOT Chakra. Use npx shadcn@latest add <component>.
• TailwindCSS — NOT CSS modules, NOT styled-components.
• Zustand for client state, TanStack Query for server state — NOT Redux, NOT Context-only.
• Vitest for tests — NOT Jest.

File Structure (Convention)

lo6/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── (auth)/             # Auth group route
│   │   ├── (dashboard)/        # Main dashboard layout
│   │   │   ├── triage/         # Triage Board page
│   │   │   ├── research/       # Research Desk page
│   │   │   ├── editor/         # Writing Studio page
│   │   │   ├── editorial/      # Editorial Review page
│   │   │   └── signals/        # Signal Exchange page
│   │   ├── api/                # API routes (tRPC)
│   │   └── layout.tsx
│   ├── components/
│   │   ├── ui/                 # Shadcn/UI primitives
│   │   └── features/           # Feature-specific components
│   ├── lib/
│   │   ├── agents/             # LangGraph agent definitions
│   │   │   ├── sourcing.ts     # SourcingAgent node
│   │   │   ├── research.ts    # ResearchAgent node
│   │   │   ├── drafting.ts    # DraftingAgent node
│   │   │   ├── triage.ts      # TriageAgent (scoring)
│   │   │   └── graph.ts       # Main LangGraph workflow
│   │   ├── db/                 # Prisma client & queries
│   │   ├── auth/               # Supabase auth helpers
│   │   ├── validators/         # Zod schemas
│   │   └── utils/              # Shared utilities
│   ├── hooks/                  # Custom React hooks
│   ├── stores/                 # Zustand stores
│   └── types/                  # Shared TypeScript types
├── prisma/
│   └── schema.prisma
├── docs/                        # Architecture & spec documents
├── tests/                       # Vitest test files
├── public/
├── .env.example
├── AGENTS.md                    # This file
├── CONTRIBUTING.md
└── README.md

Critical Rules

Security (OWASP/NIST)

• ALL API inputs validated with Zod schemas — no exceptions.
• ALL rich text rendered through DOMPurify — no dangerouslySetInnerHTML without sanitization.
• Use Supabase Auth with MFA. Never roll your own auth.
• RBAC enforced at both API and UI level.
• Audit log every agent and user action.
• See docs/security_spec.md and docs/lib/security.md for concrete patterns.

Source Provenance

• Every claim generated by an AI agent MUST include a sourceUrl and sourceSnippet.
• The UI MUST display provenance links inline — no hiding sources behind tooltips or collapsed sections.
• If an agent cannot verify a claim, it MUST flag it as [UNVERIFIED].

Human-in-the-Loop

• The LangGraph workflow has interrupt nodes at Triage, Research, and Review stages.
• AI agents NEVER auto-publish. A human must approve at the Review stage.
• The state machine: Lead → Triage → Research → Draft → Review → Publish

Code Style

• Use named exports, not default exports (except Next.js pages).
• Component files: PascalCase (e.g., TriageCard.tsx).
• Utility files: camelCase (e.g., formatSource.ts).
• Agent files: camelCase (e.g., sourcing.ts, researchNode.ts).
• One component per file. One agent node per file.

How to Contribute (as an AI agent)

1. Pick an issue labeled good-first-issue or help-wanted from the GitHub issue board.
2. Read the relevant spec doc in /docs before writing any code.
3. Create a branch: feat/<issue-number>-<short-description>.
4. Write tests first (TDD): create the test file in /tests, then implement.
5. Run the full check before committing:

   npm run lint && npm run typecheck && npm run test && npm run build
   

6. Open a PR with a clear description referencing the issue number.

Common Pitfalls

• Don’t use Python. This is a TypeScript/Node.js project. LangChain.js, not LangChain.py.
• Don’t skip Zod validation. Even internal API calls need it.
• Don’t auto-publish content. Every story stops at the Review node for human approval.
• Don’t use any. Run npm run typecheck — it must pass with zero errors.
• Don’t create new Shadcn components from scratch. Use npx shadcn@latest add <component>.
• Don’t put business logic in React components. Extract to lib/ or hooks/.

Specs to Read Before Contributing

Area	Read This
Architecture	docs/implementation_plan.md
Database schema	docs/data_model.md
Agent workflows	docs/agent_interface_spec.md
UI/UX	docs/frontend_spec.md
Security	docs/security_spec.md
Security snippets	docs/lib/security.md
Accessibility	docs/accessibility_appendix.md

This site is open source. Improve this page.