tri-agent-loop

name

tri-agent-loop

description

Orchestrate a plan → review → implement delivery loop across three PLUGGABLE agent roles — planner, reviewer, implementer — where any agent can fill any role in any order. One agent drafts an artifact (SRS / design / per-task plan), a second adversarially reviews it through a shared markdown thread until convergence (Final ACK), and a third implements; the orchestrator (the agent running this skill) relays handoffs, monitors the review thread, and reviews the resulting PR. Use when the user asks to "run the planner / reviewer / implementer loop", "tri-agent loop", "plan-review-implement", "use X to plan, Y to review, Z to implement" (any permutation, e.g. Claude plans, Codex reviews, Cursor implements), or wants the docs-first / Codex-reviewed / Cursor-implemented workflow from feedback_planner_reviewer_codex_loop generalized to arbitrary agents.

Tri-Agent Loop

A delivery protocol that splits work across three roles and keeps each artifact rigorously vetted before it advances:

1. Planner — drafts the artifact: an SRS, design doc, or per-task implementation plan. Decides what and how, not the code.
2. Reviewer — adversarially reviews the artifact through a shared markdown thread, returning concrete deltas until convergence.
3. Implementer — writes the actual code/change after the plan converges, and opens a PR.

The roles are pluggable: any agent can fill any role, in any order. The agent running this skill is the orchestrator — it authors artifacts when it holds a role, relays handoffs when a role belongs to an external agent, monitors the review thread, and reviews the implementer's PR. The orchestrator is usually also one of the three roles (commonly planner+reviewer), but need not be.

This is the generalized form of the workflow captured in the user's feedback_planner_reviewer_codex_loop memory: planner+reviewer authored by one agent, a separate implementer, every artifact Codex-reviewed before handoff. Here the agent behind each role is a parameter.

When to use

Fire when the user wants multi-agent delivery with separation of concerns:

• "Run the planner/reviewer/implementer loop on X."
• "Use Claude to plan, Codex to review, Cursor to implement" — or any role permutation.
• "Tri-agent loop", "plan-review-implement", "the docs-first Codex-reviewed loop."
• A substantial feature where the user wants each artifact adversarially reviewed before code.

Do not use for:

• Trivial / single-file changes (one agent, no ceremony).
• Pure research with no artifact to review or implement.
• When the user wants one agent to do everything end-to-end.

Step 0 — Assign the three roles

Resolve, from the user's request (ask via AskUserQuestion if unstated):

Role	Agent	Common choices
planner	who drafts	this Claude · a Task subagent (Plan) · an external agent the user drives
reviewer	who critiques	Codex · another Claude · Gemini · a Task subagent · a human
implementer	who codes	Cursor · this Claude · a Task subagent · a human

Each agent participates in one of two modes:

• In-session (callable): this Claude itself, or a Task-tool subagent the orchestrator spawns. The orchestrator drives it directly.
• External (relayed): an agent running in its own tool/terminal (Codex, Cursor, Gemini app, a teammate). The orchestrator can't call it — it produces a handoff prompt + shared file and the human relays the turn. (Codex/Cursor in our reference run were external; the human pasted prompts and pinged.)

Pick a short topic slug for the work (<topic>); it names every file.

Step 1 — PLAN (planner role)

Produce the artifact:

• In-session planner: draft it directly. If a grill-me-style interrogation skill is available, run it first to resolve the decision tree; then write the artifact (SRS → per-task plans). Follow any repo doc conventions (recommendation-first / decision-table / references-at-end).
• External planner: emit a planning prompt for the user to relay; when the draft returns, save it to the artifact file.

