AGENTS.md

docs/

Philosophy: AGENTS.md is a map, not an encyclopedia. A monolithic instruction file crowds out the task and rots instantly. Keep it short; point to deeper docs.

• The project has no

  AGENTS.md

  and you're about to run a swarm or any agent workflow.
• User asks to "create AGENTS.md", "set up this repo for agents", or "bootstrap agent context".
• The project has an existing AGENTS.md that is overly long or monolithic and needs restructuring.

Product Specs (docs/product-specs/)       Acceptance Tests (docs/acceptance/)
─────────────────────────────────────     ──────────────────────────────────────
Prose. Human intent. The "what & why."    Gherkin. Testable contract. The "how to verify."
Organized by domain area.                 Organized by feature, date-named like migrations.
Evolves as the product vision changes.    Updated when specific behaviors change.
Read by humans and agents for context.    Read by agents to verify behavior, can generate
                                          runnable tests (Playwright, Detox, Vitest).

Example:                                  Example:
"Users hear audio chunks and self-grade   Feature: Listening Session
 their comprehension using an Anki-style    Scenario: Grade gating — phrases tapped
 rating system. Grade gating restricts      Given the answer is revealed
 higher grades when hints are used."        And I have tapped 1 or more phrases
                                            Then the "All" grade button should be disabled

1. Product specs capture the vision and requirements (prose)
2. Acceptance tests distill the specs into precise, testable scenarios (Gherkin)
3. E2E tests implement the scenarios as runnable code (Playwright/Detox)

1. Update the product spec first (the intent)
2. Update or create acceptance test .feature files (the contract)
3. The failing acceptance tests drive the implementation change

docs/product-specs/

• overview.md

  — high-level product description, target user, core principles

• data-model.md

  — schemas, entities, relationships

• screens.md

  or individual screen files (e.g.,

  home-screen.md

  ,

  session-screen.md

  )

• api-integration.md

  — external API contracts

• visual-design.md

  — theme, typography, haptics (can also live in design-docs/)

audio-system.md

docs/acceptance/

• YYYY-MM-DD-feature-name.feature

• e.g.,

  2026-03-07-listening-session.feature

• Name: [PROJECT NAME]
• Description: [One-line description]
• Tech stack: [e.g. TypeScript, React, Vite, Vitest, Playwright, Stryker]
• Package manager: [pnpm/npm/yarn/bun]
• Source layout:

  • [dir]/

    — [purpose]

  • [dir]/

    — [purpose]

1. [Typecheck command]

2. [Lint command]

3. [Unit test command]

4. [Mutation command — only if detected]

5. [E2E command — only if detected]

Progressive disclosure: Do NOT load all docs upfront. Read this file, then load the specific doc relevant to your current task.

• Simplicity First: Make every change as simple as possible. Impact minimal code.
• No Laziness: Find root causes. No temporary fixes. Senior developer standards.
• Verify Before Done: Run tests. Ask: "Would a staff engineer approve this?"
• Spec Traceability: Every behavior should trace to an acceptance test in docs/acceptance/.
• Architecture First: Consult docs/adrs/ before making structural decisions.

• When requirements change, update the relevant

  .feature

  file in

  docs/acceptance/

• New features MUST have acceptance scenarios before implementation begins
• Update

  docs/acceptance/index.md

  when adding/removing feature files
• Use

  YYYY-MM-DD-feature-name.feature

  naming (sorted chronologically)
• Acceptance tests are the contract — if the code doesn't match the .feature file, the code is wrong (unless the spec changed, in which case update the spec first)

• Product specs capture the vision and requirements in prose
• When the product evolves, update the relevant spec file in

  docs/product-specs/

• Break large specs into domain files — each independently loadable
• Specs should be readable without loading the entire knowledge base

• When making structural decisions (new deps, pattern changes, tech choices), create

  docs/adrs/YYYY-MM-DD-decision-name.md

• ADRs are append-only — never edit old decisions, create new ones that supersede
• Update

  docs/adrs/index.md

  with the new entry

• docs/lessons.md

  — persistent project knowledge. Things any agent needs to know: platform gotchas discovered the hard way, architectural mistakes to avoid, patterns that work well. This file is versioned and survives across all runs.

• .swarm/lessons.md

  — tactical swarm-specific lessons. Merge strategies, agent coordination tips, worktree issues. Managed by the swarm skill.

1. Ask: "Would this lesson help ANY future agent working on this project?"
   • Yes → add to

     docs/lessons.md

   • Only relevant to swarm operations → add to

     .swarm/lessons.md

2. Review

   docs/lessons.md

   at the start of each task

• [Project-specific: e.g. Don't modify CI without approval; don't change DB schema]

undefined

• Tell the user the structure is ready. Agents will read AGENTS.md as their entry point.
• You can output

  <promise>AGENTS_CREATED</promise>

  when done so scripts know to continue.

1. Update the product spec (the intent)
2. Update or create the .feature file (the contract)
3. Failing acceptance tests drive the implementation change

undefined

1. Repository is the system of record — anything not in the repo doesn't exist for agents
2. Progressive disclosure — start with AGENTS.md, load deeper docs only when needed
3. Enforce mechanically — prefer linters and tests over documentation for enforcing rules
4. Stale docs are actively harmful — keep docs current or delete them
5. Docs are part of the change — updating docs is not a separate task, it's part of completing the work

undefined

• A — Well tested, clean architecture, documented
• B — Adequate tests, minor debt, mostly documented
• C — Gaps in coverage, some debt, docs may be stale
• D — Significant gaps, needs attention
• F — Untested, undocumented, high risk

undefined

Rule of thumb: If this lesson would save a future agent from making the same mistake, it belongs here. If it's only about swarm coordination or merge strategy, it goes in

.swarm/lessons.md

instead.

• [e.g. "NativeWind v4: never use @tailwind base — it breaks Pressable styles"]
• [e.g. "Detox on Fabric: testID alone doesn't work, must add nativeID too"]

• [e.g. "Keep all Gemini calls in a single service file — spreading them causes inconsistent error handling"]

• [e.g. "Always disable Detox synchronization for async operations"]

• [e.g. "When breaking up a monolith, move tests first — they tell you what's actually coupled"]

undefined