feat(workflows): add --dry-run flag to preview spec/plan output without AI invocation

Implements GitHub issue #2661.

- Add dry_run field to StepContext (workflows/base.py)
- Add dry_run parameter to WorkflowEngine.execute() (workflows/engine.py)
- Add --dry-run to 'specify workflow run' CLI command
- Add 'specify specify' and 'specify plan' CLI commands with --dry-run support
- CommandStep: in dry-run mode, renders the command/integration/model and
  returns COMPLETED without spawning the integration CLI subprocess
- GateStep: in dry-run mode, skips interactive prompt and returns COMPLETED
- Add tests for dry-run in TestCommandStep, TestGateStep, and
  TestWorkflowEngine

Usage:
  specify specify --spec 'Build a kanban board' --dry-run
  specify plan --spec 'Build a kanban board' --dry-run
  specify workflow run speckit --input spec='Build kanban' --dry-run

Author: MiniMax-M2

src/specify_cli/__init__.py

@@ -541,6 +541,152 @@ def version(
 app.add_typer(_self_app, name="self")
 
 
+# ===== Spec / Plan Commands (direct CLI access with dry-run) =====
+
+specify_app = typer.Typer(
+    name="specify",
+    help="Create a feature specification (direct CLI alternative to /speckit.specify in coding agents)",
+    add_completion=False,
+)
+app.add_typer(specify_app, name="specify")
+
+
+@specify_app.command("specify")
+def specify_specify(
+    spec: str = typer.Option(
+        ..., "--spec", "-s", help="Feature description (what to build and why)"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show rendered prompt/inputs without invoking the AI"
+    ),
+):
+    """Create a feature specification from a description.
+
+    This is a direct CLI alternative to the /speckit.specify agent command.
+    Runs the spec workflow and generates spec.md in the feature directory.
+
+    Examples:
+        specify specify --spec "Build a kanban board with drag-and-drop"
+        specify specify --spec "Photo album app" --dry-run
+    """
+    from .workflows.engine import WorkflowEngine
+
+    project_root = _require_specify_project()
+    engine = WorkflowEngine(project_root)
+    engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
+
+    try:
+        definition = engine.load_workflow("speckit")
+    except FileNotFoundError:
+        console.print("[red]Error:[/red] speckit workflow not installed. Run 'specify init' first.")
+        raise typer.Exit(1)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] Invalid workflow: {exc}")
+        raise typer.Exit(1)
+
+    errors = engine.validate(definition)
+    if errors:
+        console.print("[red]Workflow validation failed:[/red]")
+        for err in errors:
+            console.print(f"  \u2022 {err}")
+        raise typer.Exit(1)
+
+    inputs = {"spec": spec, "integration": "auto", "scope": "full"}
+
+    console.print(f"\n[bold cyan]Running:[/bold cyan] specify specify")
+    console.print(f"[dim]Spec: {spec[:60]}{'...' if len(spec) > 60 else ''}[/dim]\n")
+
+    if dry_run:
+        console.print("[bold yellow]DRY RUN — no AI invocation will occur[/bold yellow]\n")
+
+    try:
+        state = engine.execute(definition, inputs, dry_run=dry_run)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+    except Exception as exc:
+        console.print(f"[red]Workflow failed:[/red] {exc}")
+        raise typer.Exit(1)
+
+    if dry_run:
+        status_color = "yellow"
+    else:
+        status_color = {"completed": "green", "paused": "yellow", "failed": "red", "aborted": "red"}.get(
+            state.status.value, "white"
+        )
+    console.print(f"\n[{status_color}]Status: {state.status.value}[/{status_color}]")
+    if dry_run:
+        console.print("[dim]Run with --dry-run to see step details. Run without --dry-run to execute.[/dim]")
+
+
+@specify_app.command("plan")
+def specify_plan(
+    spec: str = typer.Option(
+        ..., "--spec", "-s", help="Feature description (what to build and why)"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show rendered prompt/inputs without invoking the AI"
+    ),
+):
+    """Create an implementation plan from a feature description.
+
+    This is a direct CLI alternative to the /speckit.plan agent command.
+    Runs the plan step of the speckit workflow.
+
+    Examples:
+        specify plan --spec "Build a kanban board with drag-and-drop"
+        specify plan --spec "Photo album app" --dry-run
+    """
+    from .workflows.engine import WorkflowEngine
+
+    project_root = _require_specify_project()
+    engine = WorkflowEngine(project_root)
+    engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
+
+    try:
+        definition = engine.load_workflow("speckit")
+    except FileNotFoundError:
+        console.print("[red]Error:[/red] speckit workflow not installed. Run 'specify init' first.")
+        raise typer.Exit(1)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] Invalid workflow: {exc}")
+        raise typer.Exit(1)
+
+    errors = engine.validate(definition)
+    if errors:
+        console.print("[red]Workflow validation failed:[/red]")
+        for err in errors:
+            console.print(f"  \u2022 {err}")
+        raise typer.Exit(1)
+
+    inputs = {"spec": spec, "integration": "auto", "scope": "full"}
+
+    console.print(f"\n[bold cyan]Running:[/bold cyan] specify plan")
+    console.print(f"[dim]Spec: {spec[:60]}{'...' if len(spec) > 60 else ''}[/dim]\n")
+
+    if dry_run:
+        console.print("[bold yellow]DRY RUN — no AI invocation will occur[/bold yellow]\n")
+
+    try:
+        state = engine.execute(definition, inputs, dry_run=dry_run)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1)
+    except Exception as exc:
+        console.print(f"[red]Workflow failed:[/red] {exc}")
+        raise typer.Exit(1)
+
+    if dry_run:
+        status_color = "yellow"
+    else:
+        status_color = {"completed": "green", "paused": "yellow", "failed": "red", "aborted": "red"}.get(
+            state.status.value, "white"
+        )
+    console.print(f"\n[{status_color}]Status: {state.status.value}[/{status_color}]")
+    if dry_run:
+        console.print("[dim]Run with --dry-run to see step details. Run without --dry-run to execute.[/dim]")
+
+
 # ===== Extension Commands =====
 
 extension_app = typer.Typer(
@@ -4012,6 +4158,9 @@ def workflow_run(
     input_values: list[str] | None = typer.Option(
         None, "--input", "-i", help="Input values as key=value pairs"
     ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Show the rendered prompt/inputs for each step without invoking the AI"
+    ),
 ):
     """Run a workflow from an installed ID or local YAML path."""
     from .workflows.engine import WorkflowEngine
@@ -4050,8 +4199,11 @@ def workflow_run(
     console.print(f"\n[bold cyan]Running workflow:[/bold cyan] {definition.name} ({definition.id})")
     console.print(f"[dim]Version: {definition.version}[/dim]\n")
 
+    if dry_run:
+        console.print("[bold yellow]DRY RUN — no AI invocation will occur[/bold yellow]\n")
+
     try:
-        state = engine.execute(definition, inputs)
+        state = engine.execute(definition, inputs, dry_run=dry_run)
     except ValueError as exc:
         console.print(f"[red]Error:[/red] {exc}")
         raise typer.Exit(1)

src/specify_cli/workflows/base.py

@@ -73,6 +73,9 @@ class StepContext:
     #: Current run ID.
     run_id: str | None = None
 
+    #: Dry-run mode: preview rendered prompt/inputs without AI invocation.
+    dry_run: bool = False
+
 
 @dataclass
 class StepResult:

src/specify_cli/workflows/engine.py

@@ -415,6 +415,7 @@ def execute(
         definition: WorkflowDefinition,
         inputs: dict[str, Any] | None = None,
         run_id: str | None = None,
+        dry_run: bool = False,
     ) -> RunState:
         """Execute a workflow definition.
 
@@ -462,6 +463,7 @@ def execute(
             default_options=definition.default_options,
             project_root=str(self.project_root),
             run_id=state.run_id,
+            dry_run=dry_run,
         )
 
         # Execute steps

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

@@ -53,12 +53,6 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
         if step_options:
             options.update(step_options)
 
-        # Attempt CLI dispatch
-        args_str = str(resolved_input.get("args", ""))
-        dispatch_result = self._try_dispatch(
-            command, integration, model, args_str, context
-        )
-
         output: dict[str, Any] = {
             "command": command,
             "integration": integration,
@@ -67,6 +61,34 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             "input": resolved_input,
         }
 
+        # Dry-run: show the rendered prompt without invoking the AI
+        if context.dry_run:
+            args_str = str(resolved_input.get("args", ""))
+            # Reconstruct what the integration would build for the invocation
+            invoke_str = f"{command} {args_str}".strip()
+            output["dispatched"] = False
+            output["dry_run"] = True
+            output["exit_code"] = None
+            output["stdout"] = ""
+            output["stderr"] = ""
+            output["invoke_command"] = invoke_str
+            output["message"] = (
+                f"[DRY RUN] Command: {invoke_str}\n"
+                f"         Integration: {integration}\n"
+                f"         Model: {model}\n"
+                f"         (AI invocation skipped — use without --dry-run to execute)"
+            )
+            return StepResult(
+                status=StepStatus.COMPLETED,
+                output=output,
+            )
+
+        # Attempt CLI dispatch
+        args_str = str(resolved_input.get("args", ""))
+        dispatch_result = self._try_dispatch(
+            command, integration, model, args_str, context
+        )
+
         if dispatch_result is not None:
             output["exit_code"] = dispatch_result["exit_code"]
             output["stdout"] = dispatch_result["stdout"]

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

@@ -43,6 +43,13 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             "choice": None,
         }
 
+        # Dry-run: skip interactive gates
+        if context.dry_run:
+            return StepResult(
+                status=StepStatus.COMPLETED,
+                output=output,
+            )
+
         # Non-interactive: pause for later resume
         if not sys.stdin.isatty():
             return StepResult(status=StepStatus.PAUSED, output=output)

tests/test_workflows.py

@@ -641,6 +641,34 @@ def test_dispatch_failure_returns_failed_status(self, tmp_path):
         assert result.output["dispatched"] is True
         assert result.output["exit_code"] == 1
 
+    def test_dry_run_returns_completed_without_dispatch(self):
+        """Dry-run mode: step returns COMPLETED and shows rendered prompt without invoking CLI."""
+        from specify_cli.workflows.steps.command import CommandStep
+        from specify_cli.workflows.base import StepContext, StepStatus
+
+        step = CommandStep()
+        ctx = StepContext(
+            inputs={"name": "login"},
+            default_integration="claude",
+            project_root="/tmp",
+            dry_run=True,
+        )
+        config = {
+            "id": "test",
+            "command": "speckit.specify",
+            "input": {"args": "{{ inputs.name }}"},
+        }
+        result = step.execute(config, ctx)
+
+        assert result.status == StepStatus.COMPLETED
+        assert result.output["dry_run"] is True
+        assert result.output["dispatched"] is False
+        assert result.output["command"] == "speckit.specify"
+        assert result.output["input"]["args"] == "login"
+        # No AI call was made (shutil.which would fail anyway, but dry_run short-circuits before that)
+        assert "invoke_command" in result.output
+        assert "DRY RUN" in result.output["message"]
+
 
 class TestPromptStep:
     """Test the prompt step type."""
@@ -818,6 +846,23 @@ def test_validate_invalid_on_reject(self):
         })
         assert any("on_reject" in e for e in errors)
 
+    def test_dry_run_skips_interactive_gate(self):
+        """Dry-run mode: gate step returns COMPLETED without pausing for user input."""
+        from specify_cli.workflows.steps.gate import GateStep
+        from specify_cli.workflows.base import StepContext, StepStatus
+
+        step = GateStep()
+        ctx = StepContext(dry_run=True)
+        config = {
+            "id": "review",
+            "message": "Review the spec.",
+            "options": ["approve", "reject"],
+            "on_reject": "abort",
+        }
+        result = step.execute(config, ctx)
+        assert result.status == StepStatus.COMPLETED
+        assert result.output["message"] == "Review the spec."
+
 
 class TestIfThenStep:
     """Test the if/then/else step type."""
@@ -1459,6 +1504,49 @@ def test_execute_with_gate_pauses(self, project_dir):
         assert "gate" in state.step_results
         assert state.step_results["gate"]["status"] == "paused"
 
+    def test_execute_dry_run(self, project_dir):
+        """Dry-run: engine returns COMPLETED without invoking the AI for command steps."""
+        from unittest.mock import patch
+        from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
+        from specify_cli.workflows.base import RunStatus
+
+        yaml_str = """
+schema_version: "1.0"
+workflow:
+  id: "dryrun-test"
+  name: "Dry Run Test"
+  version: "1.0.0"
+inputs:
+  spec:
+    type: string
+    default: "test spec"
+steps:
+  - id: specify
+    command: speckit.specify
+    input:
+      args: "{{ inputs.spec }}"
+  - id: plan
+    command: speckit.plan
+    input:
+      args: "{{ inputs.spec }}"
+"""
+        definition = WorkflowDefinition.from_string(yaml_str)
+        engine = WorkflowEngine(project_dir)
+
+        # In dry-run mode, even if the CLI tool is installed, no AI calls are made
+        with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \
+             patch("subprocess.run") as mock_run:
+            state = engine.execute(definition, {"spec": "login feature"}, dry_run=True)
+
+        assert state.status == RunStatus.COMPLETED
+        assert "specify" in state.step_results
+        assert state.step_results["specify"]["output"]["dry_run"] is True
+        assert state.step_results["specify"]["output"]["dispatched"] is False
+        assert "plan" in state.step_results
+        assert state.step_results["plan"]["output"]["dry_run"] is True
+        # subprocess.run should NOT have been called in dry-run mode
+        assert mock_run.call_count == 0
+
     def test_execute_with_shell_step(self, project_dir):
         from specify_cli.workflows.engine import WorkflowEngine, WorkflowDefinition
         from specify_cli.workflows.base import RunStatus