[Feature]: Add dry-run flag to preview spec output without AI invocation

[fuleinist]

Problem Statement

When running commands like specify workflow run, the CLI immediately invokes the AI model to generate output. For large projects or when iterating on constitution/principles, users may want to preview what the output would look like without burning tokens or waiting for generation — especially useful in CI environments or when testing templates.

Proposed Solution

Add a --dry-run flag to specify workflow run. When enabled, the CLI prints the rendered prompt/inputs that would be sent to the AI for each step without actually making the API call. This lets users verify their workflow definitions, templates, and configuration are correct before spending time or money on actual generation.

Scope Re-scope (2026-06-04)

The original proposal also asked for --dry-run on specify specify and specify plan. After design review with maintainer @mnriem (comment #2704 (comment)), those were intentionally not added:

"The specify CLI is NOT the command executor — coding agent is. The per-stage surface (/speckit.specify, /speckit.plan, ...) belongs to the agent, not the CLI."

specify specify and specify plan are scaffolders — they copy .specify/scripts/<variant>/ and .specify/templates/ into the project. There is nothing meaningful to "dry run" in that copy step; the actual AI invocation is the coding agent's job (Claude / Copilot / Cursor / etc.), not the CLI's. The only place where the CLI itself drives a step-based invocation is specify workflow run, which is what this issue now targets.

Acceptance Criteria

• --dry-run flag added to specify workflow run command
• Output shows the rendered prompt/configuration per step without AI invocation
• Clear message indicates this is a dry run with no actual generation
• AI invocation short-circuits across CommandStep, GateStep, and PromptStep
• dry_run flag persists across workflow resume so an interrupted dry-run does not silently become a real run
• --json mode emits a single well-formed JSON object (no banner / preview leak on stdout)

Out of scope (intentional)

• --dry-run on specify specify / specify plan — see scope re-scope above
• start_at / stop_after step-ID filtering — separate concern, would be a follow-up PR

Implementation

Tracked in PR #2704 (#2704). Once that PR merges, this issue closes.

Alternatives Considered

• Running in a separate sandboxed environment — heavyweight, impractical for quick iteration
• Checking generated output after the fact — wastes tokens on incorrect configurations
• Modifying templates blindly — error-prone without feedback

Component

Specify CLI (workflows)

AI Agent (if applicable)

All agents (only via the per-step integrations that specify workflow run already wires up; the per-stage agent surface is unchanged).

Use Cases

1. When authoring custom workflow definitions, preview the rendered prompts and command invocations before running for real
2. When onboarding new team members, demonstrate a workflow's step sequence without making API calls
3. When debugging a workflow failure, surface the partial step previews that were resolved before the failure point

Additional Context

Addresses token cost concerns in large teams and CI environments. Similar to how kubectl apply --dry-run works for Kubernetes manifests.

[mnriem]

Go for it!