USM

Appearance

usm/cli-config-outputs [in-progress] ​

Configurable output paths in usmconfig.json and simplified command convention. Generators read output paths from config instead of hardcoding. generate:xxx commands replaced with generate --only flag.

Status: in-progress

Intent ​

Output paths are hardcoded to .usm-workspace/ in every generator. Users can't configure where outputs go without editing source code. The command convention is inconsistent (generate:help-docs uses colons, docs serve uses spaces). This feature makes all output paths configurable via usmconfig.json and simplifies the command convention to verb + target with --only flag.

Decisions ​

outputs-from-config [accepted] ​

Decision: All generators read output paths from usmconfig.json outputs section

Rationale: Users may want outputs in different locations (e.g. docs/ instead of .usm-workspace/docs/, or a custom build directory). Reading from config with sensible defaults means it works out of the box but is overridable.

Consequences: All generators need to call a shared getOutputPath() utility instead of hardcoding paths

generate-only-flag [accepted] ​

Decision: Replace generate:xxx commands with generate --only <target> flag

Rationale: generate:help-docs, generate:togaf, generate:archimate use colon syntax which is inconsistent with docs serve, mcp serve (space syntax). Using --only flag keeps generate as a single command with a filter, which is simpler and more consistent.

Alternatives considered:

  • Keep colon commands (generate:togaf, generate:archimate) — rejected: Inconsistent with space-syntax subcommands, clutters --help output
  • Subcommands (generate togaf, generate archimate) — rejected: Makes generate a parent command, changes default behaviour, more complex Commander setup

Consequences: Breaking change — generate:xxx commands removed. Pre-public-release so acceptable.

scaffold-project-to-subcommand [accepted] ​

Decision: Rename scaffold-project to 'scaffold project' (subcommand)

Rationale: Consistent with 'docs serve', 'mcp serve', 'scan infrastructure' — all use space syntax for subcommands.

Consequences: Breaking change — scaffold-project becomes 'scaffold project'

Flows ​

Resolve output paths from usmconfig.json (resolve-output-paths) ​

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.

  1. read → usmconfig.json from root
  2. parse → outputs section
  3. resolve → each output type to a full path
  4. return → map of output type → path

Generate with --only flag (generate-with-only) ​

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.

  1. parse → --only flag from CLI args
  2. check → is target valid?
  3. generate → only the specified output's generators
  4. observe → if no --only, run all generators (default)

Contracts ​

outputs-configurable ​

All output paths are configurable via usmconfig.json

Acceptance criteria:

  • [ ] Generators read paths from config, not hardcoded
  • [ ] Defaults work when config is missing or outputs section absent
  • [ ] All output types have config keys: workspace, docs, help_docs, archimate, togaf, openapi, tests, agents_md

only-flag-works ​

generate --only <target> runs only the specified output

Acceptance criteria:

  • [ ] Invalid target shows error with valid options
  • [ ] No --only runs all generators (backward compatible)
  • [ ] Valid targets: docs, help-docs, togaf, archimate, openapi, tests, rules, agents-md

no-colon-commands ​

generate:xxx commands are removed

Acceptance criteria:

  • [ ] generate:help-docs removed — use 'generate --only help-docs'
  • [ ] generate:togaf removed — use 'generate --only togaf'
  • [ ] generate:archimate removed — use 'generate --only archimate'

Tests ​

default-paths-work ​

Given:

  • usmconfig_without_outputs: true

Then:

  • assertion: docs go to .usm-workspace/docs/
  • assertion: togaf goes to .usm-workspace/togaf/

custom-paths-work ​

Given:

  • usmconfig_with_custom_outputs: true

Then:

  • assertion: docs go to configured path

only-flag-filters ​

Given:

  • only_flag: "togaf"

Then:

  • assertion: only TOGAF files generated
  • assertion: no docs files generated

invalid-only-target ​

Given:

  • only_flag: "invalid"

Then:

  • assertion: error message with valid targets listed

Implementation ​

  • Primary: src/cli/index.ts
  • Test code status: none

See Also ​

  • usm/cli-generate
  • usm/cli-docs
  • usm/gen-docs-split