# summary

Scaffold and orchestrate a multi-phase story workflow (state records only — no AI invoked).

# description

Creates orchestration state for a story lifecycle across phases:

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

**This command is an orchestration scaffold.** It creates task records, records handoffs,
and pauses at gate transitions. No AI runtime is invoked. Total elapsed time is typically
under 5 seconds because no work is executed.

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 gates auto-approved.
- `phase` — human approval at BA→Architect and QA→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 or backlog item id.

# flags.story.description

The story id to track throughout the workflow, e.g. `SA-102` or `#102`.

# flags.gates.summary

Gate approval mode.

# flags.gates.description

Controls where human approval is required: `none` (fully autonomous),
`phase` (gate at BA→Architect and QA→Release, default), or `all` (every transition).

# 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 run that is in the QA phase. Omitting it defaults to `pass`.

# 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

- Fully autonomous run (no human gates):

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

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

Workflow complete for %s [run=%s]

# 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
