π« Toolkit to help you get started with SDD or any other process!
feat(workflows): add workflow slots (#4352)
Markus Wondrak878f0316d7a9
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.mdindex 3b838b722..df634ffe7 100644--- a/docs/reference/workflows.md+++ b/docs/reference/workflows.md@@ -286,6 +286,40 @@ edits:Lower priority values have higher precedence. Change this overlay to `priority: 5` if it must win a conflict with the `add-lint` overlay above. It replaces the `review-plan` gate with a non-interactive command.+### Workflow slots (upstream extension points)++Workflow authors can declare a named, no-op workflow slot with `type: slot`:++```yaml+- id: post-implement+ type: slot+ name: "Post-implementation checks"+```++The step `id` is the unique overlay anchor; `name` is a required non-blank,+human-readable label only. An unfilled slot completes as a `skipped` step with+`output: {slot: <name>}`, so subsequent steps continue normally.++Fill a slot with a schema-valid overlay `replace` edit anchored on the step+`id`, not its `name`:++```yaml+id: fill-post-implement+extends: my-workflow+edits:+ - replace: post-implement+ step:+ id: post-implement+ type: shell+ run: "echo Run project-specific checks"+```++Reuse the slot's `id` when later expressions or `fan-in.wait_for` refer to it.+The replacement must also preserve every output key those later steps consume:+an unfilled workflow slot supplies only `steps.<id>.output.slot`. Slot steps are+not supported inside `fan-out.step` templates because runtime-multiplied+templates cannot be overlay anchors.+### Interaction with Bundles and Updates`specify workflow add <local-directory>` installs the complete local workflow@@ -494,6 +528,7 @@ specify workflow run speckit -i spec="Build a kanban board with drag-and-drop ta| `prompt` | Send an arbitrary prompt to the AI coding agent || `shell` | Execute a shell command and capture output || `init` | Bootstrap a project (like `specify init`) |+| `slot` | Named workflow slot; skipped when unfilled || `gate` | Pause for human approval before continuing || `if` | Conditional branching (then/else) || `switch` | Multi-branch dispatch on an expression |diff --git a/src/specify_cli/workflows/__init__.py b/src/specify_cli/workflows/__init__.pyindex 0d1e101a9..1e608ca16 100644--- a/src/specify_cli/workflows/__init__.py+++ b/src/specify_cli/workflows/__init__.py@@ -53,6 +53,7 @@ def _register_builtin_steps() -> None:from .steps.init import InitStepfrom .steps.prompt import PromptStepfrom .steps.shell import ShellStep+ from .steps.slot import SlotStepfrom .steps.switch import SwitchStepfrom .steps.while_loop import WhileStep@@ -65,6 +66,7 @@ def _register_builtin_steps() -> None:_register_step(InitStep())_register_step(PromptStep())_register_step(ShellStep())+ _register_step(SlotStep())_register_step(SwitchStep())_register_step(WhileStep())diff --git a/src/specify_cli/workflows/engine.py b/src/specify_cli/workflows/engine.pyindex d17513cc0..411c1aac8 100644--- a/src/specify_cli/workflows/engine.py+++ b/src/specify_cli/workflows/engine.py@@ -139,7 +139,7 @@ def _get_valid_step_types() -> set[str]:if STEP_REGISTRY:return set(STEP_REGISTRY.keys())return {- "command", "shell", "prompt", "gate", "if", "init",+ "command", "shell", "prompt", "gate", "if", "init", "slot","switch", "while", "do-while", "fan-out", "fan-in",}@@ -432,6 +432,13 @@ def _validate_steps(step_errors = step_impl.validate(step_config)errors.extend(step_errors)+ if step_type == "slot" and inside_fan_out:+ errors.append(+ f"Slot step {step_id!r} is not supported inside fan-out "+ "templates because overlays cannot address runtime-multiplied "+ "templates."+ )+# Validate optional `continue_on_error` field. The engine honours# this on any step that returns StepStatus.FAILED so the pipeline can route# around the failure via a downstream `if` or `switch` (or adiff --git a/src/specify_cli/workflows/steps/slot/__init__.py b/src/specify_cli/workflows/steps/slot/__init__.pynew file mode 100644index 000000000..bd784a7b0--- /dev/null+++ b/src/specify_cli/workflows/steps/slot/__init__.py@@ -0,0 +1,67 @@+"""Slot step β a named, no-op workflow slot.++An upstream workflow declares a slot at the position where a downstream+project may extend it. The step ``id`` is the overlay anchor; ``name`` is only+the human-readable slot label. A project overlay fills the slot with the+standard ``replace`` operation on the slot step's ``id``. Unfilled slots are+skipped when the workflow runs.++Example YAML::++ # Upstream workflow+ - id: post-implement+ type: slot+ name: post-implement++ # .specify/workflows/overlays/my-workflow/fill-post-implement.yml+ id: fill-post-implement+ extends: my-workflow+ edits:+ - replace: post-implement+ step:+ id: post-implement+ type: shell+ run: echo "Run project-specific checks"+"""++from __future__ import annotations++from typing import Any++from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus+++class SlotStep(StepBase):+ """Provide a named workflow slot that skips when unfilled."""++ type_key = "slot"++ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:+ if context.inside_fan_out:+ return StepResult(+ status=StepStatus.FAILED,+ error=(+ f"Slot step {config.get('id', '?')!r} is not supported "+ "inside fan-out templates because overlays cannot address "+ "runtime-multiplied templates."+ ),+ )+ return StepResult(+ status=StepStatus.SKIPPED,+ output={"slot": config.get("name")},+ )++ def validate(self, config: dict[str, Any]) -> list[str]:+ errors = super().validate(config)+ name = config.get("name")+ if name is None:+ errors.append(+ f"Slot step {config.get('id', '?')!r} requires a 'name' field "+ "(the slot label)."+ )+ elif not isinstance(name, str) or not name.strip():+ errors.append(+ f"Slot step {config.get('id', '?')!r}: 'name' must be a "+ "non-blank string."+ )+ return errorsdiff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex 229975285..ca502ef4c 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -4,7 +4,7 @@ Covers:- Step registry & auto-discovery- Base classes (StepBase, StepContext, StepResult)- Expression engine-- All 10 built-in step types+- All 12 built-in step types- Workflow definition loading & validation- Workflow engine execution & state persistence- Workflow catalog & registry@@ -108,7 +108,7 @@ class TestStepRegistry:expected = {"command", "shell", "prompt", "gate", "if", "switch",- "while", "do-while", "fan-out", "fan-in", "init",+ "while", "do-while", "fan-out", "fan-in", "init", "slot",}assert expected.issubset(set(STEP_REGISTRY.keys()))diff --git a/tests/unit/test_bundler_references.py b/tests/unit/test_bundler_references.pyindex b9ad42666..b910a93e9 100644--- a/tests/unit/test_bundler_references.py+++ b/tests/unit/test_bundler_references.py@@ -27,7 +27,7 @@ def test_bundled_extension_resolves(tmp_path: Path):def test_builtin_step_type_resolves(tmp_path: Path):"""A built-in step type must resolve, like a bundled extension.- Spec Kit ships 11 step types as built-ins registered in ``STEP_REGISTRY``+ Spec Kit ships 12 step types as built-ins registered in ``STEP_REGISTRY``rather than as on-disk asset directories, so there is no``_locate_bundled_step``. The ``steps`` branch of ``_resolved_locally`` onlyasked ``StepRegistry(root).is_installed()``, which tracks *community* step@@ -40,7 +40,7 @@ def test_builtin_step_type_resolves(tmp_path: Path):warnings: list[str] = []check = make_reference_checker(root, allow_network=True, warnings=warnings)- for step_id in ("shell", "gate", "command", "if"):+ for step_id in ("shell", "gate", "command", "if", "slot"):assert step_id in BUILTIN_STEP_TYPES, step_idassert check(_ref("steps", step_id)) is None, step_idassert warnings == []diff --git a/tests/workflows/test_slot_step.py b/tests/workflows/test_slot_step.pynew file mode 100644index 000000000..50416586a--- /dev/null+++ b/tests/workflows/test_slot_step.py@@ -0,0 +1,242 @@+"""Tests for the workflow slot step."""++from __future__ import annotations++import json+from pathlib import Path++import pytest+import yaml++from specify_cli.workflows import BUILTIN_STEP_TYPES, get_step_type+from specify_cli.workflows.base import RunStatus, StepContext, StepStatus+from specify_cli.workflows.engine import WorkflowDefinition, WorkflowEngine, validate_workflow+from specify_cli.workflows.overlays import WorkflowResolver+from specify_cli.workflows.steps.slot import SlotStep+++def _workflow_data(steps: list[dict[str, object]]) -> dict[str, object]:+ return {+ "schema_version": "1.0",+ "workflow": {"id": "slot-workflow", "name": "Slot Workflow", "version": "1.0.0"},+ "steps": steps,+ }+++def _write_workflow(project_root: Path, data: dict[str, object]) -> None:+ workflow_dir = project_root / ".specify" / "workflows" / "slot-workflow"+ workflow_dir.mkdir(parents=True, exist_ok=True)+ (workflow_dir / "workflow.yml").write_text(+ yaml.safe_dump(data), encoding="utf-8"+ )+++def _write_overlay(project_root: Path, data: dict[str, object]) -> None:+ overlay_dir = (+ project_root / ".specify" / "workflows" / "overlays" / "slot-workflow"+ )+ overlay_dir.mkdir(parents=True, exist_ok=True)+ (overlay_dir / "fill-slot.yml").write_text(yaml.safe_dump(data), encoding="utf-8")+++def test_slot_step_is_registered_as_builtin():+ step = get_step_type("slot")++ assert isinstance(step, SlotStep)+ assert step.type_key == "slot"+ assert "slot" in BUILTIN_STEP_TYPES+++def test_slot_step_validate_returns_errors_for_malformed_names():+ step = SlotStep()++ assert any("missing required 'id'" in error for error in step.validate({}))+ assert "requires a 'name' field" in step.validate({"id": "slot"})[0]+ assert "requires a 'name' field" in step.validate({"id": "slot", "name": None})[0]+ for name in ("", " ", 123):+ errors = step.validate({"id": "slot", "name": name})+ assert len(errors) == 1+ assert "non-blank string" in errors[0]+ assert step.validate({"id": "slot", "name": "lint"}) == []+++ ("name", "expected_error"),+ [+ (None, "requires a 'name' field"),+ ("", "non-blank string"),+ (" ", "non-blank string"),+ (123, "non-blank string"),+ ],+)+def test_slot_step_errors_are_reported_through_workflow_validation(+ name: object, expected_error: str+):+ definition = WorkflowDefinition(+ _workflow_data([{"id": "slot", "type": "slot", "name": name}])+ )++ errors = validate_workflow(definition)++ assert any("Slot step 'slot'" in error for error in errors)+ assert any(expected_error in error for error in errors)+++def test_addressable_nested_slot_step_validates_cleanly():+ definition = WorkflowDefinition(+ _workflow_data(+ [+ {+ "id": "conditional",+ "type": "if",+ "condition": "true",+ "then": [{"id": "slot", "type": "slot", "name": "lint"}],+ }+ ]+ )+ )++ assert validate_workflow(definition) == []+++def test_slot_step_skips_without_mutating_the_shared_instance():+ step = SlotStep()+ before = vars(step).copy()++ result = step.execute({"id": "slot", "name": "lint"}, StepContext())++ assert result.status is StepStatus.SKIPPED+ assert result.output == {"slot": "lint"}+ assert vars(step) == before+++def test_slot_step_fails_when_executed_inside_fan_out():+ step = SlotStep()++ result = step.execute(+ {"id": "slot", "name": "per-item"},+ StepContext(inside_fan_out=True),+ )++ assert result.status is StepStatus.FAILED+ assert "not supported inside fan-out" in result.error+ assert result.output == {}+++def test_unfilled_slot_is_persisted_and_does_not_halt_workflow(project_dir):+ _write_workflow(+ project_dir,+ _workflow_data(+ [+ {"id": "slot", "type": "slot", "name": "post-implement"},+ {"id": "marker", "type": "shell", "run": "echo marker"},+ ]+ ),+ )+ engine = WorkflowEngine(project_dir)++ definition = engine.load_workflow("slot-workflow")+ assert engine.validate(definition) == []+ state = engine.execute(definition, run_id="slot-run")++ assert state.status is RunStatus.COMPLETED+ state_data = json.loads((state.runs_dir / "state.json").read_text(encoding="utf-8"))+ assert state_data["step_results"]["slot"]["status"] == "skipped"+ assert state_data["step_results"]["slot"]["output"] == {"slot": "post-implement"}+ assert state_data["step_results"]["marker"]["status"] == "completed"++ log_entries = [+ json.loads(line)+ for line in (state.runs_dir / "log.jsonl").read_text(encoding="utf-8").splitlines()+ ]+ skipped_events = [+ entry+ for entry in log_entries+ if entry["event"] == "step_completed" and entry["step_id"] == "slot"+ ]+ assert len(skipped_events) == 1+ assert skipped_events[0]["status"] == "skipped"+++def test_overlay_replaces_slot_and_attributes_it_to_the_overlay(project_dir):+ _write_workflow(+ project_dir,+ _workflow_data(+ [+ {"id": "before", "type": "shell", "run": "echo before"},+ {"id": "slot", "type": "slot", "name": "post-implement"},+ {"id": "after", "type": "shell", "run": "echo after"},+ ]+ ),+ )+ _write_overlay(+ project_dir,+ {+ "id": "fill-slot",+ "extends": "slot-workflow",+ "edits": [+ {+ "replace": "slot",+ "step": {"id": "slot", "type": "shell", "run": "echo filled"},+ }+ ],+ },+ )+ engine = WorkflowEngine(project_dir)++ definition = engine.load_workflow("slot-workflow")+ assert [step["id"] for step in definition.steps] == ["before", "slot", "after"]+ assert definition.steps[1]["type"] == "shell"+ assert engine.validate(definition) == []+ state = engine.execute(definition, run_id="filled-slot-run")+ assert state.status is RunStatus.COMPLETED+ assert "filled" in state.step_results["slot"]["output"]["stdout"]++ _definition, _layers, attribution = WorkflowResolver(project_dir).resolve_with_layers(+ "slot-workflow"+ )+ sources = {step.step_id: step.source for step in attribution}+ assert sources == {+ "before": "base",+ "slot": "project:fill-slot",+ "after": "base",+ }+++def test_slot_steps_are_rejected_inside_fan_out_templates():+ definition = WorkflowDefinition(+ _workflow_data(+ [+ {+ "id": "fan",+ "type": "fan-out",+ "items": [],+ "step": {"id": "slot", "type": "slot", "name": "per-item"},+ }+ ]+ )+ )++ errors = validate_workflow(definition)++ assert any(+ "Slot step 'slot' is not supported inside fan-out templates" in error+ for error in errors+ )+++def test_non_slot_fan_out_templates_remain_valid():+ definition = WorkflowDefinition(+ _workflow_data(+ [+ {+ "id": "fan",+ "type": "fan-out",+ "items": [],+ "step": {"id": "template", "type": "shell", "run": "echo item"},+ }+ ]+ )+ )++ assert validate_workflow(definition) == []diff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.mdindex 477c0968a..680cfc423 100644--- a/workflows/ARCHITECTURE.md+++ b/workflows/ARCHITECTURE.md@@ -19,6 +19,7 @@ flowchart TDG --> H{Step type?}H -- command --> I["CommandStep.execute()"]H -- shell --> J["ShellStep.execute()"]+ H -- slot --> V["SlotStep.execute()"]H -- gate --> K["GateStep.execute()"]H -- "if" --> L["IfThenStep.execute()"]H -- switch --> M["SwitchStep.execute()"]@@ -27,12 +28,13 @@ flowchart TDI --> P{Result status?}J --> P+ V --> PK --> PL --> PM --> PN --> PO --> P- P -- COMPLETED --> Q{Has next_steps?}+ P -- "COMPLETED / SKIPPED" --> Q{Has next_steps?}P -- PAUSED --> R["Save state β exit"]P -- FAILED --> S["Log error β exit"]Q -- Yes --> G@@ -77,7 +79,7 @@ When a `gate` step pauses execution, the engine persists `current_step_index` an## Step Types-The engine ships with 11 built-in step types, each in its own subpackage under `src/specify_cli/workflows/steps/`:+The engine ships with 12 built-in step types, each in its own subpackage under `src/specify_cli/workflows/steps/`:| Type Key | Class | Purpose | Returns `next_steps`? ||----------|-------|---------|-----------------------|@@ -85,6 +87,7 @@ The engine ships with 11 built-in step types, each in its own subpackage under `| `prompt` | `PromptStep` | Send an arbitrary inline prompt to integration CLI | No || `shell` | `ShellStep` | Run a shell command, capture output | No || `init` | `InitStep` | Bootstrap a project (equivalent to `specify init`) | No |+| `slot` | `SlotStep` | Named workflow slot; skipped when unfilled | No || `gate` | `GateStep` | Interactive human review/approval | No (pauses in CI) || `if` | `IfThenStep` | Conditional branching (then/else) | Yes || `switch` | `SwitchStep` | Multi-branch dispatch on expression | Yes |@@ -200,6 +203,7 @@ src/specify_cli/β βββ command/ # Dispatch command to AI integrationβ βββ shell/ # Run shell commandβ βββ init/ # Bootstrap a project (specify init)+β βββ slot/ # Named workflow slot; skipped when unfilledβ βββ gate/ # Human review checkpointβ βββ if_then/ # Conditional branchingβ βββ prompt/ # Arbitrary inline promptsdiff --git a/workflows/PUBLISHING.md b/workflows/PUBLISHING.mdindex 2caf55d81..4e26fdfb2 100644--- a/workflows/PUBLISHING.md+++ b/workflows/PUBLISHING.md@@ -90,7 +90,7 @@ steps:- β `version` follows semantic versioning (X.Y.Z)- β `description` is concise- β All step IDs are unique-- β Step types are valid: `command`, `prompt`, `shell`, `gate`, `if`, `switch`, `while`, `do-while`, `fan-out`, `fan-in`+- β Step types are valid: `command`, `prompt`, `shell`, `init`, `slot`, `gate`, `if`, `switch`, `while`, `do-while`, `fan-out`, `fan-in`- β Required fields present per step type (e.g., `condition` for `if`, `expression` for `switch`)- β Input types are valid: `string`, `number`, `boolean`- β Step IDs do not contain `:` (reserved for engine-generated nested IDs like `parentId:childId`)diff --git a/workflows/README.md b/workflows/README.mdindex d5569541a..70a34bc53 100644--- a/workflows/README.md+++ b/workflows/README.md@@ -78,7 +78,7 @@ specify workflow run speckit \## Step Types-Workflows support 11 built-in step types:+Workflows support 12 built-in step types:### Command Steps (default)@@ -150,6 +150,24 @@ and resolves the integration from the step config or the workflow default:preset: healthcare-compliance # Optional preset ID```+### Workflow Slots++Declare a named workflow slot that downstream projects can fill with a+workflow overlay. The slot is skipped when unfilled; its `id` is the overlay+anchor and `name` is a required human-readable label:++```yaml+- id: post-implement+ type: slot+ name: "Post-implementation checks"+```++Use an overlay `replace` edit anchored on `post-implement` to fill the slot.+Keep the same `id` when downstream expressions or fan-in steps reference it,+and preserve any output keys they consume. Slot steps are invalid inside+`fan-out.step` templates because those runtime-multiplied templates cannot be+targeted by overlays.+### Gate StepsPause for human review. The workflow resumes when `specify workflow resume` is called: