USM

Appearance

Architecture Vision (TOGAF Phase A) ​

Auto-generated from USM. Source: .usm/system.usm

System Identity ​

FieldValue
NameUSM
Domainusm.dev
Contact[email protected]

Summary ​

Universal System Map — a structured source of truth for agentic systems. A single .usm/ directory describes apps, services, features, flows, contracts, and decisions in YAML validated by a JSON Schema, and generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.

Architecture Principles ​

Structured Source of Truth (structured-source-of-truth) ​

Statement: Every system artifact is captured in YAML validated by a JSON Schema — no scattered, stale docs.

Rationale: Agents and humans need a single, machine-checkable source. Free-form docs drift; schema-validated YAML stays consistent.

Implications:

  • All system descriptions must live in .usm/ YAML files

  • The v1 JSON Schema is the contract — no undocumented fields

Agent First (agent-first) ​

Statement: USM files are designed for AI agent consumption via MCP tools before human readability.

Rationale: The MCP server exposes 12 tools (8 read + 4 write) that let agents navigate, search, reference, and author USM data without reading raw YAML.

Implications:

  • Every .usm field must be parseable and queryable by agents

  • The MCP server must stay in sync with the schema

Idempotent Generation (idempotent-generation) ​

Statement: Scan and generate are safe to run repeatedly; smart-merge preserves human edits.

Rationale: Re-running usm scan or usm generate should never destroy hand-written content. The smart-merge strategy preserves human-edited fields and updates mechanical ones.

Implications:

  • Smart-merge distinguishes human-edited from scan-derived fields

  • --force bypasses merge for intentional overwrite

One Source, Many Outputs (one-source-many-outputs) ​

Statement: A single .usm/ directory generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.

Rationale: Maintaining 6+ doc formats independently is unsustainable. Derive all from one source so they stay in sync.

Implications:

  • Generators must read .usm files — never write docs from other docs

  • Each generator is independent and composable

Roadmap ​

IDTitleStatusTarget Date
vitepress-docsVitePress docs integrationshipped2026-06-22
review-quality-markdownReview-quality feature markdownshipped2026-06-22
empty-section-suppressionSuppress empty sections in generated docsshipped2026-06-22
roles-schemaRoles field in system schemashipped2026-06-22
adr-schema-enrichmentADR schema enrichmentshipped2026-06-22
roadmap-improvementsRoadmap with feature links and delivery trackingshipped—
config-outputsConfigurable output pathsshipped—
help-reference-expansionHelp docs reference expansionshipped—
agent-authoring-toolsMCP write toolsshipped—
rules-file-generationTool-specific rules filesshipped—
marketing-siteMarketing siteplanned—
user-docs-compositionUser docs composed from personas and journeysshipped—
rules-files-generatorTool-specific rules files generatorshipped—
docs-split-generatorHelp vs developer docs splitshipped—
help-reference-generatorHelp docs reference expansionshipped—
mcp-write-toolsMCP write tools (spec authoring)shipped—
consumer-blocker-fixesConsumer integration fixes (config validation, CI gate, help docs, MCP merge)shipped—
package-universal-docsUniversal onboarding docs shipped in the npm packageshipped—
docs-ia-restructureDocs sidebar information architecture restructurein-progress—
help-docs-filter-deprecationDeprecate subtraction-based help docs for feature pagesin-progress—

Feature Index ​

IDNameStatusTags
cli-initInit Commandactivecli, config
cli-scanScan Commandactivecli, scanner
cli-validateValidate Commandactivecli, schema
cli-generateGenerate Commandactivecli, docs
cli-enrichEnrich Commandactivecli, llm
cli-scaffoldScaffold Commandactivecli, templates
cli-scaffold-projectScaffold Project Commandactivecli, project-setup
cli-docsDocs Serve & Buildplannedcli, docs, vitepress, dev-server
gen-markdownMarkdown Generatoractivegenerator, docs
gen-mermaidMermaid Generatoractivegenerator, diagrams
gen-openapiOpenAPI Generatoractivegenerator, api
gen-archimateArchiMate Generatoractivegenerator, enterprise-arch
gen-togafTOGAF Generatoractivegenerator, enterprise-arch
gen-agentsmdAGENTS.md Generatoractivegenerator, agent-context
gen-testspecsTest Specs Generatoractivegenerator, testing
gen-feature-reviewFeature Review Markdown Generatorplannedgenerator, markdown, spec-first
gen-rules-filesRules Files Generatorbuiltgenerator, agent-rules, plugin
gen-roadmapRoadmap Generatorin-progressgenerator, roadmap, schema
gen-user-docsUser Docs Composition (Personas & Journeys)in-progressgenerator, personas, user-docs, e2e
gen-docs-splitDocs Split (Help vs Developer)builtgenerator, docs, audience
gen-help-referenceHelp Docs Reference Expansionbuiltgenerator, docs, reference, schema
cli-config-outputsConfigurable Outputs + Command Conventionbuiltcli, config, commands
cli-multi-lang-scanMulti-Language Scanner Supportplannedcli, scanner, multi-language, python, go, rust
mkt-language-tabsMarketing Language Tabsplannedmarketing, website, languages, tabs
mcp-listMCP List Toolactivemcp, discovery
mcp-readMCP Read Toolactivemcp, data
mcp-searchMCP Search Toolactivemcp, search
mcp-validateMCP Validate Toolactivemcp, schema
mcp-contractsMCP Contracts Toolactivemcp, contracts
mcp-flowsMCP Flows Toolactivemcp, flows
mcp-referencesMCP References Toolactivemcp, impact-analysis
mcp-summaryMCP Summary Toolactivemcp, overview
mcp-writeMCP Write Toolsbuiltmcp, authoring, spec-first
agent-feedbackAgent Feedback Protocolplannedmcp, agents, feedback, policy, schema, cross-cutting
upgradeProject Upgradeplannedcli, upgrade, capabilities, versioning
vitepress-schema-polishVitePress Docs + Schema Polishin-progressdocs, vitepress, schema, help-docs, generators
schema-v1V1 JSON Schemaactiveschema, validation
data-usmconfigUSM Config Shapeactiveconfig, data

Services Overview ​

mermaid
graph TD
    subgraph "Packages"
        cli["USM CLI"]
        mcp["USM MCP Server"]
    end