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

	Built-in /loop	ralph-loop	supervise-loop
Mechanism	re-runs one command on a timer	re-feeds the same prompt to one agent in-session	supervisor dispatches worker + separate critic, grades, re-dispatches
Who judges "done"	nobody (it just repeats)	the agent grades itself	mechanical checks + an independent critic
Acceptance criteria	none	a self-asserted promise string	an explicit, per-item rubric (passed to both worker and critic)
Anti-thrash / pivot	none	none	plateau detection, regression revert, pivot-on-stuck, escalate
Best for	polling / cron-style repeats	greenfield self-iteration	driving a goal to a verified bar

📦 Install

Option A — as a Claude Code plugin (recommended)

/plugin marketplace add wdzhwsh4067/supervise-loop
/plugin install supervise-loop@wdzhwsh4067

Then invoke it any time with /supervise-loop <goal>.

Option B — as a personal skill (manual)

git clone https://github.com/wdzhwsh4067/supervise-loop.git
cp -R supervise-loop/plugin/skills/supervise-loop ~/.claude/skills/supervise-loop

Restart your Claude Code session so the skill is discovered, then use /supervise-loop <goal>.

Note — the loop runs from the top-level session (a sub-agent cannot spawn the worker/critic sub-agents). It uses the Agent/Task sub-agent dispatch tool; if your harness has no such tool, the skill stops and tells you instead of silently self-executing.

🚀 Usage

/supervise-loop <goal>  [--max-rounds N] [--workers single|auto|N] [--gate] [--no-critic] [--rubric "..."]

Examples

/supervise-loop Build a working CLI todo app: add/list/done/delete, persists to JSON,
all commands have passing tests, README with usage. Don't ask me — loop until it's solid.

/supervise-loop --max-rounds 8 --gate Rewrite my landing page copy until it's punchy,
on-brand, and every claim is backed. Show me the rubric first.

Flags

Flag	Default	Meaning
--max-rounds N	5	Global hard ceiling on rounds. On cap, returns the best partial result.
--workers single|auto|N	auto	Dispatch one worker, let the supervisor decide, or fan out to N parallel workers.
--gate	off	Pause for human approval at phase boundaries (rubric, final sign-off).
--no-critic	off	Mechanical checks only — skip the LLM critic (faster, weaker).
--rubric "..."	—	Supply acceptance criteria directly instead of letting the supervisor draft them.

📂 What's in the box

plugin/
└── skills/supervise-loop/
    ├── SKILL.md                  # roles, the loop, execution model, autonomy rules, flags
    ├── references/
    │   ├── rubric-guide.md       # turn a vague goal into a checkable, mechanically-grounded rubric
    │   ├── prompts.md            # worker + critic dispatch templates and the verdict contract
    │   └── termination.md        # pass/revise/stop logic, anti-thrash, terminal states
    └── scripts/
        └── init-run.sh           # scaffolds an absolute run dir with STATE/RUBRIC/MEMORY templates

🧠 Design principles

The skill encodes a set of research-grounded rules so the loop terminates honestly rather than on vibes:

1. Operationalize "done" as a checkable rubric — give the same rubric to the worker (target) and the critic (scoring sheet); tag each item [mech] (a command that exits 0) or [judge] (critic-scored).
2. Ground every round in mechanical verification, not self-assessment — tests / typecheck / lint / build are the primary ground truth.
3. Separate the worker from the critic — the doer never grades itself.
4. Binary verdict + structured feedback — PASS | REVISE | FAIL with actionable per-finding notes; the critic flags only what affects correctness, to avoid infinite polishing.
5. Composable termination with a non-negotiable hard cap — succeed on PASS, but always AND-in a round/budget ceiling that returns the best partial.
6. Anti-thrash guardrails — plateau detection, regression revert, pivot-on-stuck, then escalate — measured from facts the supervisor records each round, not the worker's self-report.
7. No placeholders / stubs — an explicit high-priority rule, re-detected each round.
8. Autonomous by default, one level deep — no mid-loop questions unless --gate; sub-agents don't spawn sub-agents.

📚 References & credits

• Anthropic — Building Effective Agents (evaluator-optimizer, orchestrator-workers)
• Anthropic — Demystifying evals for AI agents
• Geoffrey Huntley — the Ralph technique (single-agent self-iteration; the grassroots cousin)
• Packaging conventions modeled on thedotmack/claude-mem.

🀄 中文说明

一句话：你只发布一个目标，主 Agent 当监工（自己不干活），定好可验收的标准，派给子 Agent 干活，每轮用机械检查（测试/lint/build）加一个独立的评委子 Agent 打分审查，不达标就带着反馈打回重做——全程不问你——直到验收单全过或撞到 --max-rounds。

这正是大家在找的"loop"：评估器-优化器 + 编排器-工人模式。比现在很火的 ralph-loop 强在那个独立评委——防止 Agent 自己给自己盖章说"做完了"。

• 安装：/plugin marketplace add wdzhwsh4067/supervise-loop 然后 /plugin install supervise-loop@wdzhwsh4067
• 使用：/supervise-loop <你的目标>，加 --gate 可在关键节点让你确认，默认全自主。

📄 License

MIT © 2026 王少煌 (wdzhwsh4067)