Chapter 27 | First Run of `/dev`

Updated on 5/12/2026

Chapter 27: First Run of /dev

Learning Objectives

Connect what you've learned in the first 26 chapters and run your first line of real code.

Pre-flight Checklist

flowchart TB
    Pre["Before running /dev"] --> C1{git init'd?}
    C1 -->|No| Init1["git init + commit openspec/, .claude/, CLAUDE.md"]
    C1 -->|Yes| C2{Have examples/.md?}
    Init1 --> C2
    C2 -->|No| C2N["Create a simple one first, as E2E entry point"]
    C2 -->|Yes| C3{Python venv activated?}
    C2N --> C3
    C3 -->|No| C3N["python3 -m venv .venv && source .venv/bin/activate"]
    C3 -->|Yes| C4{tmux/ffmpeg/Chrome?}
    C3N --> C4
    C4 -->|No| C4N["Go back to Ch 4 to install"]
    C4 -->|Yes| Ready["✓ Ready to start"]
    C4N --> Ready

    style Ready fill:#c8e6c9

Expected Flow for the First Run

You: /dev status
   ↓
trace:
  Group 1: PENDING (4 task)
  Group 2: PENDING (5 task)
  ...
  
You: /dev 1
   ↓
trace:
  → Group 1: dispatch developer (sonnet)        ... done
  → Group 1: dispatch tester (sonnet)           ... PASS
  → Group 1: dispatch reviewer (opus) R1        ... APPROVED
  ✓ Group 1: Project scaffolding

→ This is the ideal success path. The first run is likely not.

Common Sticking Points for the First Run (by probability)

Sticking Point Reason Fix
1. Developer reports "pyproject.toml not found" Group 1 task needs to create it, but path is incorrect Wait for developer to create it
2. Tester reports ImportError Dev dependencies not installed Activate venv, pip install -e ".[dev]"
3. edge-tts network error Rate limit or network issue Retry or mock first
4. tmux misbehaves Old version brew upgrade tmux
5. Reviewer rejects (justified) Developer genuinely deviated from design Check review/N.md, send developer back to rework
6. Reviewer rejects (nitpicking) Sonnet occasionally too strict Automatically escalates to deep after threshold 3

Three Essential Checks After Each Dispatch

flowchart LR
    Dispatch["After dispatch"] --> A["1. Agent's stdout report"]
    A --> B["2. Files it claims to have written (Read verification)"]
    B --> C["3. git status / git diff"]
    C --> Decide["Confirm status before proceeding"]

    style Decide fill:#c8e6c9

→ Don't just trust stdout—agents can lie or miss checkboxes.

After the First Run of Group 1, You Should See

$ git log --oneline
abc1234 feat(group-1): Project scaffolding
def5678 init: openspec scaffold

$ tree src/ tests/
src/doc2video/
├── __init__.py
└── ...
tests/
└── ...

$ ls openspec/changes/add-doc2video/
proposal.md  design.md  specs/  tasks.md  review/  test-reports/

review/1.md and test-reports/1.md should both exist.

Starting Group 2 = Getting into the Rhythm

/dev 2  →  /dev 3  →  /dev 4  →  ...

Or directly:

/dev   →  Run all to E2E

Mental Preparation

✅ It's normal for the first group to be slow (environment setup)
✅ There will be several reworks in between (this is the value of the reviewer)
✅ Occasionally stuck on architect (indicates a genuine flaw in the spec, don't fret)
❌ Don't doubt the entire design if the first group fails—it's likely an infrastructure issue

What You Can Do Now

  • Complete the pre-flight checklist
  • Run the first group's full cycle
  • Understand the dispatch trace and know where to check progress

The next chapter covers troubleshooting—don't panic when things go wrong.