---
name: wf-orchestrate
description: 'WellForge command — Orchestrate the full agent team on a goal (spec → plan → tasks → implementation → QE verdict). Invoke explicitly: $wf-orchestrate <goal> [--mode spike|mvp|production] [--ledger <path>] [--terse|--no-terse] — feature request, bug report, refactor, or infra change'
---
> WellForge command, generated for Codex from `wellforge-plugin/commands/orchestrate.md` — do not edit; regenerate with `adapters/codex/generate.py`.
> Invoked as `$wf-orchestrate <goal> [--mode spike|mvp|production] [--ledger <path>] [--terse|--no-terse] — feature request, bug report, refactor, or infra change`. **ARGUMENTS** below means the text the user wrote after `$wf-orchestrate` in the invoking message (empty if nothing).
>
> **Codex:** dispatch a `wf-<role>` agent by asking Codex to spawn the custom agent of that name. Codex subagents share this checkout — `isolation: "worktree"` is not a spawn option — so the worktree-isolation **Fallback** applies to every batch of ≥2 implementation agents: run them **sequentially** in the main tree and record the isolation mode as `sequential (codex: no worktree isolation)`. Read-only agents (security review, eval) may still run in parallel.


Drive the WellForge agent team end-to-end on this goal, following the **spec-driven** skill
conventions (load that skill now).

Goal: ARGUMENTS

## Step 0 — Resolve the rigor tier and terse mode

Load the **rigor-tiers** skill and run its *"Resolving the tier and terse at dispatch"*
section verbatim — precedence, strip the flags, state both. Load the **terse** skill for the
cue itself. Then pick the pipeline:

- **`spike`** → do NOT run the pipeline below. Hand off to the `$wf-spike` procedure
  (main loop, brief.md, no agents, advisory gates), forwarding any `--terse`/`--no-terse`
  token unchanged — spike resolves its own terse default. Run that and stop.
- **`mvp`** → the **mvp** pipeline (one gate, mid agents only, no architect/designer/eval).
- **`production`** (default) → the full **feature** pipeline as written.

bugfix / refactor / infra flows below are tier-independent (always production-shaped) — a
spike doesn't need orchestration, and infra/refactor carry their own gate by nature.

## Your role

You are the orchestrator — you coordinate, you never implement. All production work is
done by the role agents (`wf-product-owner`, `wf-architect`, `wf-designer`, `wf-frontend-dev`,
`wf-backend-dev`, `wf-devops`, `wf-quality-engineer`) and specialists (`wf-adr-writer`,
`wf-owasp-reviewer`). You are also the ONLY place human approval happens: subagents cannot
ask the user anything and must never self-approve.

## Handoff contract (applies to every stage)

- Each stage's artifact is **written to disk before the next stage starts**. After every
  agent returns, verify its artifact exists and is well-formed; pass **file paths** to
  the next agent, never chat-context summaries — this survives compaction and keeps
  agents honest.
- An agent reporting drift (spec/plan wrong) PAUSES the pipeline: surface the proposed
  amendment to the user, apply it via the owning agent (PO for spec, architect for plan),
  re-sync tasks (`$wf-tasks` re-sync mode), then resume.
  - **Batch it.** One agent's return usually carries several drift items; a stage's worth
    goes to the owner in **one** dispatch, and tasks re-sync **once** after all owners have
    returned — not one PO → architect → re-sync chain per item.
- **Scope is frozen at gate 1.** After approval, drift may *correct* the spec — a wrong
  premise, an untestable AC, a contract the code contradicts. It may not *grow* it. When a
  stage surfaces something new that no approved AC requires (an adjacent defect, a
  hardening idea, a refactor the baseline wants), record it and ask the user once, with the
  default first: **new spec / bugfix after this one** (recommended) · add it here, which
  re-opens gate 1 and is said in those words. Every accepted addition is re-planned,
  re-tasked, re-verified and re-evaluated; a feature that doubles its ACs after approval
  has stopped being the thing that was approved. State the running count when you ask
  ("spec approved at 49 ACs, now 61").
- **Every dispatch is a fresh agent handed paths.** Resume an agent only to question the
  output it has just returned; a new round of work — a fix round, a re-verification, an
  amendment — is a new dispatch (rigor-tiers skill, *"Fresh agents, not resumed ones"*).
