Project Overview
Project Name: USM
Domain: usm.dev
Repository: https://github.com/Smith-Gray-Pty-Ltd/usm
Project Description
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.
Stakeholders
| Name | Description | Needs |
|---|---|---|
| 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. | ||
| 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. | ||
| 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. | ||
| 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. | ||
| 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. | ||
| Cross-cutting views — decisions, risks, roadmap; Architecture diagrams; Feature status overview (planned vs built) |
Use-cases
Core features and capabilities of the system:
| Feature | Name | Status |
|---|---|---|
| cli-init | Init Command | active |
| cli-scan | Scan Command | active |
| cli-validate | Validate Command | active |
| cli-generate | Generate Command | active |
| cli-enrich | Enrich Command | active |
| cli-scaffold | Scaffold Command | active |
| cli-scaffold-project | Scaffold Project Command | active |
| cli-docs | Docs Serve & Build | planned |
| gen-markdown | Markdown Generator | active |
| gen-mermaid | Mermaid Generator | active |
| gen-openapi | OpenAPI Generator | active |
| gen-archimate | ArchiMate Generator | active |
| gen-togaf | TOGAF Generator | active |
| gen-agentsmd | AGENTS.md Generator | active |
| gen-testspecs | Test Specs Generator | active |
| gen-feature-review | Feature Review Markdown Generator | planned |
| gen-rules-files | Rules Files Generator | built |
| gen-roadmap | Roadmap Generator | in-progress |
| gen-docs-split | Docs Split (Help vs Developer) | built |
| gen-help-reference | Help Docs Reference Expansion | built |
| cli-config-outputs | Configurable Outputs + Command Convention | built |
| cli-multi-lang-scan | Multi-Language Scanner Support | planned |
| mkt-language-tabs | Marketing Language Tabs | planned |
| mcp-list | MCP List Tool | active |
| mcp-read | MCP Read Tool | active |
| mcp-search | MCP Search Tool | active |
| mcp-validate | MCP Validate Tool | active |
| mcp-contracts | MCP Contracts Tool | active |
| mcp-flows | MCP Flows Tool | active |
| mcp-references | MCP References Tool | active |
| mcp-summary | MCP Summary Tool | active |
| mcp-write | MCP Write Tools | built |
| agent-feedback | Agent Feedback Protocol | planned |
| upgrade | Project Upgrade | planned |
| vitepress-schema-polish | VitePress Docs + Schema Polish | in-progress |
| schema-v1 | V1 JSON Schema | active |
| data-usmconfig | USM Config Shape | active |