openspec-develop

OpenSpec Develop

Implementation engine for approved OpenSpec proposals. Turns tasks.md checkboxes into working code.

⚠️ AskUserQuestion Guard

CRITICAL: After EVERY AskUserQuestion call, check if answers are empty/blank. Known Claude Code bug: outside Plan Mode, AskUserQuestion silently returns empty answers without showing UI.

If answers are empty: DO NOT proceed with assumptions. Instead:

1. Output: "⚠️ Questions didn't display (known Claude Code bug outside Plan Mode)."
2. Present the options as a numbered text list and ask user to reply with their choice number.
3. WAIT for user reply before continuing.

Workflow: Explore → Implement → Mark → Gate

flowchart LR
    A["Read task"] --> B["Explore context"]
    B --> C["Implement"]
    C --> D["Mark ✅ in tasks.md"]
    D --> E{"More tasks\nin section?"}
    E -->|Yes| A
    E -->|No| G{"Gate exists?"}
    G -->|No| H{"More sections?"}
    G -->|Yes| I["🚧 Checkpoint prompt"]
    I --> J["STOP"]
    H -->|Yes| A
    H -->|No| F["Report complete"]

    classDef action fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef decision fill:#FFF9C4,stroke:#FBC02D,color:#000
    classDef gate fill:#FFE0B2,stroke:#F57C00,color:#000
    class A,B,C,D,F action
    class E,G,H decision
    class I,J gate

Critical: Mark checkbox immediately after each task. Enables crash recovery.

Guardrails

Autonomous (no confirmation needed):

• Code generation matching specs
• File edits within scope
• Checkbox updates
• Pattern-matching existing code

Ask-first (pause and confirm):

• Architectural decisions not in specs
• New dependencies not mentioned
• Scope deviation >20% from proposal
• Files outside change scope

Scope check: Before creating files not mentioned in proposal.md, count affected files. If >20% more than proposal's "Affected files", ask:

⚠️ Scope expansion detected
Proposal mentions: {n} files
Implementation needs: {m} files ({percent}% more)

Proceed with expanded scope? [y/N]

Commands

implement

Implement all pending tasks from tasks.md, pausing at gates.

Input: $ARGUMENTS = change-id

Workflow:

1. Read openspec/changes/{change-id}/tasks.md
2. If tasks.md has a **Design**: header → read openspec/changes/{change-id}/design.md for BC scope, invariants, ubiquitous language, and ADRs
3. Group tasks by section headers (## N. Section Name)
4. For each section (in order): a. For each unchecked task in section:
   • Consult Exploration Strategy for context/tools
   • Read specs and must-read files
   • Explore codebase for patterns
   • Implement the task
   • Immediately mark checkbox: - [ ] → - [x] b. After all section tasks complete, check for ### GATE N: line c. If gate exists and not [PASS]: output checkpoint prompt, stop processing d. If no gate or already [PASS]: continue to next section
5. When all sections complete: Report "All tasks complete"

Gate checkpoint (stops processing):

🚧 GATE {n}: {description}
Section {n} tasks: {done}/{total} complete
→ Run checkpoint: /openspec-test checkpoint {change-id} {n}
→ Skip gate: /openspec-develop section {change-id} {n+1}

All complete:

✅ All tasks complete for {change-id}
Progress: {done}/{total} tasks
Ready for: /openspec-test {change-id}

task

Implement a specific task by number.

Input: $ARGUMENTS = change-id task-number (e.g., add-feature 1.3)

Workflow:

1. Read tasks.md, find task by number (e.g., 1.3)
2. If already checked: Report "Task {number} already complete"
3. If unchecked: Implement using same workflow as implement
4. Mark checkbox immediately after completion

Already complete:

⏭️ Task {number} already complete
Description: {task description}

section

Implement all tasks in one section only.

Input: $ARGUMENTS = change-id section-number (e.g., add-feature 3)

Workflow:

1. Read tasks.md, find section ## {section-number}. ...
2. For each unchecked task in that section: implement and mark checkbox
3. After completing: if gate exists, output checkpoint prompt; else suggest next section

Section complete (with gate):

🚧 GATE {n}: {description}
Section {n} tasks: {done}/{total} complete
→ Run checkpoint: /openspec-test checkpoint {change-id} {n}
→ Skip gate: /openspec-develop section {change-id} {n+1}

Section complete (no gate):

✅ Section {n} complete: {section-name}
Progress: {done}/{total} tasks in section
→ Next: /openspec-develop section {change-id} {n+1}

status

Show implementation progress.

Input: $ARGUMENTS = change-id

Run:

openspec show {change-id}

Display task completion progress from CLI output.

Philosophy Check

Before implementing, read openspec/project.md → Execution Philosophy → mode.

During implementation, flag anti-patterns for current mode:

⚠️ Philosophy check ({mode} mode):
- Anti-pattern detected: {anti-pattern}
- Current action: {what you're about to do}
- Question: {is this necessary or gold-plating?}

Proceed anyway? [y/N]

Examples by mode:

• garage: Flag premature abstractions, over-engineering, excessive documentation
• scale: Flag missing tests, undocumented decisions, cowboy changes
• maintenance: Flag unnecessary refactors, feature creep, risky upgrades

Task Parsing

Parse tasks.md format:

## 1. Section Name
- [ ] 1.1 Task description here
- [x] 1.2 Already complete task
- [ ] 1.3 Another pending task

Match pattern: - \[([ x])\] (\d+\.\d+) (.+)$

• Group 1: checkbox state (space = pending, x = complete)
• Group 2: task number (e.g., 1.3)
• Group 3: task description

Section & Gate Parsing

Parse section headers and gate markers in tasks.md:

Section header: ## (\d+)\. (.+)$ Gate line: ### GATE (\d+): (.+?)(?:\s+\[(PASS|PARTIAL|BLOCKED)\])?$

Group tasks by their parent section header. Gates are optional markers between sections.

Gate states:

• Unmarked = not attempted
• [PASS] = checkpoint verified
• [PARTIAL] = some failures, needs attention
• [BLOCKED] = cannot proceed without resolution

Checkbox Update

After completing task, edit tasks.md:

• Find: - [ ] {task-number} {description}
• Replace: - [x] {task-number} {description}

Use Edit tool for surgical update. Never rewrite entire file.

Gate Update

After checkpoint passes, mark gate in tasks.md:

• Find: ### GATE {n}: {description}
• Replace: ### GATE {n}: {description} [PASS]

Use Edit tool. Gate state drives crash recovery — on resume, develop skips [PASS] gates and re-prompts unmarked gates after completed sections.

Exploration Strategy

Before implementation, consult openspec/project.md → Exploration Strategy section:

1. Context sources: Read primary files (project.md, proposal.md, specs)
2. Must-read files: CLAUDE.md, settings.json (project constraints)
3. Tools: Use configured codebase tools (Glob, Grep, Read, or MCP if enabled)
4. Pattern matching: Read existing similar files to match structure/style
5. Philosophy: Read Execution Philosophy section for current mode and principles