Orchestration

Orchestration — Multi-agent loop

A workflow for orchestrating complex tasks across specialized agents: workers implement, validators verify, verifiers critique with adversarial eyes. The main session is the orchestrator — it plans, dispatches, integrates, and decides when to ship.

This skill is not a script you run. It is a mental model + persona library + workflow template that the orchestrator (you, the main session) loads when a task is too big or risky for a single linear pass.

When this fires (and why it works)

A single linear pass works fine for "fix this typo" or "rename this variable." It breaks down when:

• The task spans multiple files or domains (frontend + backend + DB, or design + functional + security).
• The user values quality higher than speed ("1티어", "prod-ready", "real users will see this") and a single Claude session — even a careful one — can miss things its own bias hides.
• The work needs adversarial eyes the orchestrator can't provide for itself (testing its own design, reviewing its own code).
• The user explicitly wants autonomous progress without micro-confirmation at each step.

The pattern works because each agent gets a fresh context and a narrow remit. The worker implementing a fix can't sneak its own design opinions past a validator who has never seen the code before. The orchestrator stays clean — it doesn't try to be implementer + critic + tester at once.

Four phases

Phase 1 — Audit (parallel-safe, read-only)
   ↓ findings + fix proposals
Phase 2 — Implement (serial, fresh worker per feature)
   ↓ commits + 5-field handoffs
Phase 3 — Verify (independent context, adversarial)
   ↓ PASS / NEEDS_REVISION / FAIL
Phase 4 — Loop
   ↓ NEEDS_REVISION → critique-driven fix worker → back to Verify
   ↓ PASS → ship + report

Phase 1 — Audit + Research

Before any code changes, dispatch read-only workers in parallel to map the territory. Two distinct directions, both read-only, both safe to run in one batch:

Audit Worker — reads YOUR codebase. Three common audit assignments (same persona, different task):

• Domain Audit — map current code + DB + business rules against the proposed change. Returns: where the change touches, what invariants matter, what edge cases lurk.
• Codebase Audit — find structural opportunities (deepening, DRY, dead code). Returns: prioritized refactor candidates with deletion-test reasoning.
• Design Audit — 1-tier designer eyes on the current screens. Returns: typography / spacing / color / hierarchy issues with reference patterns.

Research Worker — reads the OUTSIDE WORLD. Dispatch when a decision needs facts the codebase doesn't contain:

• Library behavior / version differences (does react-aria MenuTrigger handle keyboard escape?).
• Spec / RFC questions (what does the W3C ARIA spec say about menu focus management?).
• Prior art / best practice surveys (what auth approach do similar Postgres + Next.js apps use in 2026?).

Audit and Research can run in parallel — different sources, different tools, no conflict. Skip either when the task is small and the territory is well-known. Don't skip Audit when you don't already know "where does this live and what does it touch?" Don't skip Research when the implementer would otherwise guess at library behavior from training memory (which may be stale).

Phase 2 — Implement

Serial. One worker at a time. Next worker inherits the previous commit via git. This avoids merge conflicts and keeps the architecture coherent.

Branch first. Before the first implementer, cut a named orchestration branch (orch/) off the base; workers commit there, never straight onto the user's main or working branch. This makes the whole loop disposable — a FAIL or a wrong direction becomes a branch you abandon, not history you have to surgically unpick. The ledger records each commit's state (accepted / superseded / reverted / abandoned); only accepted SHAs reach the merge target. Full mechanics in workflow.md → Branch & rollback strategy.

The exception: workers in completely separate file regions (e.g., a frontend page and a backend endpoint that don't share files) can run in parallel — but only when you've verified there's no overlap. When in doubt, serial.

Each worker:

• Gets a fresh context (a clean Agent dispatch, not a continuation).
• Implements one logical commit worth of work. Big changes split into 2-4 commits.
• Returns a 5-field handoff (see Structured handoff below).

Phase 3 — Verify

Independent context. Each verifier has never seen the code. This is the whole point.

Verifier intensity scales with the commit's risk tier — not a flat default. The risk tier is set during sizing (workflow.md) and recorded in the ledger before dispatch; matching verification to risk is what separates a loop people actually run from one too expensive to use. The verifier types, and when each runs:

1. Functional Verifier — does it work? Runs npx tsc --noEmit / npm run build / pytest / linters. Re-traces the diff against the original task. Checks edge cases, error paths, security boundaries. Reads the [General] Functional correctness + [General] Surgical scope + [General] Layout shift + stack-specific functional rules in scrutiny-rules.md.
2. Architecture Verifier — is it well-built? Critiques HOW the change is implemented: DRY, simplicity, deepening, N+1 / perf, dead code, premature abstraction, terminology consistency. Reads the [General] Simplicity + [General] DRY violations + [General] Terminology consistency + stack-specific architecture rules ([ORM] N+1 absolute prohibition, etc.) in scrutiny-rules.md.
3. Black-User E2E Validator — does a clueless real user succeed? Drives the actual running app via playwright / simctl. Logs in as a real user with no prior knowledge of the diff or the codebase — only knows the user-facing task ("add a deal", "view this month's settlement"). Looks for what only a fresh user would notice: confusing labels, dead-end flows, regressions in adjacent screens.

Plus, conditional:

1. Design Verifier — is it 1-tier quality? Senior designer persona, plays back screens, critiques typography / color / spacing / hierarchy against named reference tiers (Stripe / Linear / Apple). Dispatch only when the commit touched UI.

Budget by risk tier — pick the row matching the commit's tier and record it in the ledger before dispatching:

| Risk tier | What it is | Verifier budget | |---|---|---| | Low | cosmetic / a 1–3 line const / comment / isolated rename — no money, no security, no UI or flow change | orchestrator local checks (typecheck / build if cheap) + 1 Functional Verifier. Architecture optional. | | Medium | ordinary feature or refactor logic — no money math, no security boundary | Functional + Architecture (the classic pair). | | High | money math, a security / permission boundary, data isolation, or a named 1-tier UI bar | Functional + Architecture + Black-User E2E and/or Design and/or a security-focused pass — verifiers escalated to the frontier tier. | | Critical | settlement correctness, auth / permission, destructive ops | everything in High + a frontier tie-breaker or a human gate before ship. |

Functional + Architecture are the floor for Medium and up — they answer the two questions every non-trivial change must pass (does it work? / is it well-built?), and one verifier in one context can't do both at adversarial depth. Only Low-risk commits drop to a single functional check; never run zero verifiers. When unsure which tier, round up — one extra verifier costs far less than a missed money/security bug, but a flat 3–4 on every trivial commit is the over-verification that makes the loop too slow to actually use.

iOS / mobile stack: Functional Verifier 는 XCUITest 실행 의무. Code trace 만으론 false positive 잦음 (예: testBackPreservesSession 가 PASS 단 실제 사용자는 lost — assertion 약함). XCUITest 가 진짜 end-user gesture verify. xcodebuild test -only-testing: 통과가 PASS 의 1st signal.

Model: inherit by default, escalate by risk — see [Model policy](#model-policy). Fresh context + an adversarial prompt is what catches most issues, so a cost-efficient verifier with clean eyes is the right default. But raw capability is what catches the subtle miss — a hidden cross-file N+1, a total that's off by VAT, a boundary that leaks on one code path only — so escalate verifiers to the frontier tier when the commit carries money math, a security boundary, or a named 1-tier quality bar.

**Main session does zero product verification — but mandatory meta-verification. Don't be the fifth opinion on whether the code is good or the design is 1-tier: dispatch a fresh verifier, because you carry the same blind spots as the worker. But you are the ship-decider, so the process evidence is yours to check, not to take on faith.** Independently confirm git status is clean, that the commands a worker or verifier claims to have run actually exited 0, that named artifacts exist, and that the handoff's claims — "tests pass", "0 skipped", "only X touched", "surgical" — match the actual tree. A handoff that reports "12 passed, 0 skipped" over a skipped test, or "surgical" with a stray file committed, gets caught here. Never take the handoff's word over the evidence.

Phase 4 — Loop

Verifier returns one of four verdicts:

• PASS — ship. Report to user.
• PASSWITHCONCERNS — ship the main change. Concerns become follow-up tickets (backlog).
• PASSWITHUNVERIFIED — ship, but a declared pass-check couldn't be verified; record the gap in the user-facing report. Non-blocking unless a HIGH+ finding backs it.
• NEEDS_REVISION — dispatch a fix worker with the verifier's critique handed in verbatim. Then re-verify.
• FAIL — wrong direction, broken approach, or a missing assumption. Don't just dispatch another fix worker: git revert the rejected commit(s) (when later work sits on top) or abandon the orchestration branch (when the whole direction was wrong), then stop and rethink — usually surface to the user. Never carry rejected code into the merge target.

Aggregating verifiers — gate on evidence, not just severity (the orchestrator's rule). Don't improvise the tie-break — but don't treat every HIGH as ground truth either. A verifier can be wrong, over-severe, stale, blocked by a missing environment, or making a subjective call no other verifier can contradict. So weigh severity × evidence:

• A finding blocks (CRITICAL → FAIL; HIGH → NEEDS_REVISION; FAIL if a CRITICAL is also present) only when it carries reproducible evidence — a failing command, a concrete file:line, or a named pass-criterion it violates. A bare assertion is not enough at HIGH+.
• A HIGH/CRITICAL without that evidence does not block on its own: route it to one challenge (tie-breaker) verifier, or record it as PASSWITHUNVERIFIED. Promote it to blocking only if the challenge verifier reproduces it.
• 3+ MID with evidence, across all verifiers combined → NEEDSREVISION; otherwise PASS / PASSWITHCONCERNS / PASSWITH_UNVERIFIED (all non-blocking).
• Dispatch a single challenge verifier when verifiers assert contradictory facts (one calls a query an N+1, another calls it batched), or when a blocking finding is disputed, unsupported, environment-blocked, or a subjective design call. Challenge/tie-breaker rounds don't count against the 5-round cap — they resolve verifier disputes, not implementation defects.

Round cap: 5. If verification still fails after 5 rounds, the issue isn't implementation — the reference / direction is wrong. Stop and surface this to the user: "we've tried 5 rounds, the gap suggests we're aiming at the wrong target." (Only implementation fix rounds count toward the cap; challenge/tie-breaker rounds that resolve verifier disputes don't.)

Personas

This skill carries nine reusable agent personas, each in its own file under references/personas/. When dispatching, point the worker at its own persona file — the worker reads references/personas/.md + references/personas/_universal.md and follows them. When a persona prompt references `, substitute this skill's absolute root path (e.g. ~/.claude/skills/orchestration) before dispatching, so the worker gets a real openable path. Don't load all the persona prose into the orchestrator's context; the prose belongs with the worker that uses it. references/personas.md` is the index (which persona, which file).

| Persona | Role | Mandatory tool | Tools | When to dispatch | |---|---|---|---|---| | Domain Audit Worker | Map territory inside the codebase before changes | — | Read, Grep, SQL via MCP if available (prefer a read-only agent type like Explore when your harness offers one) | Phase 1, before any non-trivial change | | Research Worker | Investigate external knowledge — library docs, specs, prior art | — | WebFetch, WebSearch, Context7 MCP | Phase 1 (parallel to audit), or whenever a decision needs facts the codebase doesn't contain | | Feature Implementer | Build NEW behavior → one commit | — | Read, Edit, Write, Bash | Phase 2, when the assignment adds new behavior | | Refactor Implementer | Restructure WITHOUT changing behavior (DRY / consolidation / deepening) | Full existing test suite still green | Read, Edit, Write, Bash | Phase 2, when the assignment is structural-only | | Fix Implementer | Fix a broken behavior using TDD (failing test first, then green) | Reproducer test that fails before, passes after, fails again when fix inverted | Read, Edit, Write, Bash | Phase 2, when the assignment is a bug / regression / wrong calculation | | Functional Verifier | Does it work? — builds, tests, scope, correctness, security | xcodebuild test -only-testing: (iOS) | Read, Bash | Phase 3 — floor: runs at every tier | | Architecture Verifier | Is it well-built? — DRY, simplicity, perf (N+1), deepening, dead code | — | Read, Grep, Bash | Phase 3 — Medium+ (floor pair w/ Functional) | | Black-User E2E Validator | Does a clueless user succeed? — drives running app as fresh user | Playwright (web) / XCUITest (iOS) | playwright MCP, Bash | Phase 3 — High risk / any user-visible change | | Design Verifier | Is it 1-tier quality? — typography / color / spacing critique | — | playwright MCP, Read | Phase 3 — when UI touched (High+) |

Model choice is deliberately not a column here — pin it by tier and risk, not by version name. See [Model policy](#model-policy) below.

See references/personas/ for per-persona prompt templates (index + grouping notes in references/personas.md). See references/workflow.md for detailed phase-by-phase mechanics and decision trees.

Model policy

The old rule was "Sonnet for everything, Opus only for creative implementers." It was written when the orchestrator itself ran on a mid-tier model and token cost dominated every call. Two things have since changed, and the policy moves with them:

1. Sessions now routinely run on a frontier model (the strongest available — Opus 4.8 and up). An orchestrator that capable shouldn't reflexively hand every worker a weaker brain.
2. The dispatch tools now default a sub-agent to inherit the orchestrator's model unless you override. Inheriting is almost always correct — so not pinning a model is the new default, and a pin is the deliberate exception.

The principles:

• Don't pin a model name. Inherit by default. A dispatched agent inherits the session model unless told otherwise, and that's usually right. Hard-coding "Sonnet" freezes the skill to whatever that alias meant the day it was written — it silently ages every time the model line moves (4.6 → 4.8 → …). Express intent as a tier + reason, never a version.

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WonjunJoe
• Source: WonjunJoe/claude-orchestration-skill
• License: MIT

Install and usage instructions live in the source repository linked above.