Skip to content
specdacular

The Orchestrator (Brain)

The brain is specdacular’s central orchestrator. It reads pipeline.json, determines the next step from task state, dispatches step workflows, executes hooks, updates state, and loops. All flow control lives here.

Design principle

Section titled “Design principle”

Step workflows are pure execution — they do their work and return. They never decide what comes next. That’s exclusively the brain’s job.

This separation means:

  • Any step can be replaced without touching control flow
  • Hooks can modify state between steps without special treatment
  • Execution modes (default, interactive, auto) are handled in one place

The brain loop

Section titled “The brain loop”
┌─────────────────────────────────────────────┐
│                    BRAIN                    │
│                                             │
│  1. Read state (config.json, STATE.md)      │
│  2. Determine next step from pipeline       │
│  3. Pre-hooks → step workflow → post-hooks  │
│  4. Update state                            │
│  5. Loop back to 1                          │
└─────────────────────────────────────────────┘

State is persisted before each dispatch. If a session ends mid-execution, the next continue picks up from the last saved state.

State machine

Section titled “State machine”

The brain maintains a state machine across the task lifecycle. Each stage maps to a step in the pipeline:

discussion → research → planning → execution → complete

Within execution, there’s a nested sub-pipeline per phase:

phase-plan → execute → review → revise → (next phase)

State is stored in two files:

  • config.json — Machine-readable: stage, phase number, phase status, timestamps
  • STATE.md — Human-readable: current position, next actions, plan completion table

Routing logic

Section titled “Routing logic”

On each loop iteration, the brain determines $NEXT_STEP by reading the task’s current state:

Current stateNext step
Stage: discussion, gray areas remaindiscuss
Stage: discussion, all resolvedresearch
Stage: researchplan (task-level)
Stage: planningphase-execution pipeline
Phase status: pending, no PLAN.mdphase-plan
Phase status: pending, PLAN.md existsexecute
Phase status: executedreview
Phase status: needs-revisionrevise
Phase status: completed, more phasesadvance phase, phase-plan
Phase status: completed, no more phasestask complete

Execution modes

Section titled “Execution modes”

The brain supports three modes, passed as flags to /specd.continue:

Default mode

Section titled “Default mode”

Auto-runs steps that don’t have pause: true. Pauses before steps marked pause: true (execute and review in the default pipeline). Smart-skips steps that add no value:

  • discuss: skipped if no gray areas remain in CONTEXT.md
  • research: skipped for simple tasks with clear requirements and no external dependencies

Interactive mode (--interactive)

Section titled “Interactive mode (--interactive)”

Prompts at every stage transition, regardless of the pause field. At each step, presents options:

  • The recommended action (the natural next step)
  • Skip options (e.g., “Skip to planning”)
  • Jump options (e.g., “Discuss more”)

Does not auto-skip steps — instead marks the skip option as “Recommended” if skipping is appropriate.

Auto mode (--auto)

Section titled “Auto mode (--auto)”

Runs the entire pipeline without prompting. Applies smart skipping. Stops only on:

  • Pipeline errors
  • Required hook failures
  • Task completion

Useful for fully automated execution in CI environments or when you trust the pipeline to handle everything.

Hook execution

Section titled “Hook execution”

The brain executes hooks at four points around each step:

Global pre-step hook
        │
Step pre-hook
        │
        ▼
   Step runs
        │
Step post-hook
        │
Global post-step hook

Hooks are markdown workflow files — the same format as step workflows. They can read and modify task files, commit changes, or call external services.

Required hooks (optional: false) stop the pipeline on failure. Optional hooks log a warning and continue.

See Pipeline customization for hook configuration.

Orchestrator mode (multi-project)

Section titled “Orchestrator mode (multi-project)”

When the root .specd/config.json has "type": "orchestrator", the brain operates in orchestrator mode. The pipeline is the same — orchestrator awareness lives in the step workflows that need it:

  • new.md detects orchestrator mode and creates per-project tasks
  • plan.md detects orchestrator mode and creates DEPENDENCIES.md
  • execute.md reads DEPENDENCIES.md to schedule phases across projects in dependency order

The brain itself doesn’t change routing logic for orchestrator mode. Multi-project complexity is encapsulated in the step workflows.

Pipeline resolution

Section titled “Pipeline resolution”

On each invocation, the brain resolves the pipeline in this order:

  1. Check .specd/pipeline.json (project-level override — full replace)
  2. Fall back to the installed default pipeline.json

Validation checks:

  • schema_version is "1.0"
  • All referenced workflow paths exist
  • All referenced pipeline names exist
  • No circular pipeline references

State persistence

Section titled “State persistence”

Before dispatching any step, the brain commits:

docs({task-name}): starting {step-name}

After the step completes, it commits:

docs({task-name}): {step-name} complete

This creates a dense git history that doubles as an audit trail. If a session ends between these two commits, the brain detects the incomplete state on next invocation and re-dispatches the step.

Section titled “Related concepts”