Open
Conversation
…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>
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
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
AI
changed the title
[WIP] Add workflow engine with catalog system to Specify CLI
Add workflow engine with catalog system
Apr 10, 2026
Contributor
There was a problem hiding this comment.
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.workflowscore 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 samplespeckitworkflow, 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()treatsresult.next_stepsas 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, enforcingmax_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
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)
Contributor
There was a problem hiding this comment.
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.workflowsengine 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
…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
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling YAML-defined multi-step automation with resumable execution, control-flow steps, and a catalog/registry mechanism aligned with the existing catalog patterns.
Changes:
- Introduces workflow engine primitives (definition loading/validation, expression evaluation, step registry, run state persistence, resume support).
- Adds built-in workflow step types (command/prompt/shell/gate + control-flow and fan-out/fan-in).
- Adds workflow CLI commands plus built-in/workflow community catalog files and documentation.
Show a summary per file
| File | Description |
|---|---|
| workflows/speckit/workflow.yml | Adds an example built-in “Full SDD Cycle” workflow definition. |
| workflows/catalog.json | Adds the official workflow catalog entry for speckit. |
| workflows/catalog.community.json | Adds an (empty) community workflow catalog scaffold. |
| workflows/README.md | Documents workflow usage, step types, expressions, state/resume, and catalogs. |
| workflows/PUBLISHING.md | Adds workflow catalog submission/publishing instructions and conventions. |
| workflows/ARCHITECTURE.md | Documents engine execution model, step registry, expression engine, and catalogs. |
| tests/test_workflows.py | Adds comprehensive unit/integration tests for workflows subsystem. |
| src/specify_cli/workflows/base.py | Defines core workflow types (context/result/status/base step). |
| src/specify_cli/workflows/init.py | Implements the step registry and built-in step registration. |
| src/specify_cli/workflows/expressions.py | Adds a sandboxed Jinja2-like expression evaluator and filters. |
| src/specify_cli/workflows/engine.py | Implements workflow execution, nested steps, loops, fan-out, and run persistence/resume. |
| src/specify_cli/workflows/catalog.py | Implements workflow catalog resolution/caching and installed workflow registry. |
| src/specify_cli/workflows/steps/*/init.py | Implements built-in step types (command/prompt/shell/gate/if/switch/while/do-while/fan-out/fan-in). |
| src/specify_cli/integrations/base.py | Adds generic CLI dispatch primitives used by workflow steps. |
| src/specify_cli/integrations/copilot/init.py | Adds Copilot CLI dispatch support used by workflow command/prompt steps. |
| src/specify_cli/integrations/codex/init.py | Adds Codex CLI argument builder for non-interactive dispatch. |
| src/specify_cli/init.py | Adds specify workflow ... CLI commands and catalog management commands. |
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: 1
- Add workflows/speckit to pyproject.toml force-include for wheel builds - Add _locate_bundled_workflow() helper (mirrors _locate_bundled_extension) - Auto-install speckit workflow during specify init (after git extension) - Update all integration file inventory tests to expect workflow files
- Keep both workflow and preset force-include in pyproject.toml - Keep both _locate_bundled_workflow and _locate_bundled_preset helpers - Add workflow files to yaml base inventory test (goose)
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling YAML-defined multi-step, resumable automation workflows with built-in control-flow steps, CLI dispatch to integrations, run-state persistence, and a catalog/registry system consistent with existing catalog patterns.
Changes:
- Introduces workflow engine core (definition loading/validation, execution, expressions, state persistence) plus 10 built-in step types.
- Adds workflow catalog + registry management, CLI commands (
specify workflow ...), and bundles an example “speckit” workflow into init/install flows. - Adds extensive test coverage for the workflow system and updates integration tests/file inventories accordingly.
Show a summary per file
| File | Description |
|---|---|
| workflows/speckit/workflow.yml | Adds a bundled example “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 usage, step types, expressions, catalogs, and state/resume. |
| workflows/PUBLISHING.md | Adds workflow publishing guidelines and community catalog rules. |
| workflows/ARCHITECTURE.md | Documents workflow engine architecture, execution model, and catalog resolution. |
| tests/test_workflows.py | Adds comprehensive tests for workflow engine, steps, expressions, catalog, and persistence. |
| tests/integrations/test_integration_generic.py | Updates expected project inventory to include bundled workflow + registry. |
| tests/integrations/test_integration_copilot.py | Updates expected project inventory to include bundled workflow + registry. |
| tests/integrations/test_integration_base_toml.py | Updates expected inventory helper to include bundled workflow + registry. |
| tests/integrations/test_integration_base_skills.py | Updates expected inventory helper to include bundled workflow + registry. |
| tests/integrations/test_integration_base_markdown.py | Updates expected inventory helper to include bundled workflow + registry. |
| 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 (local shell execution). |
| src/specify_cli/workflows/steps/prompt/init.py | Adds prompt step implementation (inline prompt dispatch). |
| src/specify_cli/workflows/steps/if_then/init.py | Adds if step implementation (then/else branching). |
| src/specify_cli/workflows/steps/gate/init.py | Adds gate step (interactive/CI pause + reject handling). |
| src/specify_cli/workflows/steps/fan_out/init.py | Adds fan-out step (template expansion over items). |
| src/specify_cli/workflows/steps/fan_in/init.py | Adds fan-in step (aggregation/join). |
| 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 (integration CLI dispatch). |
| 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 evaluator and filters. |
| src/specify_cli/workflows/engine.py | Adds workflow definition/model, validation, execution engine, and run-state persistence. |
| src/specify_cli/workflows/catalog.py | Adds catalog stack resolution, URL validation, caching, search, and registry management. |
| src/specify_cli/workflows/base.py | Adds workflow base types: statuses, context, result, abstract step base. |
| src/specify_cli/workflows/init.py | Registers built-in step types into a global registry. |
| src/specify_cli/integrations/copilot/init.py | Extends Copilot integration to support CLI dispatch (workflows). |
| src/specify_cli/integrations/codex/init.py | Adds Codex CLI exec-arg builder for dispatch support. |
| src/specify_cli/integrations/base.py | Adds generic CLI-dispatch primitives to IntegrationBase + subclasses. |
| src/specify_cli/init.py | Adds workflow CLI commands and installs bundled workflow during 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.
- Files reviewed: 34/34 changed files
- Comments generated: 4
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, multi-step, resumable automation (including control-flow steps) with a catalog/registry model similar to extensions/presets, plus new CLI commands to run/manage workflows.
Changes:
- Introduces workflow engine core (definition loading/validation, step execution, expression evaluation, run-state persistence/resume).
- Adds built-in step types (command/prompt/shell/gate + branching/loops + fan-out/fan-in) and a workflow catalog/registry layer.
- Extends integrations with a CLI-dispatch interface and updates
specify init+ CLI surface area to bundle/install and manage workflows.
Show a summary per file
| File | Description |
|---|---|
| workflows/speckit/workflow.yml | Adds a bundled “Full SDD Cycle” example workflow definition. |
| workflows/catalog.json | Introduces official workflow catalog format and initial entry for speckit. |
| workflows/catalog.community.json | Adds the community workflow catalog scaffold. |
| workflows/README.md | Documents workflow concepts, step types, expressions, and catalog usage. |
| workflows/PUBLISHING.md | Provides workflow publishing guidance and catalog entry requirements. |
| workflows/ARCHITECTURE.md | Documents workflow engine internals and execution model. |
| tests/test_workflows.py | Adds comprehensive unit/integration tests for the workflow subsystem. |
| tests/integrations/test_integration_generic.py | Updates expected file inventories to include bundled workflow artifacts. |
| tests/integrations/test_integration_copilot.py | Updates expected file inventories to include bundled workflow artifacts. |
| tests/integrations/test_integration_base_yaml.py | Updates baseline inventory expectations for YAML integrations. |
| tests/integrations/test_integration_base_toml.py | Updates baseline inventory expectations for TOML integrations. |
| tests/integrations/test_integration_base_skills.py | Updates baseline inventory expectations for Skills integrations. |
| tests/integrations/test_integration_base_markdown.py | Updates baseline inventory expectations for Markdown integrations. |
| src/specify_cli/workflows/init.py | Adds step registry + built-in step registration. |
| src/specify_cli/workflows/base.py | Defines workflow base types (context/result/status + step base). |
| src/specify_cli/workflows/expressions.py | Implements a sandboxed, Jinja-like expression evaluator for templates/conditions. |
| src/specify_cli/workflows/engine.py | Implements workflow loading, validation, execution, fan-out, loops, and run persistence. |
| src/specify_cli/workflows/catalog.py | Implements catalog resolution/caching + installed workflow registry. |
| src/specify_cli/workflows/steps/init.py | Adds steps package (auto-discovery placeholder). |
| src/specify_cli/workflows/steps/command/init.py | Adds the command-dispatch step type (integration CLI dispatch). |
| src/specify_cli/workflows/steps/prompt/init.py | Adds the prompt step type (free-form integration prompt). |
| src/specify_cli/workflows/steps/shell/init.py | Adds the shell step type (local shell command execution). |
| src/specify_cli/workflows/steps/gate/init.py | Adds the gate step type (interactive pause/approval). |
| src/specify_cli/workflows/steps/if_then/init.py | Adds conditional branching step type. |
| src/specify_cli/workflows/steps/switch/init.py | Adds switch/case branching step type. |
| src/specify_cli/workflows/steps/while_loop/init.py | Adds pre-condition loop step type. |
| src/specify_cli/workflows/steps/do_while/init.py | Adds post-condition loop step type. |
| src/specify_cli/workflows/steps/fan_out/init.py | Adds fan-out step type (iterative expansion over items). |
| src/specify_cli/workflows/steps/fan_in/init.py | Adds fan-in step type (aggregation/join behavior). |
| src/specify_cli/integrations/base.py | Adds generic CLI dispatch hooks for integrations (exec args + dispatch). |
| src/specify_cli/integrations/copilot/init.py | Adds Copilot CLI dispatch behavior and updates integration description. |
| src/specify_cli/integrations/codex/init.py | Adds Codex CLI exec-args builder. |
| src/specify_cli/init.py | Adds bundled workflow installation in init and new specify workflow ... CLI commands. |
| 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: 5
…ta, fan-out normalization - PromptStep returns FAILED when CLI not installed (was silent COMPLETED) - Engine step_data prefers resolved values from step output - Fan-out normalizes output.results=[] for empty item lists - subprocess.run inherits stdout/stderr (no explicit sys.stdout) - Registry tests use issubset for extensibility
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, multi-step, resumable automation with control-flow steps, state persistence, CLI dispatch to integrations, and a workflow catalog/registry model aligned with existing extension/preset patterns.
Changes:
- Introduces workflow engine core (
WorkflowDefinition, validation, sequential executor with nested steps,RunStatepersistence/resume). - Adds built-in step types (command/prompt/shell/gate/control-flow/fan-out/fan-in) plus expression evaluation for templating.
- Adds workflow catalogs + registry + new
specify workflow ...CLI surface area and bundles thespeckitworkflow intospecify 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 containing the bundled speckit entry. |
| workflows/catalog.community.json | Adds initial empty community workflow catalog scaffold. |
| workflows/README.md | Documents workflow usage, step types, expressions, state/resume, and catalog management. |
| workflows/PUBLISHING.md | Adds workflow publishing guide and 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, catalog/registry, persistence). |
| tests/integrations/test_integration_generic.py | Updates expected installed file inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_copilot.py | Updates expected installed file inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_base_yaml.py | Updates expected file inventory helpers for YAML integrations to include bundled workflow + registry. |
| tests/integrations/test_integration_base_toml.py | Updates expected file inventory helpers for TOML integrations to include bundled workflow + registry. |
| tests/integrations/test_integration_base_skills.py | Updates expected file inventory helpers for skills integrations to include bundled workflow + registry. |
| tests/integrations/test_integration_base_markdown.py | Updates expected file inventory helpers for markdown integrations to include bundled workflow + registry. |
| src/specify_cli/workflows/steps/while_loop/init.py | Adds while control-flow step implementation and validation. |
| src/specify_cli/workflows/steps/switch/init.py | Adds switch control-flow step implementation and validation. |
| src/specify_cli/workflows/steps/shell/init.py | Adds shell step executing local shell commands with captured output. |
| src/specify_cli/workflows/steps/prompt/init.py | Adds prompt step dispatching free-form prompts to integration CLIs. |
| src/specify_cli/workflows/steps/if_then/init.py | Adds if control-flow step implementation and validation. |
| src/specify_cli/workflows/steps/gate/init.py | Adds interactive/CI-pausing gate step type. |
| src/specify_cli/workflows/steps/fan_out/init.py | Adds fan-out step emitting an item-expanded template for execution. |
| src/specify_cli/workflows/steps/fan_in/init.py | Adds fan-in aggregation step over prior step outputs. |
| src/specify_cli/workflows/steps/do_while/init.py | Adds do-while control-flow step implementation and validation. |
| src/specify_cli/workflows/steps/command/init.py | Adds default command step that dispatches Spec Kit commands via integration CLIs. |
| src/specify_cli/workflows/steps/init.py | Adds steps package marker for built-in step auto-discovery. |
| src/specify_cli/workflows/expressions.py | Adds sandboxed Jinja-like expression/template evaluator and filters. |
| src/specify_cli/workflows/engine.py | Adds workflow definition loading, validation, execution engine, and RunState persistence/resume. |
| src/specify_cli/workflows/catalog.py | Adds workflow catalog resolution/caching/search and installed-workflow registry. |
| src/specify_cli/workflows/base.py | Adds base workflow types (StepBase, StepContext, StepResult, status enums). |
| src/specify_cli/workflows/init.py | Adds global STEP_REGISTRY and registers built-in step implementations. |
| src/specify_cli/integrations/copilot/init.py | Adds CLI dispatch support for Copilot integration (agent-based invocation). |
| src/specify_cli/integrations/codex/init.py | Adds CLI exec arg builder for Codex integration. |
| src/specify_cli/integrations/base.py | Adds generic CLI-dispatch building blocks to integration base classes. |
| src/specify_cli/init.py | Adds bundled workflow install during init and new specify workflow ... CLI commands. |
| 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.
Comments suppressed due to low confidence (2)
src/specify_cli/workflows/engine.py:670
_resolve_inputs()also assumesdefinition.inputsis a dict and will throw ifinputs:in YAML isnull/a list. Consider normalizingWorkflowDefinition.inputsto{}when not a mapping, or adding an explicit type check here that raises a clearValueError(or returns a validation error earlier) soworkflow runfails gracefully.
"""Resolve workflow inputs against definitions and provided values."""
resolved: dict[str, Any] = {}
for name, input_def in definition.inputs.items():
if not isinstance(input_def, dict):
continue
src/specify_cli/integrations/copilot/init.py:94
dispatch_command()also hard-codes--allow-all-toolsfor streamed runs. If--allow-all-toolsremains necessary for some workflows, it should still be gated behind an explicit opt-in (and ideally recorded in run state/logs) so users understand they're granting full tool permissions to the agent.
# NOTE: --allow-all-tools is required for non-interactive execution
# so the agent can perform file edits and shell commands. The
# workflow engine's gate steps serve as the human approval mechanism.
# Making tool approval configurable (e.g. via workflow config or
# env var) is tracked as a future enhancement.
cli_args = [
"copilot", "-p", prompt,
"--agent", agent_name,
"--allow-all-tools",
]
- Files reviewed: 34/34 changed files
- Comments generated: 6
… guards, reserved prefix - FanInStep docstring: aggregate-only, no blocking semantics - FanInStep: guard output_config as dict, handle None - Gate validate: use same default options as execute - Validate inputs is dict and steps is list before iterating - Reserve _fanout_ prefix in step ID validation - PUBLISHING.md: remove unenforced checklist items, add _fanout_ note
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling YAML-defined multi-step automation with resumable execution, control-flow steps, an expression evaluator, and a workflow catalog/registry model aligned with existing catalogs.
Changes:
- Introduces workflow engine core (definition loading/validation, execution, state persistence, expression evaluation, catalog + registry).
- Adds 10 built-in workflow step types (command/prompt/shell/gate + control flow + fan-out/fan-in).
- Extends the CLI with
specify workflow ...commands and bundles a built-inspeckitworkflow (packaged + installed duringspecify init), with extensive new test coverage.
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 with speckit entry. |
| workflows/catalog.community.json | Adds empty community workflow catalog scaffold. |
| workflows/README.md | Documents workflow usage, step types, expressions, catalogs, state/resume. |
| workflows/PUBLISHING.md | Adds workflow publishing/submission guidance (incl. community catalog rules). |
| workflows/ARCHITECTURE.md | Documents internal engine architecture and execution model. |
| tests/test_workflows.py | Adds comprehensive tests for workflow engine, steps, expressions, catalog/registry. |
| tests/integrations/test_integration_generic.py | Updates expected .specify/ inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_copilot.py | Updates expected .specify/ inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_base_yaml.py | Updates base integration inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_base_toml.py | Updates base integration inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_base_skills.py | Updates base integration inventory to include bundled workflow + registry file. |
| tests/integrations/test_integration_base_markdown.py | Updates base integration inventory to include bundled workflow + registry file. |
| src/specify_cli/workflows/base.py | Adds step/run status enums and base dataclasses/contracts for steps. |
| src/specify_cli/workflows/init.py | Adds global STEP_REGISTRY and explicit built-in step registration. |
| src/specify_cli/workflows/expressions.py | Adds sandboxed expression evaluator + filters for workflow templates. |
| src/specify_cli/workflows/engine.py | Implements definition loading, validation, execution, resume, and run-state persistence. |
| src/specify_cli/workflows/catalog.py | Implements workflow catalog stack resolution, caching, search, and installed registry. |
| src/specify_cli/workflows/steps/init.py | Step package scaffold for built-in step implementations. |
| src/specify_cli/workflows/steps/command/init.py | Implements command dispatch step via integration CLIs. |
| src/specify_cli/workflows/steps/prompt/init.py | Implements free-form prompt step via integration CLIs. |
| src/specify_cli/workflows/steps/shell/init.py | Implements local shell execution step with captured output. |
| src/specify_cli/workflows/steps/gate/init.py | Implements interactive/non-interactive approval gate step. |
| src/specify_cli/workflows/steps/if_then/init.py | Implements conditional branching control-flow step. |
| src/specify_cli/workflows/steps/switch/init.py | Implements multi-branch switch control-flow step. |
| src/specify_cli/workflows/steps/while_loop/init.py | Implements while-loop control-flow step. |
| src/specify_cli/workflows/steps/do_while/init.py | Implements do-while loop control-flow step. |
| src/specify_cli/workflows/steps/fan_out/init.py | Implements fan-out expansion step template over an item list. |
| src/specify_cli/workflows/steps/fan_in/init.py | Implements fan-in aggregation step for fan-out results. |
| src/specify_cli/integrations/base.py | Adds CLI dispatch primitives (build_exec_args, dispatch_command, invocation building). |
| src/specify_cli/integrations/copilot/init.py | Adds Copilot CLI dispatch support (agent selection + exec args). |
| src/specify_cli/integrations/codex/init.py | Adds Codex CLI exec-args builder. |
| src/specify_cli/init.py | Adds workflow CLI commands and installs bundled speckit workflow during specify init. |
| pyproject.toml | Bundles workflows/speckit into the packaged core assets. |
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/expressions.py:193
- Membership operators can raise at runtime here:
left in right/left not in rightwill throwTypeErrorifrightis a non-iterable (e.g., an int). Since expressions are user-authored YAML, it’d be safer for the evaluator to catchTypeErrorand returnFalse(or a deterministic value) instead of crashing the workflow engine.
if op == " in ":
return left in right if right is not None else False
if op == " not in ":
return left not in right if right is not None else True
- Files reviewed: 34/34 changed files
- Comments generated: 3
…dot-path keys - PUBLISHING.md: update ID regex docs to match implementation (single-char OK) - FanInStep: wrap expression evaluation in try/finally for context.fan_in - Expression dot-path: allow hyphens in keys before list index (e.g. run-tests[0])
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling YAML-defined, resumable multi-step automation with a catalog/registry model and new CLI surface area.
Changes:
- Introduces workflow engine core (definition loading/validation, execution, state persistence, expression evaluation).
- Adds built-in step types (command/prompt/shell/gate + control-flow and fan-out/fan-in) and workflow catalog + installed registry support.
- Bundles an example “speckit” workflow, wires workflow commands into the CLI, and adds extensive tests.
Show a summary per file
| File | Description |
|---|---|
| workflows/speckit/workflow.yml | Adds bundled example workflow definition. |
| workflows/catalog.json | Adds official workflow catalog (speckit entry). |
| workflows/catalog.community.json | Adds empty community workflow catalog scaffold. |
| workflows/README.md | Documents workflow usage, step types, expressions, catalogs, and layout. |
| workflows/PUBLISHING.md | Adds workflow publishing and community catalog submission guide. |
| workflows/ARCHITECTURE.md | Documents workflow engine architecture and execution model. |
| src/specify_cli/workflows/init.py | Implements step registry and built-in step registration. |
| src/specify_cli/workflows/base.py | Adds core workflow types (context/result/status + base class). |
| src/specify_cli/workflows/expressions.py | Adds sandboxed template/expression evaluation and filters. |
| src/specify_cli/workflows/engine.py | Adds workflow definition parsing, validation, execution, resume, and run-state persistence. |
| src/specify_cli/workflows/catalog.py | Adds catalog stack resolution, caching, search, and installed registry. |
| src/specify_cli/workflows/steps/init.py | Adds step package marker for built-in step discovery. |
| src/specify_cli/workflows/steps/command/init.py | Adds command-dispatch step implementation. |
| src/specify_cli/workflows/steps/prompt/init.py | Adds free-form prompt step implementation. |
| src/specify_cli/workflows/steps/shell/init.py | Adds local shell execution step implementation. |
| src/specify_cli/workflows/steps/gate/init.py | Adds interactive/CI-pausing human review gate step. |
| src/specify_cli/workflows/steps/if_then/init.py | Adds conditional branching step. |
| src/specify_cli/workflows/steps/switch/init.py | Adds multi-branch switch 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 control-flow step. |
| src/specify_cli/workflows/steps/fan_out/init.py | Adds fan-out step definition (engine expands execution). |
| src/specify_cli/workflows/steps/fan_in/init.py | Adds fan-in aggregation step. |
| src/specify_cli/integrations/base.py | Adds generic CLI dispatch primitives for integrations. |
| src/specify_cli/integrations/copilot/init.py | Adds Copilot CLI dispatch support for workflows. |
| src/specify_cli/integrations/codex/init.py | Adds Codex CLI exec-args builder for dispatch. |
| src/specify_cli/init.py | Installs bundled workflow on init; adds specify workflow ... commands. |
| tests/test_workflows.py | Adds workflow subsystem test coverage (registry/expressions/engine/steps/catalog). |
| tests/integrations/test_integration_*.py | Updates expected file inventories to include bundled workflow + registry file. |
| pyproject.toml | Packages bundled workflow into 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/integrations/copilot/init.py:51
--allow-all-toolsis being added to Copilot CLI invocations by default. This effectively grants the agent unrestricted tool (file + shell) access during command/prompt steps, including before any workflowgateruns, which weakens the safety model for workflows installed from catalogs/URLs. Consider making tool-approval opt-in (e.g., a workflow/step flag or env var) and defaulting to the safer CLI behavior unless explicitly enabled by the user.
# GitHub Copilot CLI uses ``copilot -p "prompt"`` for
# non-interactive mode. --allow-all-tools lets the agent
# execute file edits and shell commands without manual approval.
args = ["copilot", "-p", prompt, "--allow-all-tools"]
if model:
- Files reviewed: 34/34 changed files
- Comments generated: 2
…irement
- Workflow integration selectable via input (default: claude)
- Each command step uses {{ inputs.integration }} instead of hardcoded copilot
- Copilot docstring documents CLI requirement for workflow dispatch
- Added install_url for Copilot CLI docs
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new workflow subsystem to Specify CLI, enabling multi-step, resumable automation workflows defined in YAML, with execution/state persistence and a catalog/registry system similar to extensions/presets.
Changes:
- Introduces workflow engine core (
WorkflowEngine, step base types, expression evaluation, run state persistence, validation). - Adds built-in step types (command/prompt/shell/gate + control-flow constructs like if/switch/while/do-while/fan-out/fan-in).
- Adds workflow CLI commands and workflow catalog/registry management, plus bundled “speckit” workflow and extensive tests/docs.
Show a summary per file
| File | Description |
|---|---|
| workflows/speckit/workflow.yml | Adds a bundled example “Full SDD Cycle” workflow definition. |
| workflows/catalog.json | Introduces 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 usage, step types, expressions, state/resume, and catalog management. |
| workflows/PUBLISHING.md | Adds publishing guidance and community catalog submission requirements. |
| workflows/ARCHITECTURE.md | Documents workflow engine architecture, execution model, and catalog resolution. |
| tests/test_workflows.py | Adds broad unit/integration coverage for the workflow subsystem and step types. |
| tests/integrations/test_integration_generic.py | Updates expected file inventory to include bundled workflow + workflow registry. |
| tests/integrations/test_integration_copilot.py | Updates expected file inventory to include bundled workflow + workflow registry. |
| 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 | Implements the while control-flow step. |
| src/specify_cli/workflows/steps/switch/init.py | Implements the switch control-flow step. |
| src/specify_cli/workflows/steps/shell/init.py | Implements the shell step for local command execution. |
| src/specify_cli/workflows/steps/prompt/init.py | Implements the prompt step for free-form integration prompts. |
| src/specify_cli/workflows/steps/if_then/init.py | Implements the if control-flow step. |
| src/specify_cli/workflows/steps/gate/init.py | Implements the interactive/non-interactive gate step. |
| src/specify_cli/workflows/steps/fan_out/init.py | Implements fan-out (iterative 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 the do-while control-flow step. |
| src/specify_cli/workflows/steps/command/init.py | Implements the default command step dispatching to 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 a sandboxed expression evaluator for {{ ... }} templates. |
| src/specify_cli/workflows/engine.py | Adds workflow parsing/validation, sequential execution, resume, loops, and fan-out handling. |
| src/specify_cli/workflows/catalog.py | Adds workflow catalog resolution, caching, search, and installed workflow registry. |
| src/specify_cli/workflows/base.py | Defines StepBase, StepContext, StepResult, and status enums. |
| src/specify_cli/workflows/init.py | Adds global STEP_REGISTRY and registers built-in steps. |
| src/specify_cli/integrations/copilot/init.py | Adds CLI dispatch support for Copilot (build args + dispatch behavior). |
| src/specify_cli/integrations/codex/init.py | Adds CLI exec-args builder for Codex integration. |
| src/specify_cli/integrations/base.py | Adds shared CLI-dispatch primitives (build_exec_args, dispatch_command, invocation building). |
| src/specify_cli/init.py | Adds bundled workflow installation during init + workflow CLI command group and subcommands. |
| pyproject.toml | Bundles workflows/speckit into the wheel via hatch force-include. |
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
- Add .specify/ project check to workflow run/resume/status/search/info - remove_catalog validates config shape (dict + list) before indexing - _fetch_single_catalog validates response is a dict - _get_merged_workflows raises when all catalogs fail to fetch - add_catalog guards against non-dict catalog entries in config
Contributor
There was a problem hiding this comment.
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
Comment on lines
+285
to
+292
| def evaluate_condition(condition: str, context: Any) -> bool: | ||
| """Evaluate a condition expression and return a boolean. | ||
|
|
||
| Convenience wrapper around ``evaluate_expression`` that coerces | ||
| the result to bool. | ||
| """ | ||
| result = evaluate_expression(condition, context) | ||
| return bool(result) |
There was a problem hiding this comment.
evaluate_condition() coerces the evaluated result with bool(result), which makes a non-empty string like "false" truthy. This can yield surprising behavior if a workflow author writes condition: "false" (or any non-empty string without {{ }}), as it will evaluate to True. Consider either (a) rejecting plain strings for conditions in step validation unless they contain {{, or (b) special-casing string literals (e.g., case-insensitive "true"/"false") before bool() coercion.
Comment on lines
+54
to
+58
| if choice in ("reject", "abort"): | ||
| if on_reject == "abort": | ||
| from specify_cli.workflows.engine import WorkflowAbortError | ||
| raise WorkflowAbortError(f"Gate rejected by user at step {config.get('id', '?')!r}") | ||
| if on_reject == "retry": |
There was a problem hiding this comment.
When on_reject == "abort", this step raises WorkflowAbortError instead of returning a StepResult. Because the engine records step results only after execute() returns, the gate’s output.choice and other context are not persisted in state.step_results, which makes aborted runs harder to inspect/debug. Consider returning a StepResult that contains the chosen option and then letting the engine mark the run aborted (or raising an exception type that carries the output so the engine can persist it before aborting).
Comment on lines
+21
to
+24
| def execute(self, config: dict[str, Any], context: StepContext) -> StepResult: | ||
| condition = config.get("condition", False) | ||
| max_iterations = config.get("max_iterations", 10) | ||
| nested_steps = config.get("steps", []) |
There was a problem hiding this comment.
execute() defaults max_iterations to 10, but validate() currently treats a missing max_iterations as an error (i.e., it’s required). This mismatch makes the default unreachable in validated workflows and can confuse API users who execute without calling validate(). Consider either removing the default and failing fast when missing, or making max_iterations optional in validation (and documenting the default).
Comment on lines
+347
to
+348
| with open(cache_file, encoding="utf-8") as f: | ||
| return json.load(f) |
There was a problem hiding this comment.
If fetching the catalog URL fails, the code falls back to the cached JSON without handling the case where the cache file exists but is unreadable/invalid JSON (the json.load() here can raise and mask the original fetch error). Consider wrapping the cache fallback json.load() in a try/except and, if it fails, raising a WorkflowCatalogError that includes both the fetch failure and the cache read failure.
Suggested change
| with open(cache_file, encoding="utf-8") as f: | |
| return json.load(f) | |
| try: | |
| with open(cache_file, encoding="utf-8") as f: | |
| return json.load(f) | |
| except (json.JSONDecodeError, OSError) as cache_exc: | |
| raise WorkflowCatalogError( | |
| f"Failed to fetch catalog from {entry.url}: {exc}; " | |
| f"failed to read cached catalog from {cache_file}: {cache_exc}" | |
| ) from cache_exc |
| raise | ||
|
|
||
| if state.status == RunStatus.RUNNING: | ||
| state.status = RunStatus.COMPLETED |
There was a problem hiding this comment.
resume() doesn’t append a final "workflow_finished" (or similar) log entry the way execute() does. As a result, the run log will differ depending on whether a workflow completed via an initial run or via resume, which makes downstream tooling/log inspection less consistent. Consider appending the same completion log event(s) as execute() before saving/returning.
Suggested change
| state.status = RunStatus.COMPLETED | |
| state.status = RunStatus.COMPLETED | |
| state.append_log({"event": "workflow_finished"}) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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—StepBaseabstract class,StepContext,StepResult, status enums__init__.py—STEP_REGISTRYwith auto-discovery, mirrorsINTEGRATION_REGISTRYexpressions.py— Sandboxed Jinja2-subset evaluator (variable interpolation, comparisons, boolean logic, filters likedefault,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 aStepBasesubclass in its own subpackage, same extensibility model as integrations.CLI commands
specify workflow run|resume|status|list|add|remove|search|infoplusspecify workflow catalog list|add|remove.Catalog files
workflows/catalog.json,workflows/catalog.community.json, and an exampleworkflows/speckit/workflow.yml(full SDD cycle).Example workflow definition
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).