Implement

End-to-end workflow for taking MCP work items from queue to PR. This skill composes the schema-driven planning (spec-quality), implementation, review (review-quality), and git/PR workflow into a single pipeline.

Usage:

• /implement <item-id> — work on a specific item
• /implement — with context about what to work on
• Can process single items or multiple items in batch

Step 1 — Assess the Work

Load the item(s) and determine the execution tier and interaction mode.

Call shapes are in claude-plugins/task-orchestrator/skills/_generated/call-shapes.md and field semantics in current/docs/api-reference.md; ids below are 8-hex shorts (any id field also takes the full UUID). Read every answer through the envelope: ok, then data.results[i] (ok or error). When a write element fails, the call-level error is only partial_failure (no detail, no fix): read code, kind, detail and fix from data.results[i].error. A read (select) call reports its failure in the call-level error. A dispatch-issued seat token goes in the top-level seatToken of every call, reads included; it is never printed, committed or written to a note.

For each item, call items_read context (itemId) to understand:

• Current role and gate status (gateStatus.canAdvance, gateStatus.missing)
• Item type (feature-implementation, bug-fix, etc.)
• Existing notes already filled
• Dependencies and blocked status

When the user or an item references a PR or commit as already landed, verify its merge state before relying on it — gh pr view <n> --json state,mergeCommit plus git log origin/main — and confirm the working tree is current (Step 2, base-freshness precondition) before any pass that checks whether a change is present in the codebase.

Execution tier — classify by this table (canonical source shared with the task-orchestrator:orchestrate skill; edit the fragment, not this copy):

Force-UP signals (bump tier regardless of file count):

• Database migration → min Delegated
• New public API surface → min Delegated
• Multiple independent work streams → Parallel
• User says "let's plan" / collaborative language → min Delegated

Force-DOWN signals:

• User says "just fix it" / "quick" → Direct (unless complexity contradicts)
• The item's type resolves to the default schema, or the item is schema-free -> eligible for Direct

Delegated with ≥2 ready items, or Parallel → run /task-orchestrator:run-wave.

If the item's type has no schema, give it quick-fix for Direct tier; for Delegated/Parallel the default schema (when configured) catches it.

Trait application on classification. When the tier resolves to Delegated or Parallel and the workspace defines a delegated trait (config effective lists the declared traits), apply it before any dispatch — traits: ["delegated"] at item creation, or items_write update for an existing item:

{"tool":"items_write","op":"update","args":{"id":"4b7d0e19","traits":["delegated"]}}

The traits array replaces the item's traits, so list every trait the item already carries.

This makes the orchestrator-filled delegation-metadata note schema-visible instead of convention-only. Direct tier: do not apply it — nothing is delegated.

Model-selection traits. Seat dispatch defaults come from the delegated trait (planner opus, implementer sonnet, test-author sonnet, reviewer opus). Override them per item, at the same point:

• complex-implementation — implementer on opus. Apply for architecture-heavy or multi-file synthesis work: new public API, cross-layer seams, subtle state machines or concurrency.
• high-stakes — planner and reviewer on fable. Apply sparingly, where a wrong plan or a missed review finding is expensive: security predicates, auth, data-loss paths, hard-to-reverse design decisions. Fable draws on its own usage bucket, so it is never a default. needs-security-review does NOT imply it.

Read the resolved per-seat profile from items_read context / items_read schema (dispatchBySeat) and pass its model explicitly on the dispatch.

Test-author trigger rule. bug-fix.default_traits already includes needs-test-author — no action needed, it applies automatically. For feature-task items, apply needs-test-author per item (items_write update with traits listing the item's existing traits plus needs-test-author) when acceptance criteria involve a predicate, algorithm, parser, validator, or state transition, or when any force-ON signal is present: new public API surface, a database migration, a security predicate, or a prior vacuous-test finding in this item's area. Other item types (feature-implementation, plugin-change, quick-fix, and the global floor) do not carry the trait. Direct tier: apply the trait only in its temporal-only degraded mode, and only on bug-fixes — the test-plan gate and red-first rule still apply, test-manifest declares a single actor, and there is no separate test-author dispatch. Other Direct-tier items are exempt regardless of the criteria above — the tier is too small to separate authorship into a second dispatch.

Interaction mode — orthogonal to tier:

When processing multiple items, evaluate whether related items (e.g., bugs in the same module, fixes that touch the same files) should be grouped into a single branch and PR. Group when the changes are cohesive and independent fixes would create merge conflicts. Keep items separate when they're unrelated or when isolation makes review cleaner.

Step 2 — Prepare the Branch and Worktree

Sync local main before any implementation begins.

git checkout main
git pull origin main --tags

Base-freshness precondition. Before creating any branch or worktree, and before any source-verification pass (a grep or file read that decides whether a change is present), confirm the intended base is current:

git fetch origin
git log --oneline -1 origin/main
git rev-parse --short HEAD

The two SHAs must match, or HEAD must be a descendant of origin/main on the intended branch. A source-verification pass must never run against a working tree that has not been confirmed current — this includes the orchestrator's own session worktree. If the tree is behind, read the file directly from the remote (git show origin/main:<path>, from PowerShell on Windows — the Bash tool's MSYS layer mangles the ref:path colon) or create a fresh worktree from origin/main (fallback block below). A stale base manufactures absent-looking evidence and absence reads as a discovery, not an error: a 6-commit-stale tree reported four already-adopted proposals as missing (2026-08-04), and a one-commit-stale dispatch re-implemented existing runtime into a conflicting 17-file commit (2026-05-01) — trend 760be80d.

The branching/worktree strategy depends on tier:

Direct tier (orchestrator implements 1–2 files inline) — create a working branch on the main directory:

git checkout -b <branch-name>

Delegated tier (single subagent) — same as Direct: orchestrator creates the branch on the main directory, the subagent works against it. No worktree.

If the main checkout is unavailable (another branch checked out, uncommitted changes present) or the orchestrator itself runs from a worktree — Direct and Delegated tiers both: do not touch the occupied checkout. Create a dedicated worktree instead:

git worktree add .claude/worktrees/<slug> -b <branch-name> origin/main

Work there using absolute paths and git -C (never cd); after the PR merges, remove the worktree and delete the branch. Sync local main via git fetch origin main:main while main is not checked out anywhere, or a normal git pull from the main checkout when it is.

Parallel tier (parent feature with multiple children) — create a single feature worktree that all child agents share:

FEATURE_SLUG=<short-feature-description>          # e.g. issue-117-followup
FEATURE_BRANCH=feat/$FEATURE_SLUG
FEATURE_WORKTREE=.claude/worktrees/feat-$FEATURE_SLUG

# Resume detection — if the branch/worktree already exist (orchestrator restart
# mid-feature), reuse them rather than recreating:
if git show-ref --verify --quiet "refs/heads/$FEATURE_BRANCH"; then
  echo "Resuming existing feature branch $FEATURE_BRANCH"
else
  git branch "$FEATURE_BRANCH" main
fi
if [ ! -d "$FEATURE_WORKTREE" ]; then
  git worktree add "$FEATURE_WORKTREE" "$FEATURE_BRANCH"
fi

All child-task agents will be dispatched into this shared worktree (Step 4). The feature branch is pushed and PR'd once, when the parent feature reaches terminal (Step 6).

Plan file as dispatch contract (3+ children). For every Parallel-tier run, instantiate references/dispatch-contract-template.md into the wave's plan file before the first dispatch, fill every placeholder, and have every Step 3, 4, 4b and 5 dispatch prompt reference it under the template's conflict rule instead of restating design or process details per prompt. The template states the rules; this table only says what each slot is for — do not paraphrase a slot's rule into a prompt. Under /task-orchestrator:run-wave, the Header and File ownership rows are filled from the planner's explain output plus the planner-v1 stage's own returns rather than hand-typed, and the run reuses this same worktree by passing --mode shared --worktree $FEATURE_WORKTREE --branch $FEATURE_BRANCH — the contract file and its slot order are unchanged either way.

