Requirements
Functional Requirements
| Feature | Summary | Intent | Status |
|---|---|---|---|
| usm/cli-color-output | Comprehensive CLI polish for the USM CLI — colorized status output, animated spi | The CLI ships plain monochrome text with no progress feedback, flat file lists, | built |
| usm/cli-config-outputs | Configurable output paths in usmconfig.json and simplified command convention. G | Output paths are hardcoded to .usm-workspace/ in every generator. Users | |
| can't co | in-progress | ||
| usm/docs-serve-port-check | Add port availability checking, already-serving detection, watch mode for auto-r | usm docs serve currently has several gaps in the dev loop: (1) no port availab | built |
| usm/cli-docs | usm docs serve and usm docs build — serves generated docs locally via VitePress | The spec-first workflow requires a human to review generated feature docs | |
| before | planned | ||
| usm/cli-enrich | The usm enrich command fills in TODO: describe placeholders in .usm files using | Scanned .usm files contain TODO placeholders for summary, intent, decisions, flo | — |
| usm/cli-feedback | The usm feedback command configures the agent feedback policy in system.usm — in | The feedback policy governs how AI agents surface bugs and improvements. Teams n | built |
| usm/cli-generate | The usm generate command reads all .usm files and produces markdown, OpenAPI, Me | After scanning and enriching, generate produces all output artifacts from the .u | — |
| usm/cli-init | The usm init command analyzes the repo and generates a starter usmconfig.json. | New users need a config file that tells usm scan where to look. Init detects app | — |
| usm/internal-dsl-builder | Fluent typed TypeScript builder (internal DSL, per Fowler) that compiles to vali | Authoring flows/contracts/tests in raw YAML is verbose and error-prone for human | built |
| usm/mcp-setup-guides | Add per-editor MCP setup guides for all 35 MCP-ready editors as dedicated pages | Every USM user needs to connect their AI editor to the USM MCP server and, for e | built |
| usm/cli-multi-lang-scan | Multi-language scanner support, extended with a detector plugin system. usm scan | The .usm format, MCP tools, generators, and validator are all language-agnostic, | built |
| usm/query-layer | Predicate query language over .usm data — a tiny expression grammar (selectors, | Agents currently list everything or grep raw YAML to answer questions like "whic | built |
| usm/cli-scaffold-project | The usm scaffold-project command generates a starter .usm/ directory for single- | New projects need an initial .usm/ structure with system, service, and a starter | — |
| usm/cli-scaffold | The usm scaffold command creates a new .usm file with a template for system, ser | Users need a quick way to create a new .usm file with the correct structure. Sca | — |
| usm/cli-scan | The usm scan command reads usmconfig.json, scans the codebase, and generates .us | After init creates the config, scan detects the actual structure — services from | — |
| usm/upgrade | usm upgrade — detect stale USM projects and guide users through adopting new opt | There is no upgrade path today. Existing users who npm update USM get new code | built |
| usm/cli-validate | The usm validate command checks .usm files against the v1 JSON Schema and report | Users need to verify that their .usm files conform to the schema before generati | — |
| usm/vitepress-home-feedback-schema | Refine the VitePress docs homepage into a clean, scannable technical reference ( | The current docs homepage (from vitepress-schema-polish) is rich but marketing-h | built |
| usm/vitepress-schema-polish | Evolve the generated VitePress docs into an outstanding, adoption-accelerating s | The current docs are functional but plain: the homepage is a flat list, the side | built |
| usm/gen-agentsmd | AGENTS.md generator — produces AI agent context files with USM-augmented system | AI coding agents (Claude, Cursor, Codex) read AGENTS.md for project context. The | — |
| usm/gen-archimate | ArchiMate 3.1 generator — produces an Open Exchange XML model (XMI 2.1) from USM | Enterprise architecture teams use ArchiMate tools (Archi, BiZZdesign, Orbus iSer | — |
| usm/gen-content-blocks | First-principles redesign of the docs generator. Introduces a content-block sche | The docs generator has drifted from USM's first principle (structured source of | built |
| usm/docs-experience | Overhaul the generated docs site from a spec-dump into a real reading experience | Strategic review found the docs generators faithfully dump .usm content into Vit | built |
| usm/gen-docs-split | Split generated docs into help docs (public-facing, for visitors and new users) | Currently USM generates one combined doc set that serves both visitors and | |
| devel | built | ||
| usm/gen-feature-review | Review-quality feature markdown — restructures the feature markdown generator to | In the spec-first workflow, the agent writes a feature .usm spec, generates | |
| mark | planned | ||
| usm/feedback-upstream-routing | Scope-aware feedback routing — the generated feedback protocol, MCP tool, and do | Agents in downstream projects misattribute USM tool bugs to the project they are | built |
| usm/gen-help-reference | Help docs reference expansion — adds usage/options/prerequisites fields to featu | The help docs currently show feature specs (summary, intent, flows) but | |
| lack pra | in-progress | ||
| usm/gen-markdown | Markdown generator — produces GitHub-flavored markdown docs for each .usm file, | Markdown is the primary human-readable output. Each .usm file gets a per-file do | — |
| usm/gen-mermaid | Mermaid diagram generator — produces architecture, ER, sequence, and service-dep | Visual diagrams make the system structure immediately understandable. Mermaid di | — |
| usm/mkt-language-tabs | Marketing site language support section — clickable logo carousel showing 12 lan | The marketing site needs to communicate that USM scans 12 languages and 30+ | |
| fram | planned | ||
| usm/mkt-mock-interfaces-v2 | Update the mock interfaces to look like the real USM tooling — browser mock styl | Make the mocks instantly recognizable as real USM tooling by matching the actual | built |
| usm/mkt-mock-interfaces | Add two side-by-side animated mock interfaces below the "Works with your client" | Show visitors the spec-first workflow in action by animating two synced mock int | built |
| usm/gen-openapi | OpenAPI 3.1 generator — produces an openapi.yaml spec and TypeScript types from | API documentation must be machine-readable for SDK generation and testing. The O | — |
| usm/opencode-integration | First-class opencode support in the rules-files generator — emits a usm-workflow | Agents drift off the spec-first workflow in long sessions: AGENTS.md is loaded o | built |
| usm/gen-roadmap | Roadmap improvements — add feature links and shipped_in version to roadmap items | The roadmap page was empty because we treated it as "future plans only." A | |
| roadm | in-progress | ||
| usm/gen-rules-files | Tool-specific rules file generator with two-tier enforcement — detailed workflow | USM's distribution model is not a standalone app — it's an MCP server plus | |
| rules | built | ||
| usm/gen-source-mapping | Source mapping generator — reads all service and feature specs to build a bidire | USM specs already capture the file-to-feature relationship bidirectionally: feat | built |
| usm/structurizr-bridge | Structurizr bridge — import a Structurizr workspace JSON into .usm system and se | Teams already modelling in diagram-as-code (Structurizr/C4) face manual re-entry | built |
| usm/gen-technical-design | Technical Design Document generator — renders a 13-section detailed design docum | Every engineering team needs a detailed design document that ties the whole syst | built |
| usm/gen-testspecs | Vitest test specs generator — produces per-feature and aggregated Vitest test fi | Feature .usm files define flows and tests in a structured format. The test specs | — |
| usm/gen-togaf | TOGAF ADM generator — produces phase deliverables (A through H) from USM data fo | Organizations following TOGAF need phase-specific deliverables (Architecture Vis | — |
| usm/agent-feedback | Agent feedback protocol — teaches AI agents a consistent, configurable way to su | Agents using USM currently improvise when they discover issues — one agent auton | built |
| usm/mcp-contracts | MCP contracts tool — extracts the contracts array from a feature .usm file, incl | Agents need to review a feature's contracts to plan tests or verify guarantees. | — |
| usm/mcp-flows | MCP flows tool — extracts the flows array from a feature .usm file, including id | Agents need to understand user journeys described in feature files. The flows to | — |
| usm/mcp-list | MCP list tool — lists all .usm files in a directory or monorepo with id, type, v | AI agents need to discover what .usm files exist before reading them. The list t | — |
| usm/mcp-query | usm_query MCP tool — predicate query over all .usm files. Selectors (features/se | Agents answering questions like "which planned features have no contracts?" or " | built |
| usm/mcp-read | MCP read tool — reads and parses a .usm file, returning the full object plus met | Agents need to read the full content of a specific .usm file to understand a ser | — |
| usm/mcp-references | MCP references tool — finds all .usm files that reference a target $id, useful f | Before modifying a service or feature, agents need to know what else depends on | — |
| usm/mcp-search | MCP search tool — searches all .usm files for a query string, returning matching | Agents need to find .usm files related to a concept (e.g. "authentication", "bil | — |
| usm/mcp-summary | MCP summary tool — returns a quick summary of a .usm file with id, type, version | Agents need a lightweight overview of a .usm file without reading the full conte | — |
| usm/mcp-validate | MCP validate tool — validates a .usm file by path or inline YAML content against | Agents modifying .usm files need to validate their changes before writing. The v | — |
| usm/mcp-write | MCP write tools — let agents author and update .usm feature specs as part of the | The current MCP server is read-only — agents can list, read, search, and query | |
| e | built | ||
| usm/schema-v1 | The v1 JSON Schema — the validation contract for all .usm files, defining system | The v1.json schema is the single source of truth for what constitutes a valid .u | — |