Skip to main content

Orchestrator Mode — Sub-Agent Dispatch Rules

These rules govern when the main session ("the orchestrator") delegates to sub-agents versus working inline. They load at every session start (no paths: frontmatter — same priority as CLAUDE.md). Companion to the "Sub-agent and thinking rules" block in CLAUDE.md (model selection) and to the orchestrator-related feedback memories under ~/.claude/projects/<project>/memory/.

Repo-default code waves still use Explore -> Implement -> Validate -> Tenets. Docs-only Copilot waves may instead use Explore -> Implement -> Verify, where Verify is the docs-only name for the validation step and inherits the same FAIL -> Implement loop semantics. The committed GPT-5.5 high default docs-only Copilot carve-out is defined in .github/copilot-instructions.md and .github/instructions/valenar-docs-wave.instructions.md.

Rules​

  • Multi-wave / multi-file work defaults to orchestrator mode. First move is dispatch, not Read/Grep/Edit. Orchestrator-allowed tools: Agent, TodoWrite, mark_chapter, and short Read / Glob only when drafting an agent prompt. Bash, Grep, Edit, Write on substantive work are sub-agent territory.
  • Wave / Phase / Step N is a dispatch graph, never an inline checklist. Every named step is at minimum one Agent call. The repo-default 4-step protocol (Explore Sonnet -> Implement Opus -> Validate Sonnet -> Tenets Sonnet) means four dispatched sub-agents per wave, not four inline phases. Docs-only Copilot waves still dispatch every step, but may use Explore -> Implement -> Verify under the committed GPT-5.5 high default policy instead.
  • Explicit orchestrator-chain prompts suspend inline project work. If a prompt explicitly assigns the main agent as orchestrator and names the required agent chain or an explicit wave order, the first project move must be dispatch to the named first agent. Before that dispatch, no inline repo reads, greps, edits, validation, or synthesis may occur.
  • Named explorer -> implementer -> verifier prompts are dispatch-or-blocked. If a prompt explicitly assigns the main agent as orchestrator or requires the exact named agents explorer, implementer, and verifier, the orchestrator switches into dispatcher-only mode. The first project move must be a real dispatch to explorer. If that real named-agent dispatch cannot be performed in the current environment, stop and report exactly: Blocked: this environment cannot perform the required explorer -> implementer -> verifier named-agent orchestration.
  • Docs-only named-chain dispatches start with the mandatory hardening prefix. When the exact explorer -> implementer -> verifier chain is active, every explorer, implementer, and verifier dispatch prompt starts with the full hardening prefix from COPILOT_ORCHESTRATION_HARDENING_PROMPT.txt. The prefix comes before the Wave Brief, task body, or failure list. Missing or altered prefix text is a process FAIL, and verifier must report it from dispatch prompt evidence instead of judging only final files.
  • First response on a multi-wave prompt is a dispatch. No "let me orient myself first" greps — the Sonnet exploration agent does the orientation. One short Read / Glob to verify a path before writing the dispatch prompt is allowed; a forensic grep is not.
  • The short Read / Glob allowance does not apply to named-chain hard mode. When the prompt requires the exact named-agent chain explorer -> implementer -> verifier, there is no inline inspection allowance before the first real explorer dispatch. The orchestrator must dispatch or stop blocked.
  • Named-chain hard-mode drift is a stop, not an inline recovery path. If the orchestrator notices inline exploration, broad repo inspection, or non-agent analysis after named-chain hard mode activates, stop immediately and report PROCESS FAIL: named-chain hard-mode drift. Do not continue the wave inline; restart from the current wave's first incomplete named step with the full hardening prefix.
  • Exact configured agent names stay exact. When active guidance specifies exact sub-agent names, dispatch those names exactly as written. Do not rename, alias, substitute, or append model assignments to them.
  • File-disjoint waves dispatch in parallel. Single message, multiple Agent tool blocks. Serial dispatch where parallel is possible is a process failure.
  • Forensic findings come from sub-agents, not from inline orchestrator greps. Inventory tables, root-cause analyses, file-by-file audits → Sonnet exploration agents → quoted in the final report. The orchestrator does not assemble them inline.
  • Simulation does not count as dispatch. TodoWrite entries, plans, wave briefs, status text, prose roleplay, "dispatching..." claims, manual summaries, inline reads, inline edits, and inline validation are not dispatches and never satisfy Explore, Implement, Verify, Validate, or Tenets.
  • Named steps require matching in-thread sub-agent evidence. Explore, Implement, Verify, Validate, and Tenets count only when the corresponding dispatched sub-agent returned a result in-thread. Inline orchestrator work never satisfies those steps.
  • Status claims require matching evidence. The orchestrator must not claim or imply that a named step ran, passed, failed, or completed unless the matching sub-agent result exists in-thread.
  • FAIL -> auto-dispatch. A Validate, Verify, or Tenets-check sub-agent returning FAIL ⇒ immediately re-dispatch the Implement agent with the failure list, then re-run the matching validation agent. In docs-only named-chain hard mode, the only legal repair lane is implementer with the exact failure list, then verifier. No permission check, no inline patching, no prompt patching, and no orchestrator synthesis in between.
  • Do not claim unsupported wave outcomes. Do not report explorer findings without explorer output, implementer changes without implementer output, verifier PASS/FAIL without verifier output, or wave completion without the full required dispatch sequence.
  • mapv10 dispatches start with the mandatory prefix. Every mapv10-explore, mapv10-implement, mapv10-validate, and mapv10-tenets-check dispatch prompt starts with the full TENETS block plus forbidden-pattern list from examples/map/mapv10/wave-protocol.md Part 0. The prefix comes before the Wave Brief or failure list. Missing or altered prefix text is a process FAIL, and validators/tenets-checkers must report it instead of judging only final files.

