---
name: create-docs
description: Analyze the entire codebase and generate structured project documentation (AGENTS.md, specs/, specs/rules/, specs/integrations/). Use when the user asks to create docs, generate documentation, set up AGENTS.md, or document the project. Use ONLY when the task is about generating project documentation, not for writing app code docs inline.
---

# Create Docs

Analyze the entire codebase and create structured documentation as follows.

This skill needs only one of two params:
`new` - create new AGENTS.md and specs/ from scratch; if false, update existing files in place.
`review` - read and follow directions in `specs-reviewer.md` to review and update the generated docs.

Terminate if the user does not provide one of these two params.

## Process

1. **Detect existing docs** — check if `AGENTS.md` and/or `specs/` already exist. If they do, UPDATE them in place: preserve content that is still accurate, add missing sections, remove stale references to deleted files. Do NOT recreate from scratch unless the user explicitly asks for a full regeneration.
2. **Scan the codebase** — read directory structure, package.json / Cargo.toml / go.mod / composer.json (or equivalent), config files, entry points, source directories, test directories, CI/CD configs.
3. **Identify** — tech stack, architecture pattern, entry points, routing, ORM/DB setup, API routes, frontend components, design system, lint/format config, build scripts, deploy targets, integrations with external systems, trust boundaries.
4. **Generate** — only the files listed below. Do NOT invent anything. Base everything exclusively on existing code.
5. **Language** — all documentation in English only.

## 1. `AGENTS.md` in the project root

Main file containing:

- **Project Overview** — project name and 1-2 line description
- **Tech Stack** — technologies used (framework, languages, main libraries)
- **Architecture** — folder structure, entry points, main architectural pattern
- **Commands** — dev, build, test, deploy, lint commands (most used, inline)
- **Code Style** — preferred syntax (ES modules vs CommonJS, naming convention, formatting)
- **Coding Rules** — critical conventions that the agent must respect (max 5-8 bullets, only non-obvious things)
- **Design System** — tokens, UI libraries, component patterns (only if a frontend exists)
- **Constraints / What to avoid** — things the agent must never do in this project
- **Workflow** — operational order (e.g. typecheck after changes, single tests not full suite)
- Self-maintenance rule:
  > "When you modify code, update the relevant file in `specs/`"
- **References** — list with `@specs/filename.md` and brief description of what each contains

**AGENTS.md must be short and scannable** — for every line ask: "if I remove this, would the agent make mistakes?" — if no, cut it.

## 2. `specs/` in the root — separate files per concern

Every file in `specs/` (including subfolders) must have as its first line:
> Read this when...

Create ONLY the files that are needed among these:

- `file-structure.md` — map of main directories and files with description of each
- `commands.md` — dev, build, test, deploy, lint commands (extended version vs AGENTS.md)
- `conventions-backend.md` — patterns, conventions, backend code rules
- `conventions-frontend.md` — patterns, conventions, frontend code rules
- `conventions-database.md` — schema, ORM, migrations, seeds
- `api-routes.md` — interface table. For HTTP APIs: method, path, handler, description, auth. For IPC/CLI/event systems: command name, args, return type, description. Adapt the columns to the actual interface type — do not force HTTP columns onto non-HTTP projects.
- `module-index.md` — table of all modules with a tier column (see tier definition below)

### `module-index.md` — module priority map

A single table listing every module/subsystem with columns:

| Module | Path | Tier | Summary | Spec link |

**Tier definition** — classify each module by how heavily customized vs standard it is:
- **Tier 1** — heavily customized, core domain logic, high risk if touched
- **Tier 2** — moderate customization, business logic with some boilerplate
- **Tier 3** — standard framework usage, thin wrappers
- **Tier 4** — thin / generated / re-export files
- **Tier 5** — minimal, reference-only, no executable code

When uncertain, default to Tier 2. The tier tells the agent where to invest analysis effort and where changes are safe. Tier 1 requires full context loading; Tier 3-5 can be touched with minimal overhead.

