USM

Appearance

Opportunities & Solutions (TOGAF Phase E) ​

Auto-generated from USM roadmap and principles.

Roadmap ​

VitePress docs integration ​

  • ID: vitepress-docs
  • Status: shipped
  • Description: usm docs serve and usm docs build with auto-generated sidebar, angle bracket escaping, and index page
  • Target Date: 2026-06-22

Review-quality feature markdown ​

  • ID: review-quality-markdown
  • Status: shipped
  • Description: Flows as numbered steps, contracts as checklists, tests as Given/When/Then, decisions with alternatives
  • Target Date: 2026-06-22

Suppress empty sections in generated docs ​

  • ID: empty-section-suppression
  • Status: shipped
  • Description: No more empty App Services, No UI pages documented, or No risks defined pages
  • Target Date: 2026-06-22

Roles field in system schema ​

  • ID: roles-schema
  • Status: shipped
  • Description: Any project can describe who uses their system and what they need
  • Target Date: 2026-06-22

ADR schema enrichment ​

  • ID: adr-schema-enrichment
  • Status: shipped
  • Description: Alternatives and consequences fields on decisions for proper ADR-style recording
  • Target Date: 2026-06-22
  • ID: roadmap-improvements
  • Status: shipped
  • Description: Roadmap items link to feature specs, show shipped_in version, sidebar dead links fixed, mermaid rendering

Configurable output paths ​

  • ID: config-outputs
  • Status: shipped
  • Description: Generators read output paths from usmconfig.json — no hardcoded .usm-workspace layout

Help docs reference expansion ​

  • ID: help-reference-expansion
  • Status: shipped
  • Description: CLI reference, usage examples, options, and prerequisites rendered in help docs from spec data

MCP write tools ​

  • ID: agent-authoring-tools
  • Status: shipped
  • Description: draft_feature, update_feature_status — close the spec-first loop so agents can author .usm files

Tool-specific rules files ​

  • ID: rules-file-generation
  • Status: shipped
  • Description: Generate .cursor/rules, CLAUDE.md, copilot-instructions.md with spec-first workflow instructions

Marketing site ​

  • ID: marketing-site
  • Status: planned
  • Description: Next.js + shadcn landing page at usm.dev with spec-first workflow story

User docs composed from personas and journeys ​

  • ID: user-docs-composition
  • Status: shipped
  • Description: Personas and journey flows (actor/surface) as first-class spec data; user guides and Playwright e2e skeletons generated from the same journeys; help docs for feature pages composed instead of filtered

Tool-specific rules files generator ​

  • ID: rules-files-generator
  • Status: shipped
  • Description: Per-tool rules files (.cursor/rules, CLAUDE.md, copilot-instructions.md) generated from spec data with the spec-first workflow instructions baked in

Help vs developer docs split ​

  • ID: docs-split-generator
  • Status: shipped
  • Description: Two docs audiences from one .usm source — developer docs (full internals) and help docs (user journeys) with a subtraction filter and audience-specific sidebar

Help docs reference expansion ​

  • ID: help-reference-generator
  • Status: shipped
  • Description: CLI reference, usage examples, options, and prerequisites rendered in help docs from spec data

MCP write tools (spec authoring) ​

  • ID: mcp-write-tools
  • Status: shipped
  • Description: draft_feature, write_feature, update_feature, update_feature_status, write_system, write_service — close the spec-first loop so agents author .usm files with validation

Consumer integration fixes (config validation, CI gate, help docs, MCP merge) ​

  • ID: consumer-blocker-fixes
  • Status: shipped
  • Description: From the safekeys integration report: usmconfig.json validated at load with usm validate --config (issue #43); generate --check skips untracked outputs (issue #42); help-tree nesting guard + path-honest output (issues #44/#47); upgrade --apply stamps alignment (issue #46); update_system/update_service merge id-bearing arrays (issue #48); package ships universal onboarding docs (issue #45)

Universal onboarding docs shipped in the npm package ​

  • ID: package-universal-docs
  • Status: shipped
  • Description: getting-started, agent-setup-guide, and 36 per-editor MCP setup guides ship inside the package and merge into consumer docs when the consumer repo has no docs-source/; homepage Getting Started link lights up on first generate

Docs sidebar information architecture restructure ​

  • ID: docs-ia-restructure
  • Status: in-progress
  • Description: Single-level sidebar nesting that VitePress renders correctly; unique human labels; dedicated Reference group; Architecture naming; help docs reduced to user-journey content; roadmap kept current

Deprecate subtraction-based help docs for feature pages ​

  • ID: help-docs-filter-deprecation
  • Status: in-progress
  • Description: Feature pages in --audience help switch to composed content; subtraction filter retained for system-level pages during one transition cycle. Progressed by usm/docs-ia-restructure: help tree now excludes feature build specs entirely and surfaces composed persona guides instead.

Architecture Decisions (from Principles) ​

  • Structured Source of Truth: Every system artifact is captured in YAML validated by a JSON Schema — no scattered, stale docs.
  • Agent First: USM files are designed for AI agent consumption via MCP tools before human readability.
  • Idempotent Generation: Scan and generate are safe to run repeatedly; smart-merge preserves human edits.
  • One Source, Many Outputs: A single .usm/ directory generates markdown, Mermaid, OpenAPI, ArchiMate, TOGAF, AGENTS.md, and Vitest specs.

Roadmap Timeline ​

mermaid
graph LR
    vitepress_docs["VitePress docs integration<br/>shipped"]
    review_quality_markdown["Review-quality feature markdown<br/>shipped"]
    vitepress_docs --> review_quality_markdown
    empty_section_suppression["Suppress empty sections in generated docs<br/>shipped"]
    review_quality_markdown --> empty_section_suppression
    roles_schema["Roles field in system schema<br/>shipped"]
    empty_section_suppression --> roles_schema
    adr_schema_enrichment["ADR schema enrichment<br/>shipped"]
    roles_schema --> adr_schema_enrichment
    roadmap_improvements["Roadmap with feature links and delivery tracking<br/>shipped"]
    adr_schema_enrichment --> roadmap_improvements
    config_outputs["Configurable output paths<br/>shipped"]
    roadmap_improvements --> config_outputs
    help_reference_expansion["Help docs reference expansion<br/>shipped"]
    config_outputs --> help_reference_expansion
    agent_authoring_tools["MCP write tools<br/>shipped"]
    help_reference_expansion --> agent_authoring_tools
    rules_file_generation["Tool-specific rules files<br/>shipped"]
    agent_authoring_tools --> rules_file_generation
    marketing_site["Marketing site<br/>planned"]
    rules_file_generation --> marketing_site
    user_docs_composition["User docs composed from personas and journeys<br/>shipped"]
    marketing_site --> user_docs_composition
    rules_files_generator["Tool-specific rules files generator<br/>shipped"]
    user_docs_composition --> rules_files_generator
    docs_split_generator["Help vs developer docs split<br/>shipped"]
    rules_files_generator --> docs_split_generator
    help_reference_generator["Help docs reference expansion<br/>shipped"]
    docs_split_generator --> help_reference_generator
    mcp_write_tools["MCP write tools (spec authoring)<br/>shipped"]
    help_reference_generator --> mcp_write_tools
    consumer_blocker_fixes["Consumer integration fixes (config validation, CI gate, help docs, MCP merge)<br/>shipped"]
    mcp_write_tools --> consumer_blocker_fixes
    package_universal_docs["Universal onboarding docs shipped in the npm package<br/>shipped"]
    consumer_blocker_fixes --> package_universal_docs
    docs_ia_restructure["Docs sidebar information architecture restructure<br/>in-progress"]
    package_universal_docs --> docs_ia_restructure
    help_docs_filter_deprecation["Deprecate subtraction-based help docs for feature pages<br/>in-progress"]
    docs_ia_restructure --> help_docs_filter_deprecation