Chapter 10 | Propose Changes with `/opsx:propose`

Chapter 10: Proposing Changes with /opsx:propose

Learning Objectives

Run /opsx:propose once to obtain the complete four-piece set: proposal / design / specs / tasks.

What Happens Behind the Command

sequenceDiagram
    participant You
    participant MC as main Claude
    participant CLI as openspec CLI
    participant FS as File System
    
    You->>MC: /opsx:propose I want to do doc2video
    MC->>You: AskUserQuestion: Describe it more clearly?
    You->>MC: ...detailed description...
    MC->>CLI: openspec new change add-doc2video
    CLI->>FS: Create empty skeleton changes/add-doc2video/
    MC->>CLI: openspec status --json
    CLI->>MC: List artifacts to generate + dependencies
    loop In dependency order
        MC->>CLI: openspec instructions 
        CLI->>MC: Template + Rules
        MC->>FS: Write proposal.md / design.md / spec.md / tasks.md
    end
    MC->>You: 4-piece set ready

Hands-on: Run It Once

# In Claude Code
/opsx:propose compile markdown tutorial documents into videos, including voiceover, subtitles, and real terminal operations

main Claude will ask you 1-2 clarifying questions, then start batch generation. The final directory will look like this:

openspec/changes/add-doc2video/
├── proposal.md           ~30 lines: why + what + capabilities + impact
├── design.md             ~120 lines: 9 decisions + risks
├── specs/
│   └── doc2video/
│       └── spec.md       ~150 lines: 11 Requirements + 30+ Scenarios
└── tasks.md              ~80 lines: 13 groups, 61 tasks

Dependencies of the 4 Artifacts

flowchart LR
    P[proposal.md] --> D[design.md]
    P --> S[specs/]
    D --> T[tasks.md]
    S --> T

    style P fill:#bbdefb
    style D fill:#c5e1a5
    style S fill:#ffe0b2
    style T fill:#f8bbd0

Why this order:

• Proposal first: Decides "what to do + why"
• Design and Specs in parallel: Design describes "how to do it", Specs describe "what it looks like when done"
• Tasks last: Depends on the previous three to break down into accurate tasks

Anatomy of proposal.md

Open it and take a look:

## Why
(One-sentence pain point + why now)

## What Changes
- What's new
- What's modified
- What's removed (mark as BREAKING)

## Capabilities
### New Capabilities
- `doc2video`: One-sentence description of this capability

### Modified Capabilities
(None / List them)

## Impact
(Which code, dependencies, external systems are affected)

→ 1-2 pages are enough. Do not write "how"—that's for the design.

Key Flags of the Command

main Claude calls these three in order when running /opsx:propose; you don't need to call them directly.

Checking the Output

Immediately after running /opsx:propose, run:

openspec status --change add-doc2video

Expected output:

Progress: 4/4 artifacts complete

[x] proposal
[x] design
[x] specs
[x] tasks

All artifacts complete!

If it's 3/4 or less, it means an artifact failed to generate—check main Claude's output.

A Common "Failure" Scenario

You: /opsx:propose Add search functionality
   ↓
main Claude writes proposal "Add search functionality"
   ↓
Only in design.md do you realize if "search" means full-text search or database LIKE?
   ↓
Spec is written vaguely

→ Either explore to clarify first, or fully articulate your intent when proposing. Propose can prompt you for unclear areas to supplement, but it won't think through everything for you.

What Not to Do

✗ Immediately run /opsx:apply after propose
   First, read through all 4 files to confirm the intent has been accurately captured.

✗ Skip design.md
   With only proposal + spec + tasks, decisions are not recorded, and no one will remember why it was done this way in six months.

✗ Stuff implementation details into proposal.md
   Proposal is about why, not how.

What You Can Do Now

• Generate the complete 4-piece set
• Understand the role of each file
• Determine "whether to explore or propose" before running

Milestone Summary: What You Can Achieve After Chapter 10

flowchart LR
    Start["Chapter 1
Start"] --> Setup["Chapters 4-6
Environment Ready"]
    Setup --> Mental["Chapters 1-3
Mental Model"]
    Mental --> First["Chapters 7-10
First Change"]

    First --> You["✓ Generated complete 4-piece set
✓ Understand each file
✓ Know what's next"]

    style You fill:#c8e6c9

Core Checkpoint: By now, you should have generated an openspec/changes/<your-name>/ for a project you want to work on, with all four files complete, on your own machine.

If not—go back to Chapter 8 and redo it, as this is the foundation for all subsequent chapters.