v0.3.0 to v0.3.0

31 added, 66 removed. Audit A to A.

---

name: make-docs

description: >-

- Use when the user wants architecture docs or behavioral specs, asks to explore a codebase for documentation, sync docs after changes, refresh existing docs against current code, or record an ADR. Branches: explore (survey, confirm, generate), update (since last docs stamp → sync), refresh (full re-survey vs existing docs/), adr (decision record).

+ Writes architecture docs and observable behavior specs under `docs/`. Use when the user asks to document a codebase, write architecture docs or behavior specs, explore a repo for documentation, sync or update docs after changes, refresh or regenerate stale docs against current code, or record an ADR or architecture decision. Skip when the task is an agent instruction file, a changelog, a skill, application code, or Markdown outside that suite.

metadata:

version: 0.3.0

author: "Diego Oliveira"

tags:

- docs

- architecture

- specs

- adr

---

# Make docs

- Produces a documentation suite in `docs/`: **architecture** (how it is structured) and **specs** (what it does). Specs name only **observable** outcomes. An agent can implement or verify against them.

- **Branches:** explore (survey → confirm → generate → verify). Update (delta since the docs stamp). Refresh (full re-survey vs existing `docs/`). Adr (one decision).

- **Invariants:** Every claim in the suite cites a path, an observable command, or a config. Missing evidence: omit the section or ask. One language per suite; code identifiers and BCP 14 keywords (ALL CAPS) stay as in source. Hunters collect; the orchestrator writes. Unearned sections are omitted with no justification paragraph in the artifact. Headings and commands stay scanable (one topic per heading, commands in backticks, depth at `h3`). The index is `docs/README.md`.

- **Reference budget:** The orchestrator opens a phase file when that phase starts. Each hunter gets exactly **1** hunter file. Orchestrator-only refs (`anti-slop`, `language`, `examples`, templates, confirm / generate / verify) are not hunter paths.

- ## Commands

- | Invocation | Branch | Behavior |

- | ---------- | ------ | -------- |

- | `/make-docs explore` | **explore** | Survey → confirm → generate → verify |

- | `/make-docs update` | **update** | `./references/phases/update.md` then verify |

- | `/make-docs refresh` | **refresh** | `./references/phases/refresh.md` (survey → confirm → generate → verify) |

- | `/make-docs adr` | **adr** | `./references/phases/adr.md` then verify if architecture.md moved |

- Without a subcommand, treat as **explore** when `docs/` is missing or the user asked to generate a suite; treat as **update** when they asked to sync after changes and `docs/` exists; treat as **refresh** when they asked to regenerate existing docs against current code.

- ## Definition of Done

- Done for each phase is the completion criterion in its READ file. Open the next phase file when that criterion is met.

+ Write architecture (how the system is structured) and specs (what it does) under `docs/`. Specs name observable outcomes an agent can implement or verify. Paths in this file and in `references/` resolve from this skill folder.

- ### Branch explore

+ ## Inputs

- | Phase | Done when | READ |

- | ----- | --------- | ---- |

- | Survey | Evidence pack ready (hunters returned or `hunters: none` recorded); existing docs read | `./references/phases/survey.md` |

- | Confirm | User confirmed the brief, or answered every unknown | `./references/phases/confirm.md` |

- | Generate | Every confirmed file written from its template; unearned sections omitted; stamp set | `./references/phases/generate.md` |

- | Verify | Every check in the verify file passes | `./references/phases/verify.md` |

+ - `codebase` (workspace, required): the tree to document. It comes from the workspace.

+ - `request` (text, optional): a branch name or an unnamed docs ask. It comes from the user message.

+ - `docs/` (directory, optional): an existing suite, when the workspace has one.

- ### Branch update

+ When the workspace has no project files, stop and report the missing codebase as the next thing to provide.

- | Phase | Done when | READ |

- | ----- | --------- | ---- |

- | Update | Every classified change reflected or waived in chat; stamp refreshed | `./references/phases/update.md` |

- | Verify | Every check in the verify file passes | `./references/phases/verify.md` |

+ ## Steps

- ### Branch refresh

+ 1. **Branch.** Pick one path. **explore:** `docs/` is missing, or the user asked to generate a suite or explore the codebase for documentation. **update:** `docs/` exists and the user asked to sync docs after changes or commits. **refresh:** `docs/` exists and the user asked to regenerate docs, or said the docs are stale, against the current tree. **adr:** the user asked to record one architecture decision. When `docs/` exists and the message names no branch signal, ask once which branch to run. When one message carries both a sync signal and a stale signal, ask once which branch to run. **Done when:** the run names one of those four branches and the signal that selected it. When `docs/` is missing, that signal may be the missing suite. When `docs/` exists and the message names no signal, or names both a sync signal and a stale signal, the branch is named only after the user answers.

+ 2. **Run** that branch. Open its first phase file. Open the next phase file only when the current file's completion criterion holds. A hunter reads only its own file under `references/hunters/`. **Done when:** every phase listed for that branch meets the completion criterion in its phase file.

- | Phase | Done when | READ |

- | ----- | --------- | ---- |

- | Refresh | Existing `docs/` reconciled to current code; ADRs kept unless contradicted; stamp refreshed | `./references/phases/refresh.md` |

+ ## Branches

- Refresh runs survey → confirm → generate → verify against the current tree. Its READ file names that sequence.

+ | Branch | Open first | Then |

+ | --- | --- | --- |

+ | explore | `references/phases/survey.md` | `references/phases/confirm.md`, then `references/phases/generate.md`, then `references/phases/verify.md` |

+ | update | `references/phases/update.md` | `references/phases/verify.md` |

+ | refresh | `references/phases/refresh.md` | survey, confirm, generate, verify, in the order that file states |

+ | adr | `references/phases/adr.md` | `references/phases/verify.md` |

- ### Branch adr

+ ## Invariants

- | Phase | Done when | READ |

- | ----- | --------- | ---- |

- | Adr | Names a *why*; gains + costs present; alternatives have reasons; architecture.md updated if boundaries moved | `./references/phases/adr.md` |

+ Every claim cites a path, an observable command, or a config. A section with no evidence is omitted, and the reason stays in chat. One language per suite. Identifiers and BCP 14 keywords stay as in source. Load `references/language.md` on confirm, generate, and verify. Hunters collect evidence and the orchestrator writes the files. The index is `docs/README.md`, with a line `> Updated on` and today's ISO date. Scan rules (one topic per heading, commands in backticks, heading depth at h3) live in `references/anti-slop.md`, loaded on generate and verify.

- ## Layout

+ ## Output

```text

docs/

- README.md # includes `> Updated on <ISO-date>`

+ README.md

architecture/

architecture.md

domains/

glossary.md

- api.md # only if the project exposes an API

+ api.md

constraints.md

- decisions/ # ADR-NNNN-<slug>.md

+ decisions/

patterns.md

specs/

- <domain>.md # one per behavioral domain

+ <domain>.md

```

- By repo size: **small:** README + architecture.md + decisions/; **medium/large:** full set; **monorepo:** root docs/ + one per service (nearest wins). Cut any file or section the survey did not **earn**. Fill every earned section from evidence. Example rows in templates are not defaults.

+ `api.md` exists only when the project exposes an API. One spec file per confirmed behavioral domain. The survey file names which files a small repo, a larger repo, or a monorepo earns. Replace every template example from evidence, or cut the row.

## Templates

- Before writing a file, load its template from `references/`:

+ Load the matching template before writing the file.

- | Template | File |

- | -------- | ---- |

+ | Template | Writes |

+ | --- | --- |

| `references/template-readme.md` | `docs/README.md` |

| `references/template-architecture.md` | `docs/architecture/architecture.md` |

| `references/template-glossary.md` | `docs/architecture/domains/glossary.md` |

| `references/template-api.md` | `docs/architecture/domains/api.md` |

| `references/template-constraints.md` | `docs/architecture/domains/constraints.md` |

| `references/template-adr.md` | `docs/architecture/decisions/ADR-*.md` |

| `references/template-patterns.md` | `docs/architecture/patterns.md` |

| `references/template-spec.md` | `docs/specs/<domain>.md` |

- ## Specs

- Specs describe **observable** behavior: outcomes a user or external system can see. Name domains after behavior (`auth`, `orders`), not folder layout.

- - One requirement = one **SHALL** (split compound requirements).

- - Requirement keywords follow BCP 14 ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174.html)): English tokens, ALL CAPS only. Full list and the incorporation sentence live in `./references/language.md`.

- - Each requirement has at least one Scenario (Given/When/Then) that **exercises** it: a concrete case, not a rewording.

- - Cover the case that would hurt most to see broken; name it explicitly.

- - Pure refactor with no behavior change: no spec update. Record that in chat, not as filler in the spec file.

- ## Out of scope

+ ## Boundaries

- Data model, observability, CI/CD. Survey lists them as unknowns when present. Confirm asks. Otherwise omit the files and do not narrate the omission in `docs/`.

+ Data model, observability, and CI/CD stay out of the suite unless the survey lists them and confirm accepts them.

- Do not write instruction-file policy (`AGENTS.md` body, adapters, glob rules). The one exception: a single when-to-read pointer to `docs/README.md` on the canonical always-on file, if that file already exists. Do not create `AGENTS.md`.

+ An existing canonical always-on file (`AGENTS.md`, or the one always-on file already in the repo) may gain one when-to-read line for `docs/README.md`. The procedure is in `references/phases/generate.md`. The run leaves every other instruction-file line as it found it, and it does not create `AGENTS.md`.