usm/cli-generate

The usm generate command reads all .usm files and produces markdown, OpenAPI, Mermaid, ArchiMate, TOGAF, AGENTS.md, and Vitest test specs.

Intent

After scanning and enriching, generate produces all output artifacts from the .usm source. It runs 6 passes: per-file markdown, area overviews, aggregator docs, surface tables, Mermaid diagrams, and TOGAF deliverables.

Flows

Run usm generate (run-generate)

User runs usm generate to produce all documentation

1. parse → all .usm files in monorepo
2. observe → duplicate $id detection
3. generate → per-file markdown for each validated .usm
4. generate → aggregator docs (risks, roadmap, AGENTS.md, OpenAPI, test specs)
5. generate → surface tables injected into overview.md files
6. generate → Mermaid diagrams (architecture, ER, service deps)
7. generate → TOGAF ADM phase deliverables

Contracts

generate-from-source-only

Generate must read .usm files directly — never derive docs from other docs

Acceptance criteria:

• [ ] All outputs derived from parsed .usm data
• [ ] Duplicate $ids detected and warned
• [ ] --check mode compares without writing

Tests

generate-produces-outputs

Given:

• valid_usm_files: true

Then:

• assertion: markdown files written for each .usm
• assertion: aggregator docs written if system.usm present

generate-check-mode

Given:

• existing_outputs: true

Then:

• assertion: reports up-to-date or out-of-date without writing

Implementation

• Primary: src/cli/index.ts (generate command)
• Test code status: none

See Also

• usm/cli-scan