Spec Pipeline

Turn a high-level product overview into an implementation-ready spec — UX flows, DB schema, API contracts, and a phased build plan — before a single line of code is written.

Overview

The spec pipeline sits upstream of the Squad Workflow. Squad assumes stories are ready to implement. Spec produces those stories — and the full technical context that makes them implementable — from a product overview document.

It works scope by scope. Each run takes one area of the product (e.g. identity & auth, invoicing, marketplace), runs four domain experts in parallel, challenges their output through a CTO persona, and produces a unified SPEC.md that a developer can build from directly.

How it works

1. On first run, a CTO agent reads your product overview and identifies all logical scopes

2. Each run processes one scope — brief → 4 domain experts → CTO challenges → revisions → final SPEC.md

3. Run /spec again to continue with the next scope — progress is tracked automatically

Pipeline Personas

Each persona is a sub-agent with a specific role. The CTO persona appears three times — as scoper, challenger, and author — because it holds the most context across all rounds.

Round	Persona	What it does
Init (once)	CTO — Scoper	Reads the full product overview, identifies logical scopes, writes `spec/PROGRESS.md`
Round 0	CTO — Briefer	Defines scope boundaries, surfaces key constraints, writes questions each domain must answer
Round 1	UX Architect	Maps all user flows and screens — entry points, steps, edge cases, empty states, mobile differences
Round 1	Data Architect	Designs the full DB schema — entities, columns, indexes, relationships (ERD), multi-tenancy, data lifecycle
Round 1	Systems Architect	Defines API contracts, auth model, external services, background jobs, file storage
Round 1	Build Planner	Phases the work into epics and stories with specific, testable acceptance criteria and a risk register
Round 2	CTO — Challenger	Reads all four sections, challenges gaps and cross-section conflicts, writes `05-challenges.md`
Round 3	All four domains	Each agent revises their section based on the CTO's challenges. Unresolvable items are flagged as OPEN DECISIONs
Final	CTO — Author	Resolves all OPEN DECISIONs, writes the unified `SPEC.md`, updates PROGRESS.md and INDEX.md

Round 1 and Round 3 agents run in parallel — all four spawn simultaneously. Round 2 (challenges) and the Final (author) are sequential because they need all prior outputs.

Usage

First run — initialization

/spec
# Finds PROJECT_OVERVIEW.md (or asks you to pick)
# CTO scoper identifies all scopes → writes spec/PROGRESS.md
# Immediately runs the full pipeline for scope 01

Continuing — next scope

/spec
# Reads spec/PROGRESS.md
# Picks the next unchecked scope and runs the full pipeline

Target a specific scope

/spec 03-invoicing-payments
# Runs the pipeline for that scope directly, regardless of order

Re-run a completed scope

/spec --redo 01-identity-auth
# Deletes the scope folder and reruns all rounds from scratch

Reset everything

/spec --reset
# Confirms with you first, then deletes the entire spec/ folder

Output Structure

Every scope produces a folder with all working artifacts preserved alongside the final SPEC.md. Nothing is deleted — you can always see how the CTO challenged the initial sections and what changed in revision.

spec/
  PROGRESS.md              ← scope checklist — updated after each run
  INDEX.md                 ← master TOC linking all SPEC.md files

  01-identity-auth/
    00-brief.md            ← CTO's scoping brief (Round 0)
    01-ux.md               ← UX flows and screens (revised in Round 3)
    02-data.md             ← DB schema and relationships (revised in Round 3)
    03-systems.md          ← API contracts and services (revised in Round 3)
    04-plan.md             ← build phases and stories (revised in Round 3)
    05-challenges.md       ← CTO's challenges (Round 2)
    SPEC.md                ← final unified spec for this scope

  02-jobs-scheduling/
    ...

  03-invoicing-payments/
    ...

PROGRESS.md

Tracks which scopes are done and which are pending. The orchestrator reads this at the start of every /spec run. The source: field records which overview file was used, so you never have to specify it again.

How Rounds Work

The back-and-forth between rounds is what makes the output implementation-ready. Domain experts making decisions in isolation often contradict each other — the challenge round surfaces those contradictions before they become code.

Round 0 — Brief

The CTO reads the product overview and prior scope specs, then writes a brief that all four domain agents share. The brief defines scope boundaries, constraints, and specific questions each domain must answer. This prevents agents from making conflicting assumptions about the same part of the product.

Round 1 — Domain Experts (parallel)

All four agents spawn simultaneously. Each reads the brief and the product overview, then produces their full section. They don't read each other's output — they work from the same brief independently.

Round 2 — CTO Challenges

The CTO reads all four sections and produces a challenge file — one section per domain plus a cross-cutting conflicts section. Challenges are specific: "The UX assumes paginated job lists but the data spec has no index on workspace_id + created_at." Generic observations are excluded.

Round 3 — Revisions (parallel)

Each domain agent reads its own section and the challenges relevant to its domain, then revises in place. Items that need a decision from another domain are marked OPEN DECISION: [question] — needs Data / Systems.

Final — CTO Author

The CTO reads all revised sections, resolves every OPEN DECISION with a call and one-line reasoning, then writes the unified SPEC.md. The CTO decisions table at the bottom of each SPEC.md shows exactly what was resolved and why.

Overview File Detection

On first run, /spec looks for a product overview file automatically. It checks these names in order:

PROJECT_OVERVIEW.md
OVERVIEW.md
PRODUCT_OVERVIEW.md
BRIEF.md
product-brief.md

If one is found it's used automatically. If multiple match, you're asked to pick. If none match, all .md files in the current directory are listed and you select the one that is your product overview.

Once selected, the path is saved in spec/PROGRESS.md under source:. All subsequent runs read it from there — you never need to specify it again.

From Spec to Squad

The spec pipeline produces the input that the squad pipeline consumes. Once a scope's SPEC.md is complete, feed its build plan stories into /squad one at a time:

# 1. Run /spec until all scopes are done
/spec   # scope 01
/spec   # scope 02
/spec   # scope 03 ... and so on

# 2. Open spec/01-identity-auth/SPEC.md
#    Pick a story from the Build Plan section

# 3. Hand it to /squad
/squad "implement workspace creation — tradie signs up, workspace is created, they land on the empty dashboard"

# 4. /squad-auto runs architect → dev → test → review → doc

The spec's data model, API contracts, and acceptance criteria all become reference material for the squad's Architect and Developer agents — either by pasting relevant sections or by pointing the agents to the spec files directly.

Learn about Squad Workflow

Squad Workflow

CI Squad

Was this helpful?

Help us improve the documentation by sharing your feedback.