# summary

Run a multi-phase story workflow, with optional autonomous delegated execution and verification.

# description

Creates orchestration state for a story lifecycle across phases:

PM → BA/PO → Architect → UX? → Developer ↔ QA (loop) → Document Review → Release

Manual mode creates task records, handoffs, and gate pauses. With `--autonomous`, the same
workflow controller invokes delegated phases, executes registered verification lanes, returns
failures to Developer, and persists criterion-specific assertion evidence. Mandatory human
architecture and final release gates remain enforced. Manual mode is the default.

Autonomous verification records every governed lane as selected, excluded, or blocked with a
reason. A substantive criterion is verified only by a registered verifier contract and evidence
from the same run, iteration, and source digest. Required unavailable lanes block readiness.
The loop stops after at most five attempts or two consecutive no-progress iterations.

To dispatch work to an AI runtime (Claude, Codex, etc.), use:

sf setup-agents workflow execute --runtime claude --story <id>

Each phase creates a native task, claims it, records evidence, and creates a handoff
to the next role. Gate transitions create a review request and pause until completed
via `sf setup-agents review complete`.

The `--gates` flag controls gate behavior:

- `none` — all transition gates auto-approved in manual mode; invalid with `--autonomous`.
- `phase` — human approval at BA→Architect and Document Review→Release boundaries (default).
- `all` — human approval at every phase transition.

Run state is persisted to `.setup-agents/state/workflow-runs.jsonl`.
Resume a paused run after approving the gate review with `--resume <run-id>`.

# flags.story.summary

Story/task id — the same id you passed to `task create --id`.

# flags.story.description

The id to track throughout the workflow. This is the SAME id you registered with `task create --id <id>` — `workflow run` resolves that task's roles and phase overrides from it. e.g. `SA-102`, `#102`, or a `setup-agents-task-…` id. (Note: this is `--story`, not `--task`; the Orchestra CLI uses `--task` for the equivalent, but `sf setup-agents workflow` uses `--story`.)

# flags.gates.summary

Gate approval mode.

# flags.gates.description

Controls where human approval is required: `none` (no transition gates in manual mode),
`phase` (gate at BA→Architect and Document Review→Release, default), or `all` (every transition).
`none` applies only to manual orchestration; autonomous-v1 rejects it because its two mandatory
human gates cannot be disabled.

# flags.max-iterations.summary

Maximum Dev↔QA loop iterations.

# flags.max-iterations.description

Stop the Dev↔QA bug-fix loop after this many QA failures. Default: 5.

# flags.profiles.summary

Override active profiles for this run.

# flags.profiles.description

Comma-separated profile ids to activate for this workflow run.
Defaults to profiles in `.setup-agents/config.json`.

# flags.resume.summary

Resume a paused workflow run.

# flags.resume.description

Resume execution of a paused workflow run after a gate review was approved.
Provide the run id returned by the original invocation.

# flags.instructions-dir.summary

Directory to resolve playbooks from.

# flags.instructions-dir.description

Path relative to the workspace root where playbook files are stored.
Defaults to `.setup-agents/playbooks` (generated automatically by `sf setup-agents local`).
Override to point at a custom directory.

# flags.from-phase.summary

Start the pipeline from a specific phase, skipping all prior phases.

# flags.from-phase.description

Creates a new run with upstream phases marked as skipped and begins execution
at the specified phase. Use this when work is already in progress to avoid
creating duplicate tasks for phases that were handled manually.

When combined with --resume, overrides the auto-detected resume phase and
forces execution to start at the specified phase instead.

Example: if Apex is already written and claimed, start at the developer phase:
sf setup-agents workflow run --story PHP-313 --from-phase developer

Example: resume a run but force it to restart from QA:
sf setup-agents workflow run --story PHP-313 --resume wf-1234567-abc1 --from-phase qa

# flags.qa-result.summary

QA result for this resume.

# flags.qa-result.description

Report the QA outcome when resuming after a QA phase: `pass` to proceed to
release, `fail` to return to developer for bug fixes. Required when resuming
a manual run that is in the QA phase. Autonomous mode derives the result from
registered verification and does not accept caller-supplied QA as evidence.

# flags.autonomous.summary

Run real verification checks and automatically correct failures.

# flags.autonomous.description

Opt in to the bounded autonomous-v1 delivery loop. QA derives pass/fail from a run-baseline
changed-surface plan and criterion-specific verifier contracts in
`.setup-agents/autonomous-verifiers.json`; generic lane success cannot verify a criterion.
The validated scope/architecture and final release gates remain mandatory. The Web bridge
exposes equivalent `POST /api/v1/workflows/autonomous/start` and `/resume` requests. Each lane
is reported as selected, excluded, or blocked, and qualifying evidence is bound to run ID,
iteration, and source digest. Execution stops after no more than five attempts or two consecutive
no-progress iterations. The deterministic environment seam is test-only; production uses the
configured delegated provider, and an unavailable required provider is a blocking deferral.