- Relay agent results to the user compactly after each stage — one short block per stage,
  not the full agent output. Include each agent's one-line **self-critique** result
  (`self-critique` skill — every artifact-producing agent runs one bounded pass before
  returning): at a human gate it tells the reviewer what was already caught, and an agent
  that silently omits it skipped the pass. It is never evidence of quality — the gate, QE
  and the eval judge exactly as before.
- **Agent decisions are recorded, not relayed away.** Every dev/devops return carries a
  `DECISIONS:` block (a hook sends it back otherwise). With a spec dir, append it to
  `specs/NNN-slug/decisions.md` (spec-driven skill); without one (bugfix, infra), list the
  lines in the final report. Either way, quote every **reinterpretation** in the stage relay.
- **Prepend the resolved tier's effort cue** (rigor-tiers skill) to every agent's task
  prompt — moderate for `mvp`, full for `production`. It's plain text, not config.
- **When terse is resolved on** (Step 0), also prepend the terse cue (**terse** skill,
  verbatim — do not paraphrase) to every dispatched agent's task prompt, right beside the
  effort cue. When terse is resolved off (the `mvp`/`production` default with no `--terse`
  flag), do not prepend it at all.
- **Parallel isolation.** Any implementation batch of **≥2 independent agents** runs under the
  **worktree-isolation** skill — load it and follow it verbatim: the shared-state **preflight**
  (a class left unclassified means sequential, not a gamble), the env **carry-in** and its
  verification, `isolation: "worktree"` dispatch (each agent commits on its own branch and does
  NOT touch `tasks.md`), rebase + `--ff-only` integration, central checkbox reconciliation, and
  pruning. Independence is judged on the **effective graph** — declared `deps:` ∪ `touch:`
  overlap — not on `deps:` alone. Collision handling (a conflict = a wrong edge, surfaced like
  drift) and the sequential fallback come from the same skill. A solo agent or a sequential
  chain runs in the main tree as usual.

## Step 1 — Classify

Classify the goal as **feature** / **bugfix** / **refactor** / **infra**. If genuinely
ambiguous, ask with AskUserQuestion (one round). Then run the matching pipeline.

## Step 1b — Run preflight

Before the first agent, run the **rigor-tiers** skill's *"Run preflight — before the first
agent is spent"* section verbatim (`mvp` and `production`, every pipeline): baseline green,
commits and signing work, worktrees branch from HEAD — and, as soon as the spec says the
feature has a UI or sits behind a login, the app starts, a browser tool answers and a test
identity exists. Print the table. A red row goes to the user, never to an agent, and at
`production` there is no proceeding past one. Every row here is something an agent would
otherwise report by stopping, one dispatch at a time.

## Pipeline: feature

1. **PO** → spawn `wf-product-owner` with the goal. Artifact: `specs/NNN-slug/spec.md`.
   - **With `--ledger <path>`** (a decision ledger from `$wf-grill-me` — the
     **grilling** skill defines it): strip the flag from the goal, check the file exists,
     and pass the PO its **path** alongside the goal. The user has already answered those
     questions; this is how their answers reach an agent that cannot see this conversation.
     Once the spec exists, move a `.forge/grill/` ledger to `specs/NNN-slug/ledger.md`
     yourself (`git mv` when tracked) — the PO has no shell.
   - No flag, but `.forge/grill/` holds a ledger whose topic plainly matches this goal →
     name it and ask once whether to use it. Never pick one up silently, and never guess
     between two.
2. **Open questions** → if the spec has open questions, put them to the user
   (AskUserQuestion, batch them) and have the PO fold the answers in. With a ledger these
   are only its **Open** entries and anything the PO found it did not cover — a question
   the ledger records as Decided or Delegated is not asked again.
3. **HUMAN GATE 1** → present the spec summary (stories, ACs, non-goals). Ask: approve /
   iterate / abort. On approve, set `status: approved` + `approved: <date>` yourself
   (recording the user's decision is your job). On iterate, loop the PO with the feedback.
   - If the PO returned **glossary candidates**, show them with the spec summary and write
     the accepted ones to `.claude/context/glossary.md` yourself (`domain-modeling` skill —
     agents never edit it). Do the same for the architect's at gate 2 and for any a dev
     agent reports, alongside its ADR candidates.
4. **Architect** → spawn `wf-architect` with the spec path. Artifact: `plan.md`.
5. **HUMAN GATE 2** → present architecture, trade-offs, AC→test mapping. approve /
   iterate / abort. Record approval as in gate 1.
   - After approval: if the plan lists `## ADR candidates`, spawn `wf-adr-writer` for them.
6. **Designer** (only if the feature has UI) → spawn `wf-designer` with the spec path.
   Artifact: `design.md`. Relay reuse-vs-NEW summary; no human gate — design issues
   surface at QE.
7. **Tasks** → run the `$wf-tasks` procedure against the approved plan.
   Artifact: `tasks.md`. Set spec `status: in-progress`.
8. **Implementation** → dispatch dev agents (`wf-frontend-dev` / `wf-backend-dev` / `wf-devops`
   per task domain):
   - Tasks with no edge between them on the **effective graph** (declared `deps:` ∪ `touch:`
     overlap — glob overlap included, so two tasks creating migrations are serialized) run as
     **parallel agents in one batch** (typical: FE and BE tracks) under **worktree isolation**
     (handoff contract). Report any edge the overlap check added. Merge each track's branch
     back and reconcile checkboxes centrally per the worktree-isolation protocol; a collision
     is a wrong edge → surface and re-sync.
   - Each agent gets: spec dir path + its task ID(s). Nothing else.
   - If an agent reports a blocker or drift, pause that track, handle per the handoff
     contract, resume.
   - If an agent surfaces an **ADR candidate** (a decision it had to make that constrains
     future work and the plan didn't cover), collect it; after implementation, offer to spawn
     `wf-adr-writer` for it — same as the architect's ADR candidates at gate 2.
9. **Security review, then QE.** Before QE, run the trigger check — the dispatch comes from
   the task graph, not from anyone remembering:

   ```bash
# The deterministic layer ships INSIDE this repository for Codex; there is no
# plugin install to resolve. `wf-doctor` checks that python3 + pyyaml (or uv) can
# run it.
WF="$(git rev-parse --show-toplevel)/.codex/wellforge"
   # A FUNCTION, not a variable holding a command: `WFPY="uv run ... python"` then `wfpy x`
   # relies on word splitting, which zsh does not do for unquoted parameters — measured, it
   # fails with `command not found: uv run --quiet --with pyyaml python`.
   # uv first because forge-state needs pyyaml to read frontmatter and the system python3
   # usually lacks it; without it every field reads as unknown.
   wfpy() {
     if python3 -c "import yaml" 2>/dev/null; then python3 "$@"; else uv run --quiet --with pyyaml python "$@"; fi
   }
   wfpy "$WF/scripts/security-triggers.py" \
     --tier <resolved tier> --diff-base <feature branch base> \
     --touch '<each touch: glob in this batch>' --json
   ```

   It matches the union of declared `touch:` globs and the real `git diff --name-only`
   against `config/security-triggers.yml`; `production` reviews every batch. On
   `dispatch: true`, spawn `wf-owasp-reviewer` scoped to `scope[]` — **in parallel
   with QE**, since neither waits on the other. The plan's `## Security` YES still forces a
   pass, and so does a QE recommendation; the trigger check means none of the three is the
   only thing standing between an auth change and a review. Findings ≥ medium are defects.
   Record `verdicts.security` in the run trace with the matched rules.

   Then spawn `wf-quality-engineer` with the spec dir. Its verdict is also on disk
   at `specs/NNN-slug/qe-report.md` — that path, not your summary, is what later agents get.
   On any FAIL, follow the **rigor-tiers** skill's *"Routing a QE FAIL — triage before you
   loop"* section: the owner-per-defect table, the **2-round cap** (per feature — a user
   instruction grants one round, it does not reset the count), what to do when a re-run
   finds a defect the last pass missed, and its composition with `systematic-debugging`'s
   3-attempt stop. It is defined there, once, for this command, `$wf-implement` and
   `$wf-promote` alike.
   On **BLOCKED** (a required check could not run), same section: no fix round, no dev
   agent, **no eval** — fix the environment row it names and re-run QE for the blocked rows.
10. **Eval — only on a QE PASS.** A FAIL or BLOCKED QE verdict means the evaluator is not
    dispatched: it would fail on evidence known to be missing. Spawn `wf-evaluator` with the spec dir (LM-judge against the central
    rubric, which the agent resolves itself — a scaffolded project has no `gates/`, so it
    falls back to the plugin's bundled copy). This is the non-deterministic verification half QE
    can't cover — set the bar at the eval, not the QE demo. FAIL → **triage each failing
    dimension to its owner** (as in step 9: code → dev, spec → PO, plan → architect, design →
    designer), same bounded 2-round loop, re-eval.
11. **Record the run** → write the run trace per the **observability** skill:
    `.forge/runs/<run_id>.json` (schema `wellforge-run/v3`, include `rigor: production`, and
    `rigor_recorded` when a `--mode` flag ran this pass at a tier other than the feature's,
    and `plugin_version` — the plugin that produced the run, since the rules it ran under
    move with that version)
    capturing the full pipeline — every agent + outcome, drift events, QE + eval verdicts,
    the isolation mode + any collision events + any environment faults (observability skill
    `worktree` / `collision_events` / `env_faults`), `fix_rounds`, `result`. Write it even when the pipeline escalates or stops early
    (`result` records that). Set `terse` to the boolean resolved in Step 0 (`true` iff
    `--terse` resolved on for this run, `false` otherwise); leave `control_run_id` `null`
    (pairing a run to its control run is a later concern, not this command's). The audit
    trail.

12. **Close** → **run the `$wf-done` procedure** (production branch) for this
    feature. It re-verifies the gate against the artifacts on disk — all tasks checked, QE
    PASS, security PASS, fresh eval PASS — and records `status: done` + `done: <date>`. Do
    not flip the status yourself even though you just ran the stages that produced those
    artifacts; one implementation of this transition is the point. If its gate refuses,
    relay the missing condition instead of closing. Then summarize (stories delivered, QE +
    eval verdict tables, commits) and suggest next steps.

    **This step is AFTER the trace on purpose.** The done gate reads `verdicts.qe` and
    `verdicts.security` *from the run trace*, so on a feature whose only run is this one,
    closing first means closing against a feature with no trace — and `$wf-done`
    refuses with "QE verdict is absent" for work that just passed QE. Record, then close.

## Pipeline: mvp  (rigor tier `mvp` — collapsed, one gate, mid agents only)

A faster feature flow for a first release you'll validate with users. Same handoff
contract and disk-based artifacts, fewer stages. **Never spawn the frontier agents**
(`wf-architect`, `wf-evaluator`) — that's how mvp stays cheap (rigor-tiers skill).

1. **PO** → spawn `wf-product-owner` with the goal. Artifact: `specs/NNN-slug/spec.md`
   with `rigor: mvp` in frontmatter. Fold any open questions into one AskUserQuestion round.
   `--ledger <path>` works exactly as in the feature pipeline: pass the path to the PO, move
   the ledger beside the spec afterwards, and do not re-ask what it already settles.
2. **HUMAN GATE (the only one)** → present the spec summary. approve / iterate / abort;
   record approval as usual.
3. **Tasks** → run the `$wf-tasks` procedure yourself (main loop) directly against the
   approved spec — NO separate architect/plan.md. Capture the minimal architecture inline in
   `tasks.md` (touched files, contracts per task). Set spec `status: in-progress`.
4. **Implementation** → dispatch dev agents (`wf-frontend-dev` / `wf-backend-dev` /
   `wf-devops`) exactly as in the feature flow — parallel where the effective graph
   allows (`deps:` ∪ `touch:` overlap), under worktree isolation (handoff contract) for any
   batch of ≥2 independent agents.
5. **QE (light)** → spawn `wf-quality-engineer` scoped to the work, in **advisory** mode:
   it runs the gates and reports numbers, but only **SAST-high, lint, typecheck, and the
   security floor BLOCK** (rigor-tiers). Coverage is reported as gap-to-80%, not enforced.
   Triage blocking defects to their owner (code → dev; a wrong/untestable AC → the PO for a
   spec amendment — mvp has no architect/designer to route to). Same bounded 2-round loop.
5b. **Security review** → run the same trigger check the production pipeline runs. It was
   missing here, and the omission was not a tier decision:
   `config/security-triggers.yml` reviews `mvp` **on a match**, `implement.md` runs the
   check at every tier, and only `orchestrate`'s mvp pipeline skipped it — so the same
   batch was reviewed under `$wf-implement` and not under `$wf-orchestrate`.

   ```bash
   # $WF / wfpy as resolved earlier in this command.
   wfpy "$WF/scripts/security-triggers.py" \
     --tier mvp --diff-base <the feature branch base> \
     --touch '<each touch: glob in this batch>' --json
   ```

   `dispatch: false` → one line saying so, then QE. `dispatch: true` → spawn
   **`wf-owasp-reviewer`** over `scope[]`; findings ≥ medium route like a QE FAIL.
   Record `verdicts.security` mapped per `agents/owasp-reviewer.md`, and
   `security.matched_rules[]`. At mvp an absent verdict is legitimate (nothing matched) —
   record `security.dispatched: false` so that reads as a decision rather than an omission.
6. **Record the run** → trace as below with `command: orchestrate`, `rigor: mvp`. Before
   the close, not after: the gate reads `verdicts.qe` from the trace, so closing first
   refuses with "QE verdict is absent" on a feature whose only run is this one.
7. **Close** → **run the `$wf-done` procedure** (mvp branch: all tasks checked +
   QE-light PASS, **no eval** — mvp's bar is QE, not the LM-judge). It records `status: done`
   *and* `done: <date>`; don't flip the status here. End with the
   rigor-tiers visibility reminder: "rigor: mvp — coverage advisory, not yet production;
   `$wf-promote NNN-slug --to production` to graduate (adds plan, full coverage, eval)."

## Pipeline: bugfix

1. **QE (repro)** → spawn `wf-quality-engineer` in bug-reproduction mode: smallest failing
   test, committed alone. If QE cannot reproduce, stop and report to the user.
2. **Dev (fix)** → spawn the owning dev agent with the failing test path and the instruction
   to follow the `systematic-debugging` skill. Scope: make it green without weakening it —
   root cause stated before the fix, one change, attempts counted. Three failed attempts on
   the same symptom is an architecture signal, not a fourth try: the agent stops and reports,
   and you route it as drift (architect) rather than re-dispatching the fix.
3. **QE (verify)** → confirm green + no regressions (relevant suite, not just the one
   test). Same 2-round escalation rule.

No spec required for a bugfix UNLESS the fix changes documented behavior — then it's
drift on the original spec: pause and amend first.

## Pipeline: refactor

1. **Architect** → mini-plan: current state, target state, invariants that must not
   change (observable behavior, public contracts), migration steps. **HUMAN GATE** on it.
2. **Tasks → devs** as in the feature flow (behavior-preserving steps, each independently
   green).
3. **QE** → full gates + explicit before/after invariant check.

## Pipeline: infra

1. **DevOps** → spawn `wf-devops` with the goal. For anything touching prod-like
   infrastructure or external services, **HUMAN GATE** before execution (show the plan of
   record: what will be created/changed, where).
2. Verify via the devops agent's executed verification commands — relay actual outputs.

## Hard rules

- The **security floor** (secret scan, no hardcoded creds, critical-CVE audit) blocks in
  EVERY tier — `mvp` may make coverage advisory but never waives the floor (rigor-tiers).
- A lower tier is never silently promoted: `mvp`/`spike` reach `production` only via
  `$wf-promote`. State the resolved tier; print the visibility reminder for non-production.
- Exactly the gates listed — never auto-approve, never add approval theater elsewhere.
- Never implement, edit code, or write artifacts yourself (the two exceptions: recording
  user approvals in frontmatter, and trivial mechanical fixes to artifact frontmatter).
- Bounded loops everywhere: PO/architect iterate at user request only; QE fix loop max 2
  rounds **per feature**; then escalate with the three exits (one more round · split ·
  stop). A reply to an escalation buys one round, never a fresh count. You never loop
  silently, and you never loop two rounds at a time either.
- If the session ends mid-pipeline, state precisely where it stopped (stage + artifact
  paths) so `$wf-orchestrate` can resume from the artifacts on disk — re-read
  spec status frontmatter to find the resume point.