USM

Appearance

Getting Started ​

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.

Quick Start ​

bash
# Install USM globally
npm install -g @~usm/core

# Initialize a .usm/ scope in your project
usm init

# Scan your codebase for structure
usm scan

# Generate docs (markdown, Mermaid, OpenAPI, etc.)
usm generate

# Serve docs locally with VitePress
usm docs serve

# Start the MCP server for AI agents
usm mcp serve

Example ​

Here's a feature spec from this project (.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
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
        action: generate
        target: usmconfig.json with services, shared, data, outputs sections

contracts:
  - id: init-creates-config
    description: usm init must create a valid usmconfig.json at the specified output path
    must_have:
      - "Config has version: '1'"
      - "Config has name, services, shared, data, sources, outputs fields"
      - "Config does not overwrite unless --force is passed"

tests:
  - id: init-default
# ... (truncated)

Run usm generate to produce markdown, Mermaid diagrams, OpenAPI specs, and test specs from this file. Run usm docs serve to view the rendered docs.

Who Uses This System ​

  • 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 ​