Architecture Vision (TOGAF Phase A)
Auto-generated from USM. Source:
.usm/system.usm
System Identity
| Field | Value |
|---|---|
| Name | USM |
| Domain | usm.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
| ID | Title | Status | Target Date |
|---|---|---|---|
| vitepress-docs | VitePress docs integration | shipped | 2026-06-22 |
| review-quality-markdown | Review-quality feature markdown | shipped | 2026-06-22 |
| empty-section-suppression | Suppress empty sections in generated docs | shipped | 2026-06-22 |
| roles-schema | Roles field in system schema | shipped | 2026-06-22 |
| adr-schema-enrichment | ADR schema enrichment | shipped | 2026-06-22 |
| roadmap-improvements | Roadmap with feature links and delivery tracking | in-progress | — |
| agent-authoring-tools | MCP write tools | shipped | — |
| rules-file-generation | Tool-specific rules files | shipped | — |
| marketing-site | Marketing site | planned | — |
Feature Index
| ID | Name | Status | Tags |
|---|---|---|---|
| cli-init | Init Command | active | cli, config |
| cli-scan | Scan Command | active | cli, scanner |
| cli-validate | Validate Command | active | cli, schema |
| cli-generate | Generate Command | active | cli, docs |
| cli-enrich | Enrich Command | active | cli, llm |
| cli-scaffold | Scaffold Command | active | cli, templates |
| cli-scaffold-project | Scaffold Project Command | active | cli, project-setup |
| cli-docs | Docs Serve & Build | planned | cli, docs, vitepress, dev-server |
| gen-markdown | Markdown Generator | active | generator, docs |
| gen-mermaid | Mermaid Generator | active | generator, diagrams |
| gen-openapi | OpenAPI Generator | active | generator, api |
| gen-archimate | ArchiMate Generator | active | generator, enterprise-arch |
| gen-togaf | TOGAF Generator | active | generator, enterprise-arch |
| gen-agentsmd | AGENTS.md Generator | active | generator, agent-context |
| gen-testspecs | Test Specs Generator | active | generator, testing |
| gen-feature-review | Feature Review Markdown Generator | planned | generator, markdown, spec-first |
| gen-rules-files | Rules Files Generator | built | generator, agent-rules, plugin |
| gen-roadmap | Roadmap Generator | in-progress | generator, roadmap, schema |
| gen-docs-split | Docs Split (Help vs Developer) | built | generator, docs, audience |
| gen-help-reference | Help Docs Reference Expansion | built | generator, docs, reference, schema |
| cli-config-outputs | Configurable Outputs + Command Convention | built | cli, config, commands |
| cli-multi-lang-scan | Multi-Language Scanner Support | planned | cli, scanner, multi-language, python, go, rust |
| mkt-language-tabs | Marketing Language Tabs | planned | marketing, website, languages, tabs |
| mcp-list | MCP List Tool | active | mcp, discovery |
| mcp-read | MCP Read Tool | active | mcp, data |
| mcp-search | MCP Search Tool | active | mcp, search |
| mcp-validate | MCP Validate Tool | active | mcp, schema |
| mcp-contracts | MCP Contracts Tool | active | mcp, contracts |
| mcp-flows | MCP Flows Tool | active | mcp, flows |
| mcp-references | MCP References Tool | active | mcp, impact-analysis |
| mcp-summary | MCP Summary Tool | active | mcp, overview |
| mcp-write | MCP Write Tools | built | mcp, authoring, spec-first |
| agent-feedback | Agent Feedback Protocol | planned | mcp, agents, feedback, policy, schema, cross-cutting |
| upgrade | Project Upgrade | planned | cli, upgrade, capabilities, versioning |
| vitepress-schema-polish | VitePress Docs + Schema Polish | in-progress | docs, vitepress, schema, help-docs, generators |
| schema-v1 | V1 JSON Schema | active | schema, validation |
| data-usmconfig | USM Config Shape | active | config, data |
Services Overview
graph TD
subgraph "Packages"
cli["USM CLI"]
mcp["USM MCP Server"]
end