Skip to content

Business Architecture (TOGAF Phase B)

Auto-generated from USM features and system.usm.

Features by Service

usm/cli

FeatureSummaryStatusFlowsContracts
usm/cli-config-outputsConfigurable output paths in usmconfig.json and simplified command convention. Gin-progress23
usm/docs-serve-port-checkAdd port availability checking, already-serving detection, watch mode for auto-rbuilt46
usm/cli-docsusm docs serve and usm docs build — serves generated docs locally via VitePressplanned46
usm/cli-enrichThe usm enrich command fills in TODO: describe placeholders in .usm files using11
usm/cli-feedbackThe usm feedback command configures the agent feedback policy in system.usm — inbuilt00
usm/cli-generateThe usm generate command reads all .usm files and produces markdown, OpenAPI, Me11
usm/cli-initThe usm init command analyzes the repo and generates a starter usmconfig.json.11
usm/internal-dsl-builderFluent typed TypeScript builder (internal DSL, per Fowler) that compiles to valibuilt34
usm/cli-multi-lang-scanMulti-language scanner support — extend usm scan to detect services, routes, andplanned135
usm/query-layerPredicate query language over .usm data — a tiny expression grammar (selectors,built34
usm/cli-scaffold-projectThe usm scaffold-project command generates a starter .usm/ directory for single-11
usm/cli-scaffoldThe usm scaffold command creates a new .usm file with a template for system, ser11
usm/cli-scanThe usm scan command reads usmconfig.json, scans the codebase, and generates .us11
usm/upgradeusm upgrade — detect stale USM projects and guide users through adopting new optbuilt35
usm/cli-validateThe usm validate command checks .usm files against the v1 JSON Schema and report11
usm/vitepress-home-feedback-schemaRefine the VitePress docs homepage into a clean, scannable technical reference (built44
usm/vitepress-schema-polishEvolve the generated VitePress docs into an outstanding, adoption-accelerating sbuilt56
usm/gen-agentsmdAGENTS.md generator — produces AI agent context files with USM-augmented system11
usm/gen-archimateArchiMate 3.1 generator — produces an Open Exchange XML model (XMI 2.1) from USM11
usm/docs-experienceOverhaul the generated docs site from a spec-dump into a real reading experiencein-progress66
usm/gen-docs-splitSplit generated docs into help docs (public-facing, for visitors and new users)built24
usm/gen-feature-reviewReview-quality feature markdown — restructures the feature markdown generator toplanned43
usm/feedback-upstream-routingScope-aware feedback routing — the generated feedback protocol, MCP tool, and dobuilt44
usm/gen-help-referenceHelp docs reference expansion — adds usage/options/prerequisites fields to featuin-progress44
usm/gen-markdownMarkdown generator — produces GitHub-flavored markdown docs for each .usm file,11
usm/gen-mermaidMermaid diagram generator — produces architecture, ER, sequence, and service-dep11
usm/mkt-language-tabsMarketing site language support section — clickable logo carousel showing 12 lanplanned25
usm/gen-openapiOpenAPI 3.1 generator — produces an openapi.yaml spec and TypeScript types from11
usm/opencode-integrationFirst-class opencode support in the rules-files generator — emits a usm-workflowbuilt34
usm/gen-roadmapRoadmap improvements — add feature links and shipped_in version to roadmap itemsin-progress44
usm/gen-rules-filesTool-specific rules file generator with two-tier enforcement — detailed workflowbuilt42
usm/structurizr-bridgeStructurizr bridge — import a Structurizr workspace JSON into .usm system and sebuilt34
usm/gen-testspecsVitest test specs generator — produces per-feature and aggregated Vitest test fi11
usm/gen-togafTOGAF ADM generator — produces phase deliverables (A through H) from USM data fo11
usm/agent-feedbackAgent feedback protocol — teaches AI agents a consistent, configurable way to subuilt45
usm/mcp-queryusm_query MCP tool — predicate query over all .usm files. Selectors (features/sebuilt12
usm/schema-v1The v1 JSON Schema — the validation contract for all .usm files, defining system12

usm/mcp

FeatureSummaryStatusFlowsContracts
usm/mcp-contractsMCP contracts tool — extracts the contracts array from a feature .usm file, incl11
usm/mcp-flowsMCP flows tool — extracts the flows array from a feature .usm file, including id11
usm/mcp-listMCP list tool — lists all .usm files in a directory or monorepo with id, type, v11
usm/mcp-readMCP read tool — reads and parses a .usm file, returning the full object plus met11
usm/mcp-referencesMCP references tool — finds all .usm files that reference a target $id, useful f11
usm/mcp-searchMCP search tool — searches all .usm files for a query string, returning matching11
usm/mcp-summaryMCP summary tool — returns a quick summary of a .usm file with id, type, version11
usm/mcp-validateMCP validate tool — validates a .usm file by path or inline YAML content against11
usm/mcp-writeMCP write tools — let agents author and update .usm feature specs as part of thebuilt34

User Flows

usm/cli-config-outputs

  • Resolve output paths from usmconfig.json (4 steps) — A shared utility reads usmconfig.json and returns the configured output path for each type (docs, help-docs, archimate, togaf, openapi, tests). Falls back to defaults if not configured or config missing.

  • Generate with --only flag (4 steps) — usm generate runs all generators. usm generate --only <target> runs only the specified output. Valid targets: docs, help-docs, togaf, archimate, openapi, tests, rules, agents-md.

usm/docs-serve-port-check

  • Pre-flight port availability check (6 steps) — Before spawning VitePress, probe the target port. If in use, either fail with a clear message or auto-select the next free port.

  • Detect already-running server (6 steps) — Before starting, check if a VitePress server is already running on the target port. If it is, offer to reuse it or kill and restart.

  • Watch mode for auto-regeneration (6 steps) — Add --watch flag that watches .usm/ files and re-runs usm generate before VitePress picks up the changes, keeping docs always in sync.

  • Quality-of-life improvements (4 steps) — Graceful shutdown, browser-open, and status command.

usm/cli-docs

  • Start docs dev server (7 steps) — User runs usm docs serve. USM generates markdown from .usm files into docs/, generates VitePress config (sidebar, nav) from system.usm index, starts VitePress dev server with hot reload. When .usm files change, affected markdown regenerates and VitePress HMR updates the browser.

  • Build static docs site (4 steps) — User runs usm docs build. USM generates markdown + VitePress config, then runs vitepress build to produce a static site in docs/.vitepress/dist/ ready for Cloudflare Pages or any static host.

  • Generate VitePress sidebar and nav config (5 steps) — Generate .vitepress/config.ts from system.usm index and feature directory structure. Sidebar groups mirror .usm/features/ subdirectories. Feature status shown as badge in nav. Services listed from system.usm services[].

  • Generate docs into unified docs/ directory (6 steps) — The generate command writes all output to a single docs/ directory with a clear hierarchy: services/, features/<area>/, architecture/, cross-cutting (risks, roadmap, decisions). This replaces the current scattered output across .agents-workspace/docs/ and apps/*/.agents-workspace/docs/.

usm/cli-enrich

  • Enrich a single .usm file (5 steps) — User enriches one file with LLM-generated content

usm/cli-generate

  • Run usm generate (7 steps) — User runs usm generate to produce all documentation

usm/cli-init

  • Run usm init (4 steps) — User runs usm init in the repo root to generate a usmconfig.json

usm/internal-dsl-builder

  • Compose a feature spec with the builder (3 steps)

  • Write a built spec to disk (2 steps)

  • Extend an existing spec (3 steps)

usm/cli-multi-lang-scan

  • Detect services from multiple language manifests (5 steps) — Scanner reads usmconfig.json detection.manifests (or defaults) and checks for manifest files. Each manifest identifies a service and its language. Framework is detected from dependencies in the manifest.

  • Detect Python routes (FastAPI, Flask, Django) (4 steps) — Scan .py files for decorator-based routes. FastAPI uses @app.get/@router.get, Flask uses @app.route, Django uses urlpatterns in urls.py.

  • Detect Go routes (chi, gin, echo, net/http) (4 steps) — Scan .go files for router registration patterns. chi/gin/echo use r.GET/r.POST, net/http uses http.HandleFunc, gorilla/mux uses r.HandleFunc.

  • Detect Rust routes (Axum, Actix, Rocket) (4 steps) — Scan .rs files for route patterns. Axum uses .route(), Actix uses #[get(...)] macros, Rocket uses #[get("/path")] attributes.

  • Detect Java/Kotlin routes (Spring Boot, Javalin, Quarkus) (4 steps) — Scan .java/.kt files for annotation-based routes. Spring uses @GetMapping/@PostMapping/@RequestMapping, Javalin uses app.get/post, Quarkus uses @Path + @GET/@POST.

  • Detect C# routes (ASP.NET Core, Minimal APIs) (4 steps) — Scan .cs files for attribute-based routes. ASP.NET uses [HttpGet], [HttpPost], [Route], Minimal APIs use app.MapGet/MapPost.

  • Detect Ruby routes (Rails, Sinatra) (4 steps) — Scan config/routes.rb for Rails routes (get/post/resources) and .rb files for Sinatra routes (get '/path' do).

  • Detect PHP routes (Laravel, Symfony, Slim) (4 steps) — Scan routes/web.php for Laravel routes (Route::get/post), .php files for Symfony attributes (#[Route]) and Slim ($app->get/post).

  • Detect Elixir routes (Phoenix) (4 steps) — Scan router.ex for Phoenix routes (get/post/pipe_through/scope).

  • Detect Swift routes (Vapor) (4 steps) — Scan .swift files for Vapor route registrations (routes.get/post, app.get/post).

  • Detect Scala routes (Akka HTTP, Play, Tapir) (4 steps) — Scan .scala files for route patterns. Akka HTTP uses path/endpoints, Play uses routes file, Tapir uses endpoint.get/post.

  • Detect C++ routes (Crow, Drogon, Pistache) (4 steps) — Scan .cpp/.h files for route registration patterns. Crow uses CROW_ROUTE, Drogon uses app.registerHandler, Pistache uses router.get/post.

  • Detect data models from multiple ORMs across languages (3 steps) — Extend data model detection beyond Prisma to support ORMs across all supported languages.

usm/query-layer

  • Run a query from the CLI (4 steps)

  • Run a query via the usm_query MCP tool (3 steps)

  • Compose predicates (3 steps)

usm/cli-scaffold-project

  • Scaffold single-app project (4 steps) — User creates .usm/ for a single application

usm/cli-scaffold

  • Scaffold a .usm file (3 steps) — User creates a new .usm file from a template

usm/cli-scan

  • Run usm scan (5 steps) — User runs usm scan to generate .usm files from the codebase

usm/upgrade

  • Detect project version and missing capabilities (5 steps) — Read the installed USM version and the project's system.usm.version, walk the capability registry, and produce a status report.

  • Set up missing capabilities (4 steps) — For each missing capability, either prompt interactively (TTY) or apply defaults (--apply), calling the capability's own setup function.

  • Bump project version after applying (3 steps) — After capabilities are applied, set system.usm.version to the installed version, validate, and suggest regenerating outputs.

usm/cli-validate

  • Run usm validate (4 steps) — User runs usm validate on one or more .usm files

usm/vitepress-home-feedback-schema

  • Simplify homepage to technical reference (8 steps) — Strip marketing-heavy content from the VitePress homepage. Keep it a clean, scannable reference that links to usm.dev for marketing.

  • Add dual-mode Feedback / Report Issue button (6 steps) — Add a visible feedback mechanism to the VitePress docs site. Supports two modes: human (pre-filled GitHub issue) and agent (MCP tool with structured context).

  • Stronger cross-links and CTAs (4 steps) — Add consistent next-steps sections, cross-links between related pages, and clear CTAs throughout the docs.

  • General VitePress polish (5 steps) — Better use of VitePress callouts, tables, and diagrams. Ensure dark mode, mobile, and search work well.

usm/vitepress-schema-polish

  • Comprehensive schema reference (HIGHEST PRIORITY) (5 steps) — Rebuild generateSchemaReference to produce a deep, scannable, field-by-field reference for every major type, sourced from schema/v1.json + enriched descriptions.

  • Rich, data-driven homepage (5 steps) — Replace the flat-list README with a showcase homepage generated from system.usm.

  • Upgrade Getting Started (4 steps) — Make first-run smooth and visual.

  • Restructure sidebar navigation (3 steps) — Regroup the auto-generated sidebar to match how users explore.

  • Visuals + general polish (4 steps) — Dark-mode-aware diagrams, callouts, tables, typography, mobile, badges, CTAs.

usm/gen-agentsmd

  • Generate AGENTS.md (3 steps) — Augment AGENTS.md with USM content using smart merge

usm/gen-archimate

  • Generate ArchiMate model (4 steps) — Produce model.xml with ArchiMate elements and relationships

usm/docs-experience

  • Suppress templated stubs a service has no data for (3 steps) — A service only emits the architecture/ui/deployment/operations/decisions pages its .usm actually populates. A CLI gets no UI map or production-deployment page.

  • Surface the real TOGAF deliverables as the Architecture section (3 steps) — The togaf generator already produces Phase A-H deliverables; wire them into the dev-docs sidebar as a real Architecture section instead of empty per-service architecture stubs.

  • Widen the layout to use the viewport (2 steps) — Override VitePress defaults so reference content, tables, code, and diagrams breathe.

  • Rebuild the homepage as navigation (3 steps) — Drop the README-style metrics/identity dump; keep the hero and add a features grid whose cards ARE the navigation into the docs.

  • Give help and technical audiences distinct voices (3 steps) — The same feature spec renders differently per audience — task-oriented for help, reference-faithful for technical.

  • Anti-drift and discoverability (2 steps) — Pin the getting-started version from package.json and enable VitePress sitemap on both sites.

usm/gen-docs-split

  • Generate both help and developer docs (6 steps) — usm generate produces full docs in .usm-workspace/docs/ (developer). usm docs build --audience help copies and filters into .usm-workspace/help-docs/ with simplified content and a public-oriented sidebar.

  • Serve help docs locally (4 steps) — usm docs serve --audience help serves the filtered help docs on a local VitePress dev server for review.

usm/gen-feature-review

  • Generate review-quality markdown from feature .usm (3 steps) — When a feature .usm is generated, produce a review.md alongside overview.md that frames the spec for human approval.

  • Render flows as numbered procedural steps (3 steps) — Convert the flows[] array into readable numbered steps grouped by flow, with each step's action and target combined into a sentence.

  • Render contracts as acceptance checklist (3 steps) — Convert the contracts[] array into a markdown checklist under each contract description.

  • Render tests in given/when/then format (3 steps) — Convert the tests[] array into given/when/then blocks for readability.

usm/feedback-upstream-routing

  • Agent classifies a bug by blast radius (3 steps) — When an agent discovers a bug, it first determines whether the fault is in the project or in the USM tool itself.

  • Route a USM tool bug upstream (4 steps) — USM tool bugs are drafted and filed against the upstream tracker with version and environment context.

  • Render the scope-aware protocol everywhere (3 steps) — The Where does the bug live? guidance is emitted into every agent-facing surface from one code path.

  • MCP tool carries the distinction (2 steps) — usm_report_feedback surfaces the scope question at the tool boundary.

usm/gen-help-reference

  • Generate CLI reference page from feature specs (4 steps) — Scan all CLI feature specs for usage/options/prerequisites fields and generate a single cli-reference.md page with command examples, flag tables, and prerequisites for each command.

  • Generate usmconfig reference from JSON schema (4 steps) — Read usmconfig-v1.json and generate a config-reference.md page with field descriptions, types, defaults, and examples.

  • Generate .usm schema reference from v1.json (4 steps) — Read v1.json and generate a schema-reference.md page showing all fields for each .usm file type (system, service, feature, data).

  • Generate MCP tools reference page (4 steps) — Consolidate all MCP tool feature specs into a single mcp-reference.md with a table of all 12 tools, their inputs, and when to use each.

usm/gen-markdown

  • Generate per-file markdown (3 steps) — Generate an overview.md for each service and feature .usm file

usm/gen-mermaid

  • Generate architecture diagram (3 steps) — Produce a C4-style architecture diagram from system + service .usm files

usm/mkt-language-tabs

  • Render logo carousel on marketing site (5 steps) — Between Token Comparison and Tool Logos sections. 12 language logos in a horizontal row. Default: TypeScript selected. Click a logo to reveal frameworks + route detection code example.

  • Render full language grid in help docs (3 steps) — New page in help docs: 'Language Support'. Full grid showing all 12 languages, all 30+ frameworks, manifest file, and route detection pattern for each.

usm/gen-openapi

  • Generate OpenAPI spec (3 steps) — Produce openapi.yaml from feature routes and contracts

usm/opencode-integration

  • Generate the usm-workflow skill (4 steps) — During usm generate, emit .opencode/skills/usm-workflow/SKILL.md — a skill whose frontmatter description is the enforcement nudge (visible in the system prompt every message) and whose body is the full spec-first checklist.

  • Wire the iron-rules file into every-message instructions (4 steps) — Generate a short iron-rules markdown file and register it in opencode.json instructions so its content is appended to the system prompt on every request — the mechanism that actually counters mid-session drift.

  • Regenerate without breaking user config (3 steps) — Repeated usm generate runs replace the USM-owned skill and instructions files wholesale but leave all other opencode.json content untouched.

usm/gen-roadmap

  • Generate roadmap page with feature links and status badges (4 steps) — When usm generate runs, if the system has roadmap items, generate a roadmap.md page with a table showing status badge, title (linked to feature spec if feature field is set), shipped_in version, and target date.

  • Fix sidebar to only include links to existing files (4 steps) — The sidebar generator in docs.ts should check if the target .md file exists before adding a sidebar entry. This prevents dead links for suppressed pages (risks, roadmap) and missing feature docs.

  • Fix sidebar slug case to match actual file names (3 steps) — The sidebar slug derivation uses feat.id.replace(/^[^-]+-/, "") which produces lowercase slugs. But actual file names preserve case from the source .usm file path (e.g., agentsMd.md not agentsmd.md). The sidebar should derive the slug from the ref path, not the $id.

  • Enable mermaid rendering in VitePress config (3 steps) — VitePress doesn't render mermaid code blocks by default. Add the vitepress-plugin-mermaid to the VitePress config so architecture diagrams and other mermaid blocks render properly.

usm/gen-rules-files

  • Generate rules files for all supported tools (7 steps) — During usm generate, produce instruction files for each supported AI coding tool, each containing the spec-first workflow tailored to that tool's conventions.

  • Generate Cursor .mdc rule file (4 steps) — Cursor rules use .mdc format with YAML frontmatter specifying when the rule activates. The rule teaches the agent the spec-first workflow.

  • Generate CLAUDE.md for Claude Code (4 steps) — Claude Code reads CLAUDE.md for project instructions. The file teaches the spec-first workflow and references the MCP server.

  • Enhance AGENTS.md with workflow instructions (4 steps) — Extend the existing agentsMd generator to include spec-first workflow instructions alongside the structural context it already produces.

usm/structurizr-bridge

  • Import a Structurizr workspace JSON (4 steps)

  • Export Structurizr DSL as a generate target (3 steps)

  • Import then export stays coherent (3 steps)

usm/gen-testspecs

  • Generate Vitest test specs (4 steps) — Convert flows and tests from .usm into Vitest describe/it blocks

usm/gen-togaf

  • Generate all TOGAF phases (4 steps) — Produce markdown for each ADM phase

usm/agent-feedback

  • Configure feedback policy at init (4 steps) — usm init (and usm scan --enrich) asks the human two questions and persists a system.feedback block

  • Agent surfaces an issue following the configured policy (6 steps) — When an agent discovers a bug or improvement, its behaviour is governed entirely by system.feedback.policy

  • Render feedback protocol into all rules files (4 steps) — During usm generate, a shared Feedback Protocol block is emitted into every agent-facing file, dynamic to the project policy

  • Human reviews collected feedback (3 steps) — Feedback entries written to .usm/feedback are reviewable and convertible into issues or features

usm/mcp-contracts

  • Get feature contracts (3 steps) — Agent retrieves all contracts for a feature

usm/mcp-flows

  • Get feature flows (3 steps) — Agent retrieves all flows for a feature

usm/mcp-list

  • List all .usm files (3 steps) — Agent lists all .usm files in the monorepo

usm/mcp-query

  • Run a predicate query (3 steps)

usm/mcp-read

  • Read a .usm file (3 steps) — Agent reads a specific .usm file

usm/mcp-references

  • Find references to a $id (3 steps) — Agent searches for all files referencing a specific $id
  • Search .usm files (3 steps) — Agent searches for a term across all .usm files

usm/mcp-summary

  • Get file summary (3 steps) — Agent gets a quick summary of a .usm file

usm/mcp-validate

  • Validate by path (3 steps) — Agent validates an existing .usm file

usm/mcp-write

  • Draft a feature spec from human discussion (6 steps) — Agent and human discuss a feature in chat. Agent calls draft_feature with structured fields derived from the discussion. Tool validates, generates YAML + markdown preview. Agent shows markdown to human for review.

  • Update feature status after implementation (6 steps) — After the agent implements the feature in code, it updates the .usm file to reflect the new status and implementation paths.

  • Update arbitrary fields on an existing feature (4 steps) — Agent partially updates a feature spec — e.g., adding a flow, revising a contract, or updating tests based on what was actually built.

usm/schema-v1

  • Schema validation flow (4 steps) — A .usm file is validated against the v1 schema

Actors

ActorType
USM CLIPackage
USM MCP ServerPackage

Business Capability Map

mermaid
graph TD
    subgraph "usm/cli"
        usm_cli_cli_config_outputs["cli-config-outputs"]
        usm_cli_docs_serve_port_check["docs-serve-port-check"]
        usm_cli_cli_docs["cli-docs"]
        usm_cli_cli_enrich["cli-enrich"]
        usm_cli_cli_feedback["cli-feedback"]
        usm_cli_cli_generate["cli-generate"]
        usm_cli_cli_init["cli-init"]
        usm_cli_internal_dsl_builder["internal-dsl-builder"]
        usm_cli_more["+29 more"]
    end
    subgraph "usm/mcp"
        usm_mcp_mcp_contracts["mcp-contracts"]
        usm_mcp_mcp_flows["mcp-flows"]
        usm_mcp_mcp_list["mcp-list"]
        usm_mcp_mcp_read["mcp-read"]
        usm_mcp_mcp_references["mcp-references"]
        usm_mcp_mcp_search["mcp-search"]
        usm_mcp_mcp_summary["mcp-summary"]
        usm_mcp_mcp_validate["mcp-validate"]
        usm_mcp_more["+1 more"]
    end