generate-docs

Files (2)

• SKILL.md
• marker-mechanics.test.py

SKILL.md (first lines)

# Code Documentation (README + docs/)

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

**Usage:** `/architect:generate-docs [target] [--scope=changed|service|repo] [--source-root=<path>] [--readme-only] [--issue=<id>] [--dry-run] [--auto] [--lang=en|ja]`

Runs as a thin sonnet orchestrator delegating inventory and page writing to sub-agents.

## Desired Outcome

Documentation that a new engineer can follow to build, run, and change the code — derived from the
code as it exists, not from the design as it was imagined:

- **A README at every entry point.** The repo (or scaffold) root explains what the system is and
  how to get running; each service/module README covers its own responsibility, build/run/test
  commands, configuration, and layout.
- **Deeper docs where the README would bloat.** `docs/` carries the architecture overview,
  configuration reference, API usage, and operational notes, each linking back to the design
  reports that justify them.
- **Safe updates.** Re-running edits in place: only the sections this skill owns are regenerated,
  human-authored prose is preserved.
- **Docs shipped with the code.** In delivery mode the doc changes are committed to the same
  working branch as the implementation, so they are reviewed and merged in the same PR/MR.
- **Drift surfaced, not hidden.** Where the code and the design reports disagree, the gap is
  reported as a finding instead of being smoothed over in prose.

## Decision Criteria

- **Document what exists** — Content is derived by reading the actual code, build files, and
  configuration. The design reports supply the *why* (intent, constraints, decisions), never the
  *what*. If a designed feature is absent from the code, do not document it as if it were there.
- **No fabricated commands** — Every build/run/test/deploy command shown must be backed by
  something real (a Gradle/Maven task, an npm script, a Makefile target, a Compose service, a
  documented CLI). Verify before writing; omit what cannot be verified.
- **Update, don't overwrite** — This skill owns only the regions it marked (see Ownership Markers).
  Everything else in an existing file is preserved verbatim. Never delete a section this skill did
  not write; when an existing unmarked file needs restructuring, propose the change and confirm.
- **Scope follows the code** — `changed` (default in delivery mode) documents what the working
  branch touched; `service` documents one service/module; `repo` covers the whole tree. Do not
  rewrite the entire tree's docs to record a one-Issue change.
- **Consistency with the project vocabulary** — Terms come from
  `reports/backlog/shared-context/ubiquitous-language.md` (or `reports/01_analysis/`,
  `reports/03_domain/`) when present. Do not coin competing names in prose.

## Prerequisites

| File / source | Required/Recommended | Produced by |
|---------------|----------------------|-------------|
| Generated or implemented code in the target tree | Required | codegen skills / /architect:implement-backlog |
| `reports/03_design/target-architecture.md` | Recommended | /architect:design-microservices |
| `reports/backlog/shared-context/` (ubiquitous language, architecture guardrails, coding standards) | Recommended | /architect:implement-backlog |
| `reports/03_design/api-specifications/` | Recommended | /architect:design-api |
| `reports/08_infrastructure/` | Recommended (infra scaffolds) | /architect:design-infrastructure |

Read the output language from `work/pipeline-progress.json` (`options.output_language`, default
`en`); `--lang` overrides it. Prose uses that language; code identifiers, file paths, commands,
environment-variable names, and config keys stay verbatim in English.

## Modes

| Mode | Trigger | Code location | Commits? |
|------|---------|---------------|----------|
| **Scaffold** | After `generate-scalardb-code` / `generate-infra-code` / `generate-frontend` | `generated/{service}/`, `generated/infrastructure/`, `generated/frontend/` | No — the tree is regenerable pipeline output |
| **Delivery** | Step 5b of `/architect:implement-backlog`, or `--issue=<id>` | The resolved `source_root` (see that skill's Output Location) on the working branch | Yes — with the code, referencing the Issue |

Resolve the root in this precedence: `--source-root=<path>` → the `source_root` recorded in
`reports/backlog/shared-context/decisions.md` → the tree named by the invoking skill → the
repository root. In delivery mode the root must pass the same checks `implement-backlog` applies
(`git check-ignore -q <root>` exits 1; the root is inside the target worktree) — documentation that
git ignores cannot reach the PR/MR. If the target is not a git worktree at all, delivery mode cannot
commit: say so plainly (rather than surfacing a raw git error) and offer to continue in scaffold
mode, which needs no repository.

## Ownership Markers

Generated regions are delimited so re-runs are safe and reviewable:

```markdown
<!-- nexus:begin:build-and-run -->
...generated content...
<!-- nexus:end:build-and-run -->
```

- A **new** file is written entirely inside markers, section by section.
- An **existing marked** file has only its marked regions replaced; text outside them is untouched.
- An **existing unmarked** file (hand-written README) is never rewritten in place. Present the
  proposed additions and, on confirmation, insert them as newly marked sections in the right
  position, leaving the original prose intact. On `--auto`, append them at the end rather than
  guessing where the author wanted them.

Section keys are stable (`overview`, `build-and-run`, `configuration`, `layout`, `api`,
`operations`, `traceability`, `findings`) so a later run updates the same region. Never invent a key
outside this list — an unrecognized key makes the region unfindable on the next run.

**Removing a section.** When a run no longer justifies a section it previously wrote — the drift
recorded in `findings` is resolved, the documented surface is gone, the service was deleted —
remove the whole marked region *including its markers*, and list the removal in the run report. A
stale generated section is worse than a missing one. Only regions whose key is in the stable list
may be removed: anything else was not written by this skill and is left alone.

**Whitespace around a region.** Insert and remove must be exact inverses, or repeated runs produce
whitespace-only diff noise in a file whose whole point is being reviewable:

- a marked region is separated from its neighbours by **exactly one blank line**, or sits flush
  against the start/end of the file
- removing a region takes the region *and* the single blank line that follows it — or, at end of
  file, the one that precedes it
- the file ends with exactly one newline, and no run of two or more blank lines is ever introduced

Verified by round-trip: under this rule, remove → re-insert reproduces the file byte-for-byte, and
repeated cycles do not drift. The whole marker contract above is asserted as behaviour by
`skills/generate-docs/marker-mechanics.test.py` — run it after changing these rules.

## Sub-Agent Execution & Model Assignment

A **thin orchestrator (sonnet)** delegating to sub-agents (Agent tool; see
@skills/common/sub-agent-patterns.md). The orchestrator holds the inventory digest and the page
plan — never full source files or full report bodies.

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect