# 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 → Document Review → Release

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

- `auto` — detects the first available runtime using `--runtime-preference`, then workspace
  `orchestration.runtimePreference`, then workspace `tools`, then claude, cursor, codex.
- `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 Document Review→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 using `--runtime-preference`, workspace `orchestration.runtimePreference`,
workspace `tools`, then the fallback order claude → cursor → codex.

# 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.foreground.summary

Run the next phase inline and wait for it, even inside a chat session that could dispatch it to the background instead.

# flags.foreground.description

By default, when SETUP_AGENTS_BRIDGE_PORT, SETUP_AGENTS_BRIDGE_TOKEN, and
SETUP_AGENTS_CHAT_SESSION_ID are present in the environment (all three are
already set when this command runs from the web console chat's own Bash tool), the
next phase is dispatched via the bridge's existing async spawn pipeline (the
same one behind the console's own "Detached subagent" delegation) and this
command returns immediately instead of waiting for it — only the NEXT phase
is delegated, not the full remaining sequence; re-run with --from-phase
<next> once notified the delegated phase completed. --foreground skips that
and always runs inline, matching the pre-GH-746 behavior. Outside a chat
session (CI, manual terminal use) those environment variables are simply
absent, so this command already runs inline with or without --foreground.

# 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 Document Review→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

- Prefer Codex when auto-detecting:

  <%= config.bin %> <%= command.id %> --story SA-102 --runtime auto --runtime-preference codex,claude,cursor

- 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>

# info.background-dispatched

▶ %s dispatched in background (spawn %s) — running via the bridge, not this process. Re-run with --from-phase <next> once notified it completed.

# error.background-delegate-failed

Bridge rejected the background delegation: %s

# 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`.

# flags.runtime-preference.summary

Preferred runtime order for auto detection.

# flags.runtime-preference.description

Comma-separated runtime order used only when `--runtime auto` is selected.
For Codex-preferred execution, pass `codex,claude,cursor` or set
`orchestration.runtimePreference` in `.setup-agents/config.json`.

# 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