Write it to <main-checkout>\plans\<slug>.md and hand agents that absolute path, recorded once in the contract's Header Contract path line. The plans/ directory is gitignored, so it exists only in the main checkout and never in the feature worktree; a prompt that pins a worktree working directory and then names a relative plans/<slug>.md points at a path that is not there.

Two runs (retros 202b5d42, 6d562acb) produced zero vocabulary deviations across up to five concurrent authors this way, with prompts roughly 60% smaller. The delivery surface is itself the point (proposal 728a3e57 / #307): in a same-day controlled comparison, the wave with no contract file recurred every previously-adopted failure class, while the waves that ran from one held the gains — a rule that lives only in skill prose does not reach the agents, because agents read the dispatch prompt and their item's schema guidance. The contract guarantees deviation-free execution, not plan correctness — pair it with Step 3's "plans are spec inputs" rule so the plan's own factual claims are verified by the implementer rather than merely followed.

Why one worktree per feature, not per child: the feature is the natural PR boundary. Per-child PRs created cross-PR test contamination and PR-body staleness during the #117 follow-up (see retro a7f6024f). Shared worktree means one commit history, one CI cycle, one PR — and the parent feature's review-checklist gives a coherent point at which to finalize.

Branch naming:

• feat/<feature-slug> — feature-implementation parents (the integration branch)
• fix/<short-description> — bug-fix items (Direct or Delegated tier)
• fix/<grouped-description> — batch of related bug fixes (Delegated tier)
• chore/<short-description> — tech debt, refactoring (Direct tier)

Step 3 — Queue Phase: Planning

This step is tier-conditional:

Direct tier: Skip this step entirely. No plan mode. No queue-phase notes. Call advance transition with trigger: "start" immediately to move queue→work. The quick-fix schema has no queue-phase required notes, so the gate passes. Exception: if the item carries needs-test-author (temporal-only degraded mode, Step 1), test-plan is a queue-phase note and must be filled before this advance — see the seat-timing rule below.

Delegated tier: Fill queue-phase notes per schema. Use items_read context and items_read schema with fields: ["guidance"] to see the expected notes and their guidance text (guidanceKey is the key of the first missing required note). Pre-plan-workflow is optional - use only if scope needs exploration. Post-plan-workflow only if child items need materialization. Advance: advance transition with trigger: "start".

Parallel tier: Full planning pipeline:

Collaborative mode:

1. Tell the user the item is ready for planning and ask them to enter plan mode. The pre-plan-workflow and post-plan-workflow hooks fire automatically on plan mode entry and exit, handling context gathering and materialization.
2. During planning, follow the guidance text for each required note (read it with items_read schema, fields: ["guidance"]) - this will reference the spec-quality skill where applicable.
3. After plan approval and post-plan materialization, advance the item: advance transition with trigger: "start"

Autonomous mode:

1. Read and follow the pre-plan-workflow skill — gather existing MCP state, check schema requirements, and understand the definition floor.
2. Research the codebase — explore relevant files, understand current state.
3. Fill all queue-phase notes following the guidance text for each (items_read schema, fields: ["guidance"]). The spec-quality framework applies regardless of mode.
4. Read and follow the post-plan-workflow skill — materialize child items if the plan calls for them.
5. Advance the item: advance transition with trigger: "start"

The gate will reject advancement if required notes are missing (gate_blocked, with data.results[0].error.detail.missing[]). If rejected, fill the missing notes and retry.

Plans are spec inputs. Every file path, tool contract, or call sequence a plan names must cite its authoritative location and be verified on disk or in source before the plan is approved — child items' specification notes are generated from the plan and inherit its errors silently (spec-quality, "Cite Contracts, Don't Restate Them"). This reminder lives here because spec-quality is reached via note guidance pointers that plan mode does not traverse.

Plans carry the State matrix. For each item that changes user-visible runtime behaviour, the plan's Verification / Test strategy section carries (or points at) the item's State matrix, or one State matrix: n/a - <reason> line (spec-quality, "State matrix"). Same reason as above: plan mode does not traverse the guidance pointer that would surface it.

Do not confuse this with resource-lease contention. A queue→work advance can also fail resource_unavailable (error.kind: "transient") — a resource a trait on this item declares (resources:) is currently held by another item. This is not a note gate failure: filling notes will not fix it. Work a different item and retry later (error.retryAfterMs is a hint), or report the contended key(s) in error.detail.resources[] to the user.

Seat timing for needs-test-author items. The queue-phase test-plan note is filled by the planning seat — the orchestrator (Direct tier) or the plan author (Delegated/Parallel tier), invoking the test-author skill's scenario-derivation and oracle-derivation sections — and this happens before advance transition with trigger: "start" moves the item queue→work. This is by design: test-plan gates work entry, the same way any other required queue-phase note does. This is a distinct seat from Step 4b's test author seat, which writes test code and fills test-manifest at work phase — see Step 4b's intro for the two-seat distinction.

Planning seat (Parallel tier, one planning-class agent per stream). Under /task-orchestrator:run-wave this becomes the run plan's planner-v1 stage — it mirrors the same eight fields below, dispatched by the run rather than by hand; the field table stays the semantics either way. Dispatch one planning-class agent per stream after child items are materialized (post-plan-workflow) and before Step 4's implementer dispatch — this is the concrete, per-stream instantiation of the planning seat named above. Inputs: the stream's diagnosis/task-scope note and the CURRENT codebase, not the plan text alone. Task: verify every claim in that note against source, citing file:line for each correction; write the note if materialization left it missing, or revise it if verification finds it wrong; fill and freeze test-plan per the seat-timing rule above; then return the structured template below instead of free-form prose. Give the seat the contract by its absolute path (Step 2's Contract path line) — never a relative plans/..., which does not resolve from the worktree — so it reads the Items and Conflict rule slots it is about to extend; its return is what fills the File ownership and Planning seat return template slots for the rest of the wave.

Structured return (eight fields, each required — none is a valid value):

The fields are the budget. The return may exceed any line budget when the fields have content — trimming a field to fit a target length is the failure this stage exists to prevent, not a virtue.

Evidence. This seat produced a material correction on 15/15 items across three bug waves (retros 1b8bba5a, cc69671b, 8e6a7cf7) — every wave that ran it found at least one diagnosis error, cross-stream overlap, or missing seam the plan had missed.

Step 4 — Work Phase: Implementation

Verification commands. Throughout this step, "run tests" means running BOTH the test suite AND the project linter:

./gradlew :current:test
./gradlew :current:ktlintCheck

CI enforces both — a green test run with failing lint will still block the PR. If ktlintCheck fails, run ./gradlew :current:ktlintFormat to auto-fix formatting violations, then verify with ktlintCheck again and re-run tests.

When each check runs, and who runs it. The whole suite is the orchestrator's, once per wave; seats verify at the scope of what they wrote. Every seat prompt (implementer, test author, reviewer, and any post-run fix or second-round seat) points at the dispatch contract's "Who runs gradle" table for this; never paste a suite command into a seat prompt.

The checked-in lock helper (references/gradle-locked.ps1) enforces the seat rows: it refuses :current:test, :current:ktlintCheck and --rerun-tasks unless TO_GRADLE_OWNER=orchestrator is set inline on the call, which only the orchestrator's own invocations do. The lock is a directory carrying owner.json (holder pid, start time, acquire time), taken by renaming a staged copy into place so it is never ownerless. A waiter prints LOCK HELD by pid <p> since <iso> while it waits and reclaims the lock (LOCK RECLAIMED: <reason>) when that pid is dead or reused. With no readable owner.json (absent or unparseable) it reclaims once the directory is older than TO_GRADLE_LOCK_STALE_MINUTES (default 30); an owner.json that cannot be read counts as a live holder, and a live holder is never reclaimed by age. In a mixed-version wave, worktrees on an old base can reclaim or delete each other's locks until every worktree carries this fix. Evidence for the rule: on release/4.0 every seat was running the forced suite (~8,000 tests, 7+ minutes each) so a 1-4 hour item spent an hour or more in Gradle (retrospectives 7e698694, 462a33bb).

