Skip to content
specdacular

Pipeline Lifecycle

Every task moves through the same pipeline. This page explains each stage, what it produces, and what the brain does between stages.

Overview

Section titled “Overview”
/specd.new              → Discussion
/specd.continue         → Research
                        → Planning
                        → Phase Execution (loop)
                            ├── Phase Plan
                            ├── Execute
                            ├── Review
                            └── Revise (if needed)
                        → Complete

The pipeline is config-driven — defined in pipeline.json and loaded fresh on every continue invocation. Nothing is hardcoded in the brain. See Pipeline customization to modify it.

Stage 1: Discussion

Section titled “Stage 1: Discussion”

Triggered by: /specd.new

What happens: Claude asks “What are you building?” and follows the thread. It probes for:

  • What the feature creates or modifies
  • Integration points with existing code
  • Constraints and explicit non-goals
  • Decisions that are already made

Output:

  • FEATURE.md — Technical requirements
  • CONTEXT.md — Discussion transcript (accumulates over sessions)
  • DECISIONS.md — Decisions with date, rationale, and implications

State after: stage: "discussion"

Brain routing: After discussion, the brain checks CONTEXT.md for unresolved gray areas. If none remain, it advances to research. If the discussion is sparse or incomplete, it offers another round of discussion.

Stage 2: Research

Section titled “Stage 2: Research”

Triggered by: First continue after discussion completes

What happens: Three parallel agents run simultaneously:

AgentFocusExplores
Codebase integrationHow does this fit the existing codebase?MAP.md, PATTERNS.md, relevant source files
External patternsWhat are established approaches?Stack-specific patterns, library docs, conventions
PitfallsWhat goes wrong?Common mistakes, security concerns, edge cases

Each agent writes findings to RESEARCH.md. The orchestrating brain collects confirmations and produces a synthesis.

Output: RESEARCH.md

State after: stage: "research"

Brain routing: Research always advances to planning. The brain doesn’t loop back here unless you use /specd.toolbox to re-run research explicitly (e.g., after a scope change).

Smart skip: In default and auto modes, research is skipped for very simple tasks — few files, clear requirements, no external dependencies.

Stage 3: Planning

Section titled “Stage 3: Planning”

Triggered by: continue after research

What happens: Claude synthesizes discussion + research into a phased roadmap. Phases are derived from dependency analysis — work that must happen before other work starts a new phase.

Output: ROADMAP.md

The roadmap contains phase goals only — not detailed implementation plans. Detailed plans are created just-in-time in phase execution. This keeps later phases fresh — they can adapt based on what was learned in earlier ones.

State after: stage: "execution", phases.count: N, phases.current: 1

Brain routing: After planning, the brain enters the phase-execution sub-pipeline.

Stage 4: Phase Execution

Section titled “Stage 4: Phase Execution”

Phase execution is a nested sub-pipeline that loops once per phase.

4a. Phase Plan

Section titled “4a. Phase Plan”

What happens: The brain reads the current phase’s goal from ROADMAP.md and creates a detailed PLAN.md. This is the actual prompt the implementing agent will receive — it must be complete enough to implement without asking questions.

Output: phases/phase-{N}/PLAN.md

State: Phase status stays "pending" but with PLAN.md present, the brain routes to execute.

4b. Execute

Section titled “4b. Execute”

What happens: An implementing agent reads PLAN.md and implements the phase. It commits after completing each task within the phase. Progress is tracked in CHANGELOG.md.

Default mode behavior: The brain pauses before dispatching execute:

Current state: phase 2 of 4 — Phase Plan complete
Execute, Review plan, or Stop for now?

Output: Implemented code committed to git, CHANGELOG.md updated

State after: phases.current_status: "executed"

4c. Review

Section titled “4c. Review”

What happens: A code review agent compares the executed code against the plan intent. It checks:

  • Were all plan requirements implemented?
  • Does the code follow codebase patterns from PATTERNS.md?
  • Are there obvious bugs, missing error handling, or security issues?
  • Do the changes integrate cleanly with the rest of the codebase?

The review agent produces a structured report. You then decide:

  • Approve — Phase is done, advance to next phase
  • Request fixes — Review creates fix plans

State after (approved): phases.current_status: "completed", advance to next phase State after (fix requested): Create phases/phase-{N}.1/PLAN.md, set status to "pending" fix

4d. Revise (if needed)

Section titled “4d. Revise (if needed)”

What happens: When review requests fixes, the revise step creates decimal fix phases. For phase 1 with issues, it creates phases/phase-01.1/. The brain loops back to execute this fix plan.

Fix phases can themselves be reviewed and revised, generating phase-01.2, phase-01.3, etc., until the review approves.

Output: phases/phase-{N}.{M}/PLAN.md

State after: phases.current_status: "pending" (pointing at the decimal phase)

Phase advancement

Section titled “Phase advancement”

After each phase is approved:

phases.current += 1
phases.current_status = "pending"
phases.phase_start_commit = null

The brain loops back into the phase-execution sub-pipeline for the next phase. Later phases have full visibility into what was implemented in earlier phases — their just-in-time plans can adapt accordingly.

Stage 5: Complete

Section titled “Stage 5: Complete”

When all phases are approved, the task is complete:

stage: "complete"

The brain presents a completion summary and exits. The task remains in .specd/tasks/ as a permanent record.

Resumability

Section titled “Resumability”

State is saved before every dispatch. Tasks can be stopped at any point and resumed with /specd.continue:

/specd.continue user-dashboard

The brain reads config.json, determines the current position, and picks up from there.

Files produced across the lifecycle

Section titled “Files produced across the lifecycle”
StageFiles created
newFEATURE.md, CONTEXT.md, DECISIONS.md, CHANGELOG.md, STATE.md, config.json
researchRESEARCH.md
planningROADMAP.md
phase-planphases/phase-{N}/PLAN.md
executeUpdated CHANGELOG.md, committed code
reviewReview report (inline in STATE.md)
revisephases/phase-{N}.{M}/PLAN.md
Section titled “Related”