# summary

Execute workflow phases by spawning an AI runtime for each phase.

# description

Delegates each phase of the story workflow to an AI runtime (claude, cursor, or codex).
Unlike `workflow run`, this command does not manage state records — it simply spawns the
runtime process and streams its output to the terminal. State tracking is the runtime's
responsibility via the sub-agent protocol.

Phase sequence: PM → BA → Architect → Developer → QA → Release

The `--runtime` flag selects which AI CLI to invoke:

- `auto` — detects the first available runtime in order: claude, cursor, codex (default).
- `claude` — uses the `claude` CLI with `--system-prompt` and `--print`.
- `cursor` — uses the `cursor agent --print` CLI (requires `CURSOR_API_KEY`).
- `codex` — uses the `codex` CLI with `--instructions`.

The `--from-phase` flag resumes execution from a specific phase, skipping earlier ones.

The `--gates` flag controls when to pause between phases:

- `none` — run all phases sequentially without pausing.
- `phase` — pause at BA→Architect and QA→Release boundaries (default).
- `all` — pause at every phase boundary.

Use `--dry-run` to preview the command that would be run for each phase without executing.

# flags.story.summary

Story or backlog item id.

# flags.story.description

The story id passed to the runtime prompt for each phase, e.g. `SA-102` or `#102`.

# flags.runtime.summary

AI runtime to use for phase execution.

# flags.runtime.description

Select which AI CLI to invoke: `auto` (detect), `claude`, `cursor`, or `codex`.
`auto` checks PATH in order: claude → cursor → codex and uses the first found.

# flags.from-phase.summary

Resume execution from this phase.

# flags.from-phase.description

Skip all phases before this one and begin execution here.
Useful when resuming after a gate pause or a failed phase.

# flags.dry-run.summary

Print what would be executed per phase without running.

# flags.dry-run.description

Shows the resolved runtime, rule file path, and full command for each phase
without spawning any processes.

# flags.gates.summary

Gate approval mode.

# flags.gates.description

Controls where execution pauses for human review: `none` (no pauses),
`phase` (pause at BA→Architect and QA→Release, default), or `all` (every transition).

# examples

- Execute all phases with auto-detected runtime:

  <%= config.bin %> <%= command.id %> --story SA-102

- Execute with Claude and no gate pauses:

  <%= config.bin %> <%= command.id %> --story SA-102 --runtime claude --gates none

- Resume from the developer phase after a gate pause:

  <%= config.bin %> <%= command.id %> --story SA-102 --from-phase developer

- Preview the execution plan without running anything:

  <%= config.bin %> <%= command.id %> --story SA-102 --dry-run

# info.dry-run-header

Dry run — no processes will be spawned

# info.dry-run-phase

Phase: %s Runtime: %s Profile: %s

# info.dry-run-rule-file

Rule file: %s %s

# info.phase-start

→ %s (%s)

# info.phase-done

✓ %s done

# info.phase-failed

✗ %s failed (exit %d)

# info.no-runtime

No supported AI runtime found in PATH. Install one of the following:

claude → npm install -g @anthropic-ai/claude-code
codex → npm install -g @openai/codex
cursor → https://cursor.com (enable CLI in settings)

Then retry with: sf setup-agents workflow execute --runtime <name> --story <id>

# warn.rule-file-missing

Rule file not found — runtime will run without a system prompt.

# flags.max-iterations.summary

Maximum QA→Developer loop iterations.

# flags.max-iterations.description

Maximum number of times the QA→Developer loop can repeat before the run is blocked.
Defaults to 5. Must be at least 1.

# warn.cursor-no-api-key

CURSOR_API_KEY is not set. The cursor agent command may fail without it.

# flags.max-phase-minutes.summary

Maximum minutes a single phase may run before it is killed.

# flags.max-phase-minutes.description

If a spawned runtime process does not exit within this many minutes, it is sent SIGTERM
and the phase is marked failed with exit code 124 (timeout). Default: 60. Min: 1.

# flags.max-agents.summary

Maximum number of sub-agents the runtime may spawn per phase.

# flags.max-agents.description

Passed to the runtime CLI as --max-turns (claude/cursor) or --max-agents (codex).
Prevents sub-agent fan-out that can exhaust memory in CI environments. Default: 5. Min: 1.

# flags.capability-signals.summary

Additional runtime capability signals.

# flags.capability-signals.description

Additional task signals used to activate runtime capabilities for each phase prompt.
Sub-agent handoff records are read automatically; this flag is only an explicit override/addition.
For example: `qa evidence,acceptance criteria coverage,release evidence`.

# info.phase-timeout

⏱ Phase %s timed out after %dm — killed (exit 124)

# warn.cursor-auth-fallback

Cursor CLI is not authenticated. Open Cursor IDE and create a new Agent task manually:

Prompt (copy and paste):
%s

Rules file active in IDE: %s

Tip: Cursor IDE automatically loads .cursor/rules/\*.mdc — your profile rules are already wired in.
Once the agent finishes, resume with:
%s
