USM
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.
Identity
| Field | Value |
|---|---|
| Name | USM |
| Domain | usm.dev |
| Contact | [email protected] |
Quick Stats
| Metric | Value |
|---|---|
| App Services | 0 |
| Shared Services | 0 |
| Packages | 2 |
| Features | 32 |
| Risks | 0 |
| Roadmap Items | 9 |
Packages
Platform-Level
Architecture Principles
TOGAF-style principles that govern all architecture decisions.
1. 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
2. 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
3. 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
4. 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
Roles
Who uses this system and what they need.
Human Developer
Reviews feature specs before approving implementation. Discusses features with an AI agent, reviews the generated markdown, and approves or requests changes before the agent builds.
Needs:
- Readable feature specs with clear intent, flows, and contracts
- Checklist-format acceptance criteria for quick review
- Given/When/Then test format to verify coverage
AI Agent
Reads .usm files via MCP tools to understand system context before implementing features. Drafts feature specs from human discussion.
Needs:
- MCP tools to query system structure without reading raw YAML
- Write tools to draft and update feature specs
- Rules files that teach the spec-first workflow
New Visitor
Finds USM on GitHub or npm and visits usm.dev to evaluate whether to use it in their project.
Needs:
- Clear value proposition and workflow description
- Quick start guide
- Example feature specs
Team Member
Joins a project that uses USM and needs to understand the system architecture, services, and feature inventory.
Needs:
- System overview with architecture diagram
- Service descriptions with links to features
- Local development setup guide
Technical Lead
Reviews system design, tracks risks and roadmap, ensures architectural consistency across features.
Needs:
- Cross-cutting views — decisions, risks, roadmap
- Architecture diagrams
- Feature status overview (planned vs built)