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: in-progress
  • Description: Roadmap items link to feature specs, show shipped_in version, sidebar dead links fixed, mermaid rendering

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

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/>in-progress"]
    adr_schema_enrichment --> roadmap_improvements
    agent_authoring_tools["MCP write tools<br/>shipped"]
    roadmap_improvements --> 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