Skip to content
Skills Library
Programming · Automation

executing-plans

/executing-plans

Use when executing an implementation plan in the current session — every task goes to a role agent, is reviewed at its tier, and lands as one commit on a stacked branch and draft PR per plan phase

Repository
triqual ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
19
Scripts
4
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

Scripts: scripts/lib/footer.mjs, scripts/lib/plan.mjs, scripts/lib/task-common.mjs, scripts/stack.mjs

What it does and when to use it

Use when executing an implementation plan in the current session — every task goes to a role agent, is reviewed at its tier, and lands as one commit on a stacked branch and draft PR per plan phase

Original author description

Use when executing an implementation plan in the current session — every task goes to a role agent, is reviewed at its tier, and lands as one commit on a stacked branch and draft PR per plan phase

How it works

  1. The Process
  2. Setup
  3. Role Dispatch
  4. Tiers
  5. The Thin Controller
  6. The Task Loop
  7. Denied by Policy
  8. Records
  9. Final Review
  10. Worktrees
Original SKILL.md headings · 559 lines, 19,346 words
SKILL.md preview
---
name: executing-plans
description: Use when executing an implementation plan in the current session — every task goes to a role agent, is reviewed at its tier, and lands as one commit on a stacked branch and draft PR per plan phase
---

# Executing Plans

You are the controller of a plan's execution. Every plan task is done by a role agent (`roles:tdd-implementer` or `roles:complex-implementer`), except `coordinator` tasks, which you run yourself (see Coordinator tasks). You never run a plan inline: never run a plan inline as its implementer, whatever the plan's size, and a harness that cannot dispatch a named task role agent stops and asks its human partner (a missing `roles:phase-orchestrator` is the Fallback of The Thin Controller: announced, never a stop). Each task's review is sized by its **tier** (`heavy`, `standard`, `light`): declared by the plan, raised (never lowered) by `scripts/tier-check` from the task's real diff. Execution is stacked: each plan phase is one git branch on top of the previous phase's (and, in GitHub mode, one draft PR), and each task is exactly one commit on its phase branch, driven by `scripts/stack.mjs`. The main session does not run the task loop: it dispatches one `roles:phase-orchestrator` per phase, which runs it, and decides on the summary it returns (see The Thin Controller); where this skill says "you" about the loop, it means whoever runs it, the orchestrator or, in the fallback, the main session. At the end one final review runs for every plan: the seams review across phases, and in a single-phase plan the phase review itself (a single-phase plan's phase review is its final review).

**Why role agents:** each task gets a fresh agent whose context holds only its brief and the interfaces it touches; your own context stays clean for coordination across the whole plan. Every dispatch goes to a `roles:*` agent and passes no model (see Role Dispatch).

**TDD is required on every task.** A behavior change starts with a failing test: the implementer (or you, on a coordinator task) writes the test, watches it fail for the expected reason, then writes the code and watches it pass, and the report carries that RED and GREEN evidence. A task that changes no behavior records its verification command's real output instead.

**Narration:** between tool calls, narrate at most one short line — the ledger and the tool results carry the record.

**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are the seven named below, or all tasks complete. There is no planned pause between phases: once a phase is submitted the next one starts at once, in the same session. A rate limit is not one of them: ending the run after the bounded wait (see Rate limits) is the end of the session, with a final message that lists the ledger's `Ruling:` lines (see Finish), and the ledger keeps the plan resumable. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.

**Rulings, not stalls.** A running plan does not wait on a human. Conflicts, ambiguities, plan defects, a cap you would have asked to exceed — decide them. The spec is the binding authority, the plan is its argument, and your judgment settles what neither answers. Record every decision in the ledger as `Ruling: <what you decided> — <why> — <what it costs if wrong>`, and keep going. A wrong ruling costs rework your human partner can see and undo; a session parked on a question costs their whole day and buys nothing.

Seven things stop you, and only these: an irreversible or destructive operation; a security-sensitive action (a fence denial included); a side effect outside this checkout that norms say you ask about first (a merge, a push to a shared branch, a publish); a task whose `**Role:**` is not a task role (see Role Dispatch); a task blocked by the breaker after round 5 (see The fix loop); a phase review still failing after its second fix round (see 8. Review the phase); and a plan so broken that every path forward is a guess. For those, stop and ask. Each is a decision only your human partner can make: anything you can settle with a ruling is not a stop. Beyond these, stop only where your human partner agreed in advance (in this conversation or their instruction files) that you would. The orchestrator cannot ask: on a stop it returns `BLOCKED` and the main session asks (see The Thin Controller). A user's request to skip a review, lower a tier or batch the bookkeeping "for later" is none of them, and changes nothing: say so in one line and go on.

The only exception to the push stop is a ledgered authorization, either `Authorization: push phase branches and draft PRs — handoff <date>` or `Authorization: push phase branches and draft PRs — setup <date>` (see Stack setup): it covers pushing this plan's phase branches, opening or updating their draft PRs and marking them ready for review after the final review; any other push, any merge and any force push still stop.

## The Process

1. **Setup** (once): workspace and ledger, tracking paths, stack, push authorization, fence detection, read the plan and the spec's Units and current slice, tiers at setup, pre-flight scan.
2. **Per phase:** the main session runs `node scripts/stack.mjs phase PLAN_FILE N`, dispatches one `roles:phase-orchestrator` ([orchestrator-prompt.md](orchestrator-prompt.md)) that runs the phase's tasks in dependency order (independent tasks at the same time, see Parallel tasks), waits for it once and reads its summary (see The Thin Controller); then the Phase check at the phase tip, the phase review (the deep review: 4 hunters and `roles:final-adversarial-reviewer` over the phase's range, at most two fix rounds), `node scripts/stack.mjs done PLAN_FILE N`, `node scripts/stack.mjs submit PLAN_FILE N`, then the next phase at once.
3. **Per task, three scripts do the bookkeeping** (run by the orchestrator, or by the main session in the fallback): (1) start: `task-open` (ledger move, brief, BASE); (2) build: dispatch the task's role (or run a coordinator task); (3) `task-prep` (ledger move, `tier-check`, the review package); (4) review at the effective tier, on that one review package, saving each reviewer's final message; (5) the fix loop when the review requires it, `task-prep --fix-round` before every re-review; (6) complete: `task-close` (squash, `triqual tasks done`, the complete line, the `task-review` record built from the saved reviewer outputs, the review progress entry).
4. **End:** the seams review of `trunk..top` (`roles:final-adversarial-reviewer` alone, no hunters; in a single-phase plan the phase review is the final review and no second review runs), at most two fix rounds with a scoped re-review each, the `final-escapes` record (multi-phase plans only; a single-phase plan's `P1` record stands), `node scripts/stack.mjs submit PLAN_FILE <top N> --open`, then methodology:finishing-branch.

## Setup

No worktree by default: run the plan in the current checkout. The stack's phase branches are the isolation, so a worktree adds nothing; create one only when your human partner explicitly asks (see Worktrees); the one exception is the task worktrees of Parallel tasks, which the plan's own parallel rule creates under `.claude/worktrees/` without any request. Executing a plan, or being told to work autonomously, is not that request. Implementation never starts on the trunk: `node scripts/stack.mjs phase PLAN_FILE N` moves HEAD onto the phase branch.

Conversation memory does not survive compaction. Controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed. Track progress in the workspace ledger, not only in todos.

### Workspace and ledger

- Each plan owns a workspace: at skill start, run `node scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored directory (under `<repo-root>/.methodology/sdd/`, kept out of `git status` by `.methodology/.gitignore`), home to every artifact for THIS plan: ledger, briefs, reports, review packages, record files. Another plan's directory is never yours to read or write.
- The ledger is `<workspace>/sdd-ledger.md`. If its first line names your plan file, tasks with a `Task <N>: complete` line are DONE — do not re-dispatch them (unless a Phase check reopened it, a `Task <N>: reopened —` line after its complete line, see 7. End the phase); resume at the first task without one. A task whose last line is a fix round is mid-loop: resume the loop at the next round. A task whose last ledger line is its `Task <N>: blocked` line is the fifth stop again: it is never re-dispatched, and you ask your human partner for the decision the breaker waits on (see The fix loop). For a phase, the same: a phase whose tasks are all done and that has no `Phase review: P<n>` line gets its review run (again) before anything else (see 8. Review the phase), unless it already has a `Phase <N>: submitted` or `Phase <N>: complete` line (a plan begun before the phase review: a submitted phase is final, see 7. End the phase), and a `Phase review: P<n> blocked` line is the sixth stop again: `blocked` resumes only on the human's word. A ledger whose first line names a different plan file is another plan's progress: leave it in place and start your own, fresh.
- A plan whose run began before the rename kept its ledger in the old workspace. When `sdd-ledger.md` is missing and that old ledger exists under this exact plan, `sdd-workspace` copies it once to `sdd-ledger.md`, marks the old directory `adopted` and leaves it in place; resume from the copy. A workspace left by a 0.7.x execution resumes the same way, and its tasks get their tiers at setup (see Tiers at setup).
- Create the ledger with its identity as the first line: `# SDD ledger — plan: <plan file path>`.
- After compaction, trust the ledger and `git log` over your own recollection, and read `node scripts/stack.mjs status PLAN_FILE` alongside the ledger: it prints the stack state (each phase's branch and state, the mode, the PR numbers), so a phase already submitted is never started again.
- After compaction, when opted in, read each task's state before your next ledger move (`triqual tasks export --json`, per-task `status`, `tier` and `effectiveTier`; `triqual tasks status --json` lists only `inProgress` and `next` for each plan), and skip any move the ledger already shows: a `start` or `rework` on a task already `in_progress`, a `review` on one already `in_review`, a `done` on one already `done`, a `block` on a task already `blocked` (which stays a stop until the human decides), and, opted in, a `retier` to the tier it already has. A resumed session never fails on a move it already made: `task-open`, `task-prep` and `task-close` are idempotent and skip a move the ledger already shows, so rerunning the script of an interrupted step is the repair.
- `git clean -fdx` destroys the workspace (it is git-ignored scratch); if that happens, recover from `git log` and the task ledger.

### Tracking paths

Run `triqual tasks paths --json` once, before the first dispatch:

- **Opted in** (`"optedIn": true`; an older `triqual` prints the same fields without `optedIn`): the plan's task ledger moves with every task (the `triqual tasks` moves named in The Task Loop, each with `--plan <plan>`: `<plan>` is the plan file in `plansDir`, in store mode its bare file name, so a move never lands on another active plan's ledger), and every implementer and fixer dispatch carries the implementer template's Tracking section, filled with the mode, the `progress` and `status` paths and the plan's `*.tasks.json` in `plansDir`. Then run `triqual tasks check` once (it takes no plan option): a drift it reports is a ruling to make before Task 1.
- **Not opted in** (`"optedIn": false`, or exit 2 from an older progress-tracking): no ledger moves (run no `triqual tasks` command) and no `progress.md` rules: drop the Tracking section from every dispatch, and never create `progress.md`: creating it opts the repo in and commits a personal log into a shared repo. Tiers then live in the workspace ledger only (see Tiers at setup).
- **`triqual` missing** (exit 3, or `triqual` not on `PATH`): for your own commands, handle it as not opted in, and say so once. The scripts are different: `task-open`, `task-prep` and `task-close` need `triqual` whether or not the repo is opted in (they read `triqual tasks paths`, and `task-close` makes the review record with `triqual role-eval record`), and skipping an opted-in repo's ledger moves would go unnoticed, so with no `triqual` on the `PATH` the first script exits 1 with an `Error:` line that says so: a stop, not "not opted in". Install it (`/methodology:setup`), put `~/.local/bin` on the `PATH`, and run the script again.

Opted in with `"mode": "local"`, the tracking files live under the git dir, which Claude Code protects from agent file writes: your own entries (reviews, rulings, the plan's close) and `status` edits are drafts in the OS temp dir, each under a unique name from `mktemp` (run `mktemp`; the path it prints is the draft), landed with `triqual tracking write entry <draft>` and `triqual tracking write status <draft>`, and the Tracking section tells implementers and fixers the same. Never write or edit under `.git/` with the file tools.

Opted in with `"mode": "store"` (details: `store-mode.md` under `references` in skill `progress-tracking:progress-tracking`), the tracking lives in the store: `triqual tasks paths --json` has no `progress` or `status` path and there is no `*.tasks.json`, so no tracking file is written, staged or committed (an added or modified `progress.md`, `status.md` or `*.tasks.json` is a defect; the switch's deletions are expected). `<plan>` in every `--plan` is the bare plan file name (for example `2026-10-11-feature.md`), never the `plansDir` path; PLAN_FILE, which the scripts read, stays the plan's path. Fill the implementer template's Tracking section with `"store"` as the mode and drop the three paths. Your own entries are drafts in a private `mktemp -d` dir (run `mktemp -d`; the directory it prints holds your drafts). A task review runs after the implementer's commit already exists, and a ruling, a status-only step or the plan's close ends with no commit of its own, so each of these lands with `triqual tracking add <draft> --no-commit` (or `--commit <reviewed sha>` to record a review against the commit it reviewed), because a pending entry left behind would be stamped onto the next, unrelated commit and would let that commit past the pre-commit gate; only an entry for a commit you are about to make yourself lands with plain `triqual tracking add <draft>` before the commit it describes. Read `status` with `triqual tracking status` and change one section with `triqual tracking status set --section <heading> <draft>`; read history with `triqual tracking log`.

The workspace ledger (`sdd-ledger.md`) is kept either way: it is this skill's recovery map, not a tracking file.

### Stack setup

`scripts/stack.mjs` (run with `node`, from this skill's directory) owns the branches and the state file: `init`, `mode`, `path`, `status`, `phase`, `squash`, `done`, `submit` and `push`, each taking PLAN_FILE. Its exit codes: 0 ok, 2 usage or malformed plan, 3 a refused precondition (the message names it), 5 `gh` failed.

- **A run that began before stacked execution is not stacked.** First run `node scripts/stack.mjs path PLAN_FILE`. When the file it prints does not exist and the workspace ledger already holds a `Task <N>: complete` line, the run began before stacked execution: its completed tasks sit on an old feature branch, and phase 1 would start from the trunk and strand them. Skip `init`, `phase`, `squash`, `done`, `submit` and `push` for the whole run, ledger `Ruling: run began before stacked execution — no stack`, and finish on the current branch: methodology:finishing-branch's menu with no state file applies. As a second guard, `node scripts/stack.mjs phase PLAN_FILE 1` itself exits 3, naming HEAD's branch, when HEAD is on a branch other than the trunk that holds commits the trunk lacks.
- After the workspace and the tracking paths, run `node scripts/stack.mjs init PLAN_FILE` once, before Task 1. It prints the stack state as JSON and writes it to `<repo root>/.methodology/stack/<plan file stem>.json`. It picks the mode: `github` (phase branches pushed, one draft PR each) when `gh`, `gh stack` and a GitHub remote are all available, else `local`. `init` is safe to re-run: when the state file exists it prints it and changes nothing, which is how a resumed run finds its stack.
- **Committed tracking mode stops the run.** `init` exits 3 with `committed tracking mode cannot hold one commit per task: switch with triqual progress-init --store (or --local)`. Stop before Task 1 and tell your human partner to switch with `triqual progress-init --store` (or `--local`). Any other exit 3, and exit 2, names its cause: rule on it, ledger the `Ruling:`, and fix it or stop if every path forward is a guess.
- **Push authorization.** Pushing this plan's phase branches, opening their draft PRs and marking them ready for review after the final review is allowed only with a ledger line `Authorization: push phase branches and draft PRs — handoff <date>`, which you write yourself at setup, before Task 1, when your human partner chose (or confirmed) the execution at the writing-plans handoff in this conversation, or `Authorization: push phase branches and draft PRs — setup <date>`, which you write on a yes below. When the ledger lacks any `Authorization:` line and this conversation holds no such choice (a new session on an existing plan), ask once, before Task 1. A yes: write the `setup <date>` line. A no: run `node scripts/stack.mjs mode PLAN_FILE local` and ledger `Authorization: declined — stack in local mode`; the run goes on with local branches only. Any `Authorization:` line, the declined one included, means the question was answered and is never asked again.

### Fence

Fence is a policy harness that denies calls under protected paths. It is optional: detect it once at setup. Fence is detected when `command -v fence` finds it and `fence version` exits 0 (two plain commands, one after the other). Write one ledger line, `Fence: <version>` (the first line `fence version` prints) or `Fence: none`; a resumed run reads the last such line instead of detecting again. Without fence nothing here applies and the Task Skills section is used as written. [Denied by Policy](#denied-by-policy) applies to every run, whatever that line says, because the line can be stale.

With fence detected, installing a skill is the human's step, never the implementer's: an install writes many files under fence-protected paths, outside this checkout. The pinned `headjack add` printout runs only when fence is detected, once per task whose brief has a `**Skills:**` line, before its first dispatch (a fix round does not print it again). A coordinator task follows it too.

1. Run `triqual suggest "<the task's title and goal>"` (text mode) and print the pinned install commands in its block for the slugs of the `**Skills:**` line. When it prints nothing or exits non-zero, print one command per slug yourself: `HEADJACK_MODE=<mode> headjack add <slug> --to claude --session --source plan`, with `<mode>` taken from the `mode` of the `--json` document (it is on the document, never on a suggestion) of `triqual suggest "<the task's title and goal>" --json`: `hosted` prints `HEADJACK_MODE=remote`, `local` prints `HEADJACK_MODE=local`, and any other value prints no prefix; and a slug only when it matches headjack's slug rule `^[A-Za-z0-9][A-Za-z0-9._@:-]{0,127}$`: skip any other slug and say so.
2. When `HEADJACK_URL` is not set and the vault is hosted, tell your human partner to set it before running the commands.
3. Then ask the human to run them and to answer when they have, ledger `Skills: T<N> printed for the human — <slugs>`, and dispatch the task only after that answer. A human who declines gets the task dispatched anyway, with `Ruling: T<N> skills not installed — human declined — <what it costs if wrong>` in the ledger; the implementer then reports a missing skill instead of installing it.
4. Dispatch with the Task Skills section in its fence form (see [implementer-prompt.md](implementer-prompt.md)) and a line in the dispatch saying fence is active: the implementer neither adds nor removes a skill.

### Read the plan

Read the plan once, note its context, Global Constraints, Review Focus and `**Sensitive paths:**`, and create a todo per task. The scripts read it with `scripts/lib/plan.mjs`, the same reader as `triqual tasks`, so every reader agrees on task boundaries and fields. If the plan names a Spec, read less of it. At setup and at each resume, read the plan, the spec's `## Units` and the current phase's `## Delivery Slices` entry, not the whole spec (a spec without those headings is read whole). Before writing a `Ruling:`, read the spec sections the ruling depends on: the spec stays binding, and conflicts inside the plan resolve against it. The phase and seams reviewers get the whole spec. A plan with no reachable spec gets a ledger note saying so — rulings made without one are provisional.

Check the roles once: a task role the `roles` plugin does not define, or a reviewer role named as a task's role, is a stop (see Role Dispatch). Hunters, and a safety gate that cannot be dispatched at all, follow the skip rule at their first dispatch (see When the stage does not run).

### Tiers at setup

Every task has an effective tier before its first dispatch. Write one ledger line per task, `Tier: T<N> <tier>`, with its effective tier.

- **A tiered plan** (every task declares `**Tier:**`): the effective tier is the declared tier, or the higher `effectiveTier` that `triqual tasks export --json` already holds for a resumed run.
- **A tierless task** (a plan written before 1.0, or a resumed 0.7.x execution): a missing tier reads as `standard`. Give each pending tierless task its effective tier by the tier rubric, raising only: a task the rubric makes heavy is raised, when opted in, with `triqual tasks retier T<N> <tier> --plan <plan> --reason "<text>"` (reason `setup rubric: <criterion>`), and every other task stays standard; a tierless `roles:complex-implementer` task becomes heavy. Ledger each raise as `Tier raised: T<N> standard → heavy — setup rubric: <criterion>`.
- **The tier rubric** (the one writing-plans applies): **heavy** — any of: security-relevant code (auth, permissions, secrets, sandboxing, policy engines, parsing untrusted input, gate/enforcement hooks), live state or migrations (stores, schemas, installed setup), a contract other code parses (hook I/O, file formats, the plan format, machine-read CLI output), `roles:complex-implementer`; the task's reason is on the line under `**Tier:**`. **light** — only docs, comments, config values, version bumps, renames with no behavior change, and small code fixes within the light code allowance. **standard** — everything else. A tierless task never reads as light: the rubric only raises.
- **Not opted in:** there is no `retier`: the ledger's last `Tier:` or `Tier raised:` line for a task is its effective tier, and the floor you pass to `tier-check`.

A tier is never lowered: not by you, not by a reviewer, not on your human partner's word. `retier` refuses a lowering (exit 2), and a raise stays for the rest of the task, its fix rounds and any reopen.

### Pre-flight scan

Before dispatching Task 1, scan the plan once for conflicts, writing down what you checked as you check it:

- tasks that contradict each other or the plan's Global Constraints
- anything the plan explicitly mandates that the review rubric treats as a defect (a test that asserts nothing, verbatim duplication of a logic block)
- a declared tier the rubric contradicts (a light task that changes behavior beyond the light code allowance, a heavy trigger in a standard task): raise it now with a `Tier raised:` line (and `retier`, when opted in), never lower one

The scan's output is a table, not a verdict, and it lists only task pairs that share a file or an interface, not one row per task. One row for every pair of tasks that share a file or an interface: the two tasks, what one produces against what the other consumes, and what you found. A task whose own text contradicts itself (the tests it specifies against the code it specifies, the files it creates against the files it later touches) gets a row of its own, and only then. A plan with no such pair gets one ledger line saying so. "The scan is clean" without those rows or that line is not a scan you ran. Write the table to the ledger, rule on each conflict beside its row, and dispatch Task 1. The review loop remains the net for conflicts that only emerge from implementation.

## Role Dispatch

Every dispatch goes to a `roles:*` agent (plugin `roles`), and no dispatch passes a model: each role's definition pins its model and effort, and a model in the dispatch would override that pin. Choose the role; never choose a model.

- **Default:** `node scripts/task-brief PLAN_FILE N` copies the task's `**Role:**` line into its brief; a task with no `**Role:**` line is `roles:tdd-implementer`.
- **`roles:tdd-implementer`, `roles:complex-implementer` or `roles:review-fixer`** (the last only in plans written before 1.0): dispatch [implementer-prompt.md](implementer-prompt.md), with its header's `<task role>` filled with that role. A plan marks a task `roles:complex-implementer` (Opus) for multi-system changes, migrations of live state, or work where a mistake is costly; such a task is heavy.
- **`roles:phase-orchestrator`:** dispatched by the main session once per phase with [orchestrator-prompt.md](orchestrator-prompt.md) (see The Thin Controller), never a task's role: a task whose `**Role:**` names it is not a task role, and stops the run like any other (the fourth stop).
- **`coordinator`:** you run the task yourself (see Coordinator tasks).
- **Any other role**, a reviewer role included (`roles:spec-reviewer`, `roles:safety-reviewer`, `roles:hunter`, `roles:final-adversarial-reviewer`, `roles:brief-writer`) or a misspelled one: stop and ask your human partner. Never dispatch it, and never substitute another role for it.
- **Reviews:** by the task's effective tier (see Tiers), never the task's own role: `roles:hunter` ([hunter-prompt.md](hunter-prompt.md)), `roles:safety-reviewer` ([safety-review-prompt.md](safety-review-prompt.md)), `roles:spec-reviewer` ([task-reviewer-prompt.md](task-reviewer-prompt.md)).
- **Re-reviews:** the role or roles that raised the findings ([re-review-prompt.md](re-review-prompt.md)).
- **Fix rounds:** `roles:review-fixer`; a `roles:complex-implementer` task keeps its own role.
- **Seams review:** `roles:final-adversarial-reviewer`, once per multi-phase plan ([final-review-prompt.md](final-review-prompt.md), its Seams Scope).
- **Briefs:** `node scripts/task-brief PLAN_FILE N` extracts each brief mechanically, at no cost. Dispatch `roles:brief-writer` only when a task's plan text lacks interfaces that must come from the current code.

**Turn count beats token price.** Wall-clock and context cost scale with how many turns a subagent takes. The role pins the model; what you control is the dispatch: a brief that carries the exact values, the interfaces the task touches, and nothing else.

### Coordinator tasks

A `coordinator` task is run by the controller, never dispatched to a role: the main session runs one that edits a file (the phase orchestrator hands it over, see The Thin Controller), and the phase orchestrator runs one that edits no file itself (its role disallows `Edit` and `NotebookEdit`, and it never edits product code). A coordinator task works in the main checkout and starts like a batch task: only once every earlier task of the phase is done or dropped and nothing else runs there, whichever of the two runs it (`task-open` refuses it with exit 3 otherwise), because its BASE is `HEAD` and its close squashes `BASE..HEAD`, which would absorb an earlier task's unreviewed commits. It is light: a no-code step (a rollout step, a status update) or a small, low-risk change or fix within the light code allowance (see Tiers). In a tiered plan registration already refused a coordinator task that is not light; in a tierless plan a coordinator task stays at its setup tier (standard at least), because no tier is lowered. It keeps the discipline of a dispatched task: the same ledger moves, TDD when it changes behavior, the implementer template's Tracking and Task Skills sections followed by you, the same report file the reviewers read, its own commit, `tier-check` and the review its tier calls for. When `tier-check` raises it, its review runs at the raised tier with the controller as author, and any fix round goes to `roles:review-fixer`, never to the controller. Its `task-review` record carries `"coordinator": true`.

## Tiers

The effective tier sets the review. Spec U4, verbatim:

| Effective tier | Round 1 (together) | Round 2 | Fix-round re-review |
|---|---|---|---|
| heavy | 2 hunters: `correctness` + `security` or `state`, picked from the task's heavy reason line + safety gate | `roles:spec-reviewer` on every candidate and spec fit | scoped re-review by the raising role(s), always |
| standard | safety gate + `roles:spec-reviewer`, in parallel; no hunters | none: the spec review ran with the gate | scoped re-review, except a fix that applies an approved `Ruling:` verbatim and touches no security logic |
| light | safety gate | none, unless the gate reports a finding or `Cannot verify` (then `roles:spec-reviewer` runs on that item) | the gate re-checks |

- **Hunters belong to the heavy tier only:** a heavy task sends exactly two, a standard or light task none. The second hunter is picked from the task's heavy reason line (the plain line under its `**Tier:**`, see the tier rubric): `security` when the reason line names security code, `state` when it names live state or a parsed contract. A task raised to heavy, or declared heavy with no reason line (a plan written before 1.0.2), has no reason line (and a `roles:complex-implementer` task keeps its reason under `**Role:**`): take the category from the raise reason or that line, `security` by default. Sending more than the tier's count needs one ledger line, `Budget: hunters <tier count> → <used> for T<N> — <reason tied to the diff>`; never send fewer than the tier's count. `task-close` reads the task's last `Budget:` line of the attempt: more hunters than the tier's count are recorded from the categories whose `task-<N>-candidates-<category>.md` files exist, and fewer (an owner's override, ledgered the same way) are recorded as sent, the others not as `failed`.
- **The safety gate runs at every tier.** Never skip the task review (the one exception is a task with no commit range: see When the stage does not run): every task with commits gets at least the safety gate, whatever its tier and whoever asks.
- **`tier-check`** (`node scripts/tier-check PLAN_FILE N BASE HEAD --floor <tier>`) prints `ok <tier>` or `raise <from> <to>: <reason>: <paths>` and exits 0; exit 2 is bad input (unknown task, bad range, bad floor), an error to fix, never a reason to skip the check. Its rules, applied in order and never lowering: **→ heavy** when the diff touches a sensitive path (default `**/hooks/**`, `**/setup/**`, `**/*schema*`, `**/migrations/**`, `**/drizzle/**`, `.github/**`, `plugins/workflow-gate/**`, plus the plan's `**Sensitive paths:**`) or changes more than 300 lines (added + removed); **light → standard** when the diff touches anything outside the light classes (Markdown outside `**/skills/**`, `**/agents/**`, `**/rules/**`, `**/commands/**`, `**/templates/**`, `**/*-prompt.md`, `**/CLAUDE*.md`, `**/AGENTS*.md`; JSON whose only changed key is `version`; lockfiles are never light), beyond the **light code allowance**: other files stay light while, together, they add or remove at most 20 lines (test lines count), create no file (a new test file is a raise; cases added to an existing test file are not), and touch no excluded Markdown class or sensitive path.
- **The floor** is the task's current effective tier: its `effectiveTier` in `triqual tasks export --json`, else its declared tier; not opted in, the ledger's last `Tier:` or `Tier raised:` line for it.
- A raise is recorded with `triqual tasks retier T<N> <to> --plan <plan> --reason "<reason from tier-check>"` (opted in) and the ledger line `Tier raised: T<N> <from> → <to> — <reason>`, before any reviewer of the new tier is dispatched.

## The Thin Controller

The main session dispatches one `roles:phase-orchestrator` per phase, waits for it once and only decides; the orchestrator runs the phase's task loop (The Task Loop, below) with the same three scripts, tiers and stops. There is one set of rules: the orchestrator follows this skill, and no second implementation of the loop exists. The orchestrator is never a task's role, and it is the only role that dispatches others.

**The main session, per phase:**

1. Run `node scripts/stack.mjs phase PLAN_FILE N`.
2. Dispatch one orchestrator with [orchestrator-prompt.md](orchestrator-prompt.md): the plan path, the phase number, the ledger path, the plan's Global Constraints and a resume note (a fresh phase says so). Pass no model.
3. Wait for it once, blocking, by the waiting rule of The Task Loop; the orchestrator's completion arrives as its final message.
4. Read its summary and act on it: write `Orchestrator: P<n> — <summary first line>` to the ledger, then route on it. `Phase: P<n> done` goes on to the Phase check, the phase review, `done` and `submit` (steps 7 and 8), then the next phase. Three `BLOCKED:` kinds are not stops and each has its own route, which never asks your human partner and writes no ruling: `BLOCKED: nested dispatch unavailable` goes to Fallback, `BLOCKED: rate limit — <role> T<N>` goes to Rate limits (the run ends) and `BLOCKED: coordinator task T<N> — …` goes to Coordinator tasks. Any other `BLOCKED:` line, a stop or a script error the steps cannot resolve, goes to On `BLOCKED` (the `Error:` line of a failed script is in the ledger); the `Orchestrator:` line and the ruling it gets leave a rerun of the failed script a resume (see step 6, `task-close`).

The main session never reads code, diffs or reports: it reads the summary, the ledger and what a script prints, and in the phase review (step 8) only the reviewers' verdicts. The fallback is the exception: the main session then runs the loop itself and reads what the loop reads. Work that needs them goes to a role: the fix work of a Phase check failure's reopen and a phase-review fix go to an orchestrator or a fixer it dispatches (the resume note names the failing command and its last lines, never a diff); the main session itself runs only the reopen move and writes its ledger line (see 7. End the phase).

**The summary.** At most 20 lines, in this order: `Phase: P<n> <done|blocked>`, `Tasks: T<N> <sha>, ...`, `BLOCKED: <stop> — <details>` (only when blocked), then the lists `Rulings I made:`, `Open minors:` and `Errors and fallbacks:`, each with its lines under the heading and `none` when empty. A summary that would pass 20 lines keeps `Phase:`, `Tasks:` and `BLOCKED:` and shortens each list to its first lines plus `+<k> more in the ledger`. Rulings and errors are also in the ledger, so Finish collects them from there.

**A stop.** On any of the seven stops, and on any script error its steps cannot resolve, the orchestrator starts nothing new, lets running agents finish their current step, writes `Task <N>: awaiting landing` for any task that finished but is not landed, and returns `BLOCKED: <stop> — <details>` as the BLOCKED line of its summary (`Phase: P<n> blocked` first).

**On `BLOCKED`.** The main session asks your human partner for the decision the stop names, with the orchestrator's details beside it, and nothing else moves first. It then writes the decision to the ledger as `Task <N>: Ruling: <finding> — <decision> — <why> — <what it costs if wrong>` (for more rounds after the breaker, `Ruling: human granted <K> rounds for T<N> — <why> — <what it costs if wrong>`), makes the ledger move the decision implies (`triqual tasks start T<N> --plan <plan>` for a blocked task, opted in), and only then dispatches a new orchestrator for the same phase, with a resume note that names the ruling. The new orchestrator resumes from the ledger: a task with a `Task <N>: complete` line is never dispatched again unless the resume note reopens it (a Phase check failure's reopen, which the main session ledgers as `Task <N>: reopened — Phase check failed — <command>`), a `Task <N>: awaiting landing` task is closed first with `task-close` (a rerun of `task-close` after them is a resume: the `Orchestrator:` and `Task <N>: Ruling:` lines are not new work on the task), and for a breaker stop it carries out the rest of The breaker's Park or More rounds path. A final message that begins with `BLOCKED` instead of `Phase:` is a denial (a stop and the three kinds above arrive as the BLOCKED line of a summary that begins with `Phase:`): [Denied by Policy](#denied-by-policy) applies, the main session relays the denied call, its path and the refusal text verbatim, and dispatches nothing until your human partner answers.

**Fallback.** If the orchestrator cannot be dispatched (the `roles` plugin is too old and the role is missing), the main session sees the failed dispatch itself; if the orchestrator cannot dispatch (Codex depth 1, a harness refusal) it returns a blocked summary whose BLOCKED line is `BLOCKED: nested dispatch unavailable` with the error. Either way the main session writes `Error: orchestrator P<n> — exit 1 — <first line of the error>` to the ledger, says in one line to your human partner that it runs the phase itself, and runs the phase loop itself with the same scripts, dispatching the task roles as The Task Loop says. Announced, never silent; it is no stop and needs no ruling, and the next phase dispatches an orchestrator again.

**A cap denial.** A workflow-gate cap denial of a dispatch names the seconds to wait: wait the seconds the denial names and retry the same dispatch. It is neither a stop nor a fallback, and it holds at both levels, for the main session's dispatch of an orchestrator and for the orchestrator's dispatches of its roles.

**Coordinator tasks.** The orchestrator never edits product code: its role disallows `Edit` and `NotebookEdit`, and every change to the repository is a role agent's commit. A coordinator task works in the main checkout and starts like a batch task: only once every earlier task of the phase is done or dropped and nothing else runs there (`task-open` refuses it otherwise), so until then it waits like any task that is not independent, and the orchestrator lets running agents finish their current step first. Once it may start, a coordinator task that needs no file edit (a rollout step, a status update) the orchestrator runs itself; one that edits a file it hands over, ending the phase with the BLOCKED line `BLOCKED: coordinator task T<N> — edits files, run it in the main session`, which is a handoff and not one of the seven stops: the main session asks no one and writes no ruling, runs the task itself (see Coordinator tasks), then dispatches a new orchestrator for the rest of the phase.

## The Task Loop

**Who runs this loop.** The phase orchestrator, one phase at a time; the main session only in the fallback (see The Thin Controller).

**One task, one dispatch, one commit.** Each task is its own dispatch (or its own resume, see Batched light dispatch) and its own commit; you never compose a batch brief or send several tasks to one subagent at once. The plan sizes the tasks, and the commit is the unit the review and the squash read.

Everything you paste into a dispatch prompt — and everything a subagent prints back — stays resident in your context for the rest of the session. Hand artifacts over as files.

**Waiting on dispatched subagents:** never poll a wait interface with short timeouts, and never sit in one silent, open-ended wait either. While you have local work — ledger updates, packaging the next review, reading reports — keep working; child results arrive on their own. When you are genuinely idle, wait in bounded stretches (five to ten minutes, where your platform allows), and between stretches post one line of status and reconcile your live children: list them, and chase any that finished without reporting. Both levels follow it, the main session waiting for its orchestrator and the orchestrator waiting for its roles. In Claude the main session simply receives the orchestrator's completion; in Codex it waits with `wait_agent` in bounded stretches, the longest timeout Codex allows.

**Rate limits.** A dispatch to any role (an implementer, a fixer or a reviewer, on any model) that is rate-limited mid-plan is not a stop: wait in the bounded stretches above and retry the same dispatch, writing one `RateLimit: <role> <time>` ledger line per stretch, with `<time>` the local time as `HH:MM`. After about 6 stretches without success, end the run with a final message naming the task and listing the ledger's `Ruling:` lines (see Finish); the ledger makes the plan resumable. When the orchestrator meets it, it follows the same stretches and, after about 6, returns `BLOCKED: rate limit — <role> T<N>`; the main session then ends the run as this rule says. It never swaps the model in a dispatch: the dispatch keeps the same role and passes no model. A hunter with no Haiku quota is not this case: it is the skip rule (see When the stage does not run). The safety gate runs on Sonnet and follows this rule.

### Start the phase

Before the first task of phase N, the main session runs `node scripts/stack.mjs phase PLAN_FILE N`. It prints the phase branch and leaves HEAD on it: it creates the branch on top of phase N−1's (the trunk's, for phase 1). It needs a clean tree and phase N−1 submitted (in local mode, done) and exits 3 otherwise. Every task of the phase then commits on that branch. A resumed run starts the phase the stack state (`status`) shows active or pending, never one already submitted.

### 1. Start the task

Run `node scripts/task-open PLAN_FILE N` from the main checkout. One call does the three things this step used to: when opted in and the task is `pending`, the `start` move (a task the ledger already shows started is not moved again, and a `blocked` task is refused with exit 3: only your human partner's decision restarts it, by the `start` move the main session makes, see On `BLOCKED`); the brief, written like `node scripts/task-brief PLAN_FILE N` writes it (the task's full text, its `**Tier:**`, `**Role:**` and `**Skills:**` lines included, in a uniquely named file; never make a subagent read the whole plan file); and BASE, the `BASE: T<N> <sha>` ledger line (the last one counts), recorded from `HEAD` when the ledger has none. A task the tracking ledger already shows started (`in_progress`, `in_review` or `done`) with no `BASE:` line, such as a 1.1.0 ledger resumed mid-task, is refused with exit 3, because `HEAD` is no longer where the task began: append `BASE: T<N> <sha>` yourself, the sha being the commit before the task's first commit, and run it again. BASE is never `HEAD~1`, which silently drops all but the last commit of a multi-commit task. It prints, in this order:

- `brief:` the brief path, which goes into the dispatch;
- `report:` the implementer's report file, named after the brief (brief `…/task-N-brief.md` → report `…/task-N-report.md`); the file is not created;
- `base:` the task's BASE: the review package, `tier-check` and the squash all read `BASE..HEAD`, where HEAD is the task's head (`--head <sha>` for a worktree task, which lands in place of the squash).

A task that runs in a worktree (see Parallel tasks) is opened with `node scripts/task-open PLAN_FILE N --worktree`, which also prints `workdir:` after `base:`.

It is idempotent, so a crash between the move and the dispatch is repaired by running it again. It exits 0 ok, 2 usage, 3 a refused precondition (a linked worktree, an unknown task, a blocked task, a coordinator task while an earlier task of its phase is not done or dropped, a move the ledger refuses) and 1 any other failure, and before a non-zero exit it appends `Error: task-open T<N> — exit <code> — <first stderr line>` to the ledger, except a bad argument list and a refusal from a linked worktree (`run from the main checkout`), which come before the workspace is known and write none. An `Error:` is never worked around: read its cause and fix that.

### 2. Build

Dispatch the task's role with [implementer-prompt.md](implementer-prompt.md). Your dispatch contains: (1) one line on where this task fits; (2) the brief path, introduced as "read this first — it is your requirements, with the exact values to use verbatim"; (3) interfaces and decisions from earlier tasks that the brief cannot know; (4) your resolution of any ambiguity you noticed in the brief; (5) the report-file path and report contract; (6) the template's Denied by Policy section, when opted in the Tracking section, and when the brief has a `**Skills:**` line, the Task Skills section in its fence form when fence is detected (after the printout in Fence). Exact values appear only in the brief.

- A dispatch prompt describes one task, not the session's history. Never paste accumulated prior-task summaries into later dispatches: a fresh subagent needs its task, the interfaces it touches, and the global constraints.
- The dispatch carries the no-subagents contract (it is in the template): the implementer never dispatches subagents, and never a reviewer. Review arrives from you, after the report.
- If an earlier task parked a finding in the area this task touches, carry a pointer to that ledger entry.
- Record the implementer's agent identity from the dispatch result: fix rounds 1–3 of a `roles:complex-implementer` task resume it, and batched light dispatch resumes it.
- Two implementers run at once only as Parallel tasks says; in every other case one implementer works at a time.

#### Batched light dispatch

For consecutive light tasks of one phase whose role is `roles:tdd-implementer`, dispatch the implementer once, for the first of them, and then resume that same implementer for each next task instead of dispatching a fresh one: its context already holds the codebase, which is most of the cost of a small task.

- One task at a time. The next task is sent only after the previous task's review and `task-close` finished; never queue two briefs in one message. Batched light tasks never run in parallel (see Parallel tasks), and a task of a batch starts only when every earlier task of the phase is closed: an earlier task that has not started would be held back by it.
- Run step 1 (`task-open`) for each task as usual: its own `start` move, its own brief, its own report file, its own BASE (recorded from `HEAD`, the squashed commit of the previous task). Resume with the "Next task" message of [implementer-prompt.md](implementer-prompt.md).
- `task-prep`, the review and `task-close` stay per task: each task gets its own `tier-check` on its own `BASE..HEAD`, its own review package and review, its own squash and `done`, its own `task-review` record.
- A task that `tier-check` raises above light ends the batch: its review runs at the raised tier as usual, and the next task gets a fresh dispatch. So does a task that is not light, a task of another role, a new phase, and a resume your harness cannot make.

#### Handle the report

Implementers report one of four statuses:

- **DONE:** go to step 3 (`task-prep` makes the `review` move when opted in).
- **DONE_WITH_CONCERNS:** read the concerns first. Correctness or scope concerns are addressed before review; observations are noted and the task goes to review (step 3 as for DONE).
- **NEEDS_CONTEXT:** provide the missing context and re-dispatch.
- **BLOCKED:** A BLOCKED reply that reports a denied call goes to [Denied by Policy](#denied-by-policy), with no re-dispatch and no ruling. Otherwise a context problem gets more context and a re-dispatch to the same role; a task that needs more reasoning than its role brings is broken into smaller pieces or re-dispatched with your ruling on the approach (never override the role's model); a plan defect gets a ruling, ledgered, carried in the re-dispatch. Never ignore an escalation or force the same dispatch to retry without changes.

If the implementer asks questions — before starting or mid-task — answer clearly and completely before it implements.

### 3. Check the tier

Run `node scripts/task-prep PLAN_FILE N` (from the main checkout, as every script of this loop; `--head <sha>` names the head of a task that is not on the main checkout's `HEAD`). One call does, in order: when opted in, the `review` move; `node scripts/tier-check PLAN_FILE N BASE HEAD --floor <tier>` on the task's whole range, with the floor of Tiers (the tracking ledger's effective tier, else the last `Tier:` or `Tier raised:` line); on `raise <from> <to>: …`, the raise: a raise is recorded with `triqual tasks retier` before the review (opted in) and always with the ledger line `Tier raised: T<N> <from> → <to> — <reason>`; the review package of `BASE..HEAD`; and the ledger line `Prep: T<N> r<R> <head sha>`. It prints, in this order:

- `tier:` the effective tier after the check: the review of step 4 runs at it, never at the declared one;
- `hunters:` `correctness` plus `security` or `state` (the second picked from the heavy reason line, see Tiers) for a heavy task's first review, else `none`;
- `package:` the review package path, or `none` for a range with no commit (it then wrote `Review: T<N> — no commits, nothing to review` itself: no reviewer runs, see When the stage does not run);
- `round:` the review round `<R>`: 1 for the first review, then one more for each fix round;
- `full-review:` `yes` only for a fix round that raised the tier (see 5. The fix loop), else `no`.

A second call at the same head is a rerun: it reuses the round, prints the same and appends no second `Prep:` line. Any other call once a `Prep:` line exists must be a fix round (`--fix-round`). It exits 0 ok, 2 usage, 3 a refused precondition and 1 any other failure, and before a non-zero exit it appends `Error: task-prep T<N> — exit <code> — <first stderr line>` to the ledger.

### 4. Review the task

Per-task reviews are task-scoped gates; the broad review happens once per phase, in the phase review (see 8. Review the phase), and the final review looks across phases. Every task with commits is reviewed on one review package, at its effective tier, by the Tiers matrix. Implementer self-review never replaces the task review.

- **The package:** the `package:` line of `task-prep` — pass every reviewer that path. The output never enters your own context, and the reviewer sees the commit list, stat summary and full diff with context in one Read call. It covers the BASE `task-open` recorded, never `HEAD~1`. Never dispatch a reviewer without a diff file; a hunter is no exception.
- **Reviewer inputs:** the gate and the spec reviewer each get the brief, the report file and the package, the effective tier, plus the global constraints that bind the task (copied verbatim from the plan's Global Constraints or the spec: exact values, formats and stated relationships). The gate also gets the task's canary rules and, when opted in, the tracking files it must expect in the diff (in store mode: none is expected, and an added or modified tracking file is a finding); the spec reviewer of a heavy task also gets every candidates file. A hunter gets the inputs of [hunter-prompt.md](hunter-prompt.md).
- **Footers and saved outputs.** The gate, the spec reviewer and the re-reviewer end their final message with the v1 footer their prompt defines (the marker `<!-- triqual-review v1 -->`, a `role:` line, a `findings:` line with the counts per severity and, for the spec reviewer, one `candidate:` verdict per candidate). These roles cannot write files, so you save each final message unchanged, before you act on it, to `<workspace>/task-<N>-<role>-r<R>.md`: `<role>` is `safety-reviewer`, `spec-reviewer` or `re-reviewer`, and `<R>` is the `round:` line of `task-prep`. A final message without the footer is sent back to its reviewer to be completed: `task-close` builds the `task-review` record from these files and never guesses a count. Hunters keep writing their `task-<N>-candidates-<category>.md` files. `task-close` reads the lowest round saved for the gate and for the spec reviewer; a re-reviewer's file is the audit trail of its round and is not read.
- Do not add open-ended directives ("check all uses") without a task-specific reason, and do not ask a reviewer to re-run tests the implementer already ran on the same code.
- **Never pre-judge.** Never instruct a reviewer to ignore or not flag a specific issue. If the prompt you are writing contains "do not flag," "don't treat X as a defect," "at most Minor," or "the plan chose" — stop: you are pre-judging. You never tell a verifier how to rule on a candidate, and you never drop a hunter's candidate before round 2.

#### Round 1

- **Heavy:** dispatch together, in the background, in one message: the 2 hunters (`roles:hunter`, the categories on the `hunters:` line of `task-prep`: `correctness` and the second category picked from the heavy reason line, see Tiers) and the gate (`roles:safety-reviewer`), each with the package path. Each hunter writes `<workspace>/task-<N>-candidates-<category>.md`, at most 5 candidates.
- **Standard:** no hunters. Dispatch together, in the background, in one message: the gate (`roles:safety-reviewer`) and `roles:spec-reviewer` ([task-reviewer-prompt.md](task-reviewer-prompt.md) without its candidates sections), each with the package path and its inputs.
- **Light:** dispatch the gate alone.
- Heavy: wait up to a soft limit of 10 minutes after the gate's report for every hunter still running. One still running then is recorded `failed` (timeout), and its output is ignored if it arrives later. A hunter that fails, hangs or returns nothing usable is recorded `failed` for its category, and round 2 goes on with the other candidates. No hunter ever blocks a task.
- Ledger: `Round 1: T<N> — hunters <done>/<sent>, safety ok` (`<done>` counts usable candidates files, a valid empty file included, and a standard or light task writes `hunters 0/0`; `safety ok` means the gate reported; its findings go to the fix loop after round 2).

#### Round 2

- **Heavy:** dispatch `roles:spec-reviewer` with [task-reviewer-prompt.md](task-reviewer-prompt.md): its inputs plus every candidates file of round 1. It returns spec compliance, task quality and one verdict per candidate. The verdicts are `confirmed` (with a severity), `refuted`, `duplicate-candidate` and `duplicate-review`, as the template defines them. A missing verdict (spec, quality or any candidate) makes the review incomplete: send it back. Ledger: `Round 2: T<N> — verdicts <n>/<n>`.
- **Standard:** the spec review already ran with the gate in round 1, with no candidates to verdict. A missing spec or quality verdict makes it incomplete: send it back. Ledger: `Round 2: T<N> — verdicts 0/0`, once both reports are in.
- **Light:** no round 2 when the gate is clean. When the gate reports a finding or a `Cannot verify` item, dispatch `roles:spec-reviewer` with the template's Light Items section holding exactly those items; it judges those items only. Ledger: `Round 2: T<N> — light items <n>`.
- A `confirmed` candidate enters the fix loop like any spec-review finding, at the severity the verifier gave it.
- The spec reviewer may report "⚠️ Cannot verify from diff" items. They do not block the rest of the review, but you resolve each one yourself before completing the task: you hold the plan and cross-task context the reviewer lacks. An item you confirm as a real gap enters the fix loop.

#### When the stage does not run

- **No commit range.** `review-package` exits 3 with the message `empty commit range` on an empty range (a coordinator task with no code diff): no reviewer runs at all and the `task-review` record carries no hunters, a gate with 0 findings and a spec that did not run. Write `Review: T<N> — no commits, nothing to review` to the ledger and complete the task. Only the `empty commit range` message means no commits: any other exit 3 (for example `HEAD is not a descendant of BASE`) is an error to fix, never a reason to skip the review.
- **Unavailable hunters.** When a hunter's error arrives before the agent runs (`roles:hunter` is an unknown agent type because the `roles` plugin is too old, the hunter's pinned Haiku id is an unresolved model, or there is no Haiku quota), skip the hunters for the rest of the plan with one ledger line, `Skipped: hunters — <cause>` (it changes nothing for a standard or light task, which sends none); the safety gate keeps running (a rate-limited gate follows the Rate limits rule, never this one).
- **Unavailable safety gate.** When the gate's error arrives before the agent runs (`roles:safety-reviewer` is an unknown agent type or its model is unresolved), skip the hunters and the safety gate for the rest of the plan with one ledger line, `Skipped: hunters and safety gate — <cause>; safety checklist runs in the spec review`. The safety checklist is never skipped: it moves into round 2, where `roles:spec-reviewer` runs it through the Safety Checklist section of [task-reviewer-prompt.md](task-reviewer-prompt.md), with the gate's inputs, at every tier (a light task then gets the spec reviewer with the Safety Checklist sections, and so does a standard task, whose spec reviewer dispatched in parallel with the gate is dispatched again with them). Its safety findings enter the fix loop like the rest. Look for a `Skipped:` line in the ledger before every round 1, so the skip survives compaction. A run that starts and then fails is not a skip: a gate that fails is re-dispatched; only hunters are recorded `failed`.

### 5. The fix loop

The loop triggers when the review reports spec ❌, any Critical or Important finding (the gate's included), a `confirmed` candidate at `critical` or `important`, or a ⚠️ item you confirmed as a real gap.

Before the loop starts, two routes leave it:

- Minor findings, `minor` confirmed candidates included, go to the ledger as you go (`Task <N>: minor (deferred): <one-liner>`, and the phase review (see 8. Review the phase) rules on them). Minor findings never enter the loop.
- A finding labeled plan-mandated — or any finding that conflicts with what the plan's text requires — is yours to rule on: weigh it against the plan text, decide with the spec as the binding authority, and ledger the ruling before you act on it.

Everything else enters the loop. A fix round is one fix dispatch, one `tier-check`, and the re-review the tier calls for. Five rounds maximum per task.

- **Ledger moves:** none by hand. When the fixer reports back, run `node scripts/task-prep PLAN_FILE N --fix-round`: it makes the `rework` and `review` moves (opted in), runs the round's check and the cumulative one (below), writes the round's package, appends `Prep: T<N> r<R> <head sha>` and prints the lines of step 3; `full-review:` and the package say what the round reviews. It exits 3 on a fix round with no new commit since the last `Prep:` head.
- **Who fixes:** rounds 1–3 resume the same `roles:review-fixer` (round 1 dispatches it with the open findings verbatim, the

[…] pełny plik w paczce .zip
Files in this package (19)
  • SKILL.md 116 KB
  • final-review-prompt.md 12 KB
  • hunter-prompt.md 3 KB
  • implementer-prompt.md 15 KB
  • orchestrator-prompt.md 8 KB
  • re-review-prompt.md 7 KB
  • safety-review-prompt.md 7 KB
  • task-reviewer-prompt.md 16 KB
  • scripts/review-package 4 KB
  • scripts/sdd-workspace 6 KB
  • scripts/stack.mjs 37 KB
  • scripts/task-brief 3 KB
  • scripts/task-close 47 KB
  • scripts/task-open 9 KB
  • scripts/task-prep 10 KB
  • scripts/tier-check 16 KB
  • scripts/lib/footer.mjs 3 KB
  • scripts/lib/plan.mjs 10 KB
  • scripts/lib/task-common.mjs 21 KB

Versions

RepositoryScoreLicence
This page · Montinou/triqual95MIT
nikospavlopoulos/devops-mutant-powers100MIT
arklab/ark.tools100MIT
arklab/ark.tools100MIT
ongtungduong/legion100MIT
osmontero/opencode-skills100MIT
GanyuanRan/Aegis100MIT
seaworld008/commonly-used-high-value-skills100MIT
FrancoStino/opencode-skills-collection100MIT

Database snapshot: 13.11.2026 · package version 6ac0b93b035a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.