If a docs file becomes long, split it into multiple `.md` files in a dedicated subfolder.
Example: `specs/api/auth.md`, `specs/api/users.md`

## 3. `specs/<domain>/spec.md` — per-domain business rules and data model

A **domain** is a subsystem that has its own data model AND non-obvious business rules — not a utility module, not a thin wrapper. Examples of domains: "collections" (tree model + sort_order + auth inheritance), "http-client" (SSRF + truncation + cancellation), "auth" (tagged union + tree-walk resolution). Examples of NON-domains: "utils" (collection of helpers), "types" (type definitions only), "theme" (configuration).

For every Tier 1 domain, create a dedicated `specs/<domain>/spec.md` containing:

- **Purpose** — 1-2 lines: what this subsystem does
- **Data model** — structs/types with fields, types, and notes (markdown tables)
- **Business rules** — invariants, edge cases, validation logic, ordering rules, fallback behavior. These are NOT code patterns (those go in `rules/`) — they are the *contracts* the code must respect regardless of implementation. Example: "sort_order assigned as MAX(sort_order)+1 within parent scope", "history auto-pruned to 100 newest on every insert", "folders never inherit auth (migration normalizes legacy inherit to none)"
- **Constants** — named constants with value and location (file + line if stable)
- **Cross-links** — link to the corresponding `api-routes.md` section or `rules/` file

Create a `spec.md` ONLY for domains whose business rules are non-obvious from reading the code. If a module is thin or standard, skip it — the `module-index.md` summary is enough.

## 4. `specs/integrations/` — external system boundaries

For every integration with an external system (HTTP, DB, IPC, filesystem, third-party import/export, message queue, etc.), create one file in `specs/integrations/`:

- `index.md` — table listing all integrations: name, direction (IN/OUT/BIDIRECTIONAL), protocol, implementing files, doc link
- One file per integration containing:
  - **Implementing files** — table: file → key symbols
  - **Flow** — numbered steps end-to-end (entry point → final output)
  - **Trust boundaries** — markdown table: `Boundary | Mechanism | Location`. Examples: SSRF guard (scheme allowlist), input validation (non-empty / format check), output truncation (size cap with safe boundary), error redaction (strip sensitive data from error messages). This is the most important section — it tells the agent what NOT to relax and WHERE the guard lives.
  - **Config** — timeouts, pool sizes, client settings

Create this folder ONLY if the project has at least one integration with a trust boundary (security, data integrity, or memory safety). If the project is pure-internal with no external I/O, skip it.

## 5. `specs/rules/` — patterns and snippets

Recurring programming patterns and code snippets go as rule files in `specs/rules/`.
Examples: `error-handling.md`, `api-client.md`, `form-validation.md`, `add-ipc-command.md`

Each rules file describes the pattern with a minimal code example to follow. A rule file answers "how do I add/change X?" with numbered steps and inline code snippets — it is a recipe, not a description.

## General rules

- English only
- AGENTS.md must be short and scannable — for every line ask: "removing it, would the agent make mistakes?" — if no, cut
- Document only what is not obvious from reading the code (implicit conventions, architectural decisions, gotchas, trust boundaries, business invariants)
- Be concise: every file must be a reference, not a tutorial
- Use markdown tables where possible
- Do NOT invent anything — base everything exclusively on existing code
- **Separation of concerns between files:**
  - `conventions-*.md` → HOW to write code (style, naming, patterns)
  - `rules/*.md` → HOW to add/change a feature (recipe with steps + snippet)
  - `<domain>/spec.md` → WHAT the code must guarantee (business contracts, data model, invariants)
  - `integrations/*.md` → WHERE the trust boundaries are (security, integrity, safety)
  - `module-index.md` → WHICH modules exist and how critical they are (tier)
- **No duplication:** if a rule is already in `conventions-backend.md`, do not repeat it in `spec.md` — cross-link instead. If a business rule is already in `spec.md`, do not repeat it in `rules/` — link to the spec.
- **Cross-link aggressively:** every file should reference related files via relative markdown links. An agent navigating one file should discover the next relevant one without guessing.