Artifact location: a durable doc, e.g. <docs-dir>/<topic>-design.md (with a ## SRS section) and, for per-task plans, <topic>-tasks.md. One artifact per round; keep it scannable.

Step 2 — REVIEW (reviewer role) — the core loop

This reuses the file-review-dialogue mechanics (compose that skill if installed; otherwise inline the protocol below).

1. Seed a shared thread <docs-dir>/<topic>-review-thread.md: lead with the recommendation (pyramid), justify with file:line anchors, end with 2–5 targeted questions for the reviewer. Leave a ## <Reviewer> Response placeholder.
2. Hand off to the reviewer:
   • In-session reviewer → spawn it (Task) pointed at the thread + artifact; capture its response into the thread.
   • External reviewer → print a handoff prompt: "Read <thread> + <artifact>; respond under ## <Reviewer> Response." Tell the user any wake quirk (e.g. Codex's watcher only flushes on a turn — they may need to type check file).
3. Monitor the thread file's mtime (Monitor tool, persistent, ~3600 s) so each reviewer append wakes the orchestrator.
4. On each append: read the whole thread, then respond pyramid-style under your own dated header (## Claude Follow-Up N - <date>). Before accepting any delta, verify the reviewer's cited file:line at the source — a confidently-cited claim can still be wrong; check the call chain, not just the line. Accept (land the doc edit), refine (counter with evidence), or push back.
5. Converge when the reviewer posts a "Final ACK" / "No further objections" and you have nothing structural left. TaskStop the monitor. Mark the artifact converged.

Keep one thread per topic; spin a new thread file if a tangent appears.

Step 3 — IMPLEMENT (implementer role)

Once the artifact converges:

• In-session implementer: implement directly (or via a Task subagent / worktree-isolated agent), following the repo's TDD + quality-gate cadence.
• External implementer (e.g. Cursor): emit a precise handoff prompt — scope to one story/task, name exact files + line anchors from the converged plan, the test cases, the boundary ("don't do X — that's a later story"), the gate command, and the PR title. Tell the user to relay it. Recommend a dedicated git worktree off the base branch (and copying any gitignored .env).

The implementer opens a PR / diff.

Step 4 — VERIFY (planner or reviewer reviews the PR)

When the PR lands:

1. Pull the diff; check it against the converged plan at source (read the actual changed files, not just the PR body) — requirements met, scope boundary respected, no scope creep.
2. Confirm CI is green (and that skipped gates — e.g. a browser smoke — are flagged, not silently dropped).
3. Report a verdict; on approval, merge. Surface any carry-over items.

Then loop to Step 1 for the next task/story, accreting per-task plans into the tasks doc and reviewing each in the same thread.

Any agent, any order

The three roles are independent, so non-default orderings are first-class:

Ordering	Use
plan → review → implement (default)	greenfield feature
review → plan	red-team an artifact someone else already wrote, then re-plan
implement → review	post-hoc review of an existing change (PR review)
plan → implement → review	when speed matters and review is a final gate
reviewer == planner's critic across N rounds	iterate one artifact to convergence before any code

And the agents are swappable per round: Claude can plan one story and review the next; Codex can review while Gemini plans; Cursor or a Task subagent implements. Just re-assign roles at Step 0 of each round.

Conventions

• Files per topic: <topic>-design.md (artifact, incl. ## SRS), <topic>-tasks.md (per-task plans), <topic>-review-thread.md (the dialogue). Review threads are durable — code comments may cite their dated decisions.
• Pyramid everywhere: every thread post + handoff leads with the position/recommendation; justify after.
• Verify before accepting: re-read cited file:line at the source before folding in a reviewer delta or trusting a PR body.
• Doc-only vs code gates: doc/thread edits skip heavy gates; the implementer's code change runs the full gate suite once before commit.
• Convergence is explicit: a Final-ACK marker from the reviewer, not a vibe. Stop the monitor on close — don't burn context on no-op touches.
• One story per implementer handoff: WIP = 1; name the boundary so later-story work doesn't bleed in.

Composes with

• file-review-dialogue — the Step 2 thread mechanics (seed / monitor / respond / converge).
• grill-me — Step 1 planning interrogation (if installed).
• Monitor (built-in) — mtime watch on the review thread for async external reviewers.
• Task tool — for any role whose agent is an in-session subagent.
• Quality-gate / PR-review skills — Step 4 verification.

Notes & limits

• The orchestrator can directly drive only in-session agents; external agents (Codex/Cursor/etc. in their own terminals) are human-relayed via files + prompts. The skill makes that relay explicit rather than pretending to call them.
• A newly-created skill becomes invocable in the next session (skills load at session start).
• To promote this to a plugin later: bundle this SKILL.md plus a /tri-agent-loop slash command and optional reviewer/implementer subagent definitions under a plugin marketplace entry.