usm/cli-scaffold

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

Usage

# Scaffold a system .usm file
usm scaffold .usm/system.usm

# Scaffold a service .usm file
usm scaffold .usm/services/api.usm --type service

# Scaffold a feature .usm file
usm scaffold .usm/features/auth/login.usm --type feature

Why this exists

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.

How it works

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

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

Guarantees

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

Test specifications

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