# Workflows Workflows automate multi-step Spec-Driven Development processes — chaining commands, prompts, shell steps, and human checkpoints into repeatable sequences. They support conditional logic, loops, fan-out/fan-in, and can be paused and resumed from the exact point of interruption. ## Run a Workflow ```bash specify workflow run ``` | Option | Description | | ------------------- | -------------------------------------------------------- | | `-i` / `--input` | Pass input values as `key=value` (repeatable) | | `--json` | Emit the run outcome as a single JSON object | Runs a workflow from a catalog ID, URL, or local file path. Inputs declared by the workflow can be provided via `--input` or will be prompted interactively. Example: ```bash specify workflow run speckit -i spec="Build a kanban board with drag-and-drop task management" ``` With `--json`, a single machine-readable object is printed instead of formatted text (the default output is unchanged when the flag is omitted): ```bash specify workflow run my-pipeline.yml --json ``` ```json { "run_id": "662bf791", "workflow_id": "build-and-review", "status": "paused", "current_step_id": "review", "current_step_index": 0 } ``` `workflow_id` is the `workflow.id` declared inside the YAML, not the file name. The object is printed exactly as shown — pretty-printed with two-space indentation, on plain stdout with no Rich markup — so it always parses. While the workflow runs under `--json`, any progress a step would print (for example a gate prompt, or output from a prompt step's CLI subprocess) is redirected to stderr, so stdout carries only the JSON object. Read the object from stdout; leave stderr attached to the terminal or capture it separately. For `failed` and `aborted` runs, the payload includes an `error` field carrying the terminal step's error message: ```json { "run_id": "662bf791", "workflow_id": "build-and-review", "status": "failed", "current_step_id": "boom", "current_step_index": 0, "error": "Command exited with code 3" } ``` `completed` and `paused` runs omit the `error` field. The error is persisted in the run's `state.json`, so `specify workflow status --json` surfaces the same message after the fact. > **Note:** Most workflow commands require a project already initialized with `specify init`. The exception is `specify workflow run `, which can run outside a project; in that case, run state is stored under the current directory's `.specify/workflows/runs//`. ## Resume a Workflow ```bash specify workflow resume ``` | Option | Description | | ------------------- | -------------------------------------------------------- | | `-i` / `--input` | Updated input values as `key=value` (repeatable) | | `--json` | Emit the resume outcome as a single JSON object | Resumes a paused or failed workflow run from the exact step where it stopped. Useful after responding to a gate step or fixing an issue that caused a failure. Supplied `--input` values are merged over the run's stored inputs and re-validated against the workflow's input types, then the blocked step is re-run with the updated values. This lets a run continue with information that only became available after it paused, or with a corrected value after a failure: ```bash specify workflow resume --input cmd="exit 0" ``` ## Workflow Status ```bash specify workflow status [] ``` | Option | Description | | ------------------- | -------------------------------------------------------- | | `--json` | Emit run status (or the runs list) as a JSON object | Shows the status of a specific run, or lists all runs if no ID is given. Run states: `created`, `running`, `completed`, `paused`, `failed`, `aborted`. ## List Installed Workflows ```bash specify workflow list ``` Lists workflows installed in the current project. ## Install a Workflow ```bash specify workflow add ``` | Option | Description | | --------------- | ------------------------------------------------------ | | `--dev` | Install from a local YAML file, package directory, or archive | | `--from ` | Install from a custom URL (`` names the expected workflow ID) | Installs a workflow from the catalog, an HTTPS URL, a local YAML file, a directory containing `workflow.yml`, or a `.zip`, `.tar.gz`, or `.tgz` archive. Archives may contain `workflow.yml` at the root or inside one top-level directory. Directory and archive installs preserve the complete workflow package, including scripts and other companion files. ZIP, `.tar.gz`, and `.tgz` archives follow the same validation and installation behavior. ## Workflow Overlays Workflow overlays let a project extend or override an installed workflow without editing the installed `workflow.yml`. This keeps local customizations safe across `specify bundle update` or `specify workflow add` upgrades. When `specify workflow run ` loads a workflow, the engine composes the base workflow with all enabled overlays for that workflow id. The result is validated like any other workflow definition. ### How Overlays Work An overlay is a YAML file that declares a set of edit operations against the step list of a base workflow. Overlays use lower-wins precedence: higher priority numbers are applied first and lower numbers last. Equal-priority overlays are applied alphabetically by ID, with the last ID winning conflicts. Project overlay files live at: | Location | Purpose | | --- | --- | | `.specify/workflows/overlays//*.yml` | Project-local customizations | ### Overlay File Format The recommended edit format uses the operation name as the key and the anchor step id as the value: ```yaml id: "my-overlay" extends: "speckit" priority: 10 enabled: true edits: - insert_after: implement step: id: run-lint type: shell run: "ruff check src/" - replace: review-spec step: id: review-spec type: gate message: "Review the generated spec (overlay override)." options: [approve, reject] on_reject: abort ``` The explicit form is also supported: ```yaml edits: - operation: insert_after anchor: implement step: id: run-lint type: shell run: "ruff check src/" ``` #### Fields | Field | Required | Description | | --- | --- | --- | | `id` | yes | Identifier for this overlay. Used in `specify workflow overlay *` commands. Must be lowercase letters, digits, and hyphens only; no dots, underscores, path separators, or `overlays`. | | `extends` | yes | The workflow id this overlay applies to. Uses the same safe-id format as `id`; `overlays`, `runs`, and `steps` are reserved. | | `priority` | no | Integer; defaults to `10`. Lower values have higher precedence and win conflicts. Missing or invalid values fall back to `10`. | | `enabled` | no | Boolean. Defaults to `true`. Disabled overlays are ignored. | | `edits` | yes | Non-empty list of edit operations. | #### Edit Operations | Operation | `step` required | Effect | | --- | --- | --- | | `insert_after` | yes | Insert `step` immediately after the anchor step. | | `insert_before` | yes | Insert `step` immediately before the anchor step. | | `replace` | yes | Replace the anchor step with `step`. | | `remove` | no | Remove the anchor step from the list. | The `anchor` is the `id` of a step in the base workflow. Anchors are resolved recursively inside `then`, `else`, `steps`, `cases.*`, and `default` blocks, so nested base steps can also be targeted. Fan-out templates (`step` inside a `fan-out` step) are **not** valid anchors. Step ids must not contain `:` — that character is reserved for engine-generated nested ids. ### Overlay CLI Commands #### Add a Project Overlay ```bash specify workflow overlay add --priority ``` Validates the overlay file and copies it to `.specify/workflows/overlays//.yml`. `--priority` defaults to `10` and overrides the `priority` field in the file. #### List Overlays ```bash specify workflow overlay list ``` Shows all overlays for the workflow, ordered by resolver precedence. Disabled overlays are marked as disabled in the listing and are ignored during workflow resolution. #### Change Priority ```bash specify workflow overlay set-priority ``` #### Enable or Disable ```bash specify workflow overlay disable specify workflow overlay enable ``` #### Remove ```bash specify workflow overlay remove ``` Removes the project overlay file. #### Inspect the Composed Workflow ```bash specify workflow resolve ``` Prints the layer stack (base + overlays) and the source attribution for each step after composition. Useful for debugging which overlay contributed or overrode a step. ### Example: Adding Automated Linting after Implementation Given the built-in `speckit` workflow, create `project-overlay.yml`: ```yaml id: "add-lint" extends: "speckit" priority: 10 edits: - insert_after: implement step: id: run-lint type: shell run: "ruff check src/" ``` Install it: ```bash specify workflow overlay add project-overlay.yml --priority 10 ``` Run the workflow: ```bash specify workflow run speckit -i spec="Build a kanban board" ``` The composed workflow will now run the full SDD cycle and execute `ruff check src/` automatically after the `implement` step. ### Example: Replacing a Gate ```yaml id: "skip-plan-review" extends: "speckit" priority: 5 edits: - replace: review-plan step: id: review-plan type: command command: speckit.plan input: args: "{{ inputs.spec }}" ``` Lower priority values have higher precedence. Change this overlay to `priority: 5` if it must win a conflict with the `add-lint` overlay above. It replaces the `review-plan` gate with a non-interactive command. ### Workflow slots (upstream extension points) Workflow authors can declare a named, no-op workflow slot with `type: slot`: ```yaml - id: post-implement type: slot name: "Post-implementation checks" ``` The step `id` is the unique overlay anchor; `name` is a required non-blank, human-readable label only. An unfilled slot completes as a `skipped` step with `output: {slot: }`, so subsequent steps continue normally. Fill a slot with a schema-valid overlay `replace` edit anchored on the step `id`, not its `name`: ```yaml id: fill-post-implement extends: my-workflow edits: - replace: post-implement step: id: post-implement type: shell run: "echo Run project-specific checks" ``` Reuse the slot's `id` when later expressions or `fan-in.wait_for` refer to it. The replacement must also preserve every output key those later steps consume: an unfilled workflow slot supplies only `steps..output.slot`. Slot steps are not supported inside `fan-out.step` templates because runtime-multiplied templates cannot be overlay anchors. ### Interaction with Bundles and Updates `specify workflow add ` installs the complete local workflow package into `.specify/workflows//`. Archive installs preserve the same package contents. When an installed workflow is refreshed or reinstalled, project overlays in `.specify/workflows/overlays//` are preserved because they live outside the installed workflow directory. ### Limitations - Overlays operate on the step list only. They cannot change workflow metadata (name, description, inputs, `requires`) or expression logic. - Fan-out templates cannot be used as anchors. - An overlay that targets a step id that does not exist in the base workflow will raise a validation error when the workflow is resolved. - Overlays cannot target steps added by other overlays. - Overlays cannot add new inputs or change the input schema of the base workflow. ## Update Workflows ```bash specify workflow update [workflow_id] ``` Updates one installed catalog workflow — or all of them when no ID is given — to the latest catalog version. Prompts for confirmation and keeps the installed copy if a download or validation fails. ## Enable or Disable a Workflow ```bash specify workflow enable specify workflow disable ``` Disabled workflows stay installed and listed (marked `[disabled]`) but refuse to run until re-enabled. ## Remove a Workflow ```bash specify workflow remove ``` Removes an installed workflow from the project. ## Search Available Workflows ```bash specify workflow search [query] ``` | Option | Description | | ---------- | ----------------- | | `--tag` | Filter by tag | | `--author` | Filter by author | Searches all active catalogs for workflows matching the query. ## Workflow Info ```bash specify workflow info ``` Shows detailed information about a workflow, including its steps, inputs, and requirements. ## Catalog Management Workflow catalogs control where `search` and `add` look for workflows. Catalogs are checked in priority order. ### List Catalogs ```bash specify workflow catalog list ``` Shows all active catalog sources. ### Add a Catalog ```bash specify workflow catalog add ``` | Option | Description | | --------------- | -------------------------------- | | `--name ` | Optional name for the catalog | Adds a custom catalog URL to the project's `.specify/workflow-catalogs.yml`. ### Remove a Catalog ```bash specify workflow catalog remove ``` Removes a catalog by its index in the catalog list. ### Catalog Resolution Order Catalogs are resolved in this order (first match wins): 1. **Environment variable** — `SPECKIT_WORKFLOW_CATALOG_URL` overrides all catalogs 2. **Project config** — `.specify/workflow-catalogs.yml` 3. **User config** — `~/.specify/workflow-catalogs.yml` 4. **Built-in defaults** — official catalog + community catalog ## Workflow Definition Workflows are defined in YAML files. Here is the built-in **Full SDD Cycle** workflow that ships with Spec Kit: ```yaml schema_version: "1.0" workflow: id: "speckit" name: "Full SDD Cycle" version: "1.0.1" author: "GitHub" description: "Runs specify → plan → tasks → implement with review gates" requires: speckit_version: ">=0.8.5" integrations: any: - "alquimia" - "claude" - "copilot" - "gemini" - "opencode" inputs: spec: type: string required: true prompt: "Describe what you want to build" integration: type: string default: "auto" prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)" steps: - id: specify command: speckit.specify integration: "{{ inputs.integration }}" input: args: "{{ inputs.spec }}" - id: review-spec type: gate message: "Review the generated spec before planning." options: [approve, reject] on_reject: abort - id: plan command: speckit.plan integration: "{{ inputs.integration }}" input: args: "" - id: review-plan type: gate message: "Review the plan before generating tasks." options: [approve, reject] on_reject: abort - id: tasks command: speckit.tasks integration: "{{ inputs.integration }}" input: args: "" - id: implement command: speckit.implement integration: "{{ inputs.integration }}" input: args: "" ``` This produces the following execution flow: ```mermaid flowchart TB A["specify
(command)"] --> B{"review-spec
(gate)"} B -- approve --> C["plan
(command)"] B -- reject --> X1["⏹ Abort"] C --> D{"review-plan
(gate)"} D -- approve --> E["tasks
(command)"] D -- reject --> X2["⏹ Abort"] E --> F["implement
(command)"] style A fill:#49a,color:#fff style B fill:#a94,color:#fff style C fill:#49a,color:#fff style D fill:#a94,color:#fff style E fill:#49a,color:#fff style F fill:#49a,color:#fff style X1 fill:#999,color:#fff style X2 fill:#999,color:#fff ``` Run it with: ```bash specify workflow run speckit -i spec="Build a kanban board with drag-and-drop task management" ``` ## Step Types | Type | Purpose | | ------------ | ------------------------------------------------ | | `command` | Invoke a Spec Kit command (e.g., `speckit.plan`) | | `prompt` | Send an arbitrary prompt to the AI coding agent | | `shell` | Execute a shell command and capture output | | `init` | Bootstrap a project (like `specify init`) | | `slot` | Named workflow slot; skipped when unfilled | | `gate` | Pause for human approval before continuing | | `if` | Conditional branching (then/else) | | `switch` | Multi-branch dispatch on an expression | | `while` | Loop while a condition is true | | `do-while` | Execute at least once, then loop on condition | | `fan-out` | Dispatch a step for each item in a list | | `fan-in` | Aggregate results from a fan-out step | > **Security note:** a `shell` step runs a local command with **your** privileges. There is no capability sandbox — `requires` is an advisory pre-condition block (spec-kit version, integrations), not a runtime gate, so it does **not** restrict what a step can do. In particular there is no `requires.permissions` capability gate: it is rejected by validation precisely because it would imply a sandbox that does not exist. Review any catalog or downloaded workflow before running it, and use a `gate` step to require explicit approval before sensitive or destructive shell commands. ## Expressions Steps can reference inputs and previous step outputs using `{{ expression }}` syntax: | Namespace | Description | | ------------------------------ | ------------------------------------ | | `inputs.spec` | Workflow input values | | `steps.specify.output.file` | Output from a previous step | | `item` | Current item in a fan-out iteration | | `context.run_id` | Current workflow run ID | | `context.workflow_dir` | Resolved absolute path to the workflow source directory. Empty string for string-loaded workflows. | Available filters: `default`, `join`, `contains`, `map`, `from_json`. Example: ```yaml condition: "{{ steps.test.output.exit_code == 0 }}" args: "{{ inputs.spec }}" message: "{{ status | default('pending') }}" ``` ### Interpolation and shell safety Expressions are resolved by **plain string substitution** — the value of `{{ ... }}` is spliced into the surrounding text exactly as-is, with no quoting or escaping added. That is convenient for building `args` and `message` strings, but it has an important consequence for `shell` steps: a `run` field is handed to the system shell (`/bin/sh -c` on POSIX), so any interpolated value is interpreted as **shell syntax**, not just data. If an interpolated value can contain characters like `;`, `|`, `&`, `$( )`, backticks, or quotes, it can change or extend the command that actually runs. This matters most when the value is not fully under the workflow author's control: - **Workflow `inputs.*`** — supplied by whoever runs the workflow. - **A prior step's output**, e.g. `{{ steps.plan.output.stdout }}` — for a `prompt` step this is **text produced by the AI agent**, which can in turn be influenced by files, tickets, or web content the agent read. Treat agent output as untrusted when it flows into a `shell` step. There is **no shell-escaping filter** in the expression language and **no sandbox** around a `shell` step, so none of the practices below can be treated as a guarantee that a hostile value is neutralised. The only reliable control is to constrain what an interpolated value *can* be, and to keep values you cannot constrain out of `run` fields entirely. Scrutinise every `run` field that interpolates a value you do not control, and at minimum: - **Constrain the value at the source with `enum`/an allowlist.** When `inputs.*` feeds a `run` field, restrict it to a fixed set of known-safe values so a caller cannot supply arbitrary shell text at all. This is the strongest control the engine offers — prefer it over any downstream mitigation. ```yaml inputs: target: type: string enum: [staging, production] # caller cannot inject arbitrary text ``` - **Keep unconstrained values out of `run`.** If a value cannot be constrained to an allowlist — most agent/`prompt` output — do not interpolate it into a `run` field. Branch on it with `if`/`switch` against fixed conditions, or act on it in a `command`/`prompt` step rather than a shell command built from it. - **Quoting is not a security boundary.** Surrounding a substitution with quotes (`'{{ inputs.x }}'`) helps the shell treat a *trusted* value as a single argument and avoids word-splitting on spaces, but a value that itself contains the matching quote character can still break out and inject shell syntax. Quote for correctness on constrained values; never rely on quoting to make an *unconstrained* substitution safe. - **Gates do not inspect the next step, and `message` is printed verbatim.** A `gate` step renders only its own `message`/`show_file` — it does not display, resolve, or sanitise the command that follows it, and approval never neutralises an injectable interpolation. Do **not** interpolate raw untrusted data into `message`: it is printed as-is with no control-character stripping, so agent or caller output could inject terminal/ANSI escapes that alter or hide the approval prompt. Keep `message` to trusted, constrained text, and surface untrusted material for review via `show_file` instead — its path and contents are control/ANSI-stripped before display. A `shell` step is an arbitrary-command primitive by design; these practices reduce exposure and keep *which* command runs under the author's control, but they do not eliminate the risk of interpolating values you do not fully control. ## Shell Step Environment Variables Shell steps automatically receive the following environment variables: | Variable | Description | | -------- | ----------- | | `SPECKIT_WORKFLOW_DIR` | Resolved absolute path to the workflow source directory (same value as `{{ context.workflow_dir }}`). Not set when the workflow has no source path. | ## Input Types | Type | Coercion | | --------- | ------------------------------------------------- | | `string` | Pass-through | | `number` | `"42"` → `42`, `"3.14"` → `3.14` | | `boolean` | `"true"` / `"1"` / `"yes"` → `True` | ## State and Resume Each workflow run persists its state at `.specify/workflows/runs//`: - `state.json` — current run state and step progress - `inputs.json` — resolved input values - `log.jsonl` — step-by-step execution log This enables `specify workflow resume` to continue from the exact step where a run was paused (e.g., at a gate) or failed. ### Gate Verdict Inputs `verdict_input` binds a gate's verdict to a named workflow input. The input must be declared in the workflow's `inputs` block; `specify workflow validate` reports an undeclared reference. `verdict_input` is not supported inside a `fan-out` template. Fan-out items share workflow inputs, while workflow state can represent only one paused gate. Place a gate before the fan-out to approve the whole batch, or after a fan-in to review the aggregated results. **Input value semantics:** | Value | Behavior | |---|---| | Non-empty string, matches an option (case-insensitive) | Gate auto-decides; `output.choice` is set to the configured option spelling | | Non-empty string, no match | Gate fails immediately | | Non-string | Gate fails immediately | | Missing or empty | Gate prompts on a TTY; pauses otherwise | **Default value semantics:** A non-empty `default` is consumed as a verdict on the first run — matching an option auto-decides the gate, not matching fails it immediately. ```yaml inputs: spec_verdict: type: string default: "" steps: - id: review-spec type: gate message: "Approve the specification?" options: [approve, reject] on_reject: retry verdict_input: spec_verdict ``` Supply a verdict when resuming: ```bash specify workflow resume --input spec_verdict=approve ``` For `on_reject: retry`, a bound reject verdict is consumed before the gate pauses: the named stored input is reset to `""`. A later resume therefore prompts or pauses again until another verdict is supplied. Approve, abort, and skip outcomes leave the input unchanged. Because of that reset, a verdict input used with `on_reject: retry` must accept `""`. If it declares an `enum`, include the empty string — otherwise the reset value violates the input's own `enum` and the run can no longer be resumed with any input. `specify workflow add` reports this as a validation error. ```yaml inputs: spec_verdict: type: string enum: ["", approve, reject] default: "" ``` ## FAQ ### What happens when a workflow hits a gate step? The workflow pauses and waits for human input. Run `specify workflow resume ` after reviewing to continue. ### Can I run the same workflow multiple times? Yes. Each run gets a unique ID and its own state directory. Use `specify workflow status` to see all runs. ### Who maintains workflows? Most workflows are independently created and maintained by their respective authors. The Spec Kit maintainers do not review, audit, endorse, or support workflow code. Review a workflow's source before installing and use at your own discretion.