| name | tpp-orchestrate |
| description | Work through a queue of Technical Project Plans serially — delegate each to a TDD subagent, double-review the result with codex and a Claude /review subagent, empirically vet every finding before accepting or vetoing it, and land one coherent commit per plan. Use when executing a roadmap of plan files (e.g. a _todo/ directory) for a port, migration, or multi-stage feature. |
| allowed-tools | Bash, Read, Glob, Grep, Edit, Write, Task, Agent, AskUserQuestion |
TPP Orchestration
Documented in depth: Claude Code has amnesia. So do PRs, changelogs, and your future self.
You are the orchestrator for a queue of Technical Project Plans (TPPs) — self-contained plan files that carry research, design decisions, and acceptance criteria across sessions (typically _todo/*.md, moving to _done/ when finished, with a roadmap file as the index). The TPP system itself — layouts, frontmatter, the plan template — is defined in the bundled TPP-GUIDE.md, or the project's own docs/TPP-GUIDE.md, which wins. The sibling tpp and handoff skills work a single plan within a session; this skill is the loop that drives a whole queue of them through subagents and review gates.
Two failure modes motivate this loop:
- A subagent's green test suite is not proof of correctness. Agents satisfice: they implement until their own tests pass, and real bugs (semantic mismatches with the spec, stateful-API gotchas, edge cases the tests never pin) survive. Independent review catches these.
- Reviewers are confidently wrong, too. Every review pass produces a mix of real bugs and plausible-but-wrong findings. Accepting blindly injects regressions; vetoing blindly ships the bugs. Only empirical verification against ground truth settles a finding.
So: delegate, review twice, and vet everything with evidence.
Before the first TPP
- Read the roadmap and every queued TPP's summary. Confirm dependency order.
- Identify the project's ground truth — the thing a disputed finding can be tested against: a reference implementation you can execute, a spec with runnable examples, the real runtime/API. Write down how to query it (the exact command). If there is no executable ground truth, say so and agree on the fallback (spec text, maintainer decision) with the user.
- Ask clarifying questions now (
AskUserQuestion) — scope ambiguities are cheapest to resolve before any code exists.
The loop, per TPP
Work serially: one TPP through the full loop before starting the next. Only parallelize TPPs within a wave when their file sets are provably disjoint and neither depends on the other's decisions — review gates stay per-TPP either way.
1. Scope and clarify
Read the TPP and its sources of truth. If anything is ambiguous or the plan contradicts what you find in the code, ask the user before delegating — don't let a subagent guess.
2. Delegate with TDD
Launch an implementation subagent. Pick the model by risk: a stronger model (opus-class) for large, novel, or weakly-specified work; a faster one (sonnet-class) when the TPP and existing tests pin the behavior tightly.
The prompt must include:
- The TPP path and the sources of truth (spec files, reference implementation paths).
- Tests first: port or write the acceptance tests before implementing, then implement until green. The full suite must stay green — not just the new tests.
- Project pitfalls relevant to this TPP (from
CLAUDE.md or the TPP itself).
- "You cannot talk to the user. Record open questions, assumptions you made, and every intentional divergence from the plan in your final report."
3. Relay questions
Triage the subagent's open questions. Decision-worthy ones go to the user (AskUserQuestion) before the review gate — a review of code built on a wrong assumption is wasted.
4. Review twice, independently
Run the double-review gate on the TPP's diff — read and follow
../double-review/SKILL.md: two independent
reviewers (codex + a Claude review subagent) over the identical scope, blind
to each other, while you read the new code yourself as the third reviewer —
the only one who knows the whole roadmap. Scope both reviewer prompts with
this TPP's spec/reference files, the diff range, and a scrutiny list of the
riskiest areas the plan touches.
5. Vet every finding — accept and veto only with proof
Per the gate (steps 3-4 of double-review): test each finding against the
ground truth you identified before the first TPP; accept or veto only with
that evidence; every accepted finding gets a pinning test whose expected
values come from ground truth. Full suite green again.
6. Record the verdicts
Add a "Post-review fixes" section to the TPP listing every finding — accepted and vetoed — with the evidence for each verdict. Vetoes especially: the next session will see the same "bug" and must not re-litigate it.
7. Close out
Move the TPP to _done/, update the roadmap's status section, and make one coherent commit per TPP (implementation + tests + TPP move together), following the repo's commit conventions. Then start the next TPP.
Guidelines
- Never let a review gate slip. "The agent's tests pass and the diff looks clean" is exactly the state in which review has found real bugs.
- Rebuild before testing built artifacts. CLI/dist tests against a stale build silently test old code.
- Report honestly. The per-TPP summary to the user lists: what shipped, findings accepted/vetoed (with one-line reasons), open questions, and anything you diverged on.
Adapting for your project
- Name the ground truth explicitly — e.g. "CPython 3.12 via
uv run python -c ... in the reference submodule", "the staging API", "the RFC's test vectors". The vetting step is only as strong as this.
- Reviewer choices and scrutiny-list tuning live in the gate — adapt ../double-review/SKILL.md, and this loop inherits it.
- Tune the model heuristic to your roster — the invariant is "risk decides the model", not the specific names.
- Rename the file conventions (
_todo/, _done/, the roadmap) to whatever your plan system uses; the loop doesn't care about paths.
