Skip to content

πŸ’« 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.md
index 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__.py
index 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 InitStep
from .steps.prompt import PromptStep
from .steps.shell import ShellStep
+ from .steps.slot import SlotStep
from .steps.switch import SwitchStep
from .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.py
index 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 a
diff --git a/src/specify_cli/workflows/steps/slot/__init__.py b/src/specify_cli/workflows/steps/slot/__init__.py
new file mode 100644
index 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 errors
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index 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.py
index 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`` only
asked ``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_id
assert check(_ref("steps", step_id)) is None, step_id
assert warnings == []
diff --git a/tests/workflows/test_slot_step.py b/tests/workflows/test_slot_step.py
new file mode 100644
index 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.md
index 477c0968a..680cfc423 100644
--- a/workflows/ARCHITECTURE.md
+++ b/workflows/ARCHITECTURE.md
@@ -19,6 +19,7 @@ flowchart TD
G --> 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 TD
I --> P{Result status?}
J --> P
+ V --> P
K --> P
L --> P
M --> P
N --> P
O --> 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 prompts
diff --git a/workflows/PUBLISHING.md b/workflows/PUBLISHING.md
index 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.md
index 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 Steps
Pause for human review. The workflow resumes when `specify workflow resume` is called: