adamayoung/TMDb / .claude/skills/deliver
deliver
VerifiedDeliver
Drive the current plan through the whole feature pipeline to a PR that is
green and ready to merge. This skill is an orchestrator — it sequences the
existing skills and adds the safety gates; the expertise lives in the pieces
it invokes. It runs autonomously from invocation (which is itself plan
approval) to a single hard stop — ready-to-merge — auto-scaling its
machinery to the change's risk, and writing a short retrospective that
rides the delivery's own PR. Every run happens in its own git worktree
(Phase 1; torn down on merge, Phase 12) so the user's main checkout stays
free. The plan is created first in plan mode (or with the Plan agent;
there is no /plan skill) — /deliver picks up from there. A selection run
supplies its own plan: /deliver next takes the top startable issue off the
project board's Ready column and /deliver issue <n> takes the one you name,
then drafts a plan for it (Phase 0;
references/next-mode.md).
you approve the plan ─▶ /deliver ─────▶ entry gate (ACs?) ─▶ worktree ─▶ [review-plan] ─▶
(or: /deliver next | issue <n> ─▶ select ─▶ re-verify ─▶ claim ─▶ draft ─▶ approve ─┘)
implement ─▶ code-review + fix ─▶ security-review + fix ─▶
rubric check (ACs met?) ─▶ capture ─▶ retro (pre-PR) ─▶ /pr reviewed ─▶ /watch-pr ─▶
GATE: ready-to-merge ─▶ wrap-up (wiki + recurring-pattern scan)
▲ the only hard stop
… then, when the PR actually merges (maybe a later session): teardown (Phase 12)
Detail on demand: procedures, traps, incident history and design rationale
live in references/ — read the named file when its phase
arrives, not up front.
Agent Behaviour Contract
Non-negotiable. Do these by default, without being reminded.
- Invoking
/deliveris plan approval — run autonomously to the one gate (the diagram above), with no second "is the plan ok?" prompt. The only legitimate mid-run pauses: a blocker from/review-plan(Phase 2), a red gate you cannot triage (§4), or — on an attended selection run, under either policy — the one approval stop on a plan/deliverdrafted for itself (Phase 0): invoking the skill approves the plan you brought, and a selection run brought none. Naming the issue yourself settles what to build, not how, so/deliver issue <n>gets that stop exactly as/deliver nextdoes. Inautoit is not a pause at all — thephase0n-selectionpanel rules instead. - Delegate to the existing skills — don't reinvent them:
/review-plan,/implement-plan,/review-changes,/security-review,/capture-knowledge,/pr,/watch-pr,/fix-integration-failures. - Never work on
main— always in a fresh worktree, entered before/review-planor any file edit (CLAUDE.mdforbids editingmain). - A red gate triages before it stops. In-diff failure → fix test-first
and re-run. Pre-existing/unrelated (typically a flaky live integration
test) → route to
/fix-integration-failuresand re-run — never hard-stop on someone else's flake. Only a genuine, in-diff, unfixable break stops the pipeline. - Test-first all the way. Every review-loop fix follows
canon-tdd— failing test first. No untested patches. - Keep two records: a
TaskCreateledger and a run file. The ledger is the live view (one task per phase, statuses current, branch, PR number, weight); the run file is the durable one, because the ledger does not surviveEnterWorktree, an MCP reconnect, or a plan-mode exit. Phase 0 writes it, Phase 1 records the reconcile into it, Phases 4/5/6 each stamp it on convergence (stamps.reviewedClean/securityClean/rubricGraded— that is what makes a resume able to skip a pass already done), and Phase 6 reads the rubric from it — so a skipped step fails loudly at a later phase instead of silently. Every phase that writes is named here, so if a phase you are in is absent, nothing writes on its behalf and you must not assume something else did. (Two non-phase writers exist and are documented where they apply: an async run writes the file before anyScheduleWakeup, and Phase 1's adopt path flipsentrybefore re-locking — seereferences/.) Location and schema:references/worktree-lifecycle.md. Every run-file write afterEnterWorktreegoes throughScripts/deliver-runfile.py— the worktree guard refuses ad-hoc writes to.git/deliver/, sometimes silently — and the script verifies its own postcondition: exit 0 printsverified: …; anything else means the write did not land and is a hard stop for the phase making it. Never carry on assuming state you did not read back — the #493 delivery certified a plan revision to the juror panel that two silent refusals had kept off disk. A template→replicate delivery adds thePhase 4a — reference-unit reviewgate task, which blocks Phase 9. A multi-deliverable plan keeps one ledger sub-tree per deliverable. - Jot knowledge candidates the moment a learning occurs (a lookup, a
gotcha, a live-API surprise, a non-obvious decision) — one line each
(
<category>: <gist> [where]), in the ledger. Mirror the list into the run file (deliverables.<n>.knowledgeCandidates, viadeliver-runfile.py) at Phase 7 entry at the latest — the ledger does not surviveEnterWorktree, and the resume rule restores candidates from the file, so an unmirrored list is one a resumed run silently loses. Phase 7 curates them; reconstruction later loses the best material. - Auto-start after plan-mode approval.
ExitPlanModeapproval IS the start signal — invoke/deliverimmediately; pause first only if Phase 0's entry gate fires.
Invocation — /deliver [auto] [merge] [next | issue <n>]
The four keywords are recognised only as whole, standalone tokens in a
leading run — parsing stops at the first token that is not one of them, and
everything from there on is the named plan target Phase 0 resolves. So
/deliver auto merge next is three keywords, and /deliver auto fix the merge handling plan is one keyword plus the target "fix the merge handling plan" —
not an auto-merge. A keyword found after the target has begun is part of
the target; say so rather than acting on it — nobody notices an auto-merge they
did not ask for until it has happened.
issue takes exactly one operand — the issue number, with an optional
leading #. So /deliver auto issue 480 is two keywords plus an operand.
(issue is a keyword with an operand, not a bare-number selector, so the
leading-run rule never has to distinguish a selector from a plan target whose
first word happens to be a number.)
Four contradictions — report and stop before any board write, worktree or edit, rather than silently picking one:
issue <n>with a named plan targetissue <n>together withnext(two selection policies)- two
issueoperands issuewith no operand, or a non-numeric one
next and a named target contradict each other for the same reason. Either
selector takes precedence over a plan already in the conversation, and says so
before drafting.
Echo the parse before acting on it — one line, first thing, before any board write, worktree or edit:
parsed: auto=on · merge=off · select=issue#480 · target=(none)
select= renders as issue#<n> for an explicit pick, next for the
top-of-run-list policy, or (none) when neither was requested. The echo exists
because no grammar can disambiguate a target whose first token is a keyword
(/deliver merge conflict handling plan) — a mis-parse must become visible in
the second before it matters, not at the moment an unrequested squash-merge
lands. Phase 0 writes the same parse to the run file at the same instant.
auto— unattended; every stop-and-ask becomes a juror panel (below).merge— squash-merge once the PR is green, instead of stopping at the gate (Phase 10).next— no plan needed: requests thetop-of-run-listselection policy, which takes the top startable issue off the board's Ready column and drafts one (Phase 0;references/next-mode.md).issue <n>— no plan needed: requests theexplicitselection policy, which takes the issue you name and drafts one. Same path from there on — re-verify, claim, draft, and release the claim on any stop before the PR opens. Unlikenextit may name an issue in Backlog: choosing it yourself is the triage judgement the Ready test otherwise stands in for.
Both selectors require the user-scoped GitHub Projects MCP — explicit still
has to claim the issue — so both are unavailable on a GitHub Actions
runner.
Auto mode & async invocation
/deliver auto replaces every stop-and-ask decision with an adversarial
panel of three independent Opus jurors — a dead panel is never a proceed,
and every panel convened leaves an audit line in the ledger. Decision points
are marked Auto: below. Never delegated: a data-loss or
breaking-change plan blocker is a hard stop even in auto, and in
auto merge a breaking issue is never merged unattended: under next it is
not selectable at all, and under issue <n> the merge opt-in is dropped
so the PR waits at the gate (references/next-mode.md
§5). /deliver can also be queued headless (the plan + ACs must travel in the
trigger prompt — unless a selection policy supplies them, which only works
where the Projects MCP is mounted). Panel procedure and queuing caveats:
references/auto-and-async.md. In attended
mode the Auto: branches do not apply — stop and ask, as written.
Delivery weight — auto-scale to risk
Judge from the plan; re-confirm from the diff after Phase 3; record in the
ledger. Lite — small, mechanical, single-unit, no risky surface (no
concurrency, networking/HTTPClient, or Decodable/CodingKeys changes; no
new public API beyond a simple additive method; under a few hundred changed
lines) ⇒ skip /review-plan's critics; /review-changes takes its
single-reviewer path. Full — anything risky or large ⇒ the three-critic
/review-plan and the fan-out + adversarial-verify /review-changes.
When unsure, prefer full. The vocabulary is binary — a hybrid run
(e.g. a pre-reviewed plan with the full review machinery) records as full
with the skipped machinery noted, in the ledger and the retro; never invent a
third tier.
One named override exists, and it is not a third tier. An auto selection
run — under either policy — drafted its own plan with no human between the
issue and the implementation, so it always runs /review-plan's critics
whatever the weight (Phase 2). Record that as planReview: forced — auto-<policy> in the run file and the retro, leaving weight itself
untouched; a lite run stays lite for Phases 4 and 5. explicit is covered
too: naming the issue yourself puts a human between you and the issue, not
between anyone and the plan, and it is the plan the critics read. An
attended selection run is not covered: its Phase 0 approval stop is the
same consent ExitPlanMode gives every other run, so it follows weight as
normal.
Multi-deliverable plans — one run, several PRs
A plan that is a program of cohesive deliverables becomes one PR per
deliverable. Decompose in Phase 0 with a dependency graph: dependent
(consumes a type/API/helper/file another introduces or substantially
changes) → sequence it (branch off its dependency, or wait for its merge);
independent → own worktree + branch + PR; unsure → treat as dependent.
Execution is serial implement, concurrent watch: one deliverable at a time
through Phases 1→9, but once its PR is open, start its /watch-pr in the
background and move to the next. The gate reports the batch; each
worktree is torn down as its PR merges; a stuck PR never blocks the others.
The full per-deliverable pipeline applies unchanged. (Genuinely parallel
implementation = separate /deliver sessions.)
Context & isolation (by design)
-
The conductor stays lean (plan reference, ledger, gate, short per-phase summaries); heavy work is already isolated in Workflows/subagents — keep it that way.
-
Implement runs inline — on purpose (the TDD list stays visible). Do not convert it to a silent subagent.
-
The gate stays in the main agent; phases hand off via git / disk / the PR, not context.
-
Separate worktrees get separate
.builddirs. NoSCRATCH_PATHoverride is needed — that flag is only for multiple agents sharing one working directory. -
One Swift process per worktree — at any instant, across every agent. Not "each agent runs its builds sequentially": one build in the whole worktree, full stop. The conductor owns it. Concretely:
- Only the conductor and the
tooling-runnerit spawns may build. Reviewer, security and grader subagents must be told not to build — their prompts say so, and/review-changesand Phase 6 already carry that instruction. - Never run two analysis phases concurrently. Phase 4 and Phase 5 read the same commits and feel independent — but they serialise on disk, not on tokens. Finish one, then start the next.
- Never spawn a
tooling-runnerin the background, and never two at once.
Every target shares one scratch directory, and a
build-docsrun flips theSWIFTCI_DOCCmanifest, which invalidates a concurrent build's plan rather than queueing behind it — the processes then redo each other's work in a cycle (knowledge/gotchas.md→ Docs builds need their own scratch path). - Only the conductor and the
Phase 0 — Preconditions
-
A plan must exist (named target → plan-mode plan → most recent in conversation). None → stop; ask for one in plan mode. Never invent one — except on the one sanctioned path: a selection run selects one instead. Under
top-of-run-list(next) it takes the top startable issue off the board's Ready column; underexplicit(issue <n>) it takes the issue you named, which may sit in Backlog. Either way it then re-verifies againstorigin/main, claims it, and drafts a plan with thePlanagent — and continues through the rest of this phase unchanged. Procedure, exclusions and theselectionblock:references/next-mode.md. Selection is part of Phase 0 rather than a phase of its own so the run file keeps one writer and the knowledge consult below still precedes the drafting that consumes it. Nothing startable, or no Projects MCP → stop before the worktree; never fall through to the "no plan" stop, which reads as an unrelated failure. Write the parsed invocation into the run file when you parse the keywords — before selection runs, not after. Record every keyword, not just this one ("mode": "auto merge next", or"mode": "auto explicit"forissue <n>—nextandexplicitare the two selection-policy tokens, and every gate keys on that rather than on the literal wordnext), plus the raw argument string asinvocation, plusconductorPid— this session's PID. Why the ordering and each field matter:references/worktree-lifecycle.md→ Run state. Auto: the approval stop below becomes thephase0n-selectionpanel — proceed with this self-picked issue and self-drafted plan, vs stop. -
A plan born from a review finding is a hypothesis — verify against the code (quick
Explore) before planning or asking strategy questions. -
State the goal in a sentence; judge the weight; open the ledger.
-
Pull wiki context best-effort (
get_contexton the goal); degrade silently if thewikiMCP is absent. -
Consult the knowledge base — skim the entry headings of
knowledge/gotchas.mdandknowledge/tmdb-api-notes.md, read the entries (and anyknowledge/decisions/ADR) relevant to the goal's area, and record oneconsulted: <entries | none relevant>line in the run file (and the ledger for convenience). Captured knowledge only compounds if it is read at entry, and the line must live where it survives — the ledger alone is not enough, because Phase 1'sEnterWorktreeclears it. Phase 8 copies it into the retro, which is the committed, human-reviewed copy. -
Identify the issue this delivers, and record it. Record
issue: <number>on the deliverable in the run file (orissue: nullwhen the work is genuinely untracked). Per-deliverable, not run-scoped: a multi-deliverable plan can close a different issue per PR, or none. Phase 1 moves it to In progress and Phase 10 to In review, so an unrecorded issue is one the board silently never reflects. A selection run has already made the In progress move itself, at the pick (Phase 1's move then finds it set and no-ops), and its claim carries an obligation: any stop before the PR opens releases it back toselection.claimedFrom— the column it was claimed from (references/next-mode.md§6). -
Flag a reflexive delivery. If the plan touches any of the reflexive set —
.claude/skills/**,.claude/agents/**,.claude/workflows/**,.claude/docs/**or.github/CODE_REVIEW.md— this run is rewriting the machinery that runs it. Recordreflexive: truein the run file. When in doubt about a path, resolve it as reflexive — a false positive costs one human merge; a false negative is the pipeline silently editing its own gates.This list is the reflexive set, and it is quoted in two other places —
references/next-mode.md§5b, which refuses such an issue inmergemode, andreferences/worktree-lifecycle.md's run-file schema. Change all three or none —Scripts/tests/test_deliver_selection_prose.pyasserts they agree, because a prose cross-reference alone did not survive one delivery (the drift history lives with the schema).Then read
references/reflexive.mdnow and hold its four consequences for the rest of the pipeline: no dogfooding before merge, verification pinned to the original text, the whole-footprint sweep (re-swept after every review-loop fix), and Phases 4/5 running even on a markdown diff. -
Decompose a multi-deliverable plan (rules above); single-deliverable plans skip this.
-
Entry gate — a gradeable rubric required. Plans are expected as "As a <user-type> I want <feature> so that <reason>" + acceptance criteria. Extract the ACs verbatim as the delivery rubric (consumed in Phase 6) into the run file (and the ledger for convenience), and record
rubricProvenance: supplied. Three cases, and only the last one stops:- ACs supplied → the above.
- ACs absent but derivable — the plan has a definition of done in the
wrong shape rather than none at all: a linked issue stating observable
before/after behaviour, or an explicit
canon-tddtest list. Derive the ACs into "Given X, when Y, then Z" form, recordrubricProvenance: derived — <the source>, and say in the PR body that the rubric was derived. Bug fixes land here routinely; stopping to ask a question the plan already answers is ceremony, not rigour. A selection-run-drafted plan always lands here, under either policy: recordderived — issue <number>, neversupplied—suppliedmeans a human set the bar, and here the run that gets graded wrote its own rubric. Do not "simplify" it back. - Neither → stop and ask for them ("Given X, when Y, then Z") — don't
enter the worktree. Auto: panel — proceed rubric-less (Phase 6 no-ops)
vs stop; record that as
rubric: none, which is present-and-empty, not a missing file.
Reject a knowledge-shaped AC — it cannot pass. An AC whose evidence is a
knowledge/artifact ("an ADR records X", "a gotcha is captured") is guaranteed to fail its first grading, because Phase 7 writes that artifact after Phase 6 grades — deliberately, so capture observes the delivery's final state. Drop such an AC from the rubric when extracting it (the work still happens, enforced by Phase 7's own contract), say which ACs you dropped and why, and when deriving, don't write one in the first place.Derive to grade yourself honestly, not to pass: write the ACs from the source's own words before implementing, never after, and never soften one because the implementation went another way. Provenance makes a derived rubric auditable; Phase 6's independent grader is what stops a self-serving one.
-
Read the plan's content into context now —
EnterWorktreeswitches CWD (clearing the plans cache), and a fresh worktree lacks uncommitted local files; the plan must travel in the conversation.
Phase 1 — Reconcile prior runs, then enter an isolated worktree
Procedures and traps:
references/worktree-lifecycle.md.
-
Reconcile before
EnterWorktree(the run file already exists — Phase 0 wrote it; record the sweep into it, never mint a second one). Enumerate withgit worktree list --porcelain(neverls .claude/worktrees/), scoped to<main-root>/.claude/worktrees/, and classify every one first-match-wins:live(lock PID alive — never touch) /report/reclaim(merged and Phase 12's two proofs) /resumable/settled. Report, never remove, anything that doesn't prove reclaimable, and verify a directory is gone before counting it reclaimed. Recordreconciled:in the ledger, thereconciledblock in the run file, and the retro (Phase 8) — never asswept:, which is Phase 7's knowledge sweep and will silently take the slot.Release stranded selection claims while you are here — for every run file whose
modenames a selection-policy token (nextorexplicit) or which carries aselection.policy, withpr: null,status: open, noclaimHandedBackstamp, andselection.claimednotfalse: test itsconductorPidwithkill -0; dead → move the issue back toselection.claimedFrom, stampclaimHandedBack, and count it in thereconciledline'sclaims releasedslot; alive,EPERM, or no parseable PID → leave it and report it. Walk the deliverables (the predicate mixes run-scoped and per-deliverable fields) and key on the PID, never the worktree buckets — a selection run claims before any worktree exists. The full predicate, its two scopes, and why each clause is load-bearing:references/worktree-lifecycle.md→ Release stranded selection claims. -
Enter with
EnterWorktree(name: "<prefix>/<slug>")(feature/,fix/,chore/, …) — sanctioned auto-use, don't ask. Verify the branch name afterwards (git branch --show-current;git branch -mif the tool renamed it). Already in a worktree? Don't nest — branch there. -
Check
.claude/settings.local.jsonarrived —.worktreeincludecopies it into every worktree, so this is a verification (test -f .claude/settings.local.json), not a copy. Missing → copy it from the main checkout and say so. It carries the credentials (the TMDb env vars live in itsenvblock); never paste its contents anywhere. -
Record worktree + branch in the run file and the ledger, and (re-)create the ledger here — the ledger is CWD-scoped and cleared by
EnterWorktree, an MCP reconnect, or a plan-mode exit; found empty later → re-create from the phase list and the run file, it isn't lost work. Set the run file'sentrytocreated, or toadoptedwhen resuming an existing worktree viaEnterWorktree(path:)— Phase 12's teardown branches on it. Adopting a selection run whose deliverable carriesclaimHandedBack? Its issue was handed back while the run was dead and may now belong to someone else — re-run the claim steps (references/next-mode.md§6) before resuming, testing againstclaimedFrom, notReady(a Backlog-claimed issue is handed back to Backlog).StatusneitherclaimedFromnor claimable → stop and say the issue was re-claimed elsewhere — resuming on the strength of a claim the sweep already released is how an adopted run comes to "release" an issue a live delivery is holding. -
Move the issue to
In progress— the run file'sissue, if it has one. This is the right moment rather than Phase 0: the entry gate can still stop a run, so the worktree is the first step that commits to doing the work. Column vocabulary and the exact call:.github/ISSUE_FILING.md→ Board status — the column lifecycle. No issue → skip and say so; a failed board write is reported, never fatal. -
Edit via worktree paths: re-
Readanything read before entering, and verifygit statusshows your diff in the worktree before trusting the first green build (empty diff + baseline counts = edits went tomain).
Invoked from plan mode? That approval is the start signal — exit plan mode, enter, proceed.
Phase 2 — Harden the plan (no approval stop)
Lite, or already adversarially reviewed this session (a converged
/review-plan, or an equivalent in-conversation critique whose findings were
applied) → skip the critics. ExitPlanMode approval alone is consent, not
review — it does not skip. An auto selection run never skips, under
either policy and at any weight: no human read the plan before implementation,
so the critics are the only review it gets — record planReview: forced — auto-<policy> (see Delivery weight); an attended selection run follows
weight as normal. Full with an unreviewed plan → invoke /review-plan,
present the revised plan + a one-line change log (applied / rejected) as an
FYI, keep going — except a blocker (wrong approach, breaking,
data-loss), which stops the run. Auto: data-loss/breaking = hard stop
(never delegated); other blockers → panel.
Phase 3 — Implement the plan
Invoke /implement-plan (Canon TDD: list shown first, one failing test
at a time, done only when the list is empty and both suites green). It
commits at logical checkpoints — required: Phase 4 reviews committed
history. Don't advance until /test and /integration-test pass and the
work is committed; re-confirm the weight from the diff. Four hard checkpoints:
- Run the release build before declaring implementation done —
make build-releasedirectly viaBash, not/build(tooling-runnerhas no release target, and asking silently gets you a debug build). Debug,--build-testsand both suites all compile with-enable-testing; the release build does not, so access-level and@testablemistakes fail there and nowhere else — precisely what target extractions, new non-test targets, and visibility changes are made of. A ~30s check that guardsmake ciand both CI release steps (incident: PR #398, caught only in code review;knowledge/gotchas.md). - "Fix every instance of pattern X" → enumerate ALL sites up front with a
single type-driven sweep, listed in the test list before implementing —
piecemeal discovery ships subsets (incidents:
references/review-loops.md). Do that sweep with the LSP (ToolSearch("select:LSP")→findReferences,incomingCalls,goToImplementation), notgrep: a text pattern under-reports silently — ADR-0008's grep found four of eight sites, and the three it missed carried a credential (#421). - An absence-shaped fix must be proven able to fail. Trigger: the acceptance criteria are phrased as an absence — "X no longer appears / is no longer sent / is redacted". Every test for such a fix asserts a negative, and a negative passes just as happily when the value was never there, the key was renamed upstream, or the code path is never reached at all. Before declaring the test list empty: unwire the fix (revert its production hunks locally), confirm the new tests go red, restore, confirm green, and record the result in the retro. In #469 this one-minute check was the only evidence the two wiring tests' green meant anything. Positive-assertion deliveries skip it — the trigger is the ACs' phrasing, not a blanket rule.
- Consult the specialist skills — mandatory, topic-triggered, including for
fanned-out subagents.
swift-concurrencythe moment actors,@MainActor,Sendable/@unchecked Sendable, locks,Task/task groups, or any data-race question appears — to design, not just debug;swift-testing-expertwhen writing or structuring tests. Same in Phase 4: run concurrency-sensitive findings throughswift-concurrencybefore accepting or dismissing them.
Phase 4 — Code review + fix loop
Skip entirely if the diff has no reviewable code — no Swift, no
.claude/workflows/ script and nothing under Scripts/ (/review-changes
self-gates on the same set). Exception — a reflexive delivery (Phase 0 set
reflexive: true): do not skip — run /review-changes with
force-review (the case #407 shipped three defects through). Review
stable code once the design settles — not per TDD item. Granularity by
weight:
- Lite → one review of the full diff (single-reviewer path).
- Full, template→replicate (one pattern across N≥3 cohesive units) →
review the reference unit before the rest are generated: the hard
Phase 4a — reference-unit review @ <sha>ledger task blocks Phase 9 (procedure:references/review-loops.md). - Full, otherwise → one review of the full end diff via the fan-out path; do not interleave per unit.
A small diff does not downgrade a full review. Weight is decided by the
risk surface (§Delivery weight), and "single-unit" is one of lite's
conjunctive conditions, not an alternative to it — a cohesive 200-line
concurrency fix is still full, and still takes the fan-out (the defects of
issues #401, #433 and #461 all survived a single reviewer).
Tell /review-changes the weight when you invoke it, so its own size
heuristic cannot silently re-decide what Phase 0 already judged.
Converge via /review-changes: read the severity-graded report; fix each
Critical/High test-first, re-run /test (+ /integration-test if
behaviour changed), commit the fix (an uncommitted fix re-reviews as
still-broken); re-invoke; repeat until none remain. Cap at 3 iterations,
then stop and surface. Auto: panel — proceed (note unresolved findings in
the PR description) vs stop. Medium/Low: apply the cheap, clearly-correct
ones; note the rest in the PR description. This is the single substantive
review — /pr therefore runs in reviewed mode (Phase 9). On
convergence, stamp the run file:
python3 Scripts/deliver-runfile.py set <run file> deliverables.<n>.stamps.reviewedClean "<content hash>" (hash recipe:
references/worktree-lifecycle.md), and
mirror any findings left unresolved into deliverables.<n>.openFindings in
the same way — the ledger copy dies with the session.
Mutation-check before converging — a reflexive delivery that adds or
changes a prose-asserting test (reflexive: true and the diff touches a
test asserting on skill/doc prose, e.g. under Scripts/tests/): the
iteration cap is the wrong stopping signal for this class, because a passing
prose test is not evidence — #482 shipped three assertions that passed while
testing nothing, and two of its guards started green. So, for each rule the
new tests guard: confirm the baseline is green, revert that rule alone in
a scratch copy, and confirm the suite goes red for that rule; a guard that
stays green is not a guard. Restore, and record the matrix in the retro. The
three blind-assertion failure modes and the worked matrix:
knowledge/gotchas.md → A test that asserts on prose can be blind. Swift
suites are exempt — the compiler and --Werror already do this work.
Phase 5 — Security review + fix loop
Run only when the diff touches a security-relevant surface: Swift source,
Package.swift/Package.resolved, .github/workflows/, .claude/settings*,
or .claude/workflows/ (committed scripts that spawn agents and gate
autonomous decisions). Pure docs/markdown → skip, except a reflexive
delivery, which runs this phase on a markdown diff too
(references/reflexive.md §4). No scale-down on
lite.
Invoke /security-review (findings only — the conductor fixes) and
converge with the Phase 4 loop: fix each High (and any Medium with a
concrete attack path) test-first where reproducible, commit, re-invoke, cap
at 3. Auto: panel — but a credential leak or clear exploit is a hard
stop even in auto. This is the pipeline's only security gate (CI has no
SAST). On convergence, stamp deliverables.<n>.stamps.securityClean exactly
as Phase 4 does. Surfaces that bite:
references/review-loops.md.
Phase 6 — Rubric verification (exit gate)
Take the rubric (Phase 0 ACs) from the run file — the ledger copy is a convenience, not a source, and the plan text in context is not one either. The cases must not be conflated:
- File present, rubric populated → grade it (below). Grade a
derivedrubric exactly as strictly as asuppliedone — provenance is there to be disclosed, never to lower the bar. - File present,
rubric: none→ the sanctioned rubric-less path; skip. - File missing, or missing its
reconciledblock → hard stop. A missing run file is not a pass, exactly as a dead grader is not a pass; and a file withoutreconciledmeans Phase 1's sweep never ran. This is what makes both gates real rather than advisory. - A
modenaming a selection-policy token (nextorexplicit) withselectionmissing or empty → hard stop, the same way and for the same reason: it means the selection inreferences/next-mode.mdnever ran, so nothing established that this issue was the right one, still verified, or claimed. (modeis written at Phase 0's keyword parse, before selection, so a skipped selection shows up as a policy token with noselectionrather than as an ordinary run.) - A
modenamingauto, together with a selection-policy token (nextorexplicit) inmode— or aselection.policy— andplanReviewmissing → hard stop. That field is the sole record that the forced/review-planactually ran, and a self-drafted, unattended plan whose critics were skipped is the least-reviewed thing this pipeline can produce. Readautofrom the run file'smode, never from memory of the invocation — the ledger that held it does not surviveEnterWorktree, a resume, or Phase 10's background handoff.
How it is graded depends on weight:
- Lite → verify inline: each AC against the committed diff — behaviour
by diff-scan or a targeted test (
swift test --filter …), coverage by the test + assertion existing, integration by the integration test existing (the live run already passed in Phase 3 — no re-run needed). - Full → an independent grader, not the conductor — the maker does
not grade its own homework. Spawn ONE subagent (general-purpose; inherit
the model) given ONLY the rubric verbatim and the instruction to judge the
committed work by reading
git diff origin/main...HEADand the files — no conversation context, no implementation narrative. It returns per-ACmet/not met+ one-line evidence (file:line or test name). Run it synchronously. Grader dies or returns unusable output → fall back to the inline path and note it in the ledger — a dead grader is not a pass.- Cap what it may execute, explicitly. Tell it: at most one targeted
swift test --filter …, and nevermake ci/make test/make integration-test/make build-docs. Left unsaid, a thorough grader will run the whole ofmake ci— one did, for 72 minutes.
- Cap what it may execute, explicitly. Tell it: at most one targeted
Satisfied → mark off, and stamp deliverables.<n>.stamps.rubricGraded with
the same content hash and script as Phases 4 and 5 — the resume rule reads
all three stamps, and an unstamped grade is one a resumed run repeats. Not →
fix test-first, commit, re-verify (full weight: re-run the grader); a gap
needing a plan change is noted in the PR description. "Did we build what the
plan said?", not "did the build pass?".
Phase 7 — Capture learnings
Invoke /capture-knowledge, passing the ledger's knowledge-candidates
list as the skill argument ($ARGUMENTS — it travels with the call even
after compaction). It curates: durable, non-obvious, reusable items only,
deduped against knowledge/, written to the right file (gotchas / API notes
/ an ADR). Runs after the rubric gate, so a grading failure that changes
the design cannot invalidate an entry already committed; still before /pr,
so the notes ride the same PR. Capturing nothing is a valid outcome.
Exception: one or two small entries already authored during implementation
may be committed inline instead — note the inline capture in the retro.
That ordering is why Phase 0 drops a knowledge-shaped AC from the rubric:
grading it would always precede the work. This phase's own contract — the
swept: line and the capture report — is what enforces it instead. Its
report must include the swept: line — Phase 7 is the knowledge base's
retirement trigger (the skill's step 5), and a report without it means the
sweep did not run. That applies to the inline-capture exception too: a
delivery that touched Makefile, Package.swift, .github/workflows/ or
.claude/ still owes the sweep, whoever wrote the entries.
Phase 8 — Write the retrospective (pre-PR)
Write the retro now, before the PR opens, so it rides the PR itself and
the gate is never re-opened by a routine retro push. Mandatory. A dated entry
in knowledge/delivery-retros.md,
headed with the branch name (Phase 9 backfills the PR number): phases /
skills telemetry, what worked, friction, deviations, one improvement; omit
watch: (post-gate amendments only, Phase 11). Commit it on the PR
branch, then run the windowing step (>~12 full entries → distil the
oldest into the archive table). Format detail:
references/wrap-up.md.
Phase 9 — Create the PR
Gate check first (template→replicate only): the Phase 4a ledger task
must be completed — still open → back to Phase 4.
Invoke /pr reviewed (Phase 4 already converged this code, so /pr
skips its internal review). It formats, runs make ci — the mandatory
gate; /pr scales it to a docs-only fast gate when nothing build-affecting
changed — pushes, and opens the PR. If make ci fails, triage (§4): the
failing test/file in git diff --name-only origin/main...HEAD? In-diff →
fix test-first, commit, re-run; stop only if it can't converge (Auto:
panel — open with the failure noted vs stop). Pre-existing/unrelated → a
main problem: hand to /fix-integration-failures, update this branch,
re-run — never patch an unrelated test here.
Record the PR number/URL in the ledger. Backfill the retro heading with the PR number, commit, push immediately — pre-gate (the superseded CI run is cancelled by the concurrency group).
Phase 10 — Watch to ready → GATE: ready-to-merge
Invoke /watch-pr in watch-only mode, in the background,
passing the PR number from the ledger (/watch-pr <number>) — a
background watch must be pinned to its PR, not to "current branch", which
changes when the conductor moves to the next deliverable's worktree. It
resolves threads, fixes failing checks (routing unrelated integration
failures per §4), and loops until ready or stuck. Ready means
mergeable now (branch brought up to date with main, re-run green).
On ready it also moves the issue to In review, which it reads from the
Closes #NNN line Phase 9's PR body carries — not from an argument (two
bare numbers in one invocation would be ambiguous, and the PR body is the same
link GitHub uses to close the issue on merge). The run file's issue is what
Phase 1 uses, before any PR exists.
THE GATE — hard stop. Ready → stop; hand the merge to the user; report
the PR URL and state; run Phase 11. The worktree stays (torn down only on
merge, Phase 12). Stuck → stop, summarise what's blocking, keep the
worktree. Auto: stuck → panel (retry via ScheduleWakeup vs stop); the
gate itself is not a panel decision — in auto, ready behaves as the merge
opt-in. Opt-in auto-merge: only if the user passed merge, forward it
(/watch-pr merge <number>) — the gate becomes "report the merge" → Phase 12.
merge is dropped, not honoured, when any of these holds — read them
all from the run file, since this phase runs in the background, potentially
long after the invocation:
- the run file says
reflexive: trueand it is a selection run — itsmodenames a selection-policy token (nextorexplicit), or it carries aselection.policy; or selection.mergeRefusedis non-null — selection already refused the opt-in under §5a/§5b/§5c; or- on a selection run, the raw facts say it should have been refused,
whatever
mergeRefusedsays —selection.breakingClassis anything butnone, orselection.authorAssociationis outside{OWNER, MEMBER, COLLABORATOR}(absent or unrecognised counts as outside). Re-derive rather than trust.
A selection run did not have a human choose both the issue and the plan, so
nobody decided to merge a rewrite of the pipeline's own skills unattended.
Stop at the gate and say the opt-in was dropped and why. Why each condition
exists, why there are two witnesses for "is this a selection run", and why
condition 1 is not subsumed by condition 2:
references/next-mode.md §5–§5b (condition 3's
"record the raw facts" rationale sits in the §5 preamble).
Phase 11 — Wrap-up (wiki, pattern scan, exceptional retro amendment)
The retro is already on the PR (Phase 8) — the default path pushes nothing
after the gate. Guidance:
references/wrap-up.md.
- Amend the retro only for a noteworthy watch phase (stuck check, new
Critical/High thread, routed flake, wrong readiness call): append a
one-line
watch:bullet, commit, push — on the PR branch (watch-only), or a fresh branch offorigin/mainas a small follow-up PR (merge/auto mode, before teardown). Uneventful watch → don't touch it. - Any post-gate push re-opens the gate — after the last exceptional push
(amendment or approved skill edit), run the
/watch-prloop once more on the new tip before merge. - File what this delivery deliberately left behind. Every phase that scopes
something out — a review finding ruled out of scope, a security finding not
in this change's class, a rubric gap accepted, a breaking change deferred —
has produced a fact that exists only in this session's transcript until it
is filed. Open an issue per
.github/ISSUE_FILING.mdfor each, citing this PR as**Origin:**, and list the numbers in the retro. Auto mode files these too — it is additive, reversible, and touches no source; the Phase 11 prohibition is on editing skill files unattended, not on recording work. - Update the personal wiki — best-effort,
propose_entryonly (never autonomous writes); degrade silently if absent. - Recurring-pattern scan: friction/deviations recurring across the last
~12 retro entries → numbered proposals — plus every retro's "one
improvement" with no entry at all in the log, recurring or not
(singletons included; the procedure is in
references/wrap-up.md). Consultskill-improvement-log.mdfirst and skip anything already decided; wait for explicit approval on each proposal — never edit a skill file unasked; record every decision in the log (five-field format). Neither a new recurrence nor an unrecorded one-improvement → say so and stop. Auto: not delegable — an unattended run must never edit and push the repo's own skill files, so it records every proposal inskill-improvement-log.mdasdeferred — raised unattended, needs reviewand applies none (the panel script throws if asked;references/auto-and-async.md). Phase 11 is post-gate, so the run still completes.
Phase 12 — Teardown on merge (reclaim the worktree)
The trigger is the merge, and only the merge: right after a merge-mode
merge, or when a watch-only merge is confirmed within this session. Session
ends with the PR open → leave the worktree (the next run's Phase 1 GC
reclaims it once merged). Stuck/blocked/abandoned → never tear down.
Two preconditions, both required, then
ExitWorktree(action: "remove", discard_changes: true):
- Which teardown applies — the run file's
entry.created→ExitWorktree(action: "remove", …).adopted→ExitWorktreewill not remove a worktree entered bypath; it no-ops while you report a reclaim. Useaction: "keep"then remove by hand (unlock →git worktree remove→git branch -D). Either way, verify the directory is gone before reporting a reclaim. - The PR is actually merged (
pull_request_read→merged: true). - No unsaved work beyond what's merged:
git status --porcelainempty andgit rev-parse HEADequalsgit rev-parse @{u}. Either fails → land the work first; do not discard.
discard_changes is safe only because precondition 2 proved nothing
un-merged remains (a squash-merge means the branch commits aren't literally
on main). Leave the main checkout as you found it. Detail:
references/worktree-lifecycle.md.
When the pipeline stops
Wherever it stops — the gate, an untriageable red gate, a stuck PR — end with a concise status: phase reached, branch and PR, what passed, what's blocking, and the single next action needed from the user. The destination is a green PR ready for their merge — say plainly whether you got there.
A selection run that stops before its PR opens owes one extra line: the
issue it claimed has been released back to its selection.claimedFrom column,
or it is stranded in a column nothing else can move it out of.
Arguments: $ARGUMENTS
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |