Add workflow engine with catalog system by Copilot · Pull Request #2158 · github/spec-kit

Copilot · 2026-04-10T16:30:36Z

Adds a workflow subsystem to Specify CLI for defining multi-step, resumable automation workflows in YAML. The engine dispatches commands to CLI-based integrations, evaluates control flow, and pauses at human review gates. Ships with a catalog system mirroring the existing extension/preset catalog pattern.

Workflow engine core (`src/specify_cli/workflows/`)

base.py — StepBase abstract class, StepContext, StepResult, status enums
__init__.py — STEP_REGISTRY with auto-discovery, mirrors INTEGRATION_REGISTRY
expressions.py — Sandboxed Jinja2-subset evaluator (variable interpolation, comparisons, boolean logic, filters like default, join, map, contains)
engine.py — WorkflowDefinition (YAML loader), validate_workflow(), WorkflowEngine (sequential executor with recursive nested step support), RunState (JSON state persistence for resume)
catalog.py — WorkflowCatalog (multi-catalog stack: env var → project → user → built-in), WorkflowRegistry (installed workflow tracking)

10 built-in step types (`workflows/steps/`)

command, prompt, shell, gate, if (then/else), switch, while, do-while, fan-out, fan-in — each a StepBase subclass in its own subpackage, same extensibility model as integrations.

CLI commands

Catalog files

workflows/catalog.json, workflows/catalog.community.json, and an example workflows/speckit/workflow.yml (full SDD cycle).

Example workflow definition

schema_version: "1.0"
workflow:
  id: "sdd-pipeline"
  name: "SDD Pipeline"
  version: "1.0.0"
  integration: claude

inputs:
  feature_name:
    type: string
    required: true

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

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

  - id: check-scope
    type: if
    condition: "{{ inputs.scope == 'full' }}"
    then:
      - id: full-plan
        command: speckit.plan
        integration: gemini
        model: gemini-2.5-pro
    else:
      - id: quick-plan
        command: speckit.plan

Tests

122 new tests covering step registry, expression engine, all step types, workflow validation, engine execution (including branching/gates/shell), state persistence, catalog resolution, and registry operations. Full suite passes (1362 total).

…stem, and CLI commands Agent-Logs-Url: https://github.com/github/spec-kit/sessions/72a7bb5d-071f-4d67-a507-7e1abae2384d Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

src/specify_cli/__init__.py

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/72a7bb5d-071f-4d67-a507-7e1abae2384d Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

…me validation Agent-Logs-Url: https://github.com/github/spec-kit/sessions/72a7bb5d-071f-4d67-a507-7e1abae2384d Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI that can load YAML workflow definitions, evaluate simple template expressions, execute step types, persist run state for resuming, and discover workflows via a catalog/registry model (similar to extensions/presets).

Changes:

Introduces specify_cli.workflows core modules (base types, expression evaluator, engine + run-state persistence, catalog + registry).
Adds 9 built-in step types (command/shell/gate + control-flow primitives) with auto-registration.
Adds specify workflow ... CLI commands plus initial workflow catalog JSONs and a sample speckit workflow, with a large new test suite.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds an example “Full SDD Cycle” workflow definition.
workflows/catalog.json	Adds default workflow catalog stub (empty).
workflows/catalog.community.json	Adds community workflow catalog stub (empty).
tests/test_workflows.py	Adds comprehensive tests for workflow engine components and step types.
src/specify_cli/workflows/base.py	Defines workflow step/run base types (`StepBase`, `StepContext`, `StepResult`, enums).
src/specify_cli/workflows/init.py	Implements global step registry + registers built-in step implementations.
src/specify_cli/workflows/expressions.py	Adds a sandboxed, Jinja-like expression/template evaluator.
src/specify_cli/workflows/engine.py	Adds workflow YAML loader/validator, executor, and run-state persistence/resume.
src/specify_cli/workflows/catalog.py	Adds catalog stack resolution, URL validation, caching, search, and installed registry.
src/specify_cli/workflows/steps/init.py	Declares step auto-discovery package.
src/specify_cli/workflows/steps/command/init.py	Adds the `command` step type.
src/specify_cli/workflows/steps/shell/init.py	Adds the `shell` step type.
src/specify_cli/workflows/steps/gate/init.py	Adds the `gate` step type.
src/specify_cli/workflows/steps/if_then/init.py	Adds the `if` step type.
src/specify_cli/workflows/steps/switch/init.py	Adds the `switch` step type.
src/specify_cli/workflows/steps/while_loop/init.py	Adds the `while` step type.
src/specify_cli/workflows/steps/do_while/init.py	Adds the `do-while` step type.
src/specify_cli/workflows/steps/fan_out/init.py	Adds the `fan-out` step type.
src/specify_cli/workflows/steps/fan_in/init.py	Adds the `fan-in` step type.
src/specify_cli/init.py	Adds `specify workflow` CLI commands (run/resume/status/list/add/remove/search/info + catalog list/add/remove).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

src/specify_cli/workflows/engine.py:535

_execute_steps() treats result.next_steps as a one-time nested sequence. That means loop steps (while, do-while) and fan-out/fan-in currently can't implement their advertised semantics (re-evaluating conditions, enforcing max_iterations, running per-item dispatch, joining). If these step types are intended to work, the engine needs explicit handling for them here (or the step contract needs to change so the step implementation can drive iteration/execution).

            # Execute nested steps (from control flow)
            if result.next_steps:
                self._execute_steps(result.next_steps, context, state, registry)
                if state.status in (
                    RunStatus.PAUSED,
                    RunStatus.FAILED,
                    RunStatus.ABORTED,
                ):
                    return

Files reviewed: 20/20 changed files
Comments generated: 6

src/specify_cli/__init__.py

src/specify_cli/workflows/engine.py

workflows/speckit/workflow.yml

src/specify_cli/workflows/steps/while_loop/__init__.py

src/specify_cli/workflows/steps/if_then/__init__.py

src/specify_cli/workflows/engine.py

Review comments (7/7): - Add explanatory comment to empty except block - Implement workflow catalog download with cleanup on failure - Add input type coercion for number/boolean/enum - Fix example workflow to remove non-existent output references - Fix while_loop and if_then condition defaults (string 'false' → bool False) - Fix resume step index tracking with step_offset parameter CLI dispatch: - Add build_exec_args() and dispatch_command() to IntegrationBase - Override for Claude (skills: /speckit-specify), Gemini (-m flag), Codex (codex exec), Copilot (--agent speckit.specify) - CommandStep invokes installed commands by name via integration CLI - Add PromptStep for arbitrary inline prompts (10th step type) - Stream CLI output live to terminal (no silent blocking) - Remove timeout when streaming (user can Ctrl+C) - Ctrl+C saves state as PAUSED for clean resume Interactive gates: - Gate steps prompt [1] approve [2] reject in TTY - Fall back to PAUSED in non-interactive environments - Resume re-executes the gate for interactive prompting Documentation: - workflows/README.md — user guide - workflows/ARCHITECTURE.md — internals with Mermaid diagrams - workflows/PUBLISHING.md — catalog submission guide Tests: 94 → 122 workflow tests, 1362 total (all passing)

…d name

Copilot

Pull request overview

Introduces a new workflow subsystem to Specify CLI that can load YAML-defined workflows, execute step graphs with state persistence (run/resume/status), and manage workflow catalogs/installation—along with integration updates to support non-interactive CLI dispatch.

Changes:

Added specify_cli.workflows engine core (definition parsing, validation, expression evaluation, run state persistence, catalog/registry).
Added built-in workflow step types and corresponding tests.
Added specify workflow ... CLI commands plus integration enhancements (build_exec_args / dispatch support for Codex + Copilot).

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds an example built-in workflow definition for a full SDD cycle.
workflows/catalog.json	Adds an official workflow catalog skeleton file.
workflows/catalog.community.json	Adds a community workflow catalog skeleton file.
workflows/README.md	Adds end-user documentation for workflows, step types, catalogs, and resume.
workflows/PUBLISHING.md	Adds workflow publishing guidance and catalog submission format.
workflows/ARCHITECTURE.md	Documents workflow engine internals, step registry, and catalog resolution.
tests/test_workflows.py	Adds a large test suite covering workflow parsing/validation/execution, steps, catalog, and registry.
src/specify_cli/workflows/base.py	Introduces core workflow base types (`StepBase`, `StepContext`, `StepResult`, status enums).
src/specify_cli/workflows/init.py	Implements `STEP_REGISTRY` and registers built-in step implementations.
src/specify_cli/workflows/expressions.py	Implements the template/expression evaluator used by workflow YAML.
src/specify_cli/workflows/engine.py	Implements workflow definition loading, validation, execution, resume, and run state persistence.
src/specify_cli/workflows/catalog.py	Implements workflow catalog stacking, caching, searching, and installed workflow registry.
src/specify_cli/workflows/steps/init.py	Adds steps package marker for built-in step types.
src/specify_cli/workflows/steps/command/init.py	Adds `command` step type for dispatching Spec Kit commands via integration CLIs.
src/specify_cli/workflows/steps/shell/init.py	Adds `shell` step type for running local shell commands.
src/specify_cli/workflows/steps/gate/init.py	Adds `gate` step type for interactive/pause-based human review checkpoints.
src/specify_cli/workflows/steps/if_then/init.py	Adds `if` branching step type producing nested step lists.
src/specify_cli/workflows/steps/switch/init.py	Adds `switch` branching step type based on an evaluated expression.
src/specify_cli/workflows/steps/while_loop/init.py	Adds `while` loop step type returning nested steps conditionally.
src/specify_cli/workflows/steps/do_while/init.py	Adds `do-while` loop step type intended to repeat nested steps.
src/specify_cli/workflows/steps/fan_out/init.py	Adds `fan-out` step type intended for parallel dispatch over a collection.
src/specify_cli/workflows/steps/fan_in/init.py	Adds `fan-in` step type for aggregating results from prior steps.
src/specify_cli/workflows/steps/prompt/init.py	Adds `prompt` step type for free-form prompts to integration CLIs.
src/specify_cli/init.py	Adds the `specify workflow` CLI command group (run/resume/status/list/add/remove/search/info + catalog ops).
src/specify_cli/integrations/base.py	Adds integration primitives for CLI execution and command dispatch (`build_exec_args`, `dispatch_command`, invocation helpers).
src/specify_cli/integrations/codex/init.py	Adds Codex CLI exec argument builder for non-interactive dispatch.
src/specify_cli/integrations/copilot/init.py	Adds GitHub Copilot CLI dispatch support (agent-based invocation + exec args).

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 27/27 changed files
Comments generated: 12

src/specify_cli/workflows/engine.py

src/specify_cli/workflows/steps/shell/__init__.py

src/specify_cli/workflows/engine.py

src/specify_cli/workflows/steps/fan_out/__init__.py

src/specify_cli/__init__.py

src/specify_cli/integrations/base.py

src/specify_cli/workflows/steps/gate/__init__.py

workflows/ARCHITECTURE.md

workflows/README.md

…op/fan-out execution, URL validation - VALID_STEP_TYPES now queries STEP_REGISTRY dynamically - Shell step returns FAILED on non-zero exit code - Persist workflow YAML in run directory for reliable resume - Resume loads from run copy, falls back to installed workflow - Engine iterates while/do-while loops up to max_iterations - Engine expands fan-out per item with context.item - HTTPS URL validation for catalog workflow installs (HTTP allowed for localhost) - Fix catalog merge priority docstring (lower number wins) - Fix dispatch_command docstring (no build_exec_args_for_command) - Gate on_reject=retry pauses for re-prompt on resume - Update docs to 10 step types, add prompt step to tables and README

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, multi-step, resumable automation with built-in control-flow steps and a catalog/registry model consistent with existing extension/preset patterns.

Changes:

Introduces workflow engine core (definition loading/validation, execution, state persistence, expression evaluation).
Adds built-in step types (command/prompt/shell/gate + control flow: if/switch/while/do-while/fan-out/fan-in).
Adds workflow CLI commands + catalog/registry support, and bundles a default “speckit” workflow into specify init.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds bundled “speckit” example workflow definition.
workflows/catalog.json	Adds official workflow catalog entry for `speckit`.
workflows/catalog.community.json	Adds empty community workflow catalog scaffold.
workflows/README.md	Documents workflow usage, step types, expressions, catalogs, and paths.
workflows/PUBLISHING.md	Adds workflow publishing/submission guidance and catalog rules.
workflows/ARCHITECTURE.md	Documents workflow engine architecture and execution model.
tests/test_workflows.py	Adds comprehensive workflow subsystem tests (engine, steps, expressions, catalog, registry).
tests/integrations/test_integration_generic.py	Updates expected installed file inventory to include bundled workflow + registry.
tests/integrations/test_integration_copilot.py	Updates expected installed file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_yaml.py	Updates expected installed file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_toml.py	Updates expected installed file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_skills.py	Updates expected installed file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_markdown.py	Updates expected installed file inventory to include bundled workflow + registry.
src/specify_cli/workflows/steps/while_loop/init.py	Implements `while` control-flow step.
src/specify_cli/workflows/steps/switch/init.py	Implements `switch` control-flow step.
src/specify_cli/workflows/steps/shell/init.py	Implements `shell` execution step.
src/specify_cli/workflows/steps/prompt/init.py	Implements integration prompt step + dispatch attempt.
src/specify_cli/workflows/steps/if_then/init.py	Implements `if` control-flow step.
src/specify_cli/workflows/steps/gate/init.py	Implements interactive/non-interactive human gate step.
src/specify_cli/workflows/steps/fan_out/init.py	Implements `fan-out` step (engine-expanded iteration).
src/specify_cli/workflows/steps/fan_in/init.py	Implements `fan-in` aggregation step.
src/specify_cli/workflows/steps/do_while/init.py	Implements `do-while` control-flow step.
src/specify_cli/workflows/steps/command/init.py	Implements command dispatch step via integration CLIs.
src/specify_cli/workflows/steps/init.py	Adds steps package marker for discovery/organization.
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluation and filters.
src/specify_cli/workflows/engine.py	Adds workflow definition model, validation, execution, resume, and run state persistence.
src/specify_cli/workflows/catalog.py	Adds workflow catalog resolution, caching, search, and installed registry.
src/specify_cli/workflows/base.py	Adds workflow step base types, context/result models, and status enums.
src/specify_cli/workflows/init.py	Registers built-in step types in `STEP_REGISTRY`.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support and install URL.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI exec-args support.
src/specify_cli/integrations/base.py	Adds generic CLI dispatch primitives to integration base classes.
src/specify_cli/init.py	Adds bundled workflow install during `init` + workflow CLI command group.
pyproject.toml	Bundles `workflows/speckit` into the core pack.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 5

src/specify_cli/workflows/expressions.py

src/specify_cli/workflows/steps/gate/__init__.py

src/specify_cli/workflows/steps/while_loop/__init__.py

src/specify_cli/workflows/catalog.py

src/specify_cli/workflows/engine.py

…le default, cache guard, resume log - evaluate_condition treats plain 'false'/'true' strings as booleans - Gate abort returns StepResult(FAILED) instead of raising exception so step output is persisted in state for inspection - while_loop max_iterations optional (default 10), validation aligned - Catalog cache fallback catches invalid JSON gracefully - resume() appends workflow_finished log entry like execute()

Copilot

Pull request overview

This PR introduces a new workflow subsystem for Specify CLI, enabling multi-step, resumable YAML-defined automation workflows with control-flow step types and a catalog/registry system similar to existing extension/preset catalogs.

Changes:

Added workflow engine core (definition loading/validation, expression evaluation, step execution, run-state persistence/resume).
Added workflow catalog + installed-workflow registry, plus bundled “speckit” workflow and catalog JSON files.
Extended integrations to support CLI dispatch (build_exec_args / dispatch_command) and added extensive test coverage for workflows and inventories.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds a bundled example workflow (“Full SDD Cycle”).
workflows/catalog.json	Adds official workflow catalog with the bundled workflow entry.
workflows/catalog.community.json	Adds empty community workflow catalog scaffold.
workflows/README.md	Documents workflow concepts, step types, usage, and catalogs.
workflows/PUBLISHING.md	Documents how to publish workflows and catalog entry requirements.
workflows/ARCHITECTURE.md	Documents internal engine architecture and persistence model.
tests/test_workflows.py	Adds end-to-end and unit tests for engine, steps, expressions, catalog, and registry.
tests/integrations/test_integration_generic.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_copilot.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_yaml.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_toml.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_skills.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_markdown.py	Updates expected file inventory to include bundled workflow + registry.
src/specify_cli/workflows/init.py	Adds `STEP_REGISTRY` and registers built-in step types.
src/specify_cli/workflows/base.py	Adds workflow base types (`StepBase`, `StepContext`, `StepResult`, status enums).
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluator and filters.
src/specify_cli/workflows/engine.py	Adds workflow definition parsing/validation, executor, and run persistence/resume.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stacking/caching, searching, and installed workflow registry.
src/specify_cli/workflows/steps/init.py	Adds step package marker for built-in step discovery/organization.
src/specify_cli/workflows/steps/command/init.py	Adds command step implementation that dispatches via integration CLI.
src/specify_cli/workflows/steps/prompt/init.py	Adds prompt step implementation for ad-hoc integration prompts.
src/specify_cli/workflows/steps/shell/init.py	Adds shell step implementation for local shell execution.
src/specify_cli/workflows/steps/gate/init.py	Adds interactive/non-interactive human gate step.
src/specify_cli/workflows/steps/if_then/init.py	Adds conditional branching step.
src/specify_cli/workflows/steps/switch/init.py	Adds switch/case branching step.
src/specify_cli/workflows/steps/while_loop/init.py	Adds while-loop control-flow step.
src/specify_cli/workflows/steps/do_while/init.py	Adds do-while-loop control-flow step.
src/specify_cli/workflows/steps/fan_out/init.py	Adds fan-out step for per-item dispatch.
src/specify_cli/workflows/steps/fan_in/init.py	Adds fan-in aggregation step.
src/specify_cli/integrations/base.py	Adds CLI dispatch primitives used by workflow command/prompt steps.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support and updates install URL/docs.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI argument builder for dispatch support.
src/specify_cli/init.py	Adds workflow CLI commands and installs bundled workflow during `specify init`.
pyproject.toml	Bundles the built-in workflow into the packaged core pack.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

src/specify_cli/workflows/steps/gate/init.py:103

options is only validated as a list, but _prompt() assumes a non-empty list of strings (uses options[-1] and calls .lower() on each option). If a workflow provides options: [] or non-string items, this will raise at runtime in interactive mode. Consider validating options is a non-empty list of strings (or coercing all options to strings) in validate()/execute() before calling _prompt().

        options = config.get("options", ["approve", "reject"])
        if not isinstance(options, list):
            errors.append(
                f"Gate step {config.get('id', '?')!r}: 'options' must be a list."
            )

Files reviewed: 34/34 changed files
Comments generated: 4

src/specify_cli/integrations/copilot/__init__.py

src/specify_cli/workflows/catalog.py

src/specify_cli/workflows/engine.py

src/specify_cli/workflows/steps/while_loop/__init__.py

…ort dead code, while docstring - --allow-all-tools controlled by SPECKIT_ALLOW_ALL_TOOLS env var (default: 1) Set to 0 to disable automatic tool approval for Copilot CLI - Empty catalogs list falls back to built-in defaults (not an error) - Remove unreachable WorkflowAbortError catches from execute/resume (gate abort now returns StepResult(FAILED) instead of raising) - while_loop docstring updated: max_iterations is optional (default 10)

Copilot

Pull request overview

Adds a new workflow subsystem to the Specify CLI, including a YAML-defined workflow engine with resumable execution, built-in step types, a workflow catalog/registry mechanism, and corresponding CLI commands and tests.

Changes:

Introduces workflow engine core (definition loading/validation, execution, state persistence, expression evaluation).
Adds built-in workflow step implementations (command/prompt/shell/gate + control-flow and fan-out/fan-in).
Adds workflow catalog files/docs, bundles a default speckit workflow, wires new CLI commands, and expands test coverage.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds bundled “speckit” example workflow definition.
workflows/catalog.json	Adds official workflow catalog with `speckit` entry.
workflows/catalog.community.json	Adds empty community workflow catalog scaffold.
workflows/README.md	Adds user-facing workflow documentation (usage, step types, catalogs).
workflows/PUBLISHING.md	Adds publishing guidance for community catalog submissions.
workflows/ARCHITECTURE.md	Adds internal architecture documentation for engine/catalog design.
tests/test_workflows.py	Adds comprehensive tests for engine, steps, expressions, catalog/registry.
tests/integrations/test_integration_generic.py	Updates expected project file inventory to include bundled workflow + registry.
tests/integrations/test_integration_copilot.py	Updates expected project file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_yaml.py	Updates expected file inventory for YAML-based integrations.
tests/integrations/test_integration_base_toml.py	Updates expected file inventory for TOML-based integrations.
tests/integrations/test_integration_base_skills.py	Updates expected file inventory for skills-based integrations.
tests/integrations/test_integration_base_markdown.py	Updates expected file inventory for markdown-based integrations.
src/specify_cli/workflows/steps/while_loop/init.py	Adds `while` control-flow step.
src/specify_cli/workflows/steps/switch/init.py	Adds `switch` control-flow step.
src/specify_cli/workflows/steps/shell/init.py	Adds `shell` step for local command execution.
src/specify_cli/workflows/steps/prompt/init.py	Adds `prompt` step for free-form integration prompts.
src/specify_cli/workflows/steps/if_then/init.py	Adds `if` branching step.
src/specify_cli/workflows/steps/gate/init.py	Adds interactive/non-interactive human review gate step.
src/specify_cli/workflows/steps/fan_out/init.py	Adds `fan-out` step for per-item template dispatch.
src/specify_cli/workflows/steps/fan_in/init.py	Adds `fan-in` step to aggregate prior outputs.
src/specify_cli/workflows/steps/do_while/init.py	Adds `do-while` loop step.
src/specify_cli/workflows/steps/command/init.py	Adds default `command` dispatch step to integrations.
src/specify_cli/workflows/steps/init.py	Declares steps package for auto-discovery/organization.
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluator for templates/conditions.
src/specify_cli/workflows/engine.py	Adds workflow definition model, validation, engine execution, and run state persistence.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stacking, caching, searching, and installed registry tracking.
src/specify_cli/workflows/base.py	Adds core workflow types (`StepBase`, `StepContext`, `StepResult`, enums).
src/specify_cli/workflows/init.py	Adds step registry and explicit built-in step registration.
src/specify_cli/integrations/copilot/init.py	Extends Copilot integration with CLI dispatch support for workflows.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI dispatch arg builder for workflows.
src/specify_cli/integrations/base.py	Adds generic CLI dispatch plumbing (`build_exec_args`, `dispatch_command`, skills invocation format).
src/specify_cli/init.py	Wires workflow CLI commands and bundles/install of `speckit` workflow during init.
pyproject.toml	Bundles `workflows/speckit` into the core pack for distribution.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 2

src/specify_cli/workflows/engine.py

src/specify_cli/workflows/steps/do_while/__init__.py

… max_iterations optional - Engine detects output.aborted from gate step and sets RunStatus.ABORTED (was unreachable — gate abort returned FAILED but status was always FAILED) - do-while max_iterations now optional (default 10), aligned with while_loop - do-while docstring and validation updated accordingly

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI that can load YAML-defined, multi-step workflows; execute them with control-flow step types; persist run state for resume; and discover/install workflows via a catalog/registry system (mirroring the existing extension/preset patterns).

Changes:

Introduces specify_cli.workflows engine core (definition loading/validation, execution, state persistence, expression evaluation, catalogs/registry).
Adds 10 built-in step types (command/prompt/shell/gate + branching/looping/fan-out/fan-in).
Wires new specify workflow ... CLI commands, bundles a built-in speckit workflow, and adds comprehensive tests + docs.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds the bundled example “speckit” workflow definition (full SDD cycle).
workflows/catalog.json	Adds the official workflow catalog (initial `speckit` entry).
workflows/catalog.community.json	Adds the empty community workflow catalog scaffold.
workflows/README.md	Adds user-facing documentation for running/creating workflows and catalog usage.
workflows/PUBLISHING.md	Adds workflow publishing guidance and catalog submission rules.
workflows/ARCHITECTURE.md	Adds internal architecture documentation for engine, steps, expressions, catalogs.
tests/test_workflows.py	Adds a large test suite covering engine, steps, expressions, catalogs, and persistence.
tests/integrations/test_integration_generic.py	Updates expected inventory to include bundled workflow + registry file.
tests/integrations/test_integration_copilot.py	Updates expected inventory to include bundled workflow + registry file.
tests/integrations/test_integration_base_yaml.py	Updates base YAML integration expected inventory for bundled workflow artifacts.
tests/integrations/test_integration_base_toml.py	Updates base TOML integration expected inventory for bundled workflow artifacts.
tests/integrations/test_integration_base_skills.py	Updates base Skills integration expected inventory for bundled workflow artifacts.
tests/integrations/test_integration_base_markdown.py	Updates base Markdown integration expected inventory for bundled workflow artifacts.
src/specify_cli/workflows/steps/while_loop/init.py	Adds `while` control-flow step implementation + validation.
src/specify_cli/workflows/steps/switch/init.py	Adds `switch` control-flow step implementation + validation.
src/specify_cli/workflows/steps/shell/init.py	Adds `shell` step implementation for running local commands.
src/specify_cli/workflows/steps/prompt/init.py	Adds `prompt` step implementation for sending inline prompts to integration CLIs.
src/specify_cli/workflows/steps/if_then/init.py	Adds `if` step implementation + validation.
src/specify_cli/workflows/steps/gate/init.py	Adds `gate` step implementation for interactive approvals / CI pause.
src/specify_cli/workflows/steps/fan_out/init.py	Adds `fan-out` step implementation (engine expands template per item).
src/specify_cli/workflows/steps/fan_in/init.py	Adds `fan-in` step implementation to aggregate results.
src/specify_cli/workflows/steps/do_while/init.py	Adds `do-while` loop step implementation + validation.
src/specify_cli/workflows/steps/command/init.py	Adds default `command` step implementation dispatching Spec Kit commands via integration CLIs.
src/specify_cli/workflows/steps/init.py	Adds steps package marker for built-in step types.
src/specify_cli/workflows/expressions.py	Adds a sandboxed Jinja2-like expression evaluator (subset) for templates/conditions.
src/specify_cli/workflows/engine.py	Adds workflow definition parsing, validation, execution, and run-state persistence.
src/specify_cli/workflows/catalog.py	Adds workflow catalog resolution, caching, searching, and installed-workflow registry.
src/specify_cli/workflows/base.py	Adds base step abstractions and shared result/context/status models.
src/specify_cli/workflows/init.py	Adds step registry + built-in step registration.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support + updates metadata for workflow dispatch.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI argument builder for non-interactive dispatch.
src/specify_cli/integrations/base.py	Adds generic CLI dispatch primitives (`build_exec_args`, `dispatch_command`, skills invocation override).
src/specify_cli/init.py	Adds workflow CLI commands + init-time installation of bundled `speckit` workflow.
pyproject.toml	Bundles the `workflows/speckit` directory into the wheel `core_pack`.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 2

src/specify_cli/workflows/engine.py

src/specify_cli/__init__.py

…validator

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, multi-step automation that can be resumed across runs, with a workflow catalog/registry system and new specify workflow ... CLI commands.

Changes:

Introduces workflow engine core (definition loading/validation, execution with branching/loops/fan-out, run state persistence, expression evaluation).
Adds workflow catalog + registry management (multi-source catalog resolution, caching, install/remove/list/search/info).
Bundles and auto-installs a built-in speckit workflow, updates integrations to support CLI dispatch, and adds extensive test coverage.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds bundled “Full SDD Cycle” workflow definition.
workflows/catalog.json	Adds official workflow catalog containing `speckit`.
workflows/catalog.community.json	Adds empty community catalog scaffold.
workflows/README.md	Documents workflow usage, step types, expressions, state/resume, and catalogs.
workflows/PUBLISHING.md	Adds publishing guidance and community catalog submission rules.
workflows/ARCHITECTURE.md	Documents workflow engine architecture and execution model.
tests/test_workflows.py	Adds comprehensive workflow subsystem tests (engine, steps, expressions, catalogs).
tests/integrations/test_integration_generic.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_copilot.py	Updates expected file inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_yaml.py	Updates base YAML integration inventory expectations for bundled workflow.
tests/integrations/test_integration_base_toml.py	Updates base TOML integration inventory expectations for bundled workflow.
tests/integrations/test_integration_base_skills.py	Updates base skills integration inventory expectations for bundled workflow.
tests/integrations/test_integration_base_markdown.py	Updates base markdown integration inventory expectations for bundled workflow.
src/specify_cli/workflows/steps/while_loop/init.py	Implements `while` control-flow step.
src/specify_cli/workflows/steps/switch/init.py	Implements `switch` control-flow step.
src/specify_cli/workflows/steps/shell/init.py	Implements `shell` execution step.
src/specify_cli/workflows/steps/prompt/init.py	Implements `prompt` integration-dispatch step.
src/specify_cli/workflows/steps/if_then/init.py	Implements `if` control-flow step.
src/specify_cli/workflows/steps/gate/init.py	Implements interactive/non-interactive review `gate` step.
src/specify_cli/workflows/steps/fan_out/init.py	Implements `fan-out` expansion step.
src/specify_cli/workflows/steps/fan_in/init.py	Implements `fan-in` aggregation step.
src/specify_cli/workflows/steps/do_while/init.py	Implements `do-while` control-flow step.
src/specify_cli/workflows/steps/command/init.py	Implements `command` step dispatching Spec Kit commands via integration CLIs.
src/specify_cli/workflows/steps/init.py	Adds steps package marker for built-in step discovery.
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluation and filters.
src/specify_cli/workflows/engine.py	Adds workflow definition model, validation, execution, loops, fan-out, and run persistence/resume.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stack resolution, caching, search, and install registry.
src/specify_cli/workflows/base.py	Adds workflow base types: context/result/status enums and step interface.
src/specify_cli/workflows/init.py	Adds global step registry and built-in step registration.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support and updates install URL metadata.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI dispatch argument builder.
src/specify_cli/integrations/base.py	Adds generic CLI dispatch APIs for integrations and implementations for markdown/toml/skills.
src/specify_cli/init.py	Adds workflow CLI commands and installs bundled workflow during `specify init`.
pyproject.toml	Bundles `workflows/speckit` into the package core pack.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 3

src/specify_cli/workflows/steps/gate/__init__.py

src/specify_cli/workflows/steps/prompt/__init__.py

src/specify_cli/workflows/engine.py

… normalizes max_iterations

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, resumable multi-step automation with a catalog/registry model and CLI management commands, plus a bundled “speckit” SDD workflow.

Changes:

Introduces workflow engine core (definition loading/validation, step execution, resume state persistence) and a sandboxed expression evaluator.
Adds built-in step types (command/prompt/shell/gate + control-flow + fan-out/fan-in) and workflow catalog/registry management.
Wires new specify workflow ... CLI commands, bundles an official workflow + catalogs, and adds comprehensive test coverage.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds a bundled “Full SDD Cycle” workflow definition.
workflows/catalog.json	Adds official workflow catalog with the bundled workflow entry.
workflows/catalog.community.json	Adds empty community workflow catalog scaffold.
workflows/README.md	Documents workflow concepts, step types, expressions, state/resume, and catalog usage.
workflows/PUBLISHING.md	Adds workflow publishing/submission guidance (community catalog process).
workflows/ARCHITECTURE.md	Documents internal architecture/execution model and catalog resolution.
tests/test_workflows.py	Adds broad unit/integration coverage for engine, steps, expressions, state, and catalog.
tests/integrations/test_integration_generic.py	Updates expected init inventory to include bundled workflow + registry file.
tests/integrations/test_integration_copilot.py	Updates expected init inventory to include bundled workflow + registry file.
tests/integrations/test_integration_base_yaml.py	Updates base integration inventory expectations for bundled workflow assets.
tests/integrations/test_integration_base_toml.py	Updates base integration inventory expectations for bundled workflow assets.
tests/integrations/test_integration_base_skills.py	Updates base integration inventory expectations for bundled workflow assets.
tests/integrations/test_integration_base_markdown.py	Updates base integration inventory expectations for bundled workflow assets.
src/specify_cli/workflows/steps/while_loop/init.py	Adds `while` control-flow step implementation + validation.
src/specify_cli/workflows/steps/switch/init.py	Adds `switch` multi-branch step implementation + validation.
src/specify_cli/workflows/steps/shell/init.py	Adds local shell execution step with timeout/error handling.
src/specify_cli/workflows/steps/prompt/init.py	Adds prompt-to-integration step with optional CLI dispatch.
src/specify_cli/workflows/steps/if_then/init.py	Adds `if` branching step implementation + validation.
src/specify_cli/workflows/steps/gate/init.py	Adds interactive/non-interactive human gate step.
src/specify_cli/workflows/steps/fan_out/init.py	Adds fan-out step that expands a template across items.
src/specify_cli/workflows/steps/fan_in/init.py	Adds fan-in aggregation step with expression-resolved output.
src/specify_cli/workflows/steps/do_while/init.py	Adds `do-while` loop step implementation + validation.
src/specify_cli/workflows/steps/command/init.py	Adds command dispatch step to invoke Spec Kit commands via integration CLIs.
src/specify_cli/workflows/steps/init.py	Adds steps package marker for built-in auto-discovery.
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluation + filters.
src/specify_cli/workflows/engine.py	Adds workflow definition model, validator, executor, and resumable run state.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stack resolution, caching, search, and local registry.
src/specify_cli/workflows/base.py	Adds base types: step/run status enums, context/result dataclasses, base step API.
src/specify_cli/workflows/init.py	Adds global step registry and built-in step registration.
src/specify_cli/integrations/copilot/init.py	Extends Copilot integration with CLI dispatch support for workflows.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI exec argument builder for dispatch.
src/specify_cli/integrations/base.py	Adds common CLI dispatch API (`build_exec_args`, `dispatch_command`, invocation helpers).
src/specify_cli/init.py	Adds workflow CLI commands and installs bundled workflow during `specify init`.
pyproject.toml	Bundles `workflows/speckit` into the packaged core pack.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 1

src/specify_cli/workflows/engine.py

- Fan-out per-item IDs use parentId:templateId:index (e.g. parallel:impl:0) - Reserve ':' in user step IDs (validation rejects) - Replaces _fanout_ prefix with cleaner namespacing - Expressions like {{ steps.parallel:impl:0.output.file }} work naturally

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined multi-step workflows with control-flow steps, resumable execution state, and a workflow catalog/registry system (plus a bundled “speckit” workflow installed during specify init).

Changes:

Introduces workflow core modules (definition loading/validation, expression evaluation, execution engine, state persistence, catalog + registry).
Adds built-in workflow step implementations (command/prompt/shell/gate + branching/loops + fan-out/fan-in) and wires them into a step registry.
Extends the CLI and integration layer to support dispatching steps through integration CLIs, and adds a bundled workflow + catalogs + tests.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds a bundled end-to-end SDD workflow definition.
workflows/catalog.json	Adds the official workflow catalog with the bundled workflow entry.
workflows/catalog.community.json	Adds an empty community workflow catalog scaffold.
workflows/README.md	Documents workflow concepts, step types, expressions, and CLI usage.
workflows/PUBLISHING.md	Adds workflow publishing/submission guidelines (including catalog rules).
workflows/ARCHITECTURE.md	Documents engine execution model, state persistence, and catalog resolution.
tests/test_workflows.py	Adds comprehensive tests for workflow engine, steps, expressions, state, catalog/registry.
tests/integrations/test_integration_generic.py	Updates expected init inventory to include bundled workflow + registry.
tests/integrations/test_integration_copilot.py	Updates expected init inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_yaml.py	Updates expected init inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_toml.py	Updates expected init inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_skills.py	Updates expected init inventory to include bundled workflow + registry.
tests/integrations/test_integration_base_markdown.py	Updates expected init inventory to include bundled workflow + registry.
src/specify_cli/workflows/steps/while_loop/init.py	Adds `while` control-flow step implementation.
src/specify_cli/workflows/steps/switch/init.py	Adds `switch` control-flow step implementation.
src/specify_cli/workflows/steps/shell/init.py	Adds `shell` step implementation for local command execution.
src/specify_cli/workflows/steps/prompt/init.py	Adds `prompt` step implementation for direct integration prompting.
src/specify_cli/workflows/steps/if_then/init.py	Adds `if` (then/else) step implementation.
src/specify_cli/workflows/steps/gate/init.py	Adds interactive/non-interactive human review gate step.
src/specify_cli/workflows/steps/fan_out/init.py	Adds `fan-out` step implementation (template over items).
src/specify_cli/workflows/steps/fan_in/init.py	Adds `fan-in` step implementation (aggregate prior results).
src/specify_cli/workflows/steps/do_while/init.py	Adds `do-while` loop step implementation.
src/specify_cli/workflows/steps/command/init.py	Adds `command` step implementation that dispatches Spec Kit commands via integrations.
src/specify_cli/workflows/steps/init.py	Adds steps package marker/docstring for step discovery.
src/specify_cli/workflows/expressions.py	Adds sandboxed expression/template evaluator used by workflow steps.
src/specify_cli/workflows/engine.py	Adds workflow definition model, validation, engine execution, and run state persistence.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stack resolution, caching, search, and local workflow registry.
src/specify_cli/workflows/base.py	Adds core workflow types: context/result/status enums and base step interface.
src/specify_cli/workflows/init.py	Adds workflow package exports and registers built-in step types.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support and updates install URL metadata.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI dispatch argument construction.
src/specify_cli/integrations/base.py	Adds shared CLI dispatch API (`build_exec_args`, `dispatch_command`) and skills invocation override.
src/specify_cli/init.py	Adds workflow CLI commands and installs bundled workflow during `specify init`.
pyproject.toml	Bundles the speckit workflow into the package core pack for distribution.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 1

src/specify_cli/workflows/engine.py

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined multi-step automation with resumable execution, control-flow step types, a workflow catalog/registry system, and new specify workflow ... CLI commands. This aligns with the project’s existing “catalog + install + manage” patterns used for other assets (e.g., extensions/presets).

Changes:

Introduces workflow engine core (definition loading/validation, execution, state persistence, expression evaluation).
Adds 10 built-in workflow step types (command/prompt/shell/gate + control-flow and fan-out/fan-in).
Adds workflow catalog + registry support, CLI commands, bundled “speckit” workflow, and comprehensive tests.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds a bundled example workflow (“Full SDD Cycle”) used as the default installed workflow.
workflows/catalog.json	Introduces the official workflow catalog with the bundled `speckit` entry.
workflows/catalog.community.json	Adds an empty community catalog scaffold for future submissions.
workflows/README.md	Documents workflow usage, step types, expressions, state/resume, and catalog management.
workflows/PUBLISHING.md	Adds publishing/submission guidance for workflow authors and catalog updates.
workflows/ARCHITECTURE.md	Documents workflow system internals (engine, step registry, expressions, catalogs, state).
tests/test_workflows.py	Adds end-to-end and unit tests covering engine, steps, expressions, catalog, and persistence.
tests/integrations/test_integration_generic.py	Updates expected init file inventory to include bundled workflow + workflow registry.
tests/integrations/test_integration_copilot.py	Updates expected init file inventory to include bundled workflow + workflow registry.
tests/integrations/test_integration_base_yaml.py	Updates expected init file inventory to include bundled workflow + workflow registry.
tests/integrations/test_integration_base_toml.py	Updates expected init file inventory to include bundled workflow + workflow registry.
tests/integrations/test_integration_base_skills.py	Updates expected init file inventory to include bundled workflow + workflow registry.
tests/integrations/test_integration_base_markdown.py	Updates expected init file inventory to include bundled workflow + workflow registry.
src/specify_cli/workflows/base.py	Defines core workflow data structures (context/result/status) and step base class.
src/specify_cli/workflows/init.py	Implements step registry + explicit registration of built-in step types.
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluation for templating and conditions.
src/specify_cli/workflows/engine.py	Implements workflow definition loading/validation, execution, resume, and run-state persistence.
src/specify_cli/workflows/catalog.py	Implements workflow catalog resolution/merge, caching, search, and installed registry management.
src/specify_cli/workflows/steps/init.py	Adds step package scaffold for built-in step discovery.
src/specify_cli/workflows/steps/command/init.py	Adds command-dispatch step type to run Spec Kit commands via integration CLIs.
src/specify_cli/workflows/steps/prompt/init.py	Adds prompt step type to send arbitrary prompts to integration CLIs.
src/specify_cli/workflows/steps/shell/init.py	Adds local shell execution step type with output capture and timeouts.
src/specify_cli/workflows/steps/gate/init.py	Adds human review “gate” step type with interactive vs non-interactive behavior.
src/specify_cli/workflows/steps/if_then/init.py	Adds conditional branching step type returning nested steps.
src/specify_cli/workflows/steps/switch/init.py	Adds multi-branch switch step type returning nested steps.
src/specify_cli/workflows/steps/while_loop/init.py	Adds while-loop step type (condition evaluated before each iteration).
src/specify_cli/workflows/steps/do_while/init.py	Adds do-while loop step type (body executes at least once).
src/specify_cli/workflows/steps/fan_out/init.py	Adds fan-out step type to expand a step template across a collection.
src/specify_cli/workflows/steps/fan_in/init.py	Adds fan-in step type to aggregate outputs from prior steps.
src/specify_cli/integrations/base.py	Adds CLI dispatch primitives (`build_exec_args`, `dispatch_command`) and defaults for integration types.
src/specify_cli/integrations/copilot/init.py	Extends Copilot integration with CLI dispatch support and install URL metadata.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI dispatch argument builder.
src/specify_cli/init.py	Adds workflow CLI commands + installs bundled workflow during `specify init`.
pyproject.toml	Bundles the `workflows/speckit` assets into the core pack.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 6

src/specify_cli/workflows/engine.py

src/specify_cli/workflows/steps/do_while/__init__.py

workflows/ARCHITECTURE.md

…eserve max_concurrency - Validate schema_version is '1.0' (reject unknown future schemas) - Strict semver regex: ^\d+\.\d+\.\d+$ (rejects 1.0.0beta etc.) - load_workflow docstring: 'parsed' not 'validated' - Keep max_concurrency in fan-out output (was dropped) - do_while docstring: engine re-evaluates step_config condition - ARCHITECTURE.md: document nested resume limitation

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined multi-step automation runs (with branching/loops/gates), resumable execution via persisted state, and a workflow catalog/registry model aligned with existing extension/preset patterns.

Changes:

Introduces workflow engine core (definition loading/validation, expression evaluation, step execution, run state persistence/resume).
Adds built-in step types (command/prompt/shell/gate + control-flow steps like if/switch/loops/fan-out/in).
Adds workflow catalog + registry, CLI commands for managing/running workflows, and bundles an example speckit workflow into specify init with extensive tests.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds bundled “Full SDD Cycle” example workflow definition.
workflows/catalog.json	Adds official workflow catalog entry for `speckit`.
workflows/catalog.community.json	Adds community catalog scaffold (empty workflows object).
workflows/README.md	Documents workflow concepts, step types, expressions, state/resume, and catalog usage.
workflows/PUBLISHING.md	Adds workflow publishing/submission guidance and catalog requirements.
workflows/ARCHITECTURE.md	Documents engine architecture, execution model, and catalog resolution.
tests/test_workflows.py	Adds comprehensive workflow subsystem unit/integration test coverage.
tests/integrations/test_integration_generic.py	Updates expected project file inventory to include bundled workflow artifacts.
tests/integrations/test_integration_copilot.py	Updates expected project file inventory to include bundled workflow artifacts.
tests/integrations/test_integration_base_yaml.py	Updates expected project file inventory to include bundled workflow artifacts.
tests/integrations/test_integration_base_toml.py	Updates expected project file inventory to include bundled workflow artifacts.
tests/integrations/test_integration_base_skills.py	Updates expected project file inventory to include bundled workflow artifacts.
tests/integrations/test_integration_base_markdown.py	Updates expected project file inventory to include bundled workflow artifacts.
src/specify_cli/workflows/steps/while_loop/init.py	Implements `while` control-flow step.
src/specify_cli/workflows/steps/switch/init.py	Implements `switch` branching step.
src/specify_cli/workflows/steps/shell/init.py	Implements `shell` step for local command execution.
src/specify_cli/workflows/steps/prompt/init.py	Implements `prompt` step for ad-hoc integration prompts.
src/specify_cli/workflows/steps/if_then/init.py	Implements `if` step for conditional branching.
src/specify_cli/workflows/steps/gate/init.py	Implements interactive/non-interactive `gate` review step.
src/specify_cli/workflows/steps/fan_out/init.py	Implements `fan-out` step (template expansion over items).
src/specify_cli/workflows/steps/fan_in/init.py	Implements `fan-in` aggregation step.
src/specify_cli/workflows/steps/do_while/init.py	Implements `do-while` looping step.
src/specify_cli/workflows/steps/command/init.py	Implements default `command` step (dispatch Spec Kit commands via integration CLI).
src/specify_cli/workflows/steps/init.py	Declares built-in step auto-discovery package.
src/specify_cli/workflows/expressions.py	Adds sandboxed Jinja-like expression evaluator used by workflows.
src/specify_cli/workflows/engine.py	Adds workflow definition model, validation, execution engine, and run state persistence/resume.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stack + caching and installed workflow registry.
src/specify_cli/workflows/base.py	Adds workflow base types: StepContext/StepResult/status enums/StepBase.
src/specify_cli/workflows/init.py	Adds global step registry and explicit built-in step registration.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support for workflow execution.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI argument builder to support workflow dispatch.
src/specify_cli/integrations/base.py	Adds shared integration CLI dispatch primitives used by workflow steps.
src/specify_cli/init.py	Adds workflow CLI commands and bundles `speckit` workflow install into `specify init`.
pyproject.toml	Bundles `workflows/speckit` into the wheel core pack.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (1)

src/specify_cli/workflows/engine.py:366

WorkflowEngine.load_workflow() interpolates source into an installed-workflow path (.../workflows/<source>/workflow.yml) without validating that source is a safe workflow ID. This enables path traversal reads outside .specify/workflows (e.g., ../...). Validate source against the workflow ID regex (and/or reject any path separators / ..) before using it as a directory name.

            / ".specify"
            / "workflows"
            / str(source)
            / "workflow.yml"
        )

Files reviewed: 34/34 changed files
Comments generated: 3

src/specify_cli/workflows/engine.py

src/specify_cli/__init__.py

- RunState validates run_id is alphanumeric+hyphens (no path separators) - workflow_add validates catalog source doesn't escape workflows_dir - Loop iterations namespace nested step IDs as parentId:childId:iteration so multiple iterations don't overwrite each other in context/state

Copilot

Pull request overview

Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, multi-step automation with resumable execution, control-flow step types, and a catalog/registry system for discovery and installation.

Changes:

Introduces the workflow engine core (definition loading/validation, step execution, run state persistence/resume, sandboxed expression evaluation).
Adds 10 built-in step types (command/prompt/shell/gate + branching/loops/fan-out/fan-in) and wires them into a global step registry.
Adds workflow catalog + registry support, CLI commands for workflow management, and bundles an example speckit workflow into specify init.

Show a summary per file

