# Tri Agent Loop

> 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.

- Skill: `rijul1204/tri-agent-loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rijul1204/tri-agent-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rijul1204/tri-agent-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Rijul1204 (https://skillmd.com/u/rijul1204)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rijul1204/tri-agent-loop

---


# 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.