supervise-loop

An autonomous supervisor → worker → critic iteration loop for Claude Code.

English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇪🇸 Español • 🇫🇷 Français • 🇩🇪 Deutsch • 🇵🇹 Português • 🇷🇺 Русский

Problem • How it works • Comparison • Install • Usage • Design • 中文

---

You state one goal, once. A supervisor agent turns it into a checkable acceptance rubric, delegates the work to a worker sub-agent, grades every round with mechanical checks plus a separate critic sub-agent, and re-dispatches with targeted feedback — round after round, with no human in the loop — until the rubric passes or a hard cap is hit.

It is the evaluator-optimizer pattern fused with orchestrator-workers, hardened with the convergence and anti-thrash guardrails that grassroots single-agent loops lack. The load-bearing idea: the agent that judges the work is never the agent that did it.

🩹 The problem

The default agent flow has three friction points:

1. The agent does the work itself, then stops.
2. Mid-task it keeps asking you to pick between options — breaking your flow.
3. The result often misses the mark, so you iterate by hand, over and over.

supervise-loop removes all three. The supervisor never touches the deliverable, never asks you to choose mid-loop, and keeps iterating autonomously until an objective quality bar is met — not until it feels done.

	Default agent	supervise-loop
Who does the work	the agent itself	a worker sub-agent
Who judges "done"	the same agent (self-grades)	mechanical checks + a separate critic
Mid-task questions	frequent	none (unless --gate)
When it stops	after one pass	when the rubric passes or it hits --max-rounds

⚙️ How it works

flowchart TD
    G([One goal]) --> R[Supervisor builds a checkable rubric]
    R --> W[Dispatch worker sub-agent]
    W --> M[Run mechanical checks<br/>tests · lint · build]
    M --> C[Separate critic sub-agent<br/>scores vs the rubric]
    C --> D{All mech pass<br/>AND critic == PASS?}
    D -- yes --> A([APPROVED ✓])
    D -- no --> B{Backstops:<br/>cap · stuck · regression?}
    B -- keep going --> F[Fold feedback forward] --> W
    B -- exhausted --> E([MAX_ROUNDS / NOT_VERIFIED / STUCK<br/>return best partial + scorecard])

Three roles, kept strictly separate:

• Supervisor (the main agent) — routes, decomposes, runs mechanical checks, decides pass/revise/stop, loops. Never writes the deliverable.
• Worker (sub-agent) — does the actual work, persists to files, reports what changed. Never declares itself done.
• Critic (a separate sub-agent) — adversarially scores the deliverable against the rubric and returns PASS | REVISE | FAIL with per-finding feedback. Never contributes fixes.

Every round ends in one explicit terminal state: APPROVED, MAX_ROUNDS_REACHED, NOT_VERIFIED, or STUCK — and always returns the best artifact plus a per-item rubric scorecard, never a vague "it's basically done."

🆚 vs other loops