Architecture Change Management (TOGAF Phase H)
Auto-generated from USM decisions, risks, and future items.
Architecture Decisions (123)
| ID | Decision | Status | Source |
|---|---|---|---|
| use-deps-not-inline | Use battle-tested CLI libraries, not hand-rolled inline helpers | accepted | usm/cli-color-output |
| respect-no-color | Honor NO_COLOR env var and non-TTY stdout/stderr by emitting plain text | accepted | usm/cli-color-output |
| palette | green=✓, red=✗, yellow=⚠, cyan=→/info, dim=secondary values | accepted | usm/cli-color-output |
| cjs-pin-versions | Pin dependency versions to CJS-compatible majors | accepted | usm/cli-color-output |
| outputs-from-config | All generators read output paths from usmconfig.json outputs section | accepted | usm/cli-config-outputs |
| generate-only-flag | Replace generate:xxx commands with generate --only <target> flag | accepted | usm/cli-config-outputs |
| scaffold-project-to-subcommand | Rename scaffold-project to 'scaffold project' (subcommand) | accepted | usm/cli-config-outputs |
| no-dependency | Implement port probing with Node.js built-in net module — no third-party dependency like detect-port or chokidar. | accepted | usm/docs-serve-port-check |
| auto-port-opt-in | Auto-port selection is opt-in via --auto-port flag, not the default. | accepted | usm/docs-serve-port-check |
| lsof-best-effort | Process detection via lsof is best-effort only — graceful degradation if lsof is unavailable. | accepted | usm/docs-serve-port-check |
| pid-file-approach | Use a PID file (.usm-workspace/.vitepress.pid) plus a port file (.vitepress.port) for already-serving detection, not port-sniffing alone. | accepted | usm/docs-serve-port-check |
| watch-in-process | Watch-mode regeneration runs usm generate --only docs in-process (calling the generator functions directly), not as a subprocess. | accepted | usm/docs-serve-port-check |
| debounce-500ms | Watch-mode debounce is 500ms — a pragmatic balance between responsiveness and avoiding thrash on bulk writes. | accepted | usm/docs-serve-port-check |
| auto-port-default | Auto-port is the DEFAULT when --port is omitted; an explicit --port N is strict and fails loudly if N is taken. | accepted | usm/docs-serve-port-check |
| vitepress-over-custom | Use VitePress as the rendering layer instead of building a custom server | accepted | usm/cli-docs |
| unified-docs-directory | All generated docs write to a single docs/ directory instead of scattered .agents-workspace/ paths | accepted | usm/cli-docs |
| sidebar-from-system-index | Auto-generate VitePress sidebar config from system.usm index + feature directory structure | accepted | usm/cli-docs |
| vitepress-optional-dependency | VitePress is an optional peer dependency, not bundled with USM | accepted | usm/cli-docs |
| dont-commit-generated-docs | Generated docs are not committed to the repo — served locally and deployed via CI | accepted | usm/cli-docs |
| internal-over-external | Internal (host-language) DSL, not a custom grammar | — | usm/internal-dsl-builder |
| runtime-schema-validation | Enforce constraints by validating at build() rather than type-level branding | — | usm/internal-dsl-builder |
| all-35-in-docs | Generate per-editor setup pages for all 35 editors | accepted | usm/mcp-setup-guides |
| top-10-logos | Marketing site ToolLogos shows top 10 editors only | accepted | usm/mcp-setup-guides |
| index-plus-per-editor | Index page plus per-editor pages (shadcn pattern) | accepted | usm/mcp-setup-guides |
| rules-files-per-editor | Document rules/skills file installation on each editor page where supported | accepted | usm/mcp-setup-guides |
| stdio-config-pattern | Use the standard USM stdio pattern (usm mcp serve) for all editors | accepted | usm/mcp-setup-guides |
| manifest-based-detection | Detect services by language manifest files | accepted | usm/cli-multi-lang-scan |
| framework-specific-route-detection | Detect routes per-framework, not per-language | accepted | usm/cli-multi-lang-scan |
| configurable-in-usmconfig | Language/framework detection rules are configurable in usmconfig.json | accepted | usm/cli-multi-lang-scan |
| all-languages-from-start | Support all major languages from the initial implementation | accepted | usm/cli-multi-lang-scan |
| detectors-directory | Add .usm/detectors/*.yaml as a second auto-discovered extension surface alongside usmconfig.json detection | accepted | usm/cli-multi-lang-scan |
| script-escape-hatch | Allow routes.script in a detector to point at a .ts/.js file exporting extractRoutes(sourceDir, framework) for convention-based frameworks | accepted | usm/cli-multi-lang-scan |
| generalized-orchestrator | Generalize structural.ts service detection so any detector manifest drives it, removing the package.json hardcode | accepted | usm/cli-multi-lang-scan |
| infrastructure-as-detector | Treat infrastructure (Terraform today) as a detector kind rather than a hardcoded separate subcommand | accepted | usm/cli-multi-lang-scan |
| precedence-order | Detector precedence is built-in defaults < .usm/detectors/ files < usmconfig.json detection (last wins) | accepted | usm/cli-multi-lang-scan |
| tiny-grammar-not-sql | A ~200-line recursive-descent grammar, not SQL/jq subset | — | usm/query-layer |
| missing-field-is-false | Unknown/absent fields make predicates false instead of erroring | — | usm/query-layer |
| capability-registry-pattern | Capabilities self-describe (detect + setup + introducedIn); upgrade orchestrates without hardcoding. | accepted | usm/upgrade |
| usm-version-field-for-alignment | Use system.usm.usm_version for USM-tool alignment, NOT the project's own version field. | accepted | usm/upgrade |
| schema-version-independence | Schema $version moves independently of the package version: additive schema changes do NOT bump $version (still v1); breaking changes bump $version + CURRENT_SCHEMA_VERSION together and ship a migration in usm upgrade. | accepted | usm/upgrade |
| setup-owned-by-capability | Each registry entry owns its own setup function (interactive + default); upgrade just calls it. | accepted | usm/upgrade |
| interactive-with-flag-fallback | TTY prompts per capability; --apply uses defaults for CI/scripts; --check is report-only. | accepted | usm/upgrade |
| non-destructive | Upgrade only adds missing blocks and bumps usm_version; existing config is never overwritten. | accepted | usm/upgrade |
| homepage-simplify-not-remove | Simplify the homepage by removing marketing content, not by removing the homepage entirely. Keep the spec-first diagram, quick stats, and quick start as the core reference content. | accepted | usm/vitepress-home-feedback-schema |
| feedback-as-generated-page | The feedback page is a generated markdown page (docs/feedback.md), not a custom Vue component. The nav bar link is added via VitePress themeConfig.nav. | accepted | usm/vitepress-home-feedback-schema |
| agent-feedback-via-existing-mcp | The agent feedback path reuses the existing usm_report_feedback MCP tool (from usm/agent-feedback feature). The feedback page documents how agents should use it with page context. | accepted | usm/vitepress-home-feedback-schema |
| cross-links-in-generator | Cross-links and next-steps sections are added in the markdown generator, not hand-edited into output. | accepted | usm/vitepress-home-feedback-schema |
| schema-as-single-source | The schema reference is generated entirely from schema/v1.json; terse field descriptions are enriched in-place in the schema so the reference is self-generating and never drifts. | accepted | usm/vitepress-schema-polish |
| homepage-from-system-usm | Homepage hero, tagline, principle cards, and CTAs are derived from system.usm (identity, summary, principles, repository) so every USM project gets a reflective homepage. | accepted | usm/vitepress-schema-polish |
| mermaid-dark-mode-aware | Inject a small theme-bridge script so Mermaid follows VitePress isDark instead of the hardcoded 'default' theme. | accepted | usm/vitepress-schema-polish |
| declarative-sidebar-groups | Sidebar group order/names are driven by a declarative group-to-paths mapping while still only emitting links to pages that exist. | accepted | usm/vitepress-schema-polish |
| native-vitepress-containers | Use VitePress native containers and Mermaid code fences for visuals — no custom Vue components or heavy deps. | accepted | usm/vitepress-schema-polish |
| priority-ordering | Deliver schema-reference and homepage/getting-started first; visuals/polish last. | accepted | usm/vitepress-schema-polish |
| content-block-system | Define a content-block schema (heading, paragraph, code, mermaid, tabs, callout, table, steps, cards, badge, divider) that any .usm spec can use to express VitePress-rich content declaratively. | accepted | usm/gen-content-blocks |
| reference-pages-on-system | system.usm gains reference_pages[] for product-level reference pages (language support, getting started, agent setup) with inline content or runtime sources (detectors, schema, config). | accepted | usm/gen-content-blocks |
| reference-blocks-on-features | Feature specs gain an optional reference[] field for user-facing reference content that survives the help filter. | accepted | usm/gen-content-blocks |
| block-level-audience-filter | The help-doc filter operates at content-block granularity (keep audience: public, drop audience: internal) instead of section-level granularity (strip ## Contracts by heading name). | accepted | usm/gen-content-blocks |
| preserve-schema-reading-generators | generateConfigReference and generateSchemaReference are preserved — they read JSON schema files which ARE the source of truth for config/schema fields. | accepted | usm/gen-content-blocks |
| delete-after-migration | Hardcoded functions are deleted only after their content is migrated to specs and the replacement is proven by tests. | accepted | usm/gen-content-blocks |
| emit-only-when-populated | Emit a templated page only when its source section is populated; never write a placeholder | — | usm/docs-experience |
| togaf-as-architecture-section | Surface togaf output as the Architecture section of the docs site, not a separate target | — | usm/docs-experience |
| css-not-config-for-width | Widen via generated theme CSS custom properties, not VitePress config knobs | — | usm/docs-experience |
| feature-cards-as-nav | Use the VitePress features grid as homepage navigation rather than forcing a sidebar onto layout home | — | usm/docs-experience |
| voice-is-render-mode | Audience is a render mode (voice), not just a filter | — | usm/docs-experience |
| post-process-filtering | Generate full docs first, then filter for help audience | accepted | usm/gen-docs-split |
| visibility-field-optional | Add optional visibility field (public/internal) to features and services | accepted | usm/gen-docs-split |
| help-docs-simplified-features | Help docs show summary + intent + flows only, not contracts/tests/implementation | accepted | usm/gen-docs-split |
| docs-audience-model | Help docs = user journey only (USM adopters + downstream end users); developer docs = contributors and James (everything). Help excludes internal tooling pages (code-navigator, orphan-files, spec-coverage) and the entire design/ section; keeps getting-started, agent setup, CLI/MCP/schema/config references, roadmap, language-support, feedback, and composed guides. Dev docs unchanged (full detail). | accepted | usm/gen-docs-split |
| review-mode-separate-from-reference | Add a review-oriented template alongside the existing overview template | accepted | usm/gen-feature-review |
| flows-as-numbered-steps | Render flows as numbered human-readable steps, not tables | accepted | usm/gen-feature-review |
| contracts-as-checklist | Render contracts as a markdown checklist the human can mentally tick | accepted | usm/gen-feature-review |
| tests-as-given-when-then | Render tests in given/when/then format | accepted | usm/gen-feature-review |
| default-upstream-hardcoded | Default upstream tracker is the canonical USM repo, overridable via feedback.upstream_tracker | — | usm/feedback-upstream-routing |
| classification-instructions-not-detection | Teach scope classification via instructions rather than automatic detection in the MCP tool | — | usm/feedback-upstream-routing |
| usage-in-feature-spec | Add usage/options/prerequisites to FeatureUsm schema (optional fields) | accepted | usm/gen-help-reference |
| config-reference-from-schema | Generate usmconfig reference from usmconfig-v1.json schema descriptions | accepted | usm/gen-help-reference |
| schema-reference-from-v1-json | Generate schema reference from v1.json schema descriptions | accepted | usm/gen-help-reference |
| logo-carousel | Use a clickable logo carousel, not tabs | accepted | usm/mkt-language-tabs |
| simple-icons | Use Simple Icons (simpleicons.org) for language and framework logos | accepted | usm/mkt-language-tabs |
| full-grid-in-docs | Full language/framework reference grid goes in help docs, not marketing site | accepted | usm/mkt-language-tabs |
| reuse-real-doc-structure | Model browser mock content on real generated feature docs | accepted | usm/mkt-mock-interfaces-v2 |
| file-explorer-sync | IDE file explorer reveals .usm files in sync with agent file-write actions | accepted | usm/mkt-mock-interfaces-v2 |
| reuse-cli-animation-pattern | Reuse the line-by-line reveal pattern from CliAnimation for both mocks | accepted | usm/mkt-mock-interfaces |
| two-command-cycle | Cycle two command/spec pairs: draft_feature then generate | accepted | usm/mkt-mock-interfaces |
| responsive-stack | Side-by-side on md+ screens, stacked on mobile | accepted | usm/mkt-mock-interfaces |
| instructions-plus-skill-not-plugin | Use opencode instructions array + skill, not a plugin with experimental.chat.system.transform | — | usm/opencode-integration |
| short-dedicated-file-not-agents-md | Generate a dedicated short instructions file rather than reusing AGENTS.md | — | usm/opencode-integration |
| skill-file-usm-owned | The skill and instructions files are fully USM-owned (wholesale regeneration); opencode.json is merge-touched only in instructions | — | usm/opencode-integration |
| roadmap-links-to-features | Roadmap items can optionally reference a feature $id via a feature field | accepted | usm/gen-roadmap |
| shipped-in-optional | Add optional shipped_in field to roadmap items for version tracking | accepted | usm/gen-roadmap |
| sidebar-checks-file-existence | Sidebar generation should only include links to files that exist | accepted | usm/gen-roadmap |
| mermaid-via-vitepress-plugin | Use VitePress mermaid plugin instead of relying on native mermaid rendering | accepted | usm/gen-roadmap |
| one-generator-multiple-outputs | Single generator produces all tool-specific files in one pass | accepted | usm/gen-rules-files |
| workflow-instructions-not-just-context | Rules files contain behavioural instructions, not just system description | accepted | usm/gen-rules-files |
| smart-merge-for-rules-files | Reuse the smart-merge strategy from AGENTS.md generator | accepted | usm/gen-rules-files |
| cursor-uses-mdc-format | Generate .cursor/rules/usm.mdc in Cursor's rule format | accepted | usm/gen-rules-files |
| source-mapping-name | Name the feature source mapping rather than code navigator or file tree, because the capability is building a bidirectional source-to-spec mapping and rendering multiple views from it. | accepted | usm/gen-source-mapping |
| reference-pages-sources | Source mapping views are reference_pages sources on system.usm, rendered through the generic content-block renderer. | accepted | usm/gen-source-mapping |
| no-new-schema-fields | Use existing spec fields only — service modules[] and feature implementation — no new schema fields. | accepted | usm/gen-source-mapping |
| filesystem-walk-for-completeness | The generator walks the filesystem within service paths[] to enumerate actual files, not just the files mentioned in specs. | accepted | usm/gen-source-mapping |
| json-import-first | Import the Structurizr workspace JSON format, not the DSL grammar | — | usm/structurizr-bridge |
| features-as-components | Export features as components inside their service container | — | usm/structurizr-bridge |
| generator-not-author | The technical design document is a generator (structured renderer), not an authored doc. All content comes from .usm specs, schema, or declared content blocks. | — | usm/gen-technical-design |
| design-pages-parallel-to-reference-pages | system.usm gains a design_pages[] field parallel to reference_pages[]. Each entry can declare inline content blocks for a section, enriching the structured data. | — | usm/gen-technical-design |
| suppress-empty-sections | Sections with no data are suppressed entirely — no empty stub pages, no sidebar links to pages that don't exist. | — | usm/gen-technical-design |
| five-group-sidebar | The sidebar is restructured into five groups: Getting Started, Design, Project Management, Developers, Exports. This replaces the current fragmented groups (Core Concepts, Workflows, Architecture, Deployment, Contributing). | — | usm/gen-technical-design |
| nav-template-definition | The nav template structure is the standard for all generated technical docs. It defines five | ||
| top-level groups and the pages within each. The template is fixed in structure but adaptive in | |||
| rendering — groups and pages only appear when data exists. |
Getting Started
Home
Getting Started
Design
Project Overview
Project Name
Project Description
Stakeholders
Assumptions
Use-cases
Requirements
Functional Requirements
Non-Functional Requirements
Performance
Scalability
Security
Reliability
Maintainability
System Architecture
High-Level Diagram
Technology Stack
Frontend
Backend
Database
Infrastructure
System Components
Module Design
Module Name
Purpose
Inputs
Outputs
Dependencies
Flow
Database Design
ER Diagram
Schema Design
Indexes
Transactions
API Design
Endpoints
HTTP Method (GET/POST/PUT/DELETE)
URL Schemas / naming conventions
Request/Response structure
Authentication
Authorization (roles, resources, permissions)
Rate Limiting
Error Handling
Security Design
Authentication / Authorization
Data Encryption
Security Auditing
Vulnerabilities
Security Stack
Deployment Architecture
Deployment Diagram
Environment Setup
Development
Staging
Production
Scaling Strategy
Monitoring Stack
Testing Strategy
Unit Testing
Integration Testing
Acceptance Testing
Performance Testing
Security Testing
Automated Testing
Maintenance & Monitoring
Logging
Alerting
System Health Monitoring
Error Tracking
Backup & Recovery
Backup Strategy
Disaster Recovery
Risks & Mitigation
Technical Risks
Mitigation Strategies
Future Enhancements
Roadmap
Scalability Considerations
Project Management
Roadmap
Features (grouped by service/area)
Decision Register
Developers
Source Map
Test Coverage
Spec Coverage
API Reference
CLI Reference
Configuration
Exports (collapsed)
TOGAF Phases
ArchiMate ModelLevel 1 = sidebar group. Level 2 = sidebar page link. Level 3+ = page content sections (rendered as the page outline/TOC, not sidebar links). The sidebar is 2 levels deep (group > page). Groups and pages only appear when their data source exists — the template adapts to the project type. | — | usm/gen-technical-design | | decision-register-consolidated | A Decision Register page consolidates all decisions from features, services, and system principles into one page under Project Management. | — | usm/gen-technical-design | | features-as-project-management | Features are grouped under Project Management, not Design. Features with flows/contracts/tests/status are work records, not design prose. | — | usm/gen-technical-design | | single-vision-not-staged | Implement the full composition model in one feature — no phased rollout | accepted | usm/gen-user-docs | | minimal-personas | Personas stay minimal: id, name, description — no goals/frustrations/expertise yet | accepted | usm/gen-user-docs | | actor-default-system | Step actor defaults to system; flows without a persona actor remain pipeline flows in developer docs | accepted | usm/gen-user-docs | | e2e-link-via-tests | E2E linkage via optional tests[].flow reference — not steps referencing tests | accepted | usm/gen-user-docs | | filter-deprecated-not-deleted | Deprecate (do not delete) the --audience help subtraction filter for feature pages | accepted | usm/gen-user-docs | | default-human-gate | human-gate is the default policy | — | usm/agent-feedback | | feedback-as-first-class-usm-type | Feedback entries are $type: feedback .usm files in .usm/feedback, not a free-form markdown log | — | usm/agent-feedback | | one-shared-protocol-block | A single Feedback Protocol block is rendered into all four rules files from one code path | — | usm/agent-feedback | | setup-asks-two-questions | usm init asks exactly two questions: gh auth presence and policy choice | — | usm/agent-feedback | | mcp-tool-respects-policy | usm_report_feedback consults system.feedback.policy before writing | — | usm/agent-feedback | | write-tools-as-mcp-not-cli | Implement authoring as MCP tools rather than CLI commands only | accepted | usm/mcp-write | | draft-returns-preview | draft_feature returns both YAML and generated markdown | accepted | usm/mcp-write | | validate-before-write | All write operations validate against the v1 schema before persisting | accepted | usm/mcp-write | | json-over-yaml | Use JSON for usmconfig (not YAML) because it is machine-generated and machine-read | — | usm/usm-config |
Change Governance 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.