Who runs the lint cycle (proposal ee6f5d32, ~9 sessions of evidence):

• Delegated tier (agent owns gradle): the implementation agent runs the ktlintCheck → ktlintFormat → re-verify cycle itself before committing. Validated 2026-07-13 (PRs #213/#214/#215): zero orchestrator fix-up commits.
• Parallel tier: per-seat gradle ownership is stated once, in the dispatch contract's Compile self-check slot ("Who runs gradle"); this bullet only adds the lint-cycle detail that slot's table implies — agents get :current:ktlintFormat as part of their single pinned self-check, and the orchestrator additionally runs ktlintFormat before ktlintCheck after each commit batch (historically 3-5 fix-up commits per multi-phase run when skipped).

Capturing gradle's real exit code (use this pattern, not 2>&1 | tail -N). Piping gradle into tail discards gradle's exit code — tail always exits 0 on a successful read of the log, so BUILD FAILED at the end of the gradle output is reported by you as a successful run. Combined with gradle's daemon incremental cache, this can hide broken compilation through entire CI cycles (retro 568a8584: 9 silently-failing tests shipped on PR #151 before the followup audit caught it).

The reliable pattern, especially when running in run_in_background:

./gradlew :current:test > /tmp/gradle-out.log 2>&1; EXIT=$?
echo "EXIT=$EXIT"
tail -30 /tmp/gradle-out.log

Redirect ordering matters: use > /tmp/log 2>&1, NOT 2>&1 > /tmp/log — the latter is evaluated left-to-right and leaks stderr (where gradle writes compile errors) to the terminal instead of the log (retro ac25db89: a compileTestKotlin failure was invisible in the captured log until the ordering was fixed).

EXIT=$? captures gradle's actual exit code before any pipe consumes it. Read the captured exit code AND the tail of the log; never trust the tail alone. This applies to every orchestrator-owned gradle invocation throughout this step.

Agent-side gradle is not this pattern. In a Parallel-tier wave, agents get exactly one lock-serialized invocation, pinned verbatim — argument form included — in the dispatch contract's Compile self-check slot, together with the rule for what to do when it fails. Do not hand an agent an ad-hoc gradle command line; point it at that slot.

Use --rerun-tasks after dependency upgrades or large refactors. Gradle's incremental compile cache retains class files from prior good builds. After a gradle/libs.versions.toml bump or a refactor that changes public API surfaces (removed methods, renamed types, sealed-class arms, generic-parameter shifts), incremental compilation can keep the OLD class files alongside source that no longer compiles, producing apparent BUILD SUCCESSFUL on stale bytecode. Run ./gradlew :current:test --rerun-tasks once after such changes to force a clean run; ordinary incremental builds are safe afterwards. This is the ONLY use of the flag: it is orchestrator-only, never a routine verification, and a seat that reports a --rerun-tasks run has breached the contract (the lock helper refuses the flag without TO_GRADLE_OWNER=orchestrator). A forced run recompiles everything and reruns the whole suite; on a large suite that is the single most expensive thing a session can do per item.

This step is tier-conditional:

Direct tier: Implement directly. Edit the files, run the test suite. No subagent dispatch. No /simplify pass. Exception — a Direct-tier bug-fix carrying needs-test-author: follow Step 4b's Direct-tier test-first-then-fix sequence (test-plan frozen at queue → regression test observed red → fix → green) instead of implementing first. Fill the session-tracking note (required by both quick-fix and default schemas) as a delta record per its schema guidance: outcome, the Commits: line, the Verified: line, deviations and friction (for quick-fix, one short paragraph on what the fix was and why that way, then those lines). No file list and no test counts. Advance (start): to review, or to terminal when the schema has no review phase (quick-fix); Step 5 reads newRole: advance transition with trigger: "start".

Delegated and Parallel tiers: Use items_read schema (itemId) to see the work-phase notes, with fields: ["guidance"] to read their guidance text. Fill each required note following its guidance. Follow /task-orchestrator:orchestrate (model table, return formats, UUID inclusion). The key decisions at this step are:

• Single item (Delegated): delegate to one implementation subagent or implement directly. Subagent works in the main directory on the working branch.
• Multiple child tasks, independent (Parallel): dispatch parallel subagents into the shared feature worktree created in Step 2. Each agent receives the worktree path and branch name. Do not use isolation: "worktree" on the Agent tool — that would spawn a separate worktree per dispatch, which is the deprecated per-child PR pattern.
• Multiple child tasks, dependent (a semantic dependency; sharing a file alone is not one): dispatch sequentially into the shared feature worktree. Wait for each agent's commit to land before dispatching the next.

Under /task-orchestrator:run-wave, both bullets above are executed by the run plan (Method A via Workflow, Method B via next-scheduling), reading each stage's dispatchBySeat entry for model/agent instead of the table below. The hand-dispatch form in this section and the template it points at remain the fallback for dispatches a run plan doesn't cover — a one-off fix agent, or an arbitration re-dispatch (Step 4b) — not the default path for a Parallel-tier wave.

Test-file ownership boundary. Every implementation dispatch (Delegated single agent or Parallel per-child agent) excludes src/test/** from scope — implementers do not create or modify test files. When a change surfaces a needed test update, the agent reports it in its return (or in implementation-notes) rather than editing the test itself; the test author (Step 4b) owns that file tree exclusively on items carrying needs-test-author.

Parallel dispatch into a shared feature worktree:

Agent(
  prompt="""
  Working directory: <feature-worktree-path>
  Branch (already checked out): feat/<feature-slug>
  Dispatch contract: <ABSOLUTE path from the contract's Header "Contract path" line, e.g.
  D:\Projects\task-orchestrator\plans\<slug>.md> — read it first; it wins on conflict with
  this prompt. It lives in the main checkout, not in the worktree above.
  Scope (modify ONLY these files): <explicit list> — the same list as your row in the
  contract's File ownership slot.
  Do NOT create or modify any file under src/test/** — test authoring is a separate,
  independent dispatch (Step 4b) on items carrying needs-test-author. If your change
  surfaces a needed test update, report it in your return; never edit the test yourself.

  Before returning: run the compile self-check exactly as the contract's "Compile self-check"
  slot pins it, and handle its outcome by that slot's rules. Then commit exactly as the
  "Commit discipline" slot states, including the post-commit verification.
  Do NOT run :current:test or :current:ktlintCheck — the orchestrator owns full build
  verification.
  """,
  model="<dispatch.model, else the implementation class>",  // see "Model selection" below
  effort="<dispatch.effort, else the implementation class>",
  subagent_type="<dispatch.agent when the item's resolved profile names one, else general-purpose>"
  // NOTE: no isolation parameter — agents share the feature worktree
)

Why the prompt points at slots instead of carrying the commands: the self-check is fast (~3s) and catches type-mismatch / signature errors that gradle's incremental cache may otherwise mask in the orchestrator's later test run (retro 568a8584: H3's dbNow() shipped with a Result<T> vs Instant return type mismatch hidden for ~6 hours), and its ktlintFormat step is formatting-only and idempotent, preventing the recurring lint fix-up commits (proposal ee6f5d32). But the invocation's exact argument form, the foreign-file early exit and the retry bound only work if every agent gets them identically — six agents in one wave each burned three lock-serialized runs against another agent's mid-refactor file, and a re-typed nested invocation flattened a [string[]] argument (#302). A prompt that restates the command drifts from the contract; a prompt that points at the slot cannot. The same applies to the commit step: never tell an agent to "commit your changes with a descriptive message" in a shared worktree — the Commit discipline slot is the only safe form (#301).

File-edit overlap discipline: Parallel agents in a shared worktree must operate on non-overlapping files. The orchestrator scopes each agent's prompt to a specific file list (the dispatch contract's File ownership slot carries the rule). When inherent overlap exists, under run-wave declare the file in both scopes (Shared file, lock-serialized: <path> (with <other short>)) and add no BLOCKS edge; a hand-dispatch still dispatches sequentially, without an edge.

Contract-change sweep discipline. When a child task tightens a contract — making a parameter required, adding validate() invariants, narrowing a sealed-class arm, or otherwise rejecting inputs that earlier passed — the orchestrator must sweep the rest of the codebase before advancing to review. Two recurrences (retros a7f6024f and 568a8584) showed that:

• Pre-existing test fixtures constructed under the old contract will fail under the new one. Example: H2's WorkItem.validate() claim-field invariants broke 8+ test fixtures that constructed mixed-state items via separate Instant.now() calls (microsecond drift) or partial claim fields.
• The failure typically surfaces on a different PR's merge commit, not the PR that introduced the contract change — the original PR's tests passed because they used the new contract correctly.

For each contract-tightening change in this run:

1. Identify the affected tool / class / method.
2. Grep all test files (and other call sites) for usages: grep -rn "<tool>\|<class>\|<method>".
3. Verify every usage is consistent with the new contract. Update any that are not.
4. Re-run the full :current:test suite (orchestrator-owned, not the agent) to confirm no fixture-vs-contract conflicts surfaced elsewhere.
5. Fixture repairs are orchestrator-owned and construction-only. When a fixture fails under the tightened contract, the orchestrator may adjust how the fixture is constructed (fix the stale call site) but must never adjust what it asserts. Anything that would touch an expectation instead of a construction call is not a fixture repair — re-dispatch the test author (this preserves the independence the trait exists to protect). Declare these commits in the review handoff: list each orchestrator fixture-repair commit's SHA alongside the impl-range/author-range pair (see Step 4's tracking table and Step 4b's disjointness check) so review-quality can tell a declared fixture repair apart from a silent implementer edit to src/test/**.
6. Doc-claims sweep after behavior-changing fixes: when an orchestrator-owned bug-fix changes shipped behavior after documentation was authored (e.g. a tokenizer or default flips mid-run), grep all changed docs for claims about the OLD behavior before finalizing (retro ac25db89: "case-insensitive" survived in 3 places after the fix made search case-sensitive).

This sweep is part of the orchestrator's verification step between waves, not the implementing agent's responsibility — agents are file-scoped and can't see the full fixture surface.

Model selection - always set model and effort explicitly on every Agent dispatch. Under /task-orchestrator:run-wave, dispatchBySeat already resolves both per seat; for dispatches the run plan doesn't cover, use the work's class from task-orchestrator:model-effort.

Omitting model causes the agent to inherit the orchestrator's model, and omitting effort runs it at the model's default (dispatch-model-guard denies both).

When dispatching an item's phase owner (implementer on work, reviewer on review), read the profile for the phase being dispatched INTO: if the orchestrator already called advance, its dispatch field already reports the profile for newRole; if the agent will enter its own phase (agent-owned-phase protocol — dispatched while the item is still in queue), items_read context returns the queue profile, not work's, so read items_read schema (itemId)'s per-phase dispatch.work map instead. When that profile names an agent, dispatch with subagent_type = dispatch.agent. Regardless of whether agent is set, still pass model explicitly — dispatch.model if set, else the work's class from task-orchestrator:model-effort. Likewise always pass effort on the Agent tool's own effort parameter: dispatch.effort if set, else the class's effort. The agent definitions declare no effort, so an omitted value runs at the model's default and dispatch-model-guard denies the call.

After implementation agents return:

For Parallel-tier features, agents return having committed to feat/<feature-slug> inside the shared feature worktree. Record each agent's commit SHA range alongside the child's MCP item ID — this map feeds the ownership two-range check below and the dispatch contract's Review scoping slot, where reviews are diffed by owned file rather than by SHA range:

| Child UUID | Agent ID | Pre-SHA | Post-SHA | Test-Pre-SHA | Test-Post-SHA | Changed Files |
|------------|----------|---------|----------|--------------|---------------|---------------|
| <uuid>     | <id>     | <sha>   | <sha>    | <sha>        | <sha>         | <file list>   |

Capture pre-commit SHA before dispatch (git -C <feature-worktree> rev-parse HEAD) and post-commit SHA after the agent returns. In a shared worktree this range can interleave other streams' commits and misses later fix-ups, so use it to confirm ownership, not to bound a review:

git -C <feature-worktree> diff <pre-sha>..<post-sha> --name-only

Test-Pre-SHA/Test-Post-SHA are captured the same way around the test author's dispatch (Step 4b) and stay blank until that wave runs.

Disjointness check (required whenever needs-test-author applies). After both ranges are captured, verify:

git -C <feature-worktree> diff <pre-sha>..<post-sha> --name-only          # impl range
git -C <feature-worktree> diff <test-pre-sha>..<test-post-sha> --name-only # author range

• impl-range ∩ src/test/** = ∅ (the implementer touched no test files)
• author-range ∩ src/main/** = ∅ and author-range is non-empty (the author touched only test files, and touched at least one)

A violation is reverted (git -C <feature-worktree> revert the offending commit, or a targeted git checkout of the crossed-boundary file back to the prior SHA) and recorded in implementation-notes — do not silently keep a cross-ownership commit.

Step 4b — Test Authoring

Applies only to items carrying the needs-test-author trait. Runs after implementation agents return (their commits exist on the branch/worktree) and before the orchestrator's build verification below (Direct tier inverts this ordering — see the Direct-tier bullet below) — the test author compiles against the real implemented surface, not a predicted one. Two distinct seats, do not conflate them: the planning seat already froze test-plan at queue phase, before this step, gating work entry (see Step 3's seat-timing rule); the test author seat here writes test CODE and fills test-manifest — it does not fill or re-open test-plan.

Per-tier sequencing:

• Direct tier: temporal-only degraded mode only (see Step 1) — no separate agent, and on a bug-fix the sequence is test-first-then-fix, not "tests after implementation": (a) fill test-plan at queue phase, before any implementation begins; (b) write the regression test from the diagnosis note's reproduction steps and observe it red against the pre-fix code, recording the red evidence (assertion, observed value) in test-manifest; (c) implement the fix; (d) confirm the test is green post-fix and record that confirmation too. test-manifest declares the single seat, and the disjointness check above does not apply (one seat, one range) — see Step 5's verdict rule for how this tier is scored.
• Delegated tier: one additional sequential dispatch on the same branch, after the implementation agent's commit lands. The test author owns its own lint cycle on that branch (ktlintCheck → ktlintFormat → re-verify, same rule as Step 4's "Who runs the lint cycle") and runs ONLY its own test classes (scoped --tests) to see them red and then green before committing — never :current:test; the orchestrator runs the suite once before review.
• Parallel tier: one test-author agent per child, dispatched as a dedicated wave between the implementation wave and the orchestrator's build verification (below). Authors in this tier do NOT run :current:test or :current:ktlintCheck — only ktlintFormat plus a compile self-check, mirroring the implementation dispatch template, since the orchestrator owns full build verification for the wave.

Blindness rule. The test author may read: the item's test-plan note, public signatures, domain models, existing test conventions/docs, and the implementer's changed-file names (not content). The test author must NOT read: the implementation diff content, the implementer's own tests, implementation-notes, or session-tracking. This is what makes the separation real rather than nominal — tests probe the spec, not the implementation's behavior.

Oracle-provenance obligation. Every scenario's expected result must trace to a source declared in test-plan (spec clause, stated algorithm, external reference) — never "what the code returns" and never the ticket's own worked example.

Manifest duty. Before returning, the test author fills test-manifest (work, required): the authoring seat, test file paths, commit SHA range, S-id→test coverage mapping (covered / not-covered:reason), probes executed with results, forbidden-pattern declaration (every assumeTrue/escape with justification, or none), and any implementer-modification-to-test-files rationale (should be none if ownership held).

Skill routing. Invoke the test-author skill before filling test-manifest — it carries the scenario-derivation, oracle-derivation, blindness, and forbidden-pattern framework this step depends on. (The planning seat also invokes it earlier, at queue phase, for the scenario-derivation sections that inform test-plan — see Step 3.)

Arbitration — Red Author-Authored Tests

When a test the author wrote comes back red against the implementation, the test author does not decide who is at fault (test-author §8/§9) — it reports. The orchestrator arbitrates, with exactly three dispositions:

1. Implementation wrong. Re-dispatch the implementer, scoped to src/main/** only.
2. Test wrong. REQUIRES a spec citation before this disposition is available: the note key plus the quoted acceptance criterion plus the asserted-vs-observed values. "The implementation does X" is not evidence for this case — it is evidence for case 1. If no covering criterion exists to cite, this disposition is not available; fall through to case 3. Before ruling case 2, confirm the failing test's INPUT fixture matches the declared input contract (the declarations file or the producing stage's schema, e.g. planner-v1): a fixture-shape mismatch is a fixture fix on the test side that keeps the oracle, not a case-2 oracle change. A case-2 fix keeps the S-id's oracle assertion; name the oracle in the re-dispatch prompt. Once cited, re-dispatch the test author, scoped to src/test/** only.
3. Spec wrong or silent. Escalate to the user. Amend task-scope/diagnosis first, then dispatch whichever side the amendment implicates.

Record every arbitration, and every other orchestrator ruling in a fix cycle — case number, the citation (for case 2), and the resolving commit SHA — as a new ## Amendment A<n> section in the child's orchestrator-decisions note (role queue, orchestrator-owned; implementation-notes is implementer-seat-owned and the orchestrator never writes it). The note is append-only: read its current body (notes_read get) and upsert the old body plus the new section. Never drop or rewrite an earlier section; mark a reversed one REVERSED by A<m> in place. Never weaken, skip, or @Disable a test to unblock a wave, regardless of disposition; that is exactly the failure mode this trait exists to prevent (test-author §7, §9).

This carve-out also modifies the build-verification rule below: a red author-authored test is not a broken build. Route it to arbitration above; if unresolved, hold the child in work and report — do not dispatch a generic "fix agent" against it.

Test-author dispatch prompt: point the agent at the Test author protocol slot of the wave's dispatch contract, named by the absolute Contract path from its Header (Step 2) and instantiated from references/dispatch-contract-template.md — it states the declarations block, the src/main tool ban, the keys= filter, stop-and-ask, fixture invariants, surface labels, commit form and manifest fields in full; on a Delegated-tier run with no contract file, paste that slot into the prompt instead of paraphrasing it. The declarations block is filled by a separate, non-author declarations-extractor seat, and the orchestrator scans and strips it of implementation prose before the author sees it — the slot states the seat's accuracy contract and the scan (proposal 234b50a0). Under /task-orchestrator:run-wave, the extractor and the test author are both run-plan stages, and the scan step is named scan-declarations in Method B or the run script's own scanDeclarations call in Method A — same accuracy contract and strip rule either way.

Capture the test author's pre/post commit SHAs the same way as implementation agents (Test-Pre-SHA / Test-Post-SHA in the tracking table above), then run the disjointness check.

Step 4c — Build Verification and Wrap-Up

Build verification (orchestrator-owned, serialized). After each parallel-batch completes (or between sequential children), run from the feature worktree:

git -C <feature-worktree> status                            # confirm clean tree
./gradlew -p <feature-worktree> :current:test
./gradlew -p <feature-worktree> :current:ktlintCheck

This is the wave's ONE full-suite run: incremental (no --rerun-tasks unless a dependency or Gradle upgrade landed in the wave), after the last writer seat has committed, before any PR opens. Do not re-run it per seat return, and do not let a seat run it for you.

A failure means a recently-committed child broke something. Dispatch a fix agent (same shared worktree) before continuing. Do not advance any child to review until the build is green — the trend memory has multiple sessions of flaky-test-hides-real-bug showing why retry-until-green is wrong.

Carve-out: a red author-authored test is not a build failure. On items carrying needs-test-author, a test failure traced to a test the test author wrote (Step 4b) is not "the build broke" — do not dispatch a generic fix agent against it. Route it to the Arbitration subsection in Step 4b instead. If arbitration doesn't resolve before this verification pass needs to conclude, hold the child in work phase and report the unresolved red test rather than forcing green through a fix-agent dispatch.

Why orchestrator owns gradle invocations: ./gradlew runs against a single Gradle daemon and a single build/ cache per project directory. Parallel gradlew test invocations against the shared feature worktree will queue at the daemon, corrupt the build cache, or hit Windows file locks. Serializing build verification at the orchestrator prevents this without slowing the agents (they're not running gradle).

For Delegated tier (single subagent), the agent commits to the working branch on the main directory. Capture the changed files via git diff main --name-only and proceed.

Post-implementation steps (run in the feature worktree for Parallel tier, or on the working branch for Direct/Delegated):

1. Run the /simplify skill on the changed code to check for reuse, quality, and efficiency — this is a cleanup pass before review, not a review itself
2. If /simplify made changes, the resulting test coverage work follows the ownership boundary above. On items carrying needs-test-author, re-dispatch the test author to write or update the covering tests (Step 4b) — the implementer/orchestrator does not touch src/test/** even for a simplify-driven update. On items without the trait, write or update tests inline as before. Either way, the simplify pass is still part of the work phase — all code changes require test coverage before advancing to review.
3. Log findings as work items — any issues surfaced by /simplify or during implementation that are not immediately addressed (pre-existing tech debt, optimization opportunities, related bugs) must be logged via /task-orchestrator:create-item before moving on. Do not discard findings.
4. CHANGELOG bullet (proposal c068c943) — written here, in the work phase, so the reviewer sees it. A user-visible change — server behaviour, the MCP or REST surface, config keys, plugin skills or hooks — adds ONE bullet under CHANGELOG.md's ## [Unreleased] section, in its ### Added / ### Changed / ### Fixed subsection (plugin skill and hook changes go under ### Plugin). The bullet describes behaviour, not the diff, and carries no volatile counts. A docs-, process- or chore-only change adds none; its PR body will state Changelog: none (<why>). Direct/Delegated: committed with the change. Parallel: the orchestrator or docs seat writes it once, after the implementation wave and before review — never an implementer (the dispatch contract's Docs slot). /prepare-release Step 8c folds these bullets into the release section.
5. Fill all work-phase notes following their guidance text (items_read schema, fields: ["guidance"]) - focus on context that downstream agents need to know
6. Live-owed check (proposal 8ecc28f1) - before the work-exit advance, read the item's session-tracking note for its **Live-owed**: line (spec-quality, "State matrix"). Any entry not ending run <date>: <result> or deferred: <item id> is open and holds the item in work until it is run or deferred. The orchestrator writes that line from the spec note's matrix when it first fills session-tracking; a matrix with live-owed cells and no **Live-owed**: line counts as an open entry. This check sits at work exit because feature-task items skip review by default (Step 5).
7. After implementation completes:
   • Subagent delegation: The agent returns after filling work-phase notes. The orchestrator then calls advance transition with trigger: "start" to advance the item to the next phase.
   • Direct implementation: The orchestrator calls advance transition with trigger: "start" itself after filling work-phase notes. In both cases, inspect newRole in the response to determine what comes next (see Step 5).

Step 5 — Review Phase

Before dispatching or performing review, check the item's current role. Inspect newRole from the advance result (data.results[0]) in the previous step:

• If newRole is terminal: The item's schema has no review phase (lightweight lifecycle). Review dispatch is not needed — the item completed through its natural lifecycle. Proceed to Step 6. Note: feature-task items skip review by default (work→terminal directly) — the needs-task-review trait re-enables a review phase for a specific child when needed.
• If newRole is review: Continue with review per tier below.

This step is tier-conditional:

Direct tier: Perform an inline review. Read the diff, verify correctness, confirm tests pass. If the review-phase note has a skillPointer (visible in the advance result or via items_read context), invoke that skill for the evaluation framework before filling the review note. Write the review note, then advance to terminal: advance transition with trigger: "start". No separate review agent — the overhead exceeds the risk for 1-2 file changes with known fixes. This inline, orchestrator-written review note applies only to items outside any run: Direct tier never runs under a run, and on a run member a seat-owned review key belongs to the reviewer seat.

Delegated and Parallel tiers: Dispatch a separate review agent. The agent that implemented the code must not review its own work.

Reviewer scoping for Parallel waves. Per-child reviewers remain the default for code-bearing waves. When every child in the wave is content-only (config, skill, or doc edits — no src/main or src/test changes) AND the wave shares a pinned plan-file contract (Step 2), dispatch ONE consolidated opus reviewer over the full feature-branch diff (git diff main...<FEATURE_BRANCH>) instead of N per-child reviewers. Cross-file coherence defects — sibling skills stating contradictory rules, gate placement contradicting seat timing, an example contradicting its own rule — are visible only to a reviewer holding the whole diff; per-child reviewers structurally cannot see them, and a shared naming contract does not prevent them, since naming consistency and semantic coherence are orthogonal. Evidence: 5 blocking cross-file contradictions caught this way at 5-item scale (retro 6d562acb) and canonical-config consistency issues at 7-item scale (retro bd4ec109) — trend 028c7b5d. The consolidated reviewer fills the review-phase review-checklist note of each reviewed CHILD (one note per child, all under the same reviewer actor). When the children's schema has no review phase (the feature-task default), this Step 5 consolidated pass is skipped and the feature review in Step 6 item 3 (run-wave post-run.md Step 7b) is the only review. It never fills the parent feature's review-checklist: the parent is reviewed once, in Step 6 item 3 (run-wave post-run.md Step 7b), after every child is terminal.

If the implementation used the shared feature worktree (Parallel tier), the review agent operates in that worktree, scoped to that child's owned files — the diff of those paths from the wave's base SHA to current HEAD, per the contract's Review scoping slot. Not the <pre-sha>..<post-sha> range captured during dispatch: in a shared worktree that range interleaves other streams' commits and excludes any later fix-up, formatter or fixture-repair commit to the same files, so it both over- and under-reports. The pre/post map still serves the ownership two-range check (list item 6 below).

Review agent template (copy verbatim, fill placeholders):

You are reviewing one child task within a shared feature worktree.

- Feature worktree: <FEATURE_WORKTREE_PATH>
- Feature branch: <FEATURE_BRANCH>
- Dispatch contract: <ABSOLUTE path from its Header "Contract path" line, e.g.
  D:\Projects\task-orchestrator\plans\<slug>.md> — read it first; it wins on conflict
  with this prompt. It lives in the main checkout, not in the worktree above.
- This child's owned files (its row in the contract's File ownership slot):
  <FILE LIST>
- Your review scope is the diff of exactly those files:
  git -C <FEATURE_WORKTREE_PATH> diff <BASE_SHA>..HEAD -- <FILE LIST>
- Other children committed into this same branch, and later fix-up, formatter or
  fixture-repair commits may touch these files. Review the owned-file diff above as it
  stands now; do NOT review another child's files, and do NOT bound your review by a
  commit range.

Run ALL commands from within the feature worktree.
Read ALL files from that directory. Do NOT read from the main working directory.

Tests have already been verified green by the orchestrator after the most recent
commit batch. Run no gradle — the contract's Compile self-check slot states who runs
it, and the Review scoping slot records the build state you rely on. Focus on plan
alignment, test quality, and simplification per the review-quality skill.

Report every finding at every severity — do not self-filter to a high-severity-only
bar. Mark each finding blocking or observation and state your confidence; the
orchestrator's verdict handling is the downstream filter, not your own judgment.

If using Direct or Delegated tier (single working branch on the main directory), the review agent reads from the working branch and runs no gradle itself (see item 4 below) - no worktree-specific scoping needed.

The review agent:

1. Reads the review-quality skill
2. Uses items_read context and notes_read list (itemId) to load the item's notes and review-phase requirements
3. Reads the changed files — on Parallel tier, the owned-file diff above; on Direct/Delegated tier, the working branch
4. Runs no gradle on any tier. In a Parallel wave the orchestrator already verified the wave and recorded the build state in the Review scoping slot. On Direct tier the orchestrator reviews inline after its own run. On Delegated tier the orchestrator runs :current:test and :current:ktlintCheck (Step 4's "Verification commands" - a PR with failing lint will not merge) and records the Verified: line (command, result, SHA) in its own session-tracking before dispatching the reviewer, which reads the build state from there per review-quality Area 1.
5. Evaluates plan alignment, test quality, and simplification
6. On items carrying needs-test-author, additionally:
   • Two-range ownership check: confirm the impl-range/author-range disjointness recorded during Step 4b actually holds by spot-checking git diff <impl-range> --name-only touches no src/test/** path and git diff <test-range> --name-only touches no src/main/** path. N/A-by-declaration on Direct-tier temporal-only items (Step 1, Step 4b): there is one seat and one range by design, so there is no second range to diff — record it as N/A: temporal-only, single seat rather than attempting the diff, and it cannot fail.
   • Temporal checks (Direct-tier temporal-only items only): confirm test-plan was filled and frozen at queue phase, before implementation began (Step 3's seat-timing rule), and — for a bug-fix — confirm the red-first evidence (the regression test observed failing against pre-fix code, per Step 4b/B3) is recorded in test-manifest.
   • Arbitration-record check: if any red author-test required arbitration (implementation wrong / test wrong / spec wrong), confirm the outcome is recorded in implementation-notes with the required detail (spec citation for a "test wrong" call: note key + quoted criterion + asserted-vs-observed).
   • assumeTrue/@Disabled scan on author-owned files: grep the test author's changed files for assumeTrue, @Disabled, or other weakening introduced after the author's first commit in this range. Any such introduction is an automatic blocking finding — independence does not permit softening a red test to unblock a wave. Verdict rule: test-independence-audit fails to not-independent (blocking) if any applicable check above fails, regardless of how green the test suite is — the ownership two-range check is not applicable, and cannot fail, on a Direct-tier temporal-only item. On a Direct-tier temporal-only item where every applicable check (temporal checks, arbitration-record, assumeTrue/@Disabled scan) passes, the verdict is independent-degraded (temporal-only) — never plain independent, matching test-author §11.
7. Fills the review-phase notes per their guidance text (items_read schema, fields: ["guidance"]) with a verdict

Handling the verdict:

Once the user rules a fix on a run-wave item whose run closed at handoff, the fix cycle follows the numbered recipe in run-wave post-run.md Step 5 "Fallback", which also finalizes the item's session-tracking.

Dispositions at child close. When a child's review returns Pass or Pass with observations, write the child's orchestrator-confirmation before advancing it: one line per O# as fixed <sha>, follow-up <item-id> (the item created first) or accepted: <reason>, N of N disposed. Nothing is left for the parent review to carry. fixed is bounded by run-wave post-run.md Step 5 "Observation triage": only a concrete failure in behaviour the item added or changed, one implementer-a<n> (or test-author-a<n>) seat scoped to the finding ids, no planner amendment, no re-review unless the fix changes behaviour beyond the finding; the Fail recipe is for blocking findings only.

Review failures surface issues that may indicate systemic problems worth learning from. Automatically retrying hides these signals.

Step 6 — Finalize and PR

The shape of Step 6 depends on tier.

Direct and Delegated tiers — finalize per item

After review passes:

0. Post-dispatch commit audit (non-blocking): run git log --oneline -3 and git status --short and compare against what the orchestrator itself committed. Any commit a subagent made despite stop-boundary instructions is flagged for review here — inspect its scope before it rides into the squash-merge (a subagent commit lacks the co-author trailer; reconcile at merge time). On items carrying needs-test-author, additionally check each commit's file list for cross-ownership: an implementer commit touching src/test/**, or a test-author commit touching src/main/**, is flagged here even if it slipped past the Step 4b disjointness check — do not let it ride into the squash-merge unreconciled.

1. Verify the working branch is committed (orchestrator commits if Direct tier; subagent committed if Delegated). Stage only the files related to the implementation:

   git add <specific-files>
   git commit -m "$(cat <<'EOF'
   <type>(<scope>): <description>
   
   <body — what changed and why, referencing the MCP item>
   
   Co-Authored-By: Claude <noreply@anthropic.com>
   EOF
   )"

   Commit types: feat for features, fix for bugs, refactor for tech debt, perf for performance, test for test-only changes, chore for maintenance.

2. CHANGELOG check and Docs line. Confirm the branch carries the [Unreleased] bullet written in Step 4c (post-implementation step 4), or that the PR body will state Changelog: none (<why>). Both PR-body lines come from the diff, never from the plan: run git diff --name-only <base>...HEAD and (a) list every changed doc path from that output on the body's Docs line; (b) require CHANGELOG.md in that output unless the body states Changelog: none (<why>). Recompute both lines after any merge round (a base merge or update-branch), before merge.
3. Push the working branch:

   git push -u origin <branch-name>

4. Create the PR:

   gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
   ## Summary
   <2-4 bullets>
   
   ## Test Results
   <test count, pass/fail, new tests>
   
   ## Review
   <verdict summary>
   
   ## Docs
   <every changed doc path from `git diff --name-only <base>...HEAD`>
   
   ## Changelog
   <the [Unreleased] bullet text, or none (<why>)>
   
   ## MCP
   <item ID>
   EOF
   )"

5. Merge gate (Parallel tier step 7 uses this same gate):
   • Wait on gh pr checks <n> --watch --fail-fast and squash-merge only when every check is green. Never merge with a check pending. If auto-merge is armed, GitHub enforces "all green" only for REQUIRED checks, so this gate still applies to the rest.
   • Review-first arming. Arm auto-merge (gh pr merge <n> --squash --auto), or merge, only after the item's review verdict is recorded with 0 blocking, and only once every observation the orchestrator chose to act on is committed on the branch. A PR opened before review (for early CI) is opened without auto-merge. If auto-merge is already armed when a review starts, disarm it first (gh pr merge <n> --disable-auto).
   • Guard landing. When a merged PR adds or tightens a guard or contract test (architecture/Konsist, a consistency test, a token or size budget), run gh api -X PUT repos/<owner>/<repo>/pulls/<n>/update-branch on every open PR against the same base, and let its CI re-run green before arming.
   • On a red check, read the failed job. An infra flake gets one gh run rerun <run-id> --failed, recorded in the item's notes; a test failure is fixed on the branch.
   • Fallback merge: if gh pr view <n> --json mergeStateStatus,autoMergeRequest shows CLEAN with no autoMergeRequest, or an armed auto-merge has not merged within 10 minutes of the last green check, run gh pr merge <n> --squash. Never directly merge a PR that is not CLEAN or has pending checks.
   • Confirm gh pr view <n> --json state reports MERGED before any worktree or branch cleanup. Then:

   git checkout main
   git pull origin main
   git branch -D <branch-name>

6. Advance the item to terminal only if it is not already terminal (review-less items reached terminal in Step 4/5; a Direct-tier item with a review reached it in Step 5); otherwise skip:

   {"tool":"advance","op":"transition","args":{"itemId":"4b7d0e19","trigger":"start"}}

   An item that has children follows the same rule before this advance, with the item in the feature's place and its parent as the holder's parent:

   Post-merge live acceptance. Once the PR has merged and the only non-terminal children are live checks that need a refreshed plugin cache or a user opt-in: (a) create one plugin-change item titled Post-merge live acceptance: <feature title> under the feature's parent, its specification filled at creation; (b) deps_write create a relates_to edge from it to the feature; (c) re-parent each such check under it (items_write update parentId); (d) add one line Post-merge live acceptance: <holder short id> (<check short ids>) to the feature's session-tracking when that note was created token-less (written token-less), else to orchestrator-confirmation (run-wave references/post-run.md Step 7b (d)); (e) complete the feature. The holder's specification opens with this fixed next-session preamble: (1) purge the plugin cache and update the marketplace, per claude-plugins/CLAUDE.md "Plugin Discovery and Cache Refresh"; (2) after the next session starts, grep the cached files for one string the change added (name the string); (3) the user's opt-in for any check that runs the Workflow tool. Then one line per re-parented check. The next session runs the checks, fills the holder's session-tracking and completes it. Create the holder and re-parent the checks before (e): a terminal auto parent takes no new children.

7. The retrospective hook fires on a successful runs_write close (or the Stop backstop for a closed run without the retro mark), never on a terminal transition; its mode key is extensions.claude-code.retrospective.mode. Work finished outside a run gets no hook: run /session-retrospective by hand.
8. Wave-boundary red-proofs (for a single Direct/Delegated item, the "wave" is the item). Only the bug-fix revert ran before merge. The item's decision-point budget mutations (the planner's red-proof-shape, test-author rule section 5) run NOW, after the merge, off the critical path: one scratch worktree at the merged main SHA (git worktree add --detach <unique-tmp> origin/main), each mutation applied with references/patch-anchored.py (DRY=1 first) and run only against the test classes the item's test-manifest maps to that scenario (--tests), one full suite only for a survivor (to classify it as covered at another seam). Record proofs run, gaps, equivalents and minutes in the item's red-proof-results note (orchestrator-owned). A real gap becomes a test-only follow-up item via /task-orchestrator:create-item (exempt from further proofs by policy), never a reopen. Skip categories per the rule. Run it in the background when other work is waiting; it never gates the merge or the terminal transition.

Report the PR URL and a summary.

Parallel tier — finalize ONCE at parent-feature completion

For Parallel-tier features with a shared feature worktree:

For each child task (after its review passes, if it has one):

1. For children whose schema/trait declares a review phase (e.g. needs-task-review), confirm review-checklist is filled. Children without one advance work→terminal directly — there is nothing to confirm.
2. Advance the child to terminal only if it is not already terminal (Step 4c item 7 already advanced each child out of work; a review-less child is terminal by now, so skip it). A child sitting in review takes one advance transition with trigger: "start" (itemId the child's id) to reach terminal, and only after its review passes.
3. Do NOT push. Do NOT create a PR. The work is committed to feat/<feature-slug> inside the shared worktree; that's the integration point.

When all children reach terminal, the parent feature is ready to finalize (a child that is only a live check needing a refreshed plugin cache or a user opt-in counts as done here; it is split off after the merge, step 8):

1. Fill the parent's implementation-notes (cross-child content only, per the feature-implementation schema guidance: decisions between children, post-review merges, routed findings, deferred scope, or the one-line empty form) and session-tracking (the run record, per the session-tracked guidance; the children's notes are not re-listed) - under the coordinator token while the parent is a member of an open run; final content written once, in confirmed past tense; the only re-edits are the ones run-wave references/post-run.md Step 3 sanctions, and the step 8 post-merge live acceptance line is written as that file's Step 7b (d) says).
2. Run final verification from the feature worktree (incremental; this and Step 4c's run are the only whole-suite runs in the wave):

   ./gradlew -p <feature-worktree-path> :current:test
   ./gradlew -p <feature-worktree-path> :current:ktlintCheck

3. Advance the parent to review. The orchestrator never authors the parent's review-checklist, whatever the child count. With 2+ children, run the feature review of run-wave post-run.md Step 7b: one independent task-orchestrator:reviewer (explicit model) over git -C <feature-worktree-path> diff <base>...HEAD, handed each child's verdict and disposition count lines (a child with no review phase is listed as such). The reviewer writes only feature-level findings, never re-lists a child's disposed observation, and fills the parent's review-checklist. The orchestrator records one line per finding in the parent's orchestrator-confirmation (fixed <sha|PR> | follow-up <item-id> | accepted: <reason>, ending N of N disposed). With exactly one child, Step 7b does not apply (it covers 2+ children only), but the rule is the same: the parent review is still done by an independent task-orchestrator:reviewer (explicit model) over the feature range, never by the orchestrator, handed the child's verdict and disposition count lines (or listed as review-less), and the dispositions go in the parent's orchestrator-confirmation. See Step 5's consolidated-reviewer paragraph, which never fills the parent note.
4. CHANGELOG check and Docs line - as the Direct/Delegated tier's step 2: the bullet the orchestrator or docs seat wrote before review (Step 4c), or Changelog: none (<why>) in the PR body; the Docs line and the CHANGELOG.md requirement are built from git diff --name-only <base>...HEAD, never from the plan, and recomputed after any merge round.
5. Push the feature branch:

   git -C <feature-worktree-path> push -u origin feat/<feature-slug>

6. Create one PR for the whole feature:

   gh pr create --base main --title "feat(<scope>): <feature description>" --body "$(cat <<'EOF'
   ## Summary
   <feature-level summary aggregating all children>
   
   ## Children completed
   - <child-1 title> (<MCP UUID>)
   - <child-2 title> (<MCP UUID>)
   ...
   
   ## Test Results
   <total test count, new tests added across feature>
   
   ## Review
   <feature reviewer verdict; N of N dispositions>
   
   ## Docs
   <every changed doc path from `git diff --name-only <base>...HEAD`>
   
   ## Changelog
   <the [Unreleased] bullet text, or none (<why>)>
   
   ## MCP
   Parent: <parent UUID>
   Children: <list of child UUIDs>
   EOF
   )"

7. Merge gate - run the Direct/Delegated tier's step 5 gate (green checks, fallback merge, state MERGED confirmed) first. Only after the PR is MERGED:

   git checkout main
   git pull origin main
   git worktree remove <feature-worktree-path>
   git branch -D feat/<feature-slug>

8. Post-merge live acceptance. Once the PR has merged and the only non-terminal children are live checks that need a refreshed plugin cache or a user opt-in: (a) create one plugin-change item titled Post-merge live acceptance: <feature title> under the feature's parent, its specification filled at creation; (b) deps_write create a relates_to edge from it to the feature; (c) re-parent each such check under it (items_write update parentId); (d) add one line Post-merge live acceptance: <holder short id> (<check short ids>) to the feature's session-tracking when that note was created token-less (written token-less), else to orchestrator-confirmation (run-wave references/post-run.md Step 7b (d)); (e) complete the feature. The holder's specification opens with this fixed next-session preamble: (1) purge the plugin cache and update the marketplace, per claude-plugins/CLAUDE.md "Plugin Discovery and Cache Refresh"; (2) after the next session starts, grep the cached files for one string the change added (name the string); (3) the user's opt-in for any check that runs the Workflow tool. Then one line per re-parented check. The next session runs the checks, fills the holder's session-tracking and completes it. Create the holder and re-parent the checks before (e): a terminal auto parent takes no new children.
9. Advance the parent feature to terminal (only after N of N disposed); when step 8 applies this is its (e), run once after (a)-(d).
10. Wave-boundary red-proofs. Now that the feature PR has merged, run every child's decision-point budget mutations in ONE batch (run-wave post-run.md Step 7a): a scratch worktree at the merged main SHA, each mutation applied with references/patch-anchored.py and run only against the test classes that child's test-manifest maps to it, one incremental whole-suite run per survivor, results recorded once on the parent's red-proof-results note. A real gap becomes a carry-in on the next item touching that seam or one test-only follow-up item, never a reopen. Background; it gates nothing.
11. Retrospective - the plugin's retrospective hook fires on a successful runs_write close (or the Stop backstop for a closed run without the retro mark), never on a terminal transition. In dispatch mode (extensions.claude-code.retrospective.mode in .taskorchestrator/config.yaml) it directs a background /session-retrospective automatically - follow its directive; in nudge mode, or for work finished outside a run (no hook), run /session-retrospective by hand.

Why one PR at parent finalization, not per child

• Coherent review context. The PR diff shows the whole feature, not N disjoint pieces.
• One CI cycle per feature instead of N. Local verification (orchestrator-owned gradle runs between commits) gives equivalent regression signal during development.
• No cross-PR contamination. Contract changes can't surface on a sibling's merge commit because there are no sibling PRs.
• No PR-body staleness. The PR body is authored once, after the feature is done, describing what actually shipped.
• Aggregate retrospective material. Distributed session-tracking notes across children plus the parent's run record give clean retro input (validated by retro a7f6024f); the parent's implementation-notes stays cross-child only.

Local main always tracks origin/main — no divergence, no reset --hard needed.

Autonomous Batch Processing

When processing a Parallel-tier feature with multiple child tasks autonomously: run /task-orchestrator:run-wave over the parent, one run per topological layer — steps 1-2 below describe what that run does under the hood; they are the fallback for a manual walk-through when a run plan doesn't apply.

1. Step 2 — One worktree, one branch. Orchestrator creates the feature worktree and feature branch (feat/<slug>) at planning time. All children share it.
2. Step 4 — Dispatch into shared worktree. Agents dispatched without isolation: "worktree". Independent children dispatch in parallel waves; dependent children dispatch sequentially. Orchestrator scopes each agent's file list to prevent overlap.
3. Step 4b — Test-author wave. For children carrying needs-test-author, dispatch one test-author agent per child as its own wave, after that child's implementation wave and before build verification. Authors run ktlintFormat + compile self-check only (never :current:test/:current:ktlintCheck — the orchestrator owns those next). Capture Test-Pre-SHA/Test-Post-SHA per child and run the disjointness check before proceeding.
4. Build verification — orchestrator-owned, serialized, once per wave. After the wave's last writer seat (implementation or test-author) commits, the orchestrator runs :current:test and :current:ktlintCheck once from the feature worktree, incrementally (--rerun-tasks only after a dependency or Gradle upgrade). Fix failures before advancing any child to review. No seat runs the suite; the checked-in lock helper refuses it.
5. Step 5 — Review per child, scoped to that child's owned files, when the child has a review phase. feature-task children skip review by default (work→terminal directly) unless the needs-task-review trait is set, or needs-test-author is set (its test-independence-audit note adds a review phase). When a review phase applies, the review agent reads from the shared worktree and diffs that child's owned files from the wave's base SHA to HEAD (git -C <feature-worktree> diff <base-sha>..HEAD -- <files>), per the contract's Review scoping slot — never a commit range, which in a shared worktree picks up other streams and misses later fix-ups. The pre/post and test-pre/post SHAs feed the ownership two-range check only.
6. Step 6 — One PR at parent finalization. Children advance to terminal without pushing or PR'ing. Only when the parent feature itself reaches terminal does the orchestrator push feat/<slug> and open the single feature-level PR. After that PR merges, the wave-boundary red-proofs run (Step 6 item 10): every child's budget mutations batched at the merged SHA, scoped to manifest-mapped test classes, in the background.
7. Track child commits — maintain a table mapping child UUID → pre-commit SHA → post-commit SHA → Test-Pre-SHA → Test-Post-SHA → status (implementing / test-authoring / reviewing / done / failed). Worktree path is shared across all children.
8. Report at the end — summarize children completed, review failures, and the single PR URL.

If any child hits a review failure, continue processing siblings (their commits are already in the feature branch). Report all failures together at the end. The orchestrator decides whether the failed child blocks parent finalization (e.g. fix-and-re-review), can be cancelled (descope from the feature), or warrants reverting its commits.

Bug-fix batches (multiple unrelated fixes) — these are NOT a Parallel-tier feature. Use Delegated tier per item, each with its own branch and PR (the legacy per-item flow). The shared-worktree pattern applies only when items share a parent feature item.

Worktree Strategy

For full setup, dispatch patterns, lifecycle, parallel validation, and test baseline management, see WORKTREE.md.

Quick reference:

Do NOT use isolation: "worktree" on the Agent tool for Parallel-tier child dispatches. That spawns a separate worktree per dispatch — the deprecated per-child PR pattern. For Parallel tier, the orchestrator pre-creates one shared worktree in Step 2 and dispatches each child agent into it.

When NOT to create any worktree:

• Direct/Delegated tier (single item — work on the main directory)
• Pure MCP operations with no file modifications
• Orchestrator implementing directly

Resuming In-Progress Work

Tier classification happens at Step 1 even when resuming. Classify the tier from the item's tags, file scope, and note state, then resume using that tier's pipeline.

If an item is already past the queue phase (e.g., previously planned but not implemented), the skill picks up from the current state:

Always call items_read context (itemId) first to determine exact state before resuming.