repo-docs

Repo docs for coding agents

This skill bootstraps a documentation layout designed for LLM-assisted development: every project area has a stable, addressable home, every product behavior has a unique ID, and every change has a clear consultation path.

When to invoke

• "Document the project for coding agents" / "set up agent docs"
• "Add AGENTS.md" / "create docs/ structure"
• "Add a feature spec" / "add an invariant" — when the repo already follows this pattern
• Any time a repo lacks structured agent documentation and would benefit from one

Do not invoke for one-off README edits or for repos that already have a different doc convention without confirming with the user.

Layout produced

<repo-root>/
├── AGENTS.md
└── docs/
    ├── README.md
    ├── architecture.md
    ├── guidelines.md
    └── product-specs/
        ├── README.md
        ├── invariants.md
        └── <feature>.md   (one per feature area)

Document responsibilities

File	Purpose	Do not put here
AGENTS.md	Project elevator pitch + tech stack + brief architecture + index of every doc with load hints	Long architectural rationale, full specs
docs/README.md	How to manage docs/ itself: spec format rules, ID conventions, when to update what, file naming	Project content
docs/architecture.md	High-level architecture, layer boundaries, important technical assumptions, migration paths	Implementation tutorials
docs/guidelines.md	Process rules: lint/test policy, planning, regression CRA (5-whys), doc-update protocol	Product behavior
docs/product-specs/README.md	Spec format requirements (testability, ID rules) + index of feature spec files	Feature behavior
docs/product-specs/invariants.md	Conditions that hold across the system. Prefix INV. Don't have to be testable in isolation.	Feature-level behavior
docs/product-specs/<feature>.md	Testable behaviors for one feature area. Each has a unique PREFIX-NUM ID.	Implementation details

Spec format — non-negotiable rules

Each feature spec is:

1. Behavioral. Describes what the system does, not how it's implemented. "Lifecycle stage is one of …", not "the LifecycleEnum Zod schema validates input".
2. Self-evidently testable. Written precisely enough that a tester can derive a verification path directly from the body. No separate **Testable:** line. If you find yourself wanting to add one, rewrite the body until it's no longer needed.
3. Identified. ### PREFIX-NUM: Short title heading. PREFIX is shared by all specs in one file (e.g., CMP in companies.md). NUM is unique within the file and never reused.

Invariants are different:

• Same ID format (e.g., INV-7) but they describe system-wide properties, not feature behaviors.
• They don't have to be testable in isolation — they're upheld by code reviews, architectural boundaries, and process together.
• Examples: "agents never write raw cells", "all writes append to change_log".

ID stability:

• Don't renumber. Deleted specs leave a hole; new specs get the next free number.
• IDs are stable references — code comments, tests, PR descriptions, and inter-doc links cite them.

Workflow when invoked

1. Survey the repo first

Before writing anything:

• Read existing README.md, package.json, source layout, any existing SPEC.md or design docs
• Identify the product domain (what does this thing do?), tech stack (languages, frameworks, package manager, runtime), and architectural layers (frontend/backend split, storage, integrations)
• Identify discrete feature areas that warrant their own spec file

If the repo already has agent docs in this pattern, skip bootstrapping and only add/edit the requested files.

2. Confirm scope with the user

Before creating files, propose:

• The list of feature spec files you'll create (e.g., companies.md, deals.md, tasks.md)
• Their prefixes (e.g., CMP, DEAL, TASK)
• Any unusual choices (combining features, splitting a large feature)

Ask before creating. The user's preferred granularity matters more than your guess.

3. Create files in this order

1. docs/product-specs/invariants.md — the floor; everything else references it
2. docs/product-specs/<feature>.md files — one per feature area
3. docs/product-specs/README.md — index + format rules
4. docs/architecture.md — layers, decisions, assumptions
5. docs/guidelines.md — process rules
6. docs/README.md — meta-doc on managing docs/
7. AGENTS.md — top-level overview + index of everything

4. Use the templates

See templates/ in this skill directory for ready-to-fill skeletons. They embed all the format requirements.

5. Cross-link

• AGENTS.md indexes every other doc with a one-line summary and a "load when…" hint
• docs/product-specs/README.md indexes every spec file with prefix + summary
• Specs reference invariants by ID where relevant (e.g., "see INV-3")

Required content checklist

AGENTS.md

• One-paragraph "what this project is"
• Tech stack table
• Architecture in 30 seconds (diagram or short list of layers)
• Project layout (directory tree)
• Documentation index — table with file path, summary, "load when…"
• Process rules (lint, test, regression protocol, doc confirmation)
• Reference to spec ID convention

docs/architecture.md

• High-level diagram or layer description
• Why each layer exists (one paragraph each)
• Key technical assumptions (e.g., concurrency model, data flow, auth)
• Tech choices table with reasons
• Future migration paths (if relevant)
• What's intentionally simple in v1 (if relevant)

docs/guidelines.md

• Lint 100% of code
• Test 100% of code (or stated project coverage policy)
• Planning checklist (mandatory for every plan):
  1. Validate assumptions
  2. Cross-validate the proposed solution against product specs (every affected spec ID)
  3. Cross-validate against the system architecture (boundaries, assumptions)
  4. Plan automated test coverage for new logic (per coverage policy)
  5. Plan end-to-end tests for the proposed solution
• On product behavior change → consult product specs
• On architecture change → consult architecture doc
• On any conflict → bring up for discussion before proceeding
• On regression → conduct a CRA using the 5-whys, report root cause before attempting a fix
• Keep specs and architecture updated, but confirm every change with the user

docs/product-specs/README.md

• Spec format requirements (behavioral, testable, identified)
• Distinction between feature specs and invariants
• Prefix table (one row per spec file)
• Spec file index with one-line summaries
• Reference to master spec if one exists

docs/product-specs/invariants.md

• Brief intro: what an invariant is, why it's not testable-in-isolation
• Each invariant: ### INV-N: Short title + 1–3 sentence body

docs/product-specs/.md

• Brief intro paragraph
• Prefix: \XXX`.` line
• --- separator
• Each spec: ### XXX-N: Short title + 1–3 sentence body that's precise enough to derive a test from

docs/README.md

• What lives in docs/ (table)
• Spec format requirements (testability, IDs, stability)
• Process rules (treat docs as code, confirm with user, surface conflicts, reference IDs)
• When to update what (table)
• When NOT to write a doc
• File naming convention

Anti-patterns to avoid

• Don't write specs that describe implementation. "The validateLifecycle function returns false for invalid stages" is not a spec; "Lifecycle stage is one of …" is.
• Don't add a **Testable:** line. If the body isn't already testable, rewrite the body.
• Don't renumber spec IDs. Ever. Even if a deletion leaves CMP-1, CMP-2, CMP-4.
• Don't silently update specs to match implementation. Specs lead; if implementation diverged, surface the conflict.
• Don't create feature spec files for things that don't have observable product behavior (e.g., "build system" — that goes in architecture).
• Don't put narrative or rationale in spec files. Each spec is a tight assertion. Rationale lives in architecture or PR descriptions.
• Don't create files without confirming with the user when bootstrapping a new repo.

Definition of done

The skill is complete when all of these are true. Each item is answerable with evidence — a file path, a grep result, a user confirmation — not a vibe.

• Scope confirmed with the user before file creation: list of feature spec files, their prefixes, any unusual splits/combines.
• Every file in the "Required content checklist" exists and ticks every box in its own checklist. Missing items get a TODO with a reason, not silent omission.
• No spec describes implementation. Re-read each spec body: if it names a function, class, schema, or file, rewrite it behaviorally.
• No spec carries a separate **Testable:** line. If the body isn't self-evidently testable, the body is rewritten — not annotated.
• Every spec ID is unique within its file. Deletions leave holes; no renumbering.
• Every invariant has an INV-N ID. Invariants live in invariants.md, not scattered into feature specs.
• Cross-links resolve: AGENTS.md indexes every file under docs/; docs/product-specs/README.md indexes every feature spec; every see INV-N / see XXX-N reference points to something that exists.
• Sizes within budget: AGENTS.md ~150 lines, each feature spec 5–15 items at 1–3 sentences, architecture 1–3 pages. Over-budget files are split or trimmed.
• If the repo already had docs in this pattern, only the requested files were touched — no silent rewrites of existing structure.
• User has been shown the final layout and asked to confirm before the skill closes.

If a checkbox cannot be ticked honestly, the skill is not done — return to the step that produces it.

Concise > comprehensive

The whole point of this layout is that an agent (or human) can quickly find the doc that answers their question. Long docs defeat that purpose. Aim for:

• AGENTS.md: ~150 lines
• Each feature spec: 5–15 specs, each 1–3 sentences
• Architecture: 1–3 pages, mostly tables and diagrams

If a spec file is growing past ~15 items, consider splitting it.