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.).

Intent ​

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.

Flows ​

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

Contracts ​

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

Tests ​

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