USM

Appearance

usm/cli-scaffold ​

The usm scaffold command creates a new .usm file with a template for system, service, or feature types.

Intent ​

Users need a quick way to create a new .usm file with the correct structure. Scaffold writes a template with all required fields and placeholder values, so the file immediately validates.

Flows ​

Scaffold a .usm file (scaffold-file) ​

User creates a new .usm file from a template

  1. setup → file path and type (system, service, feature)
  2. generate → template YAML with all required fields
  3. submit → write template to file path

Flow Diagrams ​

mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server

    Note over Server,Browser: setup — file path and type (system, service, feature)
    User->>Browser: generate template YAML with all required fields
    User->>Browser: submit write template to file path

Contracts ​

scaffold-valid-template ​

Scaffold must produce a file that validates against v1.json

Acceptance criteria:

  • [ ] All required fields present
  • [ ] File not overwritten if it already exists

Tests ​

scaffold-system ​

Given:

  • new_directory: true

Then:

  • assertion: file created with $type: system and identity block
  • assertion: file validates

scaffold-existing ​

Given:

  • existing_file: true

Then:

  • assertion: error "File already exists"
  • assertion: exit code 1

Implementation ​

  • Primary: src/cli/index.ts (scaffold command)
  • Test code status: none

See Also ​

  • usm/cli-scaffold-project