# flags.dry-run.summary

Print the planned phase graph without executing.

# flags.dry-run.description

Show which phases will run, which gates will fire, and the handoff chain — without creating any records.

# examples

- Run with default phase gates:

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

- Opt in to autonomous verification with mandatory human gates:

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

- Supervised run (gate at every transition):

  <%= config.bin %> <%= command.id %> --story SA-102 --gates all --max-iterations 3

- Preview without executing:

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

- Resume after approving a gate review:

  <%= config.bin %> <%= command.id %> --story SA-102 --resume wf-1234567-abc1

- Start at developer phase (work already in progress):

  <%= config.bin %> <%= command.id %> --story PHP-313 --from-phase developer

- Start at QA phase with immediate pass result:

  <%= config.bin %> <%= command.id %> --story PHP-313 --from-phase qa --qa-result pass

- Resume a run but force restart from QA (overrides auto-detected phase):

  <%= config.bin %> <%= command.id %> --story PHP-313 --resume wf-1234567-abc1 --from-phase qa

# info.qa-pause

⏸ QA phase — report result when resuming:
Pass: sf setup-agents workflow run --story %s --resume %s --qa-result pass
Fail: sf setup-agents workflow run --story %s --resume %s --qa-result fail

# info.starting

Starting workflow for story %s [gates=%s max-iterations=%d]

# info.autonomous-phase-dispatched

▶ %s dispatched in background (spawn via the bridge, not this process) — run paused. Resume with: sf setup-agents workflow run --story <id> --resume %s

# info.autonomous-phase-still-running

⏳ %s is still running in the background — run paused. Resume again once notified it completed: sf setup-agents workflow run --story <id> --resume %s

# info.phase-start

→ %s (task %s)

# info.phase-done

✓ %s → handoff %s

# info.gate-pause

⏸ Gate %s→%s — review %s
Approve: sf setup-agents review complete --id %s --result approved --reviewer %s
Resume: sf setup-agents workflow run --story %s --resume %s

# info.qa-fail

✗ QA failed (iteration %d/%d) — returning to developer

# info.qa-max

✗ QA failed after %d iterations — workflow blocked

# info.autonomous-authority

GO is a readiness recommendation only. This command cannot approve a human gate, merge, push, publish, deploy, or release.

# info.done

Workflow complete for %s [run=%s]

# info.already-complete

Workflow run %s is already complete for %s — nothing to resume. Every phase is done or skipped. Use --from-phase to deliberately re-run a phase, or `workflow rollback` to reopen the run.

# info.dry-run-header

Dry run — no records will be created

# info.dry-run-phase

%s (%s) gate=%s

# warn.no-config

No .setup-agents/config.json found — using default profiles.

# info.playbook-found

    📄  %s  (%s)

# warn.playbook-missing

    ⚠   %s not found in %s — run `sf setup-agents local` to generate it

# info.dry-run-playbook

      %s  %s

# info.release-check-pass

✓ Release checks passed.

# info.release-check-fail

✗ Release-check gate failed — blocking issues: %s

# errors.story-required

--story is required.

# errors.run-not-found

Workflow run not found: %s

# flags.reject-to.summary

Reject current phase and return work to a target phase.

# flags.reject-to.description

When resuming a paused run, reject the active phase and re-route work to the specified target phase with findings as context. The target phase will be re-initialized with rejection context so the role knows what to fix.

Example: QA rejects back to developer:
sf setup-agents workflow run --story SA-102 --resume wf-123 --reject-to developer --findings "Missing null check in handler"

Example: Architect rejects back to BA:
sf setup-agents workflow run --story SA-102 --resume wf-123 --reject-to ba --findings "Acceptance criteria incomplete"

# flags.findings.summary

Rejection findings to pass as context to the target phase.

# flags.findings.description

Free-text description of why the current phase is rejecting. This text is attached to the re-initialized target phase task so the responsible role has context about what needs to be fixed.

# flags.push-to.summary

Push phase completion comments to GitHub Issue or Jira ticket.

# flags.push-to-dry-run.summary

Print the write-back payload without sending.

# flags.ticket.summary

GitHub issue number or Jira ticket ID to comment on.

# info.writeBackPushed

Pushed phase %s to %s: %s

# info.writeBackDryRun

[dry-run] Would push phase %s to %s:

# warn.jira-deprecated

--push-to jira is deprecated. Use the update-jira-ticket.md playbook in your release phase instead. See .setup-agents/playbooks/update-jira-ticket.md