USM

Appearance

USMStructured source of truth for agentic systems

Universal System Map — a structured source of truth for agentic systems. A single .usm/ directory describes apps, services, features, flows, contracts, and deci

Get Started
Schema Reference
GitHub

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.

Version 0.5.1 · Generated 2026-08-14

This site is fully generated from .usm files. Edit the source of truth, not the markdown.

Quick Start ​

bash
npm install -g @smithgray/[email protected]
cd your-project
usm init          # Creates usmconfig.json
usm scan          # Detects services, routes, data models
usm generate      # Produces docs, Mermaid, OpenAPI, AGENTS.md
usm docs serve    # Preview at http://localhost:5173

At a glance ​

MetricValue
Features37 (29 built)
Packages2

Explore ​

SectionDescription
Getting StartedInstall, init, scan, generate — first-run walkthrough
Schema ReferenceField-by-field reference for every .usm type
CLI ReferenceEvery usm command and flag
MCP ToolsAgent tools for the spec-first workflow
Agent Setup GuideWire USM into Cursor, Claude, Copilot
RoadmapWhat's shipping next

Spec-first workflow ​

mermaid
flowchart LR
  A[Discuss feature] --> B[Draft .usm via MCP]
  B --> C[Human reviews markdown]
  C --> D[Write + validate .usm]
  D --> E[Implement in code]
  E --> F[usm generate]
  F --> G[Docs · Mermaid · OpenAPI · AGENTS.md]
  G --> H[Mark feature built]

A real feature from this project: Init Command (.usm/features/cli/init.usm).

yaml
$schema: https://usm.dev/schema/v1.json
$id: usm/cli-init
$type: feature
$version: 1
$last_updated: "2026-06-19"
summary: The usm init command analyzes the repo and generates a starter usmconfig.json.

$system: usm/system
$service: usm/cli
command: init
intent: |
  New users need a config file that tells usm scan where to look. Init detects apps, packages, Prisma schemas, and Docker Compose services from the repo structure and writes a usmconfig.json so the next scan can work immediately.

flows:
  - id: run-init
    name: Run usm init
    description: User runs usm init in the repo root to generate a usmconfig.json
    steps:
      - id: s1
        action: setup
        target: repo root directory
      - id: s2
        action: parse
        target: apps/* and packages/* directories for package.json
      - id: s3
        action: parse
        target: prisma schema files
      - id: s4
# … truncated
bash
usm generate
# → markdown docs (this site)
# → Mermaid diagrams
# → OpenAPI / ArchiMate / TOGAF (when present)
# → AGENTS.md + rules files for Cursor / Claude / Copilot
# → Vitest specs from contracts + tests

Using USM in production?

Visit usm.dev for the full story, language support, and community links.

Identity ​

FieldValue
NameUSM
Domainusm.dev
Contact[email protected]
Repositoryhttps://github.com/Smith-Gray-Pty-Ltd/usm

Who it's for ​

  • Human Developer — Reviews feature specs before approving implementation. Discusses features
  • AI Agent — Reads .usm files via MCP tools to understand system context before
  • New Visitor — Finds USM on GitHub or npm and visits usm.dev to evaluate whether to use
  • Team Member — Joins a project that uses USM and needs to understand the system
  • Technical Lead — Reviews system design, tracks risks and roadmap, ensures architectural

Next steps ​

Go hereIf you want to…
Getting StartedInstall USM and run your first init → scan → generate
Schema ReferenceUnderstand every field in a .usm file
CLI ReferenceSee every usm command and flag
MCP ToolsWire agents into the spec-first loop
Agent Setup GuideConnect Cursor / Claude / Copilot

Contribute

Source of truth: .usm/ on GitHub. Edit the specs, not the generated markdown.