Spec Pipeline

Turn a product overview into a full reference spec — data model, API contracts, UX flows, and squad-ready stories — one scope at a time.

Overview

The spec pipeline sits upstream of the Squad Workflow. Run /spec to break your product overview into scopes, then spec each scope into a SPEC.md that the squad pipeline can build from directly.

Each run is a single inline CTO pass — no sub-agents, no revision rounds. The CTO reads the overview and any prior scope specs (for consistency), then writes the full spec for that scope in one pass. Fast, low token cost, and the output includes copy-paste /squad commands for every story.

How it works

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

2. Each run specs one scope — data model, API contracts, UX flows, story list with squad commands

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

Usage

First run — initialization

/spec
# Finds PROJECT_OVERVIEW.md (or asks you to pick)
# CTO identifies all scopes → writes spec/PROGRESS.md
# Immediately specs scope 01

Continuing — next scope

/spec
# Reads spec/PROGRESS.md → picks the next unchecked scope

Target a specific scope

/spec 03-invoicing-payments

Re-run a completed scope

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

Start from a specific file

/spec MY_OVERVIEW.md
# Uses that file as the session source — prompts before archiving any existing spec

Append a new scope

/spec --add analytics
# Adds 05-analytics to PROGRESS.md and specs it immediately

Add stories to an existing scope

/spec --extend 02-jobs-scheduling
# Identifies new stories not already in the scope, appends them to Stories + Squad Commands
# Data model, API contracts, and UX flows are left untouched

Overnight batch — all remaining scopes

/loop /clear /spec                                # Claude Code
/goal complete every remaining scope via /spec    # Codex
# Runs each unchecked scope in sequence, context cleared between each
# Stops automatically when all scopes are done

Re-run a completed scope

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

Reset everything

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

Sessions & Archiving

The overview file you use is the session identity — it's saved as source: in spec/PROGRESS.md. Passing the same file always resumes the same session with no prompts.

When you pass a different .md file and existing progress is detected, /spec confirms before doing anything:

Found existing spec from PROJECT_OVERVIEW.md (3 of 5 scopes done).
Archive it and start fresh with NEW_FEATURE.md? (yes/no)

yes — renames spec/ to spec-archived-[timestamp]/ and starts fresh. Old work is preserved, just out of the way.

no — stops. Run /spec to continue the existing session, or /spec --reset to clear it manually.

Output Structure

Each scope produces one SPEC.md. Progress and index files track the full project.

spec/
  PROGRESS.md              ← scope checklist — updated after each run
  INDEX.md                 ← links to every completed SPEC.md

  01-identity-auth/
    SPEC.md                ← full spec for this scope

  02-jobs-scheduling/
    SPEC.md

  03-invoicing-payments/
    SPEC.md

Cross-scope consistency

Every spec run reads all previously completed SPEC.md files before writing the next one. Entities and API conventions defined in scope 01 are respected by scope 02 — no redefinitions, no contradictions.

What SPEC.md Contains

Every SPEC.md is a self-contained reference document. It covers all domains needed to implement the scope — no separate files, no switching between documents.

Section	What it contains
Summary	2–3 sentences on what this scope covers and what the team will ship
Personas	Who uses this scope and what they need from it
Data Model	Full schema — columns, types, indexes, constraints, ERD, multi-tenancy enforcement, data lifecycle
API Contracts	Every endpoint with request/response shapes, auth role, and error codes
UX Flows	Key user journeys — goal, steps, success state, and edge cases that affect implementation
Stories	Story table with size and dependencies, plus copy-paste `/squad` commands for each story
Open Questions	Unresolved items — what they block and who needs to decide
Out of Scope	Features explicitly deferred, with the scope they belong to

ASSUMPTION: markers

When the CTO fills in detail not explicit in the overview, it marks the claim inline with ASSUMPTION: [what] — [why]. Review these before building — assumptions in the spec become bugs if they're wrong.

Overview File Detection

You can pass the overview file explicitly or let /spec find it automatically.

Pass it explicitly

/spec MY_OVERVIEW.md

Any argument ending in .md is treated as an overview file, not a scope slug. See Sessions & Archiving for what happens if existing progress is detected.

Auto-detection (no argument)

On first run with no argument, /spec looks for these filenames in the project root:

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. The path is saved in spec/PROGRESS.md — you never need to specify it again on subsequent runs.

From Spec to Squad

Each SPEC.md ends with a ### Squad Commands section — copy-paste /squad commands for every story, self-contained enough to run without reading the spec.

Option 1 — run stories one at a time

# Copy a command from spec/01-identity-auth/SPEC.md → Squad Commands
/squad "S1 — Workspace schema: create workspaces table with RLS policies"
/squad-auto

Option 2 — run all stories continuously with /squad-spec

/loop /clear /squad-spec 01-identity-auth                              # Claude Code
/goal complete every story in scope 01-identity-auth via /squad-spec   # Codex
# Processes every story in the scope — one per iteration,
# context cleared between each so it never bloats

Learn about Squad Workflow

Squad Workflow

CI Squad

Was this helpful?

Help us improve the documentation by sharing your feedback.