Business Architecture (TOGAF Phase B)

Auto-generated from USM features and system.usm.

Features by Service

usm/cli

Feature	Summary	Status	Flows	Contracts
usm/cli-color-output	Comprehensive CLI polish for the USM CLI — colorized status output, animated spi	built	8	12
usm/cli-config-outputs	Configurable output paths in usmconfig.json and simplified command convention. G	built	2	3
usm/config-validation	Validate usmconfig.json at load time against the packaged usmconfig-v1.json sche	built	2	5
usm/docs-ia-restructure	Restructure the generated docs sidebar to a stable, audience-appropriate informa	built	2	5
usm/docs-serve-port-check	Add port availability checking, already-serving detection, watch mode for auto-r	built	4	6
usm/cli-docs	usm docs serve and usm docs build — serves generated docs locally via VitePress	built	5	12
usm/cli-enrich	The usm enrich command fills in TODO: describe placeholders in .usm files using	—	1	1
usm/cli-feedback	The usm feedback command configures the agent feedback policy in system.usm — in	built	0	0
usm/cli-generate	The usm generate command reads all .usm files and produces markdown, OpenAPI, Me	—	3	1
usm/cli-init	The usm init command analyzes the repo and generates a starter usmconfig.json.	—	2	1
usm/internal-dsl-builder	Fluent typed TypeScript builder (internal DSL, per Fowler) that compiles to vali	built	3	4
usm/mcp-setup-guides	Add per-editor MCP setup guides for all 35 MCP-ready editors as dedicated pages	built	1	5
usm/cli-multi-lang-scan	Multi-language scanner support, extended with a detector plugin system. usm scan	built	18	11
usm/pkg-universal-docs	Ship universal onboarding docs (getting-started, agent-setup-guide, per-editor M	built	3	5
usm/query-layer	Predicate query language over .usm data — a tiny expression grammar (selectors,	built	3	4
usm/cli-scaffold-project	The usm scaffold-project command generates a starter .usm/ directory for single-	—	1	1
usm/cli-scaffold	The usm scaffold command creates a new .usm file with a template for system, ser	—	1	1
usm/cli-scan	The usm scan command reads usmconfig.json, scans the codebase, and generates .us	—	3	1
usm/upgrade	usm upgrade — detect stale USM projects and guide users through adopting new opt	built	3	5
usm/cli-validate	The usm validate command checks .usm files against the v1 JSON Schema and report	—	1	1
usm/vitepress-home-feedback-schema	Refine the VitePress docs homepage into a clean, scannable technical reference (	built	4	4
usm/vitepress-schema-polish	Evolve the generated VitePress docs into an outstanding, adoption-accelerating s	built	5	6
usm/gen-agentsmd	AGENTS.md generator — produces AI agent context files with USM-augmented system	—	1	2
usm/gen-archimate	ArchiMate 3.1 generator — produces an Open Exchange XML model (XMI 2.1) from USM	—	1	1
usm/gen-content-blocks	First-principles redesign of the docs generator. Introduces a content-block sche	built	5	8
usm/docs-experience	Overhaul the generated docs site from a spec-dump into a real reading experience	built	6	6
usm/gen-docs-split	Split generated docs into help docs (public-facing, for visitors and new users)	built	2	5
usm/gen-feature-review	Review-quality feature markdown — restructures the feature markdown generator to	built	4	3
usm/feedback-upstream-routing	Scope-aware feedback routing — the generated feedback protocol, MCP tool, and do	built	4	4
usm/gen-help-reference	Help docs reference expansion — adds usage/options/prerequisites fields to featu	built	4	4
usm/gen-markdown	Markdown generator — produces GitHub-flavored markdown docs for each .usm file,	—	1	2
usm/gen-mermaid	Mermaid diagram generator — produces architecture, ER, sequence, and service-dep	—	1	2
usm/mkt-language-tabs	Marketing site language support section — clickable logo carousel showing 12 lan	in-progress	2	5
usm/mkt-mock-interfaces-v2	Update the mock interfaces to look like the real USM tooling — browser mock styl	built	0	2
usm/mkt-mock-interfaces	Add two side-by-side animated mock interfaces below the "Works with your client"	built	2	4
usm/gen-openapi	OpenAPI 3.1 generator — produces an openapi.yaml spec and TypeScript types from	—	1	1
usm/opencode-integration	First-class opencode support in the rules-files generator — emits a usm-workflow	built	3	4
usm/gen-roadmap	Roadmap improvements — add feature links and shipped_in version to roadmap items	built	4	4
usm/gen-rules-files	Tool-specific rules file generator with two-tier enforcement — detailed workflow	built	4	2
usm/gen-source-mapping	Source mapping generator — reads all service and feature specs to build a bidire	built	4	5
usm/structurizr-bridge	Structurizr bridge — import a Structurizr workspace JSON into .usm system and se	built	3	4
usm/gen-technical-design	Technical Design Document generator — renders a 13-section detailed design docum	built	16	7
usm/gen-testspecs	Vitest test specs generator — produces per-feature and aggregated Vitest test fi	—	1	2
usm/gen-togaf	TOGAF ADM generator — produces phase deliverables (A through H) from USM data fo	—	1	1
usm/gen-user-docs	Personas and journey flows (actor/surface per step) become first-class spec data	built	4	6
usm/agent-feedback	Agent feedback protocol — teaches AI agents a consistent, configurable way to su	built	4	5
usm/mcp-query	usm_query MCP tool — predicate query over all .usm files. Selectors (features/se	built	1	2
usm/schema-v1	The v1 JSON Schema — the validation contract for all .usm files, defining system	—	1	2

usm/mcp

Feature	Summary	Status	Flows	Contracts
usm/mcp-contracts	MCP contracts tool — extracts the contracts array from a feature .usm file, incl	—	1	1
usm/mcp-flows	MCP flows tool — extracts the flows array from a feature .usm file, including id	—	1	1
usm/mcp-list	MCP list tool — lists all .usm files in a directory or monorepo with id, type, v	—	1	1
usm/mcp-read	MCP read tool — reads and parses a .usm file, returning the full object plus met	—	2	1
usm/mcp-references	MCP references tool — finds all .usm files that reference a target $id, useful f	—	1	1
usm/mcp-search	MCP search tool — searches all .usm files for a query string, returning matching	—	1	1
usm/mcp-summary	MCP summary tool — returns a quick summary of a .usm file with id, type, version	—	1	1
usm/mcp-validate	MCP validate tool — validates a .usm file by path or inline YAML content against	—	1	1
usm/mcp-write	MCP write tools — let agents author and update .usm feature specs as part of the	built	3	5

User Flows

usm/cli-color-output

Colored status output across all commands (4 steps) — Every success/error/warning/skip/info line uses color helpers. Symbols are colored (green ✓, red ✗, yellow ⚠, dim ⊘, cyan →). File paths and counts dimmed.
Spinner during long operations (4 steps) — scan, enrich, generate show a spinner with elapsed seconds while work is in progress. Spinner clears on completion and is replaced by the result line.
Progress bar for batch operations (4 steps) — generate writing N files and scan detecting N services show an inline progress bar that updates without scrolling.
Tree view for file lists (4 steps) — Files written/skipped lists render as a tree with connectors mirroring .usm/ structure via treeify.
ASCII banner on no-args/help (3 steps) — usm with no args shows an ASCII USM banner then the help text.
Did you mean suggestions for typos (3 steps) — Unknown command triggers a did-you-mean suggestion. Commander has built-in suggestion support — just needs enabling.
Update notifier hint (3 steps) — Non-blocking check of npm registry for newer @smithgray/usm. Cached 24h. One-line hint if newer exists.
Verbosity flags (4 steps) — Global --quiet and --verbose flags control output level across all commands.

usm/cli-config-outputs

Resolve output paths from usmconfig.json (4 steps) — A shared utility reads usmconfig.json and returns the configured output path for each type (docs, help-docs, archimate, togaf, openapi, tests). Falls back to defaults if not configured or config missing.
Generate with --only flag (4 steps) — usm generate runs all generators. usm generate --only <target> runs only the specified output. Valid targets: docs, help-docs, togaf, archimate, openapi, tests, rules, agents-md.

usm/config-validation

Author and correct a usmconfig.json (4 steps) — The adopter-onboarding loop the config exists for: init writes a config, the consumer tunes output paths, and a typo fails loudly instead of silently misdirecting output.
Config validation pipeline (4 steps)

usm/docs-ia-restructure

Navigate the developer docs (3 steps)
Navigate the help docs as a new user (3 steps)

usm/docs-serve-port-check

Pre-flight port availability check (6 steps) — Before spawning VitePress, probe the target port. If in use, either fail with a clear message or auto-select the next free port.
Detect already-running server (6 steps) — Before starting, check if a VitePress server is already running on the target port. If it is, offer to reuse it or kill and restart.
Watch mode for auto-regeneration (6 steps) — Add --watch flag that watches .usm/ files and re-runs usm generate before VitePress picks up the changes, keeping docs always in sync.
Quality-of-life improvements (4 steps) — Graceful shutdown, browser-open, and status command.

usm/cli-docs

Docs serve pipeline (7 steps) — System pipeline behind usm docs serve: generate docs, config, and watch for spec changes.
Docs build pipeline (4 steps) — System pipeline behind usm docs build: generate then produce a deployable static site.
VitePress config pipeline (5 steps) — System pipeline: generate .vitepress/config.ts from system.usm index and feature directory structure.
Unified docs output pipeline (6 steps) — System pipeline: write all generated docs into a single docs/ directory with a clear hierarchy.
Review specs in the live preview (5 steps) — The spec-first review loop: a spec author starts the dev server, edits specs, and sees changes render live within a second.

usm/cli-enrich

Enrich a single .usm file (5 steps) — User enriches one file with LLM-generated content

usm/cli-generate

Generate pipeline (6 passes) (7 steps) — System pipeline behind usm generate: parse all .usm files and write every derived artifact.
Regenerate all docs from specs (3 steps) — A spec author edits .usm files and regenerates every derived artifact, confirming the browser preview stays current.
Build against generated test specs (1 steps)

usm/cli-init

Init pipeline (repo analysis) (4 steps) — System pipeline behind usm init: analyze repo structure, write starter config.
Set up USM in a new repo (3 steps) — First-run experience: an adopter initializes USM in their repository and reviews the generated usmconfig.json without reading docs first.

usm/internal-dsl-builder

Compose a feature spec with the builder (3 steps)
Write a built spec to disk (2 steps)
Extend an existing spec (3 steps)

usm/mcp-setup-guides

Editor setup flow (6 steps) — User lands on the MCP setup index, sees a grid of 35 editor cards, clicks their editor, gets the exact MCP config and rules file installation.

usm/cli-multi-lang-scan

Detect services from multiple language manifests (5 steps) — Scanner reads usmconfig.json detection.manifests (or defaults) and checks for manifest files. Each manifest identifies a service and its language. Framework is detected from dependencies in the manifest.
Detect Python routes (FastAPI, Flask, Django) (4 steps) — Scan .py files for decorator-based routes. FastAPI uses @app.get/@router.get, Flask uses @app.route, Django uses urlpatterns in urls.py.
Detect Go routes (chi, gin, echo, net/http) (4 steps) — Scan .go files for router registration patterns. chi/gin/echo use r.GET/r.POST, net/http uses http.HandleFunc, gorilla/mux uses r.HandleFunc.
Detect Rust routes (Axum, Actix, Rocket) (4 steps) — Scan .rs files for route patterns. Axum uses .route(), Actix uses #[get(...)] macros, Rocket uses #[get("/path")] attributes.
Detect Java/Kotlin routes (Spring Boot, Javalin, Quarkus) (4 steps) — Scan .java/.kt files for annotation-based routes. Spring uses @GetMapping/@PostMapping/@RequestMapping, Javalin uses app.get/post, Quarkus uses @Path + @GET/@POST.
Detect C# routes (ASP.NET Core, Minimal APIs) (4 steps) — Scan .cs files for attribute-based routes. ASP.NET uses [HttpGet], [HttpPost], [Route], Minimal APIs use app.MapGet/MapPost.
Detect Ruby routes (Rails, Sinatra) (4 steps) — Scan config/routes.rb for Rails routes (get/post/resources) and .rb files for Sinatra routes (get '/path' do).
Detect PHP routes (Laravel, Symfony, Slim) (4 steps) — Scan routes/web.php for Laravel routes (Route::get/post), .php files for Symfony attributes (#[Route]) and Slim ($app->get/post).
Detect Elixir routes (Phoenix) (4 steps) — Scan router.ex for Phoenix routes (get/post/pipe_through/scope).
Detect Swift routes (Vapor) (4 steps) — Scan .swift files for Vapor route registrations (routes.get/post, app.get/post).
Detect Scala routes (Akka HTTP, Play, Tapir) (4 steps) — Scan .scala files for route patterns. Akka HTTP uses path/endpoints, Play uses routes file, Tapir uses endpoint.get/post.
Detect C++ routes (Crow, Drogon, Pistache) (4 steps) — Scan .cpp/.h files for route registration patterns. Crow uses CROW_ROUTE, Drogon uses app.registerHandler, Pistache uses router.get/post.
Detect data models from multiple ORMs across languages (3 steps) — Extend data model detection beyond Prisma to support ORMs across all supported languages.
Discover and load detector files (4 steps) — At scan start, the orchestrator reads .usm/detectors/*.yaml (if present), validates each against detector-v1.json, and merges them with built-in defaults and the usmconfig.json detection section. Precedence: built-in defaults < .usm/detectors/ files < usmconfig.json detection (last wins).
Detect a service from any language manifest (5 steps) — Replaces the hardcoded package.json read. For each directory matched by a services rule, the orchestrator finds the detector whose manifest glob matches a file in that directory and reads that manifest (not always package.json). A Go app with go.mod is detected via the Go detector; a Zig app with build.zig.zon via the Zig detector. No package.json is required.
Extract routes for convention-based frameworks via script (4 steps) — Frameworks whose routes come from file conventions (Next.js app/page.tsx, Remix, SvelteKit) rather than declarations cannot be captured by regex. A detector declares routes.script pointing at a .ts file exporting extractRoutes(sourceDir, framework). The orchestrator imports and runs it. Declarative regex patterns remain the default; script is opt-in per detector.
Detect infrastructure from IaC files via detectors (3 steps) — Generalizes the Terraform-only infrastructure scan. An infrastructure detector declares a manifest glob (infrastructure/**/.tf, **/cloudformation.yaml, **/.pulumi.ts) and resource extraction patterns. Built-in Terraform detector preserves current behaviour; users add CloudFormation/Pulumi/CDK via detector files or usmconfig.json detection.infrastructure.
Detect data models from any ORM via detectors (3 steps) — Generalizes the Prisma-only data scan. A data-schema detector declares a manifest glob and model extraction patterns. Built-in Prisma detector preserves current behaviour; users add SQLAlchemy, Diesel, GORM, Entity Framework via detector files or usmconfig.json detection.data_models.

usm/pkg-universal-docs

Onboard with zero authored docs (4 steps)
Override with your own docs-source (3 steps)
Universal docs merge pipeline (4 steps)

usm/query-layer

Run a query from the CLI (4 steps)
Run a query via the usm_query MCP tool (3 steps)
Compose predicates (3 steps)

usm/cli-scaffold-project

Scaffold single-app project (4 steps) — User creates .usm/ for a single application

usm/cli-scaffold

Scaffold a .usm file (3 steps) — User creates a new .usm file from a template

usm/cli-scan

Scan pipeline (codebase detection) (5 steps) — System pipeline behind usm scan: read config, detect structure, write and smart-merge .usm files.
Generate specs from the codebase (3 steps) — First scan: an adopter runs usm scan after init and gets .usm files for every detected service, route, and data source.
Re-scan after enriching specs (3 steps) — A spec author re-runs usm scan after editing .usm files and confirms smart-merge kept their work.

usm/upgrade

Detect project version and missing capabilities (5 steps) — Read the installed USM version and the project's system.usm.version, walk the capability registry, and produce a status report.
Set up missing capabilities (4 steps) — For each missing capability, either prompt interactively (TTY) or apply defaults (--apply), calling the capability's own setup function.
Bump project version after applying (3 steps) — After capabilities are applied, set system.usm.version to the installed version, validate, and suggest regenerating outputs.

usm/cli-validate

Run usm validate (4 steps) — User runs usm validate on one or more .usm files

usm/vitepress-home-feedback-schema

Simplify homepage to technical reference (8 steps) — Strip marketing-heavy content from the VitePress homepage. Keep it a clean, scannable reference that links to usm.dev for marketing.
Add dual-mode Feedback / Report Issue button (6 steps) — Add a visible feedback mechanism to the VitePress docs site. Supports two modes: human (pre-filled GitHub issue) and agent (MCP tool with structured context).
Stronger cross-links and CTAs (4 steps) — Add consistent next-steps sections, cross-links between related pages, and clear CTAs throughout the docs.
General VitePress polish (5 steps) — Better use of VitePress callouts, tables, and diagrams. Ensure dark mode, mobile, and search work well.

usm/vitepress-schema-polish

Comprehensive schema reference (HIGHEST PRIORITY) (5 steps) — Rebuild generateSchemaReference to produce a deep, scannable, field-by-field reference for every major type, sourced from schema/v1.json + enriched descriptions.
Rich, data-driven homepage (5 steps) — Replace the flat-list README with a showcase homepage generated from system.usm.
Upgrade Getting Started (4 steps) — Make first-run smooth and visual.
Restructure sidebar navigation (3 steps) — Regroup the auto-generated sidebar to match how users explore.
Visuals + general polish (4 steps) — Dark-mode-aware diagrams, callouts, tables, typography, mobile, badges, CTAs.

usm/gen-agentsmd

Generate AGENTS.md (3 steps) — Augment AGENTS.md with USM content using smart merge

usm/gen-archimate

Generate ArchiMate model (4 steps) — Produce model.xml with ArchiMate elements and relationships

usm/gen-content-blocks

Render content blocks to VitePress markdown (10 steps) — The generic renderer takes an array of content blocks from a spec (or a reference_pages entry) and converts each block type to its VitePress markdown equivalent. This is the ONE rendering function — all pages flow through it.
Generate reference pages declared on system.usm (5 steps) — system.usm gains a reference_pages[] field. Each entry declares an id, title, audience (public/internal), and either inline content[] (content blocks) or a source (detectors, schema, config) for runtime-generated content. The generator renders each declared page through the generic content-block renderer. This replaces generateLanguageSupportDoc (source: detectors), generateAgentSetupGuide (inline content), and generateGettingStartedDoc (inline content).
Render feature spec reference blocks in feature docs (4 steps) — Feature specs gain an optional reference[] field — content blocks that appear in the feature's generated doc page AFTER the standard sections (summary, intent, flows). Unlike contracts (stripped by help filter), reference blocks marked audience: public survive into help docs. This lets a feature spec carry user-facing reference tables (e.g. the multi-lang-scan spec carries its supported-languages table as a reference block, not a contract).
Help-doc filter respects content block audience (3 steps) — The help-doc filter (simplifyFeatureDoc in docs.ts) is updated. Instead of stripping entire ## sections by heading name, it parses content blocks and keeps those with audience: public (or no audience field), drops those with audience: internal. This makes audience filtering block-level granular rather than section-level coarse.
Delete hardcoded generator functions (6 steps) — After the content-block system and reference_pages are working, the hardcoded functions are deleted and their content migrated into specs. This is the cleanup pass — it must not happen until the replacement is proven.

usm/docs-experience

Suppress templated stubs a service has no data for (3 steps) — A service only emits the architecture/ui/deployment/operations/decisions pages its .usm actually populates. A CLI gets no UI map or production-deployment page.
Surface the real TOGAF deliverables as the Architecture section (3 steps) — The togaf generator already produces Phase A-H deliverables; wire them into the dev-docs sidebar as a real Architecture section instead of empty per-service architecture stubs.
Widen the layout to use the viewport (2 steps) — Override VitePress defaults so reference content, tables, code, and diagrams breathe.
Rebuild the homepage as navigation (3 steps) — Drop the README-style metrics/identity dump; keep the hero and add a features grid whose cards ARE the navigation into the docs.
Give help and technical audiences distinct voices (3 steps) — The same feature spec renders differently per audience — task-oriented for help, reference-faithful for technical.
Anti-drift and discoverability (2 steps) — Pin the getting-started version from package.json and enable VitePress sitemap on both sites.

usm/gen-docs-split

Generate both help and developer docs (6 steps) — usm generate produces full docs in .usm-workspace/docs/ (developer). usm docs build --audience help copies and filters into .usm-workspace/help-docs/ with simplified content and a public-oriented sidebar.
Serve help docs locally (4 steps) — usm docs serve --audience help serves the filtered help docs on a local VitePress dev server for review.

usm/gen-feature-review

Generate review-quality markdown from feature .usm (3 steps) — When a feature .usm is generated, produce a review.md alongside overview.md that frames the spec for human approval.
Render flows as numbered procedural steps (3 steps) — Convert the flows[] array into readable numbered steps grouped by flow, with each step's action and target combined into a sentence.
Render contracts as acceptance checklist (3 steps) — Convert the contracts[] array into a markdown checklist under each contract description.
Render tests in given/when/then format (3 steps) — Convert the tests[] array into given/when/then blocks for readability.

usm/feedback-upstream-routing

Agent classifies a bug by blast radius (3 steps) — When an agent discovers a bug, it first determines whether the fault is in the project or in the USM tool itself.
Route a USM tool bug upstream (4 steps) — USM tool bugs are drafted and filed against the upstream tracker with version and environment context.
Render the scope-aware protocol everywhere (3 steps) — The Where does the bug live? guidance is emitted into every agent-facing surface from one code path.
MCP tool carries the distinction (2 steps) — usm_report_feedback surfaces the scope question at the tool boundary.

usm/gen-help-reference

Generate CLI reference page from feature specs (4 steps) — Scan all CLI feature specs for usage/options/prerequisites fields and generate a single cli-reference.md page with command examples, flag tables, and prerequisites for each command.
Generate usmconfig reference from JSON schema (4 steps) — Read usmconfig-v1.json and generate a config-reference.md page with field descriptions, types, defaults, and examples.
Generate .usm schema reference from v1.json (4 steps) — Read v1.json and generate a schema-reference.md page showing all fields for each .usm file type (system, service, feature, data).
Generate MCP tools reference page (4 steps) — Consolidate all MCP tool feature specs into a single mcp-reference.md with a table of all 12 tools, their inputs, and when to use each.

usm/gen-markdown

Generate per-file markdown (3 steps) — Generate an overview.md for each service and feature .usm file

usm/gen-mermaid

Generate architecture diagram (3 steps) — Produce a C4-style architecture diagram from system + service .usm files

usm/mkt-language-tabs

Render logo carousel on marketing site (5 steps) — Between Token Comparison and Tool Logos sections. 12 language logos in a horizontal row. Default: TypeScript selected. Click a logo to reveal frameworks + route detection code example.
Render full language grid in help docs (3 steps) — New page in help docs: 'Language Support'. Full grid showing all 12 languages, all 30+ frameworks, manifest file, and route detection pattern for each.

usm/mkt-mock-interfaces

Chat mock animation (5 steps) — Cycles through 2 scenes showing an agentic IDE/chat interface with USM-aware agent responses.
Browser mock animation (5 steps) — Cycles through 2 scenes showing a browser loading the spec/docs corresponding to the chat action.

usm/gen-openapi

Generate OpenAPI spec (3 steps) — Produce openapi.yaml from feature routes and contracts

usm/opencode-integration

Generate the usm-workflow skill (4 steps) — During usm generate, emit .opencode/skills/usm-workflow/SKILL.md — a skill whose frontmatter description is the enforcement nudge (visible in the system prompt every message) and whose body is the full spec-first checklist.
Wire the iron-rules file into every-message instructions (4 steps) — Generate a short iron-rules markdown file and register it in opencode.json instructions so its content is appended to the system prompt on every request — the mechanism that actually counters mid-session drift.
Regenerate without breaking user config (3 steps) — Repeated usm generate runs replace the USM-owned skill and instructions files wholesale but leave all other opencode.json content untouched.

usm/gen-roadmap

Generate roadmap page with feature links and status badges (4 steps) — When usm generate runs, if the system has roadmap items, generate a roadmap.md page with a table showing status badge, title (linked to feature spec if feature field is set), shipped_in version, and target date.
Fix sidebar to only include links to existing files (4 steps) — The sidebar generator in docs.ts should check if the target .md file exists before adding a sidebar entry. This prevents dead links for suppressed pages (risks, roadmap) and missing feature docs.
Fix sidebar slug case to match actual file names (3 steps) — The sidebar slug derivation uses feat.id.replace(/^[^-]+-/, "") which produces lowercase slugs. But actual file names preserve case from the source .usm file path (e.g., agentsMd.md not agentsmd.md). The sidebar should derive the slug from the ref path, not the $id.
Enable mermaid rendering in VitePress config (3 steps) — VitePress doesn't render mermaid code blocks by default. Add the vitepress-plugin-mermaid to the VitePress config so architecture diagrams and other mermaid blocks render properly.

usm/gen-rules-files

Generate rules files for all supported tools (7 steps) — During usm generate, produce instruction files for each supported AI coding tool, each containing the spec-first workflow tailored to that tool's conventions.
Generate Cursor .mdc rule file (4 steps) — Cursor rules use .mdc format with YAML frontmatter specifying when the rule activates. The rule teaches the agent the spec-first workflow.
Generate CLAUDE.md for Claude Code (4 steps) — Claude Code reads CLAUDE.md for project instructions. The file teaches the spec-first workflow and references the MCP server.
Enhance AGENTS.md with workflow instructions (4 steps) — Extend the existing agentsMd generator to include spec-first workflow instructions alongside the structural context it already produces.

usm/gen-source-mapping

Build the source mapping from all specs (6 steps) — The generator reads all service.usm files (for modules[] and paths[]) and all feature.usm files (for implementation.primary, implementation.test_code, routes[].file_path). It walks the filesystem within each service's paths[], matching each file to: (1) a module by directory, (2) a feature by implementation.primary, (3) a route by routes[].file_path. Files matching nothing are orphans. The result is a SourceMap data structure that all views render from.
Render the file-tree view (code navigator) (5 steps) — Renders the source map as a directory tree with file descriptions, grouped by service and module. Each file shows its module purpose and the feature that owns it (if any). Files with no feature are marked as unspecced. Source: file-tree on a reference_pages entry.
Render the coverage-matrix view (3 steps) — Renders the source map as a matrix showing which files have feature specs vs which are unspecced. Useful for spotting drift — code that exists but has no governing spec. Source: coverage-matrix on a reference_pages entry.
Render the orphan-report view (4 steps) — Renders only the orphan files — files in the codebase not claimed by any feature spec. This is the drift signal: code with no spec governing it. Source: orphan-report on a reference_pages entry.

usm/structurizr-bridge

Import a Structurizr workspace JSON (4 steps)
Export Structurizr DSL as a generate target (3 steps)
Import then export stays coherent (3 steps)

usm/gen-technical-design

Generate the 13-section technical design document (5 steps) — usm generate runs the technical-design generator. It reads all .usm files (system, services, features, data) and renders up to 13 pages under .usm-workspace/docs/design/. Each page is only rendered if its data source exists. The generator then updates the sidebar config with the Design group containing only the rendered pages.
Render Project Overview page (6 steps) — Section 1. Reads system.identity (name, domain, repository), system.summary, system.roles (as stakeholders/personas), new system.stakeholders[], new system.assumptions[], and system.index (features as use-cases). Renders project name, description, stakeholders table, assumptions list, and core use-cases summary.
Render Requirements page (4 steps) — Section 2. Functional requirements from features (summary + intent). Non-functional requirements from new system.non_functional{} object with sub-fields for performance, scalability, security, reliability, maintainability. Renders two sub-sections with feature table and NFR table.
Render System Architecture page (5 steps) — Section 3. High-level diagram from Mermaid (services + dependencies). Technology stack from service.tech_stack across all services. System components from system.services + system.apis. Renders diagram, tech stack table, and component list.
Render Module Design page (3 steps) — Section 4. Per-module breakdown from service.modules[]. For each module: name, purpose, inputs, outputs, dependencies, and a flow description (from features whose implementation.primary is in the module). Renders one sub-section per module.
Render Database Design page (4 steps) — Section 5. ER diagram from data .usm files or detected ORM schema. Schema design from data.usm models. Indexes from data.usm index definitions. Transactions from data.usm transaction strategies. Renders ER diagram, schema tables, index list, transaction notes. Only rendered if data .usm files or a detected ORM schema exist.
Render API Design page (5 steps) — Section 6. Endpoints from feature.routes[]. HTTP method, URL, request/response structure. Authentication from system.auth_schemes and service.security. Authorization from service.rbac (roles, resources, permissions). Rate limiting from route-level or service-level config. Error handling conventions. Renders endpoint table, auth summary, authz matrix, rate limiting notes, error format. Only rendered if any feature has routes.
Render Security Design page (6 steps) — Section 7. Authentication/authorization from system.auth_schemes and service.rbac. Data encryption from service.security and infrastructure TLS config. Security auditing from system.operations and service.infrastructure.monitoring. Vulnerabilities from system.risks where severity is high/critical. Security stack from new system.security_stack{} field (first line, last line of defense). Renders auth summary, encryption table, audit notes, vulnerability list, security stack.
Render Deployment Architecture page (5 steps) — Section 8. Deployment diagram (Mermaid) from system.infrastructure and service.infrastructure. Environment setup from system.deployment.environments (development, staging, production). Scaling strategy from service.infrastructure.scaling and system.infrastructure. Monitoring stack from system.operations and service.infrastructure.monitoring. Renders diagram, environment table, scaling notes, monitoring stack. Only rendered if deployment or infrastructure data exists.
Render Testing Strategy page (4 steps) — Section 9. Unit testing from service.testing (framework, command, coverage target). Integration testing from service.testing_details. Acceptance testing from feature.tests[]. Performance testing and security testing from new system.testing_strategy{} field. Automated testing from CI integration notes in system.testing_strategy. Renders per-layer testing table with framework, command, and notes.
Render Maintenance & Monitoring page (4 steps) — Section 10. Logging from system.operations and service.infrastructure.monitoring.logs. Alerting from system.operations.alerts. System health monitoring from service.infrastructure.monitoring.metrics. Error tracking from new system.error_tracking{} field. Renders logging strategy, alerting config, health metrics, error tracking tool.
Render Backup & Recovery page (4 steps) — Section 11. Backup strategy from service.infrastructure.data.backup_retention_days and new system.backup_recovery{} field. Disaster recovery from service.infrastructure.disaster_recovery (rto_minutes, rpo_minutes) and system.backup_recovery. Renders backup schedule table, RTO/RPO targets, disaster recovery plan. Only rendered if backup or DR data exists.
Render Risks & Mitigation page (4 steps) — Section 12. Technical risks from system.risks[] (all items). Mitigation strategies from each risk's mitigation field. Also includes service-level risks from service.risks[]. Renders risk table with ID, title, severity, status, mitigation, and a severity summary chart.
Render Future Enhancements page (5 steps) — Section 13. Roadmap from system.roadmap[] (planned and in-progress items). Scalability considerations from service.infrastructure.scaling and service.future[] items. Renders roadmap table with status badges, target dates, and future items list grouped by service.
Render Decision Register page (4 steps) — Consolidates all decisions[] from features, services, and system.principles into one page. Each decision shows ID, decision text, status, rationale, alternatives considered, consequences, date, and source. Renders a table view and a detailed view.
Restructure sidebar into five groups (6 steps) — The docs sidebar generator is updated to produce five top-level groups: Getting Started (Home, Getting Started), Design (13 pages, only rendered ones), Project Management (Roadmap, Features grouped by area, Decision Register), Developers (Source Map, Test Coverage, Spec Coverage, API Reference, CLI Reference, Configuration), Exports (TOGAF Phases, ArchiMate Model). Groups and pages only appear if data exists. The existing Core Concepts, Workflows, Architecture, Deployment, and Contributing groups are replaced by this structure.

usm/gen-testspecs

Generate Vitest test specs (4 steps) — Convert flows and tests from .usm into Vitest describe/it blocks

usm/gen-togaf

Generate all TOGAF phases (4 steps) — Produce markdown for each ADM phase

usm/gen-user-docs

Author personas and journey flows (4 steps)
Generate user documentation from personas and journeys (4 steps)
Generate e2e specs from journeys (3 steps)
Compose help docs from user content (3 steps)

usm/agent-feedback

Configure feedback policy at init (4 steps) — usm init (and usm scan --enrich) asks the human two questions and persists a system.feedback block
Agent surfaces an issue following the configured policy (6 steps) — When an agent discovers a bug or improvement, its behaviour is governed entirely by system.feedback.policy
Render feedback protocol into all rules files (4 steps) — During usm generate, a shared Feedback Protocol block is emitted into every agent-facing file, dynamic to the project policy
Human reviews collected feedback (3 steps) — Feedback entries written to .usm/feedback are reviewable and convertible into issues or features

usm/mcp-contracts

Get feature contracts (3 steps) — Agent retrieves all contracts for a feature

usm/mcp-flows

Get feature flows (3 steps) — Agent retrieves all flows for a feature

usm/mcp-list

List all .usm files (3 steps) — Agent lists all .usm files in the monorepo

usm/mcp-query

Run a predicate query (3 steps)

usm/mcp-read

Read pipeline (file access) (3 steps) — System pipeline behind usm_read: locate, parse, and return a .usm file with metadata.
Ground implementation in the governing spec (4 steps) — The spec-first handoff: a spec author assigns a task, and the agent grounds its implementation in the governing spec via MCP read before touching code.

usm/mcp-references

Find references to a $id (3 steps) — Agent searches for all files referencing a specific $id

usm/mcp-search

Search .usm files (3 steps) — Agent searches for a term across all .usm files

usm/mcp-summary

Get file summary (3 steps) — Agent gets a quick summary of a .usm file

usm/mcp-validate

Validate by path (3 steps) — Agent validates an existing .usm file

usm/mcp-write

Draft and approve a feature spec (6 steps) — The spec-first loop the write tools exist for: the human and agent discuss a feature, the agent drafts and shows the markdown, and the human reviews before anything is written.
Update status pipeline (6 steps) — System pipeline behind update_feature_status: transition enforcement and atomic persistence.
Update fields pipeline (4 steps) — System pipeline behind update_feature: merge provided fields, validate, persist.

usm/schema-v1

Schema validation flow (4 steps) — A .usm file is validated against the v1 schema

Actors

Actor	Type
USM CLI	Package
USM MCP Server	Package

Business Capability Map

mermaid

graph TD
    subgraph "usm/cli"
        usm_cli_cli_color_output["cli-color-output"]
        usm_cli_cli_config_outputs["cli-config-outputs"]
        usm_cli_config_validation["config-validation"]
        usm_cli_docs_ia_restructure["docs-ia-restructure"]
        usm_cli_docs_serve_port_check["docs-serve-port-check"]
        usm_cli_cli_docs["cli-docs"]
        usm_cli_cli_enrich["cli-enrich"]
        usm_cli_cli_feedback["cli-feedback"]
        usm_cli_more["+40 more"]
    end
    subgraph "usm/mcp"
        usm_mcp_mcp_contracts["mcp-contracts"]
        usm_mcp_mcp_flows["mcp-flows"]
        usm_mcp_mcp_list["mcp-list"]
        usm_mcp_mcp_read["mcp-read"]
        usm_mcp_mcp_references["mcp-references"]
        usm_mcp_mcp_search["mcp-search"]
        usm_mcp_mcp_summary["mcp-summary"]
        usm_mcp_mcp_validate["mcp-validate"]
        usm_mcp_more["+1 more"]
    end

Business Architecture (TOGAF Phase B) ​

Features by Service ​

usm/cli ​

usm/mcp ​

User Flows ​

usm/cli-color-output ​

usm/cli-config-outputs ​

usm/config-validation ​

usm/docs-ia-restructure ​

usm/docs-serve-port-check ​

usm/cli-docs ​

usm/cli-enrich ​

usm/cli-generate ​

usm/cli-init ​

usm/internal-dsl-builder ​

usm/mcp-setup-guides ​

usm/cli-multi-lang-scan ​

usm/pkg-universal-docs ​

usm/query-layer ​

usm/cli-scaffold-project ​

usm/cli-scaffold ​

usm/cli-scan ​

usm/upgrade ​

usm/cli-validate ​

usm/vitepress-home-feedback-schema ​

usm/vitepress-schema-polish ​

usm/gen-agentsmd ​

usm/gen-archimate ​

usm/gen-content-blocks ​

usm/docs-experience ​

usm/gen-docs-split ​

usm/gen-feature-review ​

usm/feedback-upstream-routing ​

usm/gen-help-reference ​

usm/gen-markdown ​

usm/gen-mermaid ​

usm/mkt-language-tabs ​

usm/mkt-mock-interfaces ​

usm/gen-openapi ​

usm/opencode-integration ​

usm/gen-roadmap ​

usm/gen-rules-files ​

usm/gen-source-mapping ​

usm/structurizr-bridge ​

usm/gen-technical-design ​

usm/gen-testspecs ​

usm/gen-togaf ​

usm/gen-user-docs ​

usm/agent-feedback ​

usm/mcp-contracts ​

usm/mcp-flows ​

usm/mcp-list ​

usm/mcp-query ​

usm/mcp-read ​

usm/mcp-references ​

usm/mcp-search ​

usm/mcp-summary ​

usm/mcp-validate ​

usm/mcp-write ​

usm/schema-v1 ​

Actors ​

Business Capability Map ​

Business Architecture (TOGAF Phase B)

Features by Service

usm/cli

usm/mcp

User Flows

usm/cli-color-output

usm/cli-config-outputs

usm/config-validation

usm/docs-ia-restructure

usm/docs-serve-port-check

usm/cli-docs

usm/cli-enrich

usm/cli-generate

usm/cli-init

usm/internal-dsl-builder

usm/mcp-setup-guides

usm/cli-multi-lang-scan

usm/pkg-universal-docs

usm/query-layer

usm/cli-scaffold-project

usm/cli-scaffold

usm/cli-scan

usm/upgrade

usm/cli-validate

usm/vitepress-home-feedback-schema

usm/vitepress-schema-polish

usm/gen-agentsmd

usm/gen-archimate

usm/gen-content-blocks

usm/docs-experience

usm/gen-docs-split

usm/gen-feature-review

usm/feedback-upstream-routing

usm/gen-help-reference

usm/gen-markdown

usm/gen-mermaid

usm/mkt-language-tabs

usm/mkt-mock-interfaces

usm/gen-openapi

usm/opencode-integration

usm/gen-roadmap

usm/gen-rules-files

usm/gen-source-mapping

usm/structurizr-bridge

usm/gen-technical-design

usm/gen-testspecs

usm/gen-togaf

usm/gen-user-docs

usm/agent-feedback

usm/mcp-contracts

usm/mcp-flows

usm/mcp-list

usm/mcp-query

usm/mcp-read

usm/mcp-references

usm/mcp-search

usm/mcp-summary

usm/mcp-validate

usm/mcp-write

usm/schema-v1

Actors

Business Capability Map