File	Description
workflows/speckit/workflow.yml	Adds a bundled “Full SDD Cycle” example workflow definition.
workflows/catalog.json	Adds the official workflow catalog including the bundled `speckit` entry.
workflows/catalog.community.json	Adds an empty community catalog scaffold for future submissions.
workflows/README.md	Documents workflow usage, step types, expressions, state/resume, and catalog management.
workflows/PUBLISHING.md	Adds publishing guidance for community workflow submissions and catalog requirements.
workflows/ARCHITECTURE.md	Documents internal workflow engine architecture, execution model, and catalog resolution.
tests/test_workflows.py	Adds comprehensive tests for the workflow engine, steps, expressions, state, and catalog/registry.
tests/integrations/test_integration_generic.py	Updates expected file inventories to include bundled workflows + registry file.
tests/integrations/test_integration_copilot.py	Updates expected file inventories to include bundled workflows + registry file.
tests/integrations/test_integration_base_yaml.py	Updates base integration inventory expectations for bundled workflows.
tests/integrations/test_integration_base_toml.py	Updates base integration inventory expectations for bundled workflows.
tests/integrations/test_integration_base_skills.py	Updates base integration inventory expectations for bundled workflows.
tests/integrations/test_integration_base_markdown.py	Updates base integration inventory expectations for bundled workflows.
src/specify_cli/workflows/base.py	Adds workflow step/run status enums and core StepContext/StepResult/StepBase types.
src/specify_cli/workflows/init.py	Adds STEP_REGISTRY and registers all built-in step implementations.
src/specify_cli/workflows/expressions.py	Adds a sandboxed Jinja2-subset expression/template evaluator with basic filters.
src/specify_cli/workflows/engine.py	Adds WorkflowDefinition, validation, WorkflowEngine execution, and RunState persistence/resume.
src/specify_cli/workflows/catalog.py	Adds workflow catalog stack resolution, caching, searching, and installed registry management.
src/specify_cli/workflows/steps/init.py	Adds step package marker for built-in step types.
src/specify_cli/workflows/steps/command/init.py	Implements command dispatch step type via integration CLIs.
src/specify_cli/workflows/steps/prompt/init.py	Implements free-form prompt dispatch step type via integration CLIs.
src/specify_cli/workflows/steps/shell/init.py	Implements local shell execution step type with timeout + output capture.
src/specify_cli/workflows/steps/gate/init.py	Implements interactive/non-interactive gate step type for human review pauses.
src/specify_cli/workflows/steps/if_then/init.py	Implements conditional branching step type returning nested steps.
src/specify_cli/workflows/steps/switch/init.py	Implements switch/case branching step type returning matched nested steps.
src/specify_cli/workflows/steps/while_loop/init.py	Implements while-loop control-flow step type.
src/specify_cli/workflows/steps/do_while/init.py	Implements do-while-loop control-flow step type.
src/specify_cli/workflows/steps/fan_out/init.py	Implements fan-out step type (engine expands into per-item nested steps).
src/specify_cli/workflows/steps/fan_in/init.py	Implements fan-in aggregation step type over prior step outputs.
src/specify_cli/integrations/base.py	Adds CLI dispatch primitives (`build_exec_args`, `dispatch_command`) for integrations.
src/specify_cli/integrations/copilot/init.py	Adds Copilot CLI dispatch support and an install URL for the CLI tool.
src/specify_cli/integrations/codex/init.py	Adds Codex CLI argument construction for non-interactive dispatch.
src/specify_cli/init.py	Adds workflow CLI commands and installs the bundled `speckit` workflow during init.
pyproject.toml	Bundles `workflows/speckit` into the wheel’s `core_pack` for distribution.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 34/34 changed files
Comments generated: 2

src/specify_cli/workflows/engine.py

src/specify_cli/workflows/steps/gate/__init__.py

Initial plan

58afa3e

Copilot AI assigned Copilot and mnriem Apr 10, 2026

Copilot AI requested review from Copilot and removed request for Copilot April 10, 2026 16:30

Copilot started work on behalf of mnriem April 10, 2026 16:30 View session

Copilot AI linked an issue Apr 10, 2026 that may be closed by this pull request

Workflow Engine with Catalog System #2142

Closed

Add workflow engine with step registry, expression engine, catalog sy…

9ef46b4

…stem, and CLI commands Agent-Logs-Url: https://github.com/github/spec-kit/sessions/72a7bb5d-071f-4d67-a507-7e1abae2384d Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

Copilot AI requested review from Copilot and removed request for Copilot April 10, 2026 16:44

github-code-quality bot found potential problems Apr 10, 2026

View reviewed changes

src/specify_cli/__init__.py Fixed Show fixed Hide fixed

Add comprehensive tests for workflow engine (94 tests)

51d09c0

Agent-Logs-Url: https://github.com/github/spec-kit/sessions/72a7bb5d-071f-4d67-a507-7e1abae2384d Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

Copilot AI requested review from Copilot and removed request for Copilot April 10, 2026 16:48

Address review feedback: do-while condition preservation and URL sche…

273dd70

…me validation Agent-Logs-Url: https://github.com/github/spec-kit/sessions/72a7bb5d-071f-4d67-a507-7e1abae2384d Co-authored-by: mnriem <15701806+mnriem@users.noreply.github.com>

Copilot AI requested review from Copilot and removed request for Copilot April 10, 2026 16:51

Copilot AI changed the title ~~[WIP] Add workflow engine with catalog system to Specify CLI~~ Add workflow engine with catalog system Apr 10, 2026

Copilot AI requested a review from mnriem April 10, 2026 16:54

Copilot finished work on behalf of mnriem April 10, 2026 16:54

mnriem marked this pull request as ready for review April 13, 2026 19:39

Copilot AI review requested due to automatic review settings April 13, 2026 19:39

Copilot started reviewing on behalf of mnriem April 13, 2026 19:40 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

mnriem added 2 commits April 13, 2026 16:37

Fix ruff lint errors: unused imports, f-string placeholders, undefine…

eb7a764

…d name

Copilot AI review requested due to automatic review settings April 13, 2026 21:43

Copilot started reviewing on behalf of mnriem April 13, 2026 21:43 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

Copilot AI reviewed Apr 14, 2026

View reviewed changes

mnriem requested a review from Copilot April 14, 2026 12:12

Copilot started reviewing on behalf of mnriem April 14, 2026 12:12 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

mnriem requested a review from Copilot April 14, 2026 12:37

Copilot started reviewing on behalf of mnriem April 14, 2026 12:37 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/engine.py Show resolved Hide resolved

src/specify_cli/workflows/steps/do_while/__init__.py Outdated Show resolved Hide resolved

mnriem requested a review from Copilot April 14, 2026 13:01

Copilot started reviewing on behalf of mnriem April 14, 2026 13:01 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/engine.py Outdated Show resolved Hide resolved

src/specify_cli/__init__.py Outdated Show resolved Hide resolved

Coerce default_options to dict, align bundled workflow ID regex with …

d299495

…validator

mnriem requested a review from Copilot April 14, 2026 13:18

Copilot started reviewing on behalf of mnriem April 14, 2026 13:18 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/steps/gate/__init__.py Show resolved Hide resolved

src/specify_cli/workflows/steps/prompt/__init__.py Outdated Show resolved Hide resolved

src/specify_cli/workflows/engine.py Outdated Show resolved Hide resolved

Gate validates string options, prompt uses resolved integration, loop…

b89dcf0

… normalizes max_iterations

mnriem requested a review from Copilot April 14, 2026 13:41

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/engine.py Outdated Show resolved Hide resolved

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/engine.py Show resolved Hide resolved

Validate workflow version is semantic versioning (X.Y.Z)

9893282

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/engine.py Show resolved Hide resolved

src/specify_cli/workflows/engine.py Show resolved Hide resolved

src/specify_cli/__init__.py Show resolved Hide resolved

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/workflows/engine.py Show resolved Hide resolved

src/specify_cli/workflows/steps/gate/__init__.py Show resolved Hide resolved

mnriem mentioned this pull request Apr 14, 2026

Workflow Step Catalog — community-installable step types #2216

Open

Conversation

Copilot AI commented Apr 10, 2026 • edited by mnriem Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Workflow engine core (src/specify_cli/workflows/)

10 built-in step types (workflows/steps/)

CLI commands

Catalog files

Example workflow definition

Tests

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot AI commented Apr 10, 2026 •

edited by mnriem

Loading

Workflow engine core (`src/specify_cli/workflows/`)

10 built-in step types (`workflows/steps/`)