Spec Consensus

Multi-agent spec generation with consensus. Uses Claude and Codex CLIs in parallel iTerm2 tabs to produce high-quality technical specifications through a 3-phase pipeline.

Pipeline

Phase 1 (parallel)          Phase 2 (parallel)          Phase 3
┌──────────────┐           ┌─────────────────────┐     ┌──────────────────┐
│ Claude: Spec A│──────────▶│ Claude: Consensus │────▶│                  │
└──────────────┘     ╲     └─────────────────────┘  ╲  │ Claude: Final    │
                      ╳                               ╳ │ Arbiter        │
┌──────────────┐     ╱     ┌─────────────────────┐  ╱  │                  │
│ Codex: Spec B │──────────▶│ Codex: Consensus  │────▶│                  │
└──────────────┘           └─────────────────────┘     └──────────────────┘
                                                        ▼
                                                     final_spec.md

Prerequisites

• iTerm (must be running)
• claude CLI (authenticated)
• codex CLI (authenticated)
• python3 (standard macOS)

Usage

./spec-consensus "Create a detailed technical spec for <your feature>"

Examples

./spec-consensus "Add WebSocket-based real-time notifications to the dashboard"

./spec-consensus "Migrate the user auth system from session cookies to JWT with refresh tokens"

./spec-consensus "Build a CLI tool that generates OpenAPI specs from Go struct annotations"

What happens

1. Two iTerm tabs open — Claude and Codex each generate a draft spec independently
2. The orchestrator waits for both (file-based polling with timeout)
3. Two more tabs open — each agent reads both drafts and produces a consensus merge
4. One final tab opens — Claude reads both consensus specs and produces the authoritative final spec
5. The final spec path is printed in the original terminal

All tabs stay open so you can inspect output and scroll through agent activity.

Output

Everything goes into .spec-consensus/runs/<timestamp>/:

File	Description
feature_request.txt	Your original request
spec_a.md	Claude's draft spec
spec_b.md	Codex's draft spec
consensus_claude.md	Claude's consensus merge
consensus_codex.md	Codex's consensus merge
final_spec.md	Final authoritative spec
done_*.json	Completion sentinels with status/timestamps
full_prompt_*.txt	Full prompts sent to each agent (for debugging)
*.log	stderr/progress logs

Configuration

Edit the top of spec-consensus to change timeouts:

PHASE1_TIMEOUT=900    # 15 min
PHASE2_TIMEOUT=900    # 15 min
PHASE3_TIMEOUT=900    # 15 min
POLL_INTERVAL=3       # seconds

Prompt templates

Templates are in .spec-consensus/prompts/. Edit them to adjust what the agents produce:

• spec_draft.txt — Phase 1 instructions
• consensus_review.txt — Phase 2 merge instructions
• final_arbiter.txt — Phase 3 final arbiter instructions