refactor(workflows): rename plugin slots to workflow slots

The feature reserves a no-op position replaced through a workflow
overlay; it does not register or resolve plugins. Rename per maintainer
feedback so 'plugin' stays available for a future genuine plugin
mechanism and avoid confusion with Spec Kit extensions:

- type: plugin -> type: slot
- PluginStep -> SlotStep
- 'plugin step/slot' -> 'workflow slot' in prose and error messages
- steps/plugin/ -> steps/slot/ (git mv)
- test_plugin_step.py -> test_slot_step.py (git mv)

Assisted-by: opencode (model: glm-5.3-flash, autonomous)

Author: Markus

docs/reference/workflows.md

@@ -286,13 +286,13 @@ 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.
 
-### Plugin slots (upstream extension points)
+### Workflow slots (upstream extension points)
 
-Workflow authors can declare a named, no-op extension point with `type: plugin`:
+Workflow authors can declare a named, no-op workflow slot with `type: slot`:
 
 ```yaml
 - id: post-implement
-  type: plugin
+  type: slot
   name: "Post-implementation checks"
 ```
 
@@ -316,7 +316,7 @@ edits:
 
 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 plugin slot supplies only `steps.<id>.output.slot`. Plugin slots are
+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.
 
@@ -528,7 +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`)        |
-| `plugin`     | Named extension point; skipped when unfilled     |
+| `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           |

src/specify_cli/workflows/__init__.py

@@ -51,9 +51,9 @@ def _register_builtin_steps() -> None:
     from .steps.gate import GateStep
     from .steps.if_then import IfThenStep
     from .steps.init import InitStep
-    from .steps.plugin import PluginStep
     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
 
@@ -64,9 +64,9 @@ def _register_builtin_steps() -> None:
     _register_step(GateStep())
     _register_step(IfThenStep())
     _register_step(InitStep())
-    _register_step(PluginStep())
     _register_step(PromptStep())
     _register_step(ShellStep())
+    _register_step(SlotStep())
     _register_step(SwitchStep())
     _register_step(WhileStep())
 

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", "plugin",
+        "command", "shell", "prompt", "gate", "if", "init", "slot",
         "switch", "while", "do-while", "fan-out", "fan-in",
     }
 
@@ -432,9 +432,9 @@ def _validate_steps(
             step_errors = step_impl.validate(step_config)
             errors.extend(step_errors)
 
-        if step_type == "plugin" and inside_fan_out:
+        if step_type == "slot" and inside_fan_out:
             errors.append(
-                f"Plugin step {step_id!r} is not supported inside fan-out "
+                f"Slot step {step_id!r} is not supported inside fan-out "
                 "templates because overlays cannot address runtime-multiplied "
                 "templates."
             )

…y_cli/workflows/steps/plugin/__init__.py …ify_cli/workflows/steps/slot/__init__.pysrc/specify_cli/workflows/steps/plugin/__init__.py renamed to src/specify_cli/workflows/steps/slot/__init__.py src/specify_cli/workflows/steps/plugin/__init__.py renamed to src/specify_cli/workflows/steps/slot/__init__.py

@@ -1,4 +1,4 @@
-"""Plugin step — a named, no-op workflow extension point.
+"""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
@@ -10,7 +10,7 @@
 
     # Upstream workflow
     - id: post-implement
-      type: plugin
+      type: slot
       name: post-implement
 
     # .specify/workflows/overlays/my-workflow/fill-post-implement.yml
@@ -31,17 +31,17 @@
 from specify_cli.workflows.base import StepBase, StepContext, StepResult, StepStatus
 
 
-class PluginStep(StepBase):
-    """Provide a named workflow extension point that skips when unfilled."""
+class SlotStep(StepBase):
+    """Provide a named workflow slot that skips when unfilled."""
 
-    type_key = "plugin"
+    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"Plugin step {config.get('id', '?')!r} is not supported "
+                    f"Slot step {config.get('id', '?')!r} is not supported "
                     "inside fan-out templates because overlays cannot address "
                     "runtime-multiplied templates."
                 ),
@@ -56,12 +56,12 @@ def validate(self, config: dict[str, Any]) -> list[str]:
         name = config.get("name")
         if name is None:
             errors.append(
-                f"Plugin step {config.get('id', '?')!r} requires a 'name' field "
+                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"Plugin step {config.get('id', '?')!r}: 'name' must be a "
+                f"Slot step {config.get('id', '?')!r}: 'name' must be a "
                 "non-blank string."
             )
         return errors

tests/test_workflows.py

@@ -108,7 +108,7 @@ def test_all_step_types_registered(self):
 
         expected = {
             "command", "shell", "prompt", "gate", "if", "switch",
-            "while", "do-while", "fan-out", "fan-in", "init", "plugin",
+            "while", "do-while", "fan-out", "fan-in", "init", "slot",
         }
         assert expected.issubset(set(STEP_REGISTRY.keys()))
 

tests/unit/test_bundler_references.py

@@ -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", "plugin"):
+    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 == []

tests/workflows/test_plugin_step.py tests/workflows/test_slot_step.pytests/workflows/test_plugin_step.py renamed to tests/workflows/test_slot_step.py

@@ -1,4 +1,4 @@
-"""Tests for the plugin workflow extension-point step."""
+"""Tests for the workflow slot step."""
 
 from __future__ import annotations
 
@@ -12,19 +12,19 @@
 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.plugin import PluginStep
+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": "plugin-workflow", "name": "Plugin Workflow", "version": "1.0.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" / "plugin-workflow"
+    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"
@@ -33,22 +33,22 @@ def _write_workflow(project_root: Path, data: dict[str, object]) -> None:
 
 def _write_overlay(project_root: Path, data: dict[str, object]) -> None:
     overlay_dir = (
-        project_root / ".specify" / "workflows" / "overlays" / "plugin-workflow"
+        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_plugin_step_is_registered_as_builtin():
-    step = get_step_type("plugin")
+def test_slot_step_is_registered_as_builtin():
+    step = get_step_type("slot")
 
-    assert isinstance(step, PluginStep)
-    assert step.type_key == "plugin"
-    assert "plugin" in BUILTIN_STEP_TYPES
+    assert isinstance(step, SlotStep)
+    assert step.type_key == "slot"
+    assert "slot" in BUILTIN_STEP_TYPES
 
 
-def test_plugin_step_validate_returns_errors_for_malformed_names():
-    step = PluginStep()
+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]
@@ -69,28 +69,28 @@ def test_plugin_step_validate_returns_errors_for_malformed_names():
         (123, "non-blank string"),
     ],
 )
-def test_plugin_step_errors_are_reported_through_workflow_validation(
+def test_slot_step_errors_are_reported_through_workflow_validation(
     name: object, expected_error: str
 ):
     definition = WorkflowDefinition(
-        _workflow_data([{"id": "slot", "type": "plugin", "name": name}])
+        _workflow_data([{"id": "slot", "type": "slot", "name": name}])
     )
 
     errors = validate_workflow(definition)
 
-    assert any("Plugin step 'slot'" in error for error in errors)
+    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_plugin_step_validates_cleanly():
+def test_addressable_nested_slot_step_validates_cleanly():
     definition = WorkflowDefinition(
         _workflow_data(
             [
                 {
                     "id": "conditional",
                     "type": "if",
                     "condition": "true",
-                    "then": [{"id": "slot", "type": "plugin", "name": "lint"}],
+                    "then": [{"id": "slot", "type": "slot", "name": "lint"}],
                 }
             ]
         )
@@ -99,8 +99,8 @@ def test_addressable_nested_plugin_step_validates_cleanly():
     assert validate_workflow(definition) == []
 
 
-def test_plugin_step_skips_without_mutating_the_shared_instance():
-    step = PluginStep()
+def test_slot_step_skips_without_mutating_the_shared_instance():
+    step = SlotStep()
     before = vars(step).copy()
 
     result = step.execute({"id": "slot", "name": "lint"}, StepContext())
@@ -110,8 +110,8 @@ def test_plugin_step_skips_without_mutating_the_shared_instance():
     assert vars(step) == before
 
 
-def test_plugin_step_fails_when_executed_inside_fan_out():
-    step = PluginStep()
+def test_slot_step_fails_when_executed_inside_fan_out():
+    step = SlotStep()
 
     result = step.execute(
         {"id": "slot", "name": "per-item"},
@@ -123,21 +123,21 @@ def test_plugin_step_fails_when_executed_inside_fan_out():
     assert result.output == {}
 
 
-def test_unfilled_plugin_slot_is_persisted_and_does_not_halt_workflow(project_dir):
+def test_unfilled_slot_is_persisted_and_does_not_halt_workflow(project_dir):
     _write_workflow(
         project_dir,
         _workflow_data(
             [
-                {"id": "slot", "type": "plugin", "name": "post-implement"},
+                {"id": "slot", "type": "slot", "name": "post-implement"},
                 {"id": "marker", "type": "shell", "run": "echo marker"},
             ]
         ),
     )
     engine = WorkflowEngine(project_dir)
 
-    definition = engine.load_workflow("plugin-workflow")
+    definition = engine.load_workflow("slot-workflow")
     assert engine.validate(definition) == []
-    state = engine.execute(definition, run_id="plugin-run")
+    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"))
@@ -158,13 +158,13 @@ def test_unfilled_plugin_slot_is_persisted_and_does_not_halt_workflow(project_di
     assert skipped_events[0]["status"] == "skipped"
 
 
-def test_overlay_replaces_plugin_slot_and_attributes_it_to_the_overlay(project_dir):
+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": "plugin", "name": "post-implement"},
+                {"id": "slot", "type": "slot", "name": "post-implement"},
                 {"id": "after", "type": "shell", "run": "echo after"},
             ]
         ),
@@ -173,7 +173,7 @@ def test_overlay_replaces_plugin_slot_and_attributes_it_to_the_overlay(project_d
         project_dir,
         {
             "id": "fill-slot",
-            "extends": "plugin-workflow",
+            "extends": "slot-workflow",
             "edits": [
                 {
                     "replace": "slot",
@@ -184,7 +184,7 @@ def test_overlay_replaces_plugin_slot_and_attributes_it_to_the_overlay(project_d
     )
     engine = WorkflowEngine(project_dir)
 
-    definition = engine.load_workflow("plugin-workflow")
+    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) == []
@@ -193,7 +193,7 @@ def test_overlay_replaces_plugin_slot_and_attributes_it_to_the_overlay(project_d
     assert "filled" in state.step_results["slot"]["output"]["stdout"]
 
     _definition, _layers, attribution = WorkflowResolver(project_dir).resolve_with_layers(
-        "plugin-workflow"
+        "slot-workflow"
     )
     sources = {step.step_id: step.source for step in attribution}
     assert sources == {
@@ -203,15 +203,15 @@ def test_overlay_replaces_plugin_slot_and_attributes_it_to_the_overlay(project_d
     }
 
 
-def test_plugin_steps_are_rejected_inside_fan_out_templates():
+def test_slot_steps_are_rejected_inside_fan_out_templates():
     definition = WorkflowDefinition(
         _workflow_data(
             [
                 {
                     "id": "fan",
                     "type": "fan-out",
                     "items": [],
-                    "step": {"id": "slot", "type": "plugin", "name": "per-item"},
+                    "step": {"id": "slot", "type": "slot", "name": "per-item"},
                 }
             ]
         )
@@ -220,12 +220,12 @@ def test_plugin_steps_are_rejected_inside_fan_out_templates():
     errors = validate_workflow(definition)
 
     assert any(
-        "Plugin step 'slot' is not supported inside fan-out templates" in error
+        "Slot step 'slot' is not supported inside fan-out templates" in error
         for error in errors
     )
 
 
-def test_non_plugin_fan_out_templates_remain_valid():
+def test_non_slot_fan_out_templates_remain_valid():
     definition = WorkflowDefinition(
         _workflow_data(
             [

workflows/ARCHITECTURE.md

@@ -19,7 +19,7 @@ flowchart TD
     G --> H{Step type?}
     H -- command --> I["CommandStep.execute()"]
     H -- shell --> J["ShellStep.execute()"]
-    H -- plugin --> V["PluginStep.execute()"]
+    H -- slot --> V["SlotStep.execute()"]
     H -- gate --> K["GateStep.execute()"]
     H -- "if" --> L["IfThenStep.execute()"]
     H -- switch --> M["SwitchStep.execute()"]
@@ -87,7 +87,7 @@ The engine ships with 12 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 |
-| `plugin` | `PluginStep` | Named extension point; skipped when unfilled | 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 |
@@ -203,7 +203,7 @@ src/specify_cli/
 │       ├── command/         # Dispatch command to AI integration
 │       ├── shell/           # Run shell command
 │       ├── init/            # Bootstrap a project (specify init)
-│       ├── plugin/          # Named, skipped-when-unfilled extension point
+│       ├── slot/            # Named workflow slot; skipped when unfilled
 │       ├── gate/            # Human review checkpoint
 │       ├── if_then/         # Conditional branching
 │       ├── prompt/          # Arbitrary inline prompts