USM

Appearance

usm/gen-markdown ​

Markdown generator — produces GitHub-flavored markdown docs for each .usm file, plus cross-cutting aggregator docs (risks, roadmap, data model, AGENTS.md, etc.).

Why this exists ​

Markdown is the primary human-readable output. Each .usm file gets a per-file doc, and aggregator generators produce cross-app docs like shared-services-index, packages-index, per-app-api-reference, and AGENTS.md.

How it works ​

Generate per-file markdown (per-file-md) ​

Generate an overview.md for each service and feature .usm file

  1. Parse — single .usm file
  2. Generate — markdown with headings, tables, flows, contracts, tests
  3. Submit — write to .agents-workspace/docs/<area>/overview.md

Flow Diagrams ​

mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: parse single .usm file
    User->>Browser: generate markdown with headings, tables, flows, contracts, tests
    User->>Browser: submit write to .agents-workspace/docs/&lt;area&gt;/overview.md

Guarantees ​

markdown-gfm ​

Markdown output must be valid GitHub-flavored markdown

Acceptance criteria:

  • [ ] H1 heading matches the .usm $id or name
  • [ ] Tables for flows, contracts, tests
  • [ ] No broken links

markdown-single-writer-per-path ​

Each output path must have exactly one generating pass, and output must be a pure function of the .usm inputs

Acceptance criteria:

  • [ ] No generator derives output by reading the file it is about to overwrite
  • [ ] generateDataModelDoc owns .usm-workspace/docs/data/models.md (ER section composed in)
  • [ ] Area overviews write to the root .usm-workspace/docs/features/ — never apps/<svc>/.usm-workspace/
  • [ ] usm generate --check converges immediately after a clean usm generate

Test specifications ​

md-service-file ​

Given:

  • valid_service_usm: true

Then:

  • assertion: overview.md written with identity, modules, decisions sections

md-feature-file ​

Given:

  • valid_feature_usm: true

Then:

  • assertion: overview.md written with flows, contracts, tests sections

Implementation ​

  • Primary: src/generators/markdown.ts
  • Test code status: none

See Also ​

  • usm/cli-generate