Spec-First Pipeline

intent-driven OpenSpec schema · "the spec is the durable artifact; the code is the side effect"

ONRAMPS & PREREQUISITES — upstream of the change loop, run once or as-needed (human answers, agent writes) 👤 /init → openspec/project.md (constitution — ONCE per project) 👤 /mentalmodel <topic> → docs/models/ (before a NEW layer / component / decision) Read project.md before ANY planning or code · ADRs immutable once accepted · writes to openspec/ and adr/ are human-gated ① SEED PIPELINE — interactive Socratic interviews · human answers, agent writes · MAY write openspec/ new feature 0 · /diagnose (six-move loop) Diagnose bug onramp structural → /new ≤2 files → hotfix-<id> 1 👤 Architect interview New · Inversion interview → scaffold writes proposal.md /new 2 👤 interview Grill-Me interrogate proposal → acceptance checks /grill 3 👤 interview · user chooses Reconcile vs project.md · ADRs drift / contradiction /reconcile 4 👤 HUMAN GATE · accepts ADR-Grill (3½) accepted ADRs → adr/ (immutable) /adr-grill 5 🤖 autonomous emit Emit specs · design adr-manifest · tasks /emit · validate --strict ② AUTONOMOUS BUILD LOOP — dispatch-loop.sh routes on machine-readable verdicts · one task/session · SPEC FROZEN: agents can't write openspec/ 6 Dispatch 🤖 Contractor builds ONE task's code emits COMMIT_MSG: 7 · Review 🤖 independent runs tests VERDICT → approve ✓ 10 Commit ⚙ dispatch-loop.sh tick box + git commit agent NEVER ticks ↻ next open task in tasks.md all tasks committed → blocker 8 Fix 🤖 Fixer repairs only the blocking feedback re-emits COMMIT_MSG: re-review · ≤3 rounds 4th blocker 9 Escalate 🤖 fix the SPEC, not the code (Fable) tasks.md / spec.md structural_blocker · needs_adjudication ⛔ HARD STOP → human dispatch-loop.sh exits 125 ③ IMPROVEMENT BACKLOG — reviewers collect improvements along the way; curate once, then refine each item through the SAME loop 11 Triage (Curator) 🤖 emits TRIAGE: json actionable/obsolete/deferred ⚙ script rewrites backlog 12 Refine each item reuses dispatch → review → fix → commit cap: 50 passes → HARD STOP ↻ per open item backlog empty → ④ ACCEPTANCE & ARCHIVE — per CHANGE · user-observable gate, then human archive 13 · Verify 👤 gate observe only PASS / FAIL PASS ✓ 14 👤 HUMAN / loop-archive Archive delta specs → specs/ /opsx:archive ✓ change archived FAIL spec-shaped FAIL → /escalate · bug-shaped FAIL → /diagnose reopens upstream — NEVER an inline fix; a FAIL can re-open already-committed tasks OFF-PIPELINE (not in the linear flow) /contract-coverage-critic — independent critic reconstructs ∀-obligations, flags coverage gaps as un-ratified grill-input. HUMAN-GATED only — never wired into the loop.

Who acts (four actors)

  • 👤 Human — answers interviews, accepts ADRs, archives, pushes
  • 🟢 Agent · interview — Socratic; human answers, agent writes (steps 1–4, 13)
  • 🟣 Agent · autonomous — loop roles, emit a machine-readable line (6–9, 11–12)
  • ⚙ Script — dispatch-loop.sh: state, git, ticking, routing (step 10); never judges

Decision points & branches

  • Diagnose: ≤2 files → hotfix path · else structural → /new
  • Review (4-way): approve→commit · blocker→fix · structural_blocker / needs_adjudication → hard stop
  • Fix cap: 3 rounds, then Escalate the spec → hard stop
  • Verify: PASS→archive · FAIL→escalate (spec) or diagnose (bug)

Guardrails / hard rules

  • Spec frozen before any code; loop agents can't write openspec/
  • ADRs immutable & human-accepted; adr/ + push are human-only
  • Agent never ticks its own acceptance — the script does, on the verdict
  • Backlog cap 50 passes; hard stops exit 125 for a human

Intent-driven OpenSpec schema · derived from .claude/commands/*, dispatch-loop.sh, openspec/AGENTS.md