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.

Required references

This file is the skeleton; each reference holds a step's full rules. Read it at that step.

When to invoke

• "Document the project for coding agents" / "set up agent docs"
• "Add AGENTS.md" / "create docs/ structure"
• Extending the layout in a repo that already follows it — individual specs are /spec's job

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

Spec format — the three rules

Each feature spec is behavioral (what the system does, never how), self-evidently testable (precise enough to derive a test from the body — no separate **Testable:** line; rewrite the body instead), and identified (### PREFIX-NNN: Short title — zero-padded three-digit numbers, prefix shared per file, never reused or renumbered). Cross-cutting invariants get INV-NNN in invariants.md and need not be testable in isolation; feature-local ones stay in the feature file as prose contracts, no numeric ID. Read references/spec-format.md for the full rules and anti-patterns before writing any spec.

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

Read references/checklist.md now — the required content per file and the size budgets.

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-003")

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 references/checklist.md 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 cross-cutting invariant has an INV-NNN ID in invariants.md; feature-local invariants stay in their feature file as prose contracts.
• Cross-links resolve: AGENTS.md indexes every file under docs/; docs/product-specs/README.md indexes every feature spec; every see INV-NNN / see XXX-NNN 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.