Final reporting requirements​

For future orchestrated runs, the final report must include:

  • Waves run.
  • Actual agents dispatched.
  • Verifier PASS/FAIL history.
  • Failure loops and their resolutions.
  • Files changed.
  • Validation performed.
  • Blockers.
  • Explicit confirmation that no inline work replaced agent dispatch.

If transcripts, tool traces, or log IDs are exposed in the environment, reference or summarize them in that report.

Meta-fix exception​

Edits that only change CLAUDE.md, .claude/rules/, settings, hooks, or auto-memory files are small and self-contained. The orchestrator may execute these inline rather than dispatching. The exception applies only to files that govern Claude's own behavior — not to project source, docs, or tests.

This exception does not apply when the prompt explicitly sets the main agent as orchestrator, specifies exact sub-agent names, or gives an explicit wave order. Those prompts still require dispatch-first execution and in-thread sub-agent evidence for every named step.

Source freshness and no-fallback redesign propagation​

  • Chat history, Repomix bundles, and uploaded summaries are seed evidence only. They anchor orientation but are not authoritative. The first project move is always a Read of the committed repository files in scope. Never act on memory of a prior session's file contents without re-reading the live file.
  • A committed redesign overrides the entire artifact class — no aliases, no defaults, no formal synonyms. When a design decision retires a name, term, or structural pattern, every live artifact class in scope (docs, .secs source, compiler-owned generated output, retained Generated surfaces, engine code, tests, guidance, and agent definitions) must reflect the current form. Do not keep the old form as a fallback default, a compatibility alias, or a transitional synonym. If the user has not issued a deliberate migration prompt covering the specific artifacts, those artifacts are out of scope for this wave — report them as follow-ups rather than resolving them silently or keeping both forms live.
  • File renames as a side effect are an absolute stop. If executing a wave would require renaming an existing file as a side effect of applying the committed redesign, stop immediately. Do not rename the file. Do not create a redirect stub. Report the rename as a blocker and request a separate deliberate migration prompt that names the exact source and destination paths. Renames without an explicit migration prompt are a process FAIL.

Why these rules exist​

See the corresponding feedback memories for incident history and rationale: feedback_orchestrator_default.md, feedback_dispatch_first_action.md, feedback_parallel_disjoint_waves.md, feedback_no_inline_synthesis.md.

Sub-agent execution guards​

Every dispatched sub-agent — regardless of wave or model — must:

  • Not spawn further sub-agents. Forbidden tools: Agent, Task, spawn_task, ScheduleWakeup, CronCreate, and any other scheduling tool. Deferred work belongs in the sub-agent's response text.
  • Respect wave scope. If the brief says docs-only, do not work around that limit by editing code, Content, Generated, runtime, client, server, src, tests, or build files.
  • Not invent .secs source keywords or clauses not in the committed keyword list (see CLAUDE.md).
  • Not create .secs files to satisfy provenance checks or any test.
  • Not silently absorb a deviation from the wave spec. Deviations are reported to the orchestrator in the response, not quietly accepted.

Resolver dispatch​

The resolver role is documented at .claude/agents/resolver.md. This section defines when the orchestrator dispatches it and what authority it holds.

When to dispatch. Every point where the wave protocol would otherwise halt and wait for user input is a resolver dispatch point. Resolver is for concrete blockers that would otherwise force a user question or halt; it is not a substitute for ordinary planning, coverage-matrix drafting, or routine artifact selection. This includes, but is not limited to:

  • An artifact class required by the wave is missing from the coverage matrix or does not exist on disk.
  • A redesign-vs-patch ambiguity: the wave brief says to fix a subsystem, but the correct fix requires a deeper structural change and the implementer cannot determine scope from the brief alone.
  • Conflicting designs appear in chat history or between doc surfaces, and the correct canonical form is not clear from the committed files.
  • A new doc prefix, file naming convention, or vocabulary term is needed and has no established precedent in the current rule files.
  • The verifier FAIL loop has cycled more than once on the same implementer with the same root cause and no progress — the problem is structural, not a content regression.
  • A sub-agent believes a mutating/destructive command (git stash, git reset, git clean, rm -rf, or anything on the zero-exception ban list) is required to proceed — dispatch resolver instead of executing it. Resolver finds the non-destructive alternative or returns RESOLVER_BLOCKED.
  • Any ASSUMPTION embedded in a sub-agent's output that would otherwise block the next agent from proceeding.

Authority scope. The resolver decides every non-destructive blocker question: design, scope, redesign-vs-patch, file structure, AAA technique selection, prefix selection, missing-artifact-class handling, retry-vs-escalate, naming, layout, vocabulary splits, and ASSUMPTION resolution. Routine planning, ordinary coverage-matrix choices, and non-blocking synthesis stay with the orchestrator or explorer; they are not resolver work. The resolver's first move is always to inspect the artifact(s) referenced in the blocker — it does not re-decide without reading the evidence.

Authority limits. The resolver cannot authorize commands on the zero-exception ban list of mutating/destructive git or file-recovery commands (git stash, git reset --hard, git checkout -- file, git restore, git clean, git rebase, force-push, rm -rf, empty-redirect clobber, find -delete, and equivalent destructive operations). Read-only git evidence gathering remains allowed where other guidance already permits it. The resolver cannot authorize out-of-band actions (production secrets, prod database modifications, security-sensitive operations). When either limit applies, it returns RESOLVER_BLOCKED: <reason> and the affected wave defers to morning user review. Other waves continue unless they share the same blocked dependency.

Output formats. The resolver returns exactly one of three structured outputs per dispatch:

  • RESOLVER_DECISION: — a clean decision backed by tenet application and on-disk evidence.
  • RESOLVER_ASSUMPTION: — a best-guess decision made with thin evidence, explicitly flagged for user morning review.
  • RESOLVER_BLOCKED: — the only legitimate halt; applies only to the zero-exception ban list and out-of-band actions.

The resolver does NOT return "I'm not sure, please clarify." That defeats its purpose.

No dispatch cap. The resolver may be dispatched unlimited times per wave. There is no retry cap and no run-duration cap.

Final report requirement. Every resolver dispatch and its decision (RESOLVER_DECISION, RESOLVER_ASSUMPTION, or RESOLVER_BLOCKED) must be recorded in a ## Resolver decisions section of the final orchestration report. This section must list each dispatch in order: blocker described, decision returned, evidence consulted.

Validate / Verify-agent responsibilities​

A Validate or docs-only Verify sub-agent must inspect:

  • The wave's sub-agent dispatch prompts (if available in the thread).
  • Deviation notes produced by prior sub-agents in the thread.
  • Reviewer approvals referenced in those notes.

Verify output must enumerate each acceptance item bullet-by-bullet as PASS or FAIL, citing the evidence used, the command/test run or inspected artifact, and any remaining gap.

Validating only final files while ignoring deviation notes and prompt deviations is a false PASS. If a prior sub-agent invented source syntax, violated a docs-only write scope, or fabricated a .secs file without explicit orchestrator approval, the Validate or Verify agent must report FAIL regardless of whether the files pass all other checks.