Workflows are multi-step, resumable automation pipelines defined in YAML. They orchestrate Spec Kit commands across integrations, evaluate control flow, and pause at human review gates — enabling end-to-end Spec-Driven Development cycles without manual step-by-step invocation.

A workflow definition declares a sequence of steps. The engine executes them in order, dispatching commands to AI integrations, running shell commands, evaluating conditions for branching, and pausing at gates for human review. State is persisted after each step, so workflows can be resumed after interruption.

steps:
  - id: specify
    command: speckit.specify
    input:
      args: "{{ inputs.spec }}"

  - id: review
    type: gate
    message: "Review the spec before planning."
    options: [approve, reject]
    on_reject: abort

  - id: plan
    command: speckit.plan

For detailed architecture and internals, see ARCHITECTURE.md.

# Search available workflows
specify workflow search

# Install the built-in SDD workflow
specify workflow add speckit

# Or run directly from a local YAML file
specify workflow run ./workflow.yml --input spec="Build a user authentication system with OAuth support"

# Run an installed workflow with inputs
specify workflow run speckit --input spec="Build a user authentication system with OAuth support"

# Check run status
specify workflow status

# Resume after a gate pause
specify workflow resume <run_id>

# Get detailed workflow info
specify workflow info speckit

# Remove a workflow
specify workflow remove speckit

specify workflow add speckit
specify workflow run speckit --input spec="Build a user authentication system with OAuth support"

specify workflow run ./my-workflow.yml --input spec="Build a user authentication system with OAuth support"

specify workflow run speckit \
  --input spec="Build a user authentication system with OAuth support" \
  --input scope="backend-only"

Workflows support 10 built-in step types:

Invoke an installed Spec Kit command by name via the integration CLI:

- id: specify
  command: speckit.specify
  input:
    args: "{{ inputs.spec }}"
  integration: claude        # Optional: override workflow default
  model: "claude-sonnet-4-20250514"   # Optional: override model

Send an arbitrary inline prompt to an integration CLI (no command file needed):

- id: security-review
  type: prompt
  prompt: "Review {{ inputs.file }} for security vulnerabilities"
  integration: claude

Run a shell command and capture output:

- id: run-tests
  type: shell
  run: "cd {{ inputs.project_dir }} && npm test"

Pause for human review. The workflow resumes when specify workflow resume is called:

- id: review-spec
  type: gate
  message: "Review the generated spec before planning."
  options: [approve, edit, reject]
  on_reject: abort

Conditional branching based on an expression:

- id: check-scope
  type: if
  condition: "{{ inputs.scope == 'full' }}"
  then:
    - id: full-plan
      command: speckit.plan
  else:
    - id: quick-plan
      command: speckit.plan
      options:
        quick: true

Multi-branch dispatch on an expression value:

- id: route
  type: switch
  expression: "{{ steps.review.output.choice }}"
  cases:
    approve:
      - id: plan
        command: speckit.plan
    reject:
      - id: log
        type: shell
        run: "echo 'Rejected'"
  default:
    - id: fallback
      type: gate
      message: "Unexpected choice"

Repeat steps while a condition is truthy:

- id: retry
  type: while
  condition: "{{ steps.run-tests.output.exit_code != 0 }}"
  max_iterations: 5
  steps:
    - id: fix
      command: speckit.implement

Execute steps at least once, then repeat while condition holds:

- id: refine
  type: do-while
  condition: "{{ steps.review.output.choice == 'edit' }}"
  max_iterations: 3
  steps:
    - id: revise
      command: speckit.specify

Dispatch a step template for each item in a collection (sequential):

- id: parallel-impl
  type: fan-out
  items: "{{ steps.tasks.output.task_list }}"
  max_concurrency: 3
  step:
    id: impl
    command: speckit.implement

Aggregate results from fan-out steps:

- id: collect
  type: fan-in
  wait_for: [parallel-impl]
  output: {}

By default, any step that returns StepResult(status=StepStatus.FAILED, ...) at runtime halts the entire run — most commonly a shell or command step exiting non-zero. Set continue_on_error: true on a step to record its result and continue to the next sibling step instead. When the failure was a non-zero exit, the exit code remains available on steps.<id>.output.exit_code so a downstream if or switch can branch on it (or a gate can surface it to the operator via {{ }} interpolation in message):

- id: heavy-thing
  type: command
  integration: claude
  command: speckit.heavy-thing
  continue_on_error: true

- id: check-result
  type: if
  condition: "{{ steps.heavy-thing.output.exit_code != 0 }}"
  then:
    - id: review
      type: gate
      message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Approve to run the recovery path, or reject to leave the failure recorded and move on."
      on_reject: skip
    - id: recover
      type: if
      condition: "{{ steps.review.output.choice == 'approve' }}"
      then:
        - id: rerun
          command: speckit.recovery
  else:
    - id: next-thing
      command: speckit.next-thing

A few things worth knowing about that example:

• Both gate options (approve, reject) return StepStatus.COMPLETED; on_reject: skip controls only whether the engine aborts on reject (it doesn't, with skip) — it does not auto-skip subsequent sibling steps in the then: list. Downstream branching is the workflow author's responsibility: read {{ steps.<gate-id>.output.choice }} in a follow-up if, switch, or expression, as the recover step above does.
• on_reject has three values: abort (default — reject → StepStatus.FAILED with output.aborted = True, halts the run), skip (reject → StepStatus.COMPLETED, author handles branching as shown), and retry (reject → StepStatus.PAUSED so the next specify workflow resume re-runs the gate).
• Gates do not automatically re-run the failed step. To express a retry path, either define custom gate options and branch on the choice downstream, or wrap the failing step in your own loop.

Notes:

• The field must be a literal boolean (true / false); coerced strings like "true" are rejected at validation time.
• Scope: returned failures only. The flag applies to step results with status=StepStatus.FAILED. Unhandled exceptions raised out of a step's execute() method are caught one level up by WorkflowEngine.execute(), logged as workflow_failed, and abort the run regardless of continue_on_error. If a step author wants the flag to cover an exceptional path, the step must catch the exception internally and return StepResult(status=StepStatus.FAILED, ...) with the failure encoded in output (e.g. exit_code, stderr, or a custom field).
• Gate aborts (on_reject: abort chosen by the operator) always halt the run — continue_on_error does not override them. The flag is for transient/expected step failures, not for overriding deliberate operator decisions.
• Structural validation runs up-front: specify workflow run rejects invalid workflow definitions before the run is created, so validation failures never reach this code path.
• When the flag is omitted, behaviour is byte-equivalent to before this feature.

Workflow definitions use {{ expression }} syntax for dynamic values:

# Access inputs
args: "{{ inputs.spec }}"

# Access previous step outputs
args: "{{ steps.specify.output.file }}"

# Comparisons
condition: "{{ steps.run-tests.output.exit_code != 0 }}"

# Filters
message: "{{ status | default('pending') }}"

Supported filters: default, join, contains, map.

{{ context.* }} exposes engine-managed runtime metadata for the current run:

# Stamp telemetry events with the run id for cross-system join.
- id: emit-event
  type: shell
  run: 'echo "{\"run_id\":\"{{ context.run_id }}\",\"event\":\"started\"}" >> events.jsonl'

# Per-run scratch directory.
- id: prep-scratch
  type: shell
  run: 'mkdir -p /tmp/run-{{ context.run_id }}'

# Pass run id into a command for artifact metadata.
- id: tag-artifact
  command: speckit.specify
  input:
    args: "{{ context.run_id }}"

Workflow inputs are type-checked and coerced from CLI string values:

inputs:
  spec:
    type: string
    required: true
    prompt: "Describe what you want to build"
  task_count:
    type: number
    default: 5
  dry_run:
    type: boolean
    default: false
  scope:
    type: string
    default: "full"
    enum: ["full", "backend-only", "frontend-only"]

Every workflow run persists state to .specify/workflows/runs/<run_id>/:

# List all runs with status
specify workflow status

# Check a specific run
specify workflow status <run_id>

# Resume a paused run (after approving a gate)
specify workflow resume <run_id>

# Resume a failed run (retries from the failed step)
specify workflow resume <run_id>

Run states: created → running → completed | paused | failed | aborted

Workflows are discovered through catalogs. By default, Spec Kit uses the official and community catalogs:

# List active catalogs
specify workflow catalog list

# Add a custom catalog
specify workflow catalog add https://example.com/catalog.json --name my-org

# Remove a catalog
specify workflow catalog remove <index>

1. Create a workflow.yml following the schema above
2. Test locally with specify workflow run ./workflow.yml --input key=value
3. Verify with specify workflow info ./workflow.yml
4. See PUBLISHING.md to submit to the catalog

workflows/
├── ARCHITECTURE.md                         # Internal architecture documentation
├── PUBLISHING.md                           # Guide for submitting workflows to the catalog
├── README.md                               # This file
├── catalog.json                            # Official workflow catalog
├── catalog.community.json                  # Community workflow catalog
└── speckit/                                # Built-in SDD cycle workflow
    └── workflow.yml