feat: add dry-run mode for workflow command

Add --dry-run flag to preview workflow execution without running agents.
Shows execution plan with step order, dependencies, and quality gates.
Supports all output formats (Rich, JSON, Table).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kmcallorum

src/multi_agent_cli/cli.py

@@ -29,6 +29,7 @@
 from multi_agent_cli.factory import get_default_factory
 from multi_agent_cli.metrics import get_metrics, start_metrics_server
 from multi_agent_cli.models.agent import AgentsConfig
+from multi_agent_cli.models.results import DryRunResult, DryRunStep
 from multi_agent_cli.reporters import (
     JSONReporter,
     RichReporter,
@@ -308,13 +309,15 @@ def parallel(
 @click.argument("workflow_file", type=click.Path(exists=True))
 @click.option("--strict", is_flag=True, help="Fail on first error")
 @click.option("--continue-on-error", is_flag=True, help="Continue even if steps fail")
+@click.option("--dry-run", is_flag=True, help="Preview execution plan without running")
 @click.option("--output", "-o", help="Save workflow results to file")
 @pass_context
 def workflow(
     ctx: CLIContext,
     workflow_file: str,
     strict: bool,
     continue_on_error: bool,
+    dry_run: bool,
     output: str | None,
 ) -> None:
     """Run sequential workflow.
@@ -324,11 +327,31 @@ def workflow(
     Examples:
         multi-agent-cli workflow code-review.yaml
         multi-agent-cli workflow compliance-check.yaml --strict
+        multi-agent-cli workflow analysis.yaml --dry-run
     """
     try:
         # Load workflow
         wf = load_workflow(workflow_file)
 
+        # Handle dry-run mode
+        if dry_run:
+            dry_result = _build_dry_run_result(wf)
+            ctx.reporter.display_dry_run_result(dry_result)
+
+            # Save if requested
+            if output:
+                save_result_to_file(dry_result, output)
+                if not ctx.quiet:
+                    console.print(f"[dim]Dry run results saved to {output}[/dim]")
+
+            # Exit with error if invalid
+            # Note: This is currently unreachable because load_workflow validates
+            # dependencies first. Kept for defensive programming if validation
+            # is ever changed or bypassed.
+            if not dry_result.is_valid:  # pragma: no cover
+                sys.exit(1)
+            return
+
         config = ctx.config or create_default_config()
         factory = get_default_factory()
         bridge = factory.create(config)
@@ -377,6 +400,51 @@ def workflow(
         sys.exit(2)
 
 
+def _build_dry_run_result(wf: Any) -> DryRunResult:
+    """Build dry-run result from workflow.
+
+    Args:
+        wf: Workflow to analyze.
+
+    Returns:
+        DryRunResult with execution plan preview.
+    """
+    # Validate dependencies
+    validation_errors = wf.validate_dependencies()
+
+    # Build steps
+    steps = []
+    for i, step in enumerate(wf.steps, start=1):
+        dry_step = DryRunStep(
+            order=i,
+            name=step.name,
+            agent=step.agent,
+            action=step.action,
+            params=step.params,
+            depends_on=step.depends_on,
+            timeout=step.timeout,
+            on_error=step.on_error,
+        )
+        steps.append(dry_step)
+
+    # Build quality gates dict
+    quality_gates = {
+        "max_fixmes": wf.quality_gates.max_fixmes,
+        "min_documentation_score": wf.quality_gates.min_documentation_score,
+        "max_dead_code_percent": wf.quality_gates.max_dead_code_percent,
+    }
+
+    return DryRunResult(
+        workflow_name=wf.name,
+        workflow_description=wf.description,
+        total_steps=len(wf.steps),
+        steps=steps,
+        validation_errors=validation_errors,
+        quality_gates=quality_gates,
+        is_valid=len(validation_errors) == 0,
+    )
+
+
 @cli.command("list")
 @click.option("--verbose", "-v", is_flag=True, help="Show agent capabilities")
 @pass_context

src/multi_agent_cli/models/results.py

@@ -58,6 +58,39 @@ def failure(
         )
 
 
+class DryRunStep(BaseModel):
+    """Represents a step in dry-run preview."""
+
+    order: int = Field(..., description="Execution order (1-based)")
+    name: str = Field(..., description="Step name")
+    agent: str = Field(..., description="Agent to execute")
+    action: str = Field(..., description="Action to perform")
+    params: dict[str, Any] = Field(
+        default_factory=dict, description="Action parameters"
+    )
+    depends_on: list[str] = Field(default_factory=list, description="Step dependencies")
+    timeout: int | None = Field(default=None, description="Step-specific timeout")
+    on_error: str = Field(default="fail", description="Error handling behavior")
+
+
+class DryRunResult(BaseModel):
+    """Result from dry-run workflow validation."""
+
+    workflow_name: str = Field(..., description="Workflow name")
+    workflow_description: str = Field(default="", description="Workflow description")
+    total_steps: int = Field(..., description="Total number of steps")
+    steps: list[DryRunStep] = Field(
+        default_factory=list, description="Steps to execute"
+    )
+    validation_errors: list[str] = Field(
+        default_factory=list, description="Validation errors found"
+    )
+    quality_gates: dict[str, Any] = Field(
+        default_factory=dict, description="Quality gate configuration"
+    )
+    is_valid: bool = Field(..., description="Whether workflow is valid")
+
+
 class WorkflowResult(BaseModel):
     """Result from workflow execution."""
 

src/multi_agent_cli/reporters.py

@@ -10,7 +10,7 @@
 from rich.panel import Panel
 from rich.table import Table
 
-from multi_agent_cli.models.results import AgentResult, WorkflowResult
+from multi_agent_cli.models.results import AgentResult, DryRunResult, WorkflowResult
 
 
 class Reporter(Protocol):
@@ -188,6 +188,63 @@ def display_info(self, message: str) -> None:
         """
         self.console.print(f"[blue]i[/blue] {message}")
 
+    def display_dry_run_result(self, result: DryRunResult) -> None:
+        """Display dry-run preview.
+
+        Args:
+            result: Dry-run result to display.
+        """
+        # Header
+        status_color = "green" if result.is_valid else "red"
+        status_text = "VALID" if result.is_valid else "INVALID"
+
+        self.console.print(
+            f"\n[bold cyan]DRY RUN[/bold cyan] - "
+            f"[{status_color}]{status_text}[/{status_color}]"
+        )
+        self.console.print(f"[bold]{result.workflow_name}[/bold]")
+        if result.workflow_description:
+            self.console.print(f"[dim]{result.workflow_description}[/dim]")
+        self.console.print()
+
+        # Validation errors if any
+        if result.validation_errors:
+            self.console.print("[red]Validation Errors:[/red]")
+            for error in result.validation_errors:
+                self.console.print(f"  [red]x[/red] {error}")
+            self.console.print()
+
+        # Steps table
+        table = Table(title="Execution Plan", show_header=True)
+        table.add_column("#", style="dim", width=3)
+        table.add_column("Step", style="cyan")
+        table.add_column("Agent", style="magenta")
+        table.add_column("Action", style="blue")
+        table.add_column("Depends On", style="dim")
+        table.add_column("On Error", style="yellow")
+
+        for step in result.steps:
+            deps = ", ".join(step.depends_on) if step.depends_on else "-"
+            table.add_row(
+                str(step.order),
+                step.name,
+                step.agent,
+                step.action,
+                deps,
+                step.on_error,
+            )
+
+        self.console.print(table)
+
+        # Quality gates
+        if any(v is not None for v in result.quality_gates.values()):
+            self.console.print("\n[bold]Quality Gates:[/bold]")
+            for gate, value in result.quality_gates.items():
+                if value is not None:
+                    self.console.print(f"  [dim]-[/dim] {gate}: {value}")
+
+        self.console.print(f"\n[dim]Total steps: {result.total_steps}[/dim]")
+
 
 class JSONReporter:
     """Output results as JSON."""
@@ -247,6 +304,14 @@ def display_success(self, message: str) -> None:
         """
         self.console.print(json.dumps({"success": message}, indent=self.indent))
 
+    def display_dry_run_result(self, result: DryRunResult) -> None:
+        """Display dry-run result as JSON.
+
+        Args:
+            result: Dry-run result to display.
+        """
+        self.console.print(result.model_dump_json(indent=self.indent))
+
 
 class TableReporter:
     """Output results as formatted tables."""
@@ -351,6 +416,62 @@ def display_success(self, message: str) -> None:
         """
         self.console.print(f"[green]Success:[/green] {message}")
 
+    def display_dry_run_result(self, result: DryRunResult) -> None:
+        """Display dry-run result as table.
+
+        Args:
+            result: Dry-run result to display.
+        """
+        # Status
+        status = "VALID" if result.is_valid else "INVALID"
+        status_style = "green" if result.is_valid else "red"
+        self.console.print(
+            f"[bold]DRY RUN[/bold] - [{status_style}]{status}[/{status_style}]"
+        )
+        self.console.print(f"Workflow: {result.workflow_name}")
+        self.console.print()
+
+        # Validation errors
+        if result.validation_errors:
+            self.console.print("[red]Validation Errors:[/red]")
+            for error in result.validation_errors:
+                self.console.print(f"  - {error}")
+            self.console.print()
+
+        # Steps table
+        table = Table(title="Execution Plan", show_header=True)
+        table.add_column("#", width=3)
+        table.add_column("Step", style="cyan")
+        table.add_column("Agent")
+        table.add_column("Action")
+        table.add_column("Depends On")
+        table.add_column("On Error")
+
+        for step in result.steps:
+            deps = ", ".join(step.depends_on) if step.depends_on else "-"
+            table.add_row(
+                str(step.order),
+                step.name,
+                step.agent,
+                step.action,
+                deps,
+                step.on_error,
+            )
+
+        self.console.print(table)
+
+        # Quality gates
+        gates_table = Table(title="Quality Gates", show_header=True)
+        gates_table.add_column("Gate", style="cyan")
+        gates_table.add_column("Value")
+
+        for gate, value in result.quality_gates.items():
+            if value is not None:
+                gates_table.add_row(gate, str(value))
+
+        if any(v is not None for v in result.quality_gates.values()):
+            self.console.print(gates_table)
+
 
 def get_reporter(
     format_type: str,
@@ -376,7 +497,7 @@ def get_reporter(
 
 
 def save_result_to_file(
-    result: AgentResult | WorkflowResult,
+    result: AgentResult | WorkflowResult | DryRunResult,
     path: str | Path,
 ) -> None:
     """Save result to JSON file.