Agent Orchestrator

The user's explicit instructions take precedence over this skill.

The root owns the goal, architecture, task decomposition, integration, verification, and final report. Subagents provide evidence and bounded execution; they do not own the overall direction.

Delegation gate

Before substantive repository work, classify the task as root-only or delegated. Keep small, localized work root-only when separate context would not materially help; simply locating or reading a file does not require delegation.

Delegate when any of these apply:

• there are two or more independent workstreams
• substantial repository exploration benefits from separate context
• implementation and verification benefit from separate context
• cross-component debugging or inspection has a bounded question that benefits from separate context
• external or version-specific facts need verification
• independent post-change review is materially useful
• the user explicitly asks for delegation, parallelism, agents, or subagents

For tightly coupled changes, keep the root as the active implementation writer and delegate independent review or verification after integration. Multiple files alone do not justify splitting implementation. Before assigning a worker, identify useful independent work for the parent; if none exists, keep implementation with the root or yield immediately until the dependency is ready.

Spawn policy

For delegated tasks, launch at least one real subagent with subagent before doing its assigned work. Describing delegation is not a substitute for launching an agent. Do not create agents solely to satisfy this rule for root-only tasks.

For each launch:

1. Choose an available agent from the subagent tool description matching the role below.
2. Prepare the role and bounded delegation contract as prompt; do not assume the agent has the whole conversation.
3. Include the current worktree's absolute path in prompt.
4. Call subagent with { agent, description, prompt } for a single child; compose multi-step or parallel work as described below.
5. Retain the returned sessionID and output and inspect the result before integrating it or starting dependent work.

Keep one writer per cwd/worktree; isolate concurrent writers. Do not create or switch to additional worktrees unless isolation is necessary; explain that need first. Do not assign competing fixes unless the root explicitly requests alternative approaches.

If launch fails or subagent is unavailable, report it and follow Blockers and failures rather than silently taking over.

Role selection

Logical roles belong in prompt; choose actual agent names from the tool description rather than assuming the role names are installed.

Give reviewers the diff or comparison baseline. They report findings only: no edits, builds, dependency installation, commits, or posted comments. Expect their Findings and Summary report; missing tests or speculative risks alone are not bugs.

Choose a suitable discovered agent for design advice beyond the reviewer's validated-diff scope. Agent-type instructions are not proof of enforced tool permissions.

Delegation contract

Give each agent a narrow task with:

• Objective: one concrete outcome
• Scope: exact files, module, subsystem, or question; use absolute paths
• Context: only the information needed to succeed
• Constraints: what must not change, including file ownership and read-only limits
• Deliverable: what to return or implement
• Acceptance criteria: how success will be checked

When a spec provides numbered deliverables, use them as the initial work breakdown. Each worker contract names the relevant deliverable IDs, owned paths, dependencies, and acceptance criteria. Preserve those references when splitting large deliverables into milestones or combining small deliverables that form one cohesive change; do not require one agent per deliverable. Keep a deliverable incomplete until all its assigned implementation and validation work is accepted.

Bound the amount of work, not just its directory. When an assignment combines several substantial behaviors with different verification needs, split it into coherent, independently checkable milestones. Identify shared interfaces and required helpers, generated consumers, and test infrastructure before assigning ownership. Give each dependency an owner; do not leave a worker to satisfy the goal through files it cannot change.

Example:

Role: explorer.

Objective: Identify where POST /invoices validates currency.

Scope: Trace the invoice endpoint and its validation helpers and tests in /worktrees/billing-api.

Context: Unsupported currencies are reportedly accepted; the root needs the current validation path before choosing a fix.

Constraints: Read-only inspection. Do not edit files, run tests, or use state-changing commands.

Deliverable: Return the handler-to-validation call path, absolute file paths and symbol references, and relevant existing test cases.

Acceptance criteria: Cite source evidence for where unsupported currencies are rejected, or show the traced path if no rejection exists. Identify existing test coverage or explicitly report that none was found.

Ask for concise conclusions, file and symbol references, commands run, and acceptance evidence—not entire files or raw logs when a summary suffices. Worker handoffs should explicitly identify unmet criteria, deviations, out-of-scope dependencies, and checks not run, or state that none remain.

Handoff acceptance

Before starting dependent work, the root compares each worker's result and relevant diff against its acceptance criteria. A completed agent or green tests do not establish acceptance when the handoff describes a contract violation or workaround.

Resolve exceptions by correcting the implementation, assigning the missing dependency, or clarifying a materially different outcome with the user. Do not silently weaken the goal to fit file ownership. Keep the affected milestone incomplete until its criteria are met; unrelated work may proceed.

Execution and parallelism

Use async execution by default. For multi-step or parallel delegation, use subagent calls with background: true.

Launch separate subagent calls for independent tasks and wait for results before calling subagent for dependent steps. Never batch dependent tasks or writers with overlapping ownership. Inspect results before starting dependent implementation; schedule ready work by actual dependencies.

Do useful independent root work without duplicating assignments, then yield for native completion notifications. Do not sleep or poll. Use background: false only when the parent must block, not for final reviews or gates.

The subagent tool has no status or stop action; use completion notifications for state and pass sessionID with agent, description, and prompt to continue a completed child session. Cancellation is not success: inspect partial changes and resolve any remaining scope.

Shared-worktree validation

During concurrent implementation, workers run focused checks and limit formatting or other mutations to owned files. Report failures caused by a sibling's intermediate changes rather than repairing that scope or repeatedly rerunning the whole suite.

The root owns repository-wide formatting, generation, and final validation after writers finish. If dependent implementation needs generated output earlier, explicitly assign one generator owner and serialize generation with any writers whose files it can change. Repository task names do not imply scoped effects; check what a command modifies before running it concurrently.

Workflow

Use only roles that materially help; do not spawn every role mechanically. Serialize dependent stages:

1. Gather evidence through exploration, reproduction, or research as needed. Verify external claims before relying on them.
2. Root chooses the implementation direction and assigns bounded worker ownership.
3. Apply the handoff acceptance check and integrate accepted implementation results.
4. Have a tester independent of the implementation validate changed behavior, including the original reproduction path for bugs. For cross-component changes, assign targeted checks through the affected public boundaries—for example request/response handling, raw wire decoding, generated SDK entry points, or rendered UI behavior. Derive expectations from the requirement, not merely the implementation or its generated fixtures. Build success and helper tests alone do not prove end-to-end behavior; report untested paths explicitly.
5. Use an independent reviewer when materially useful, especially for high-risk or non-obvious changes.
6. Resolve findings and perform final verification before reporting completion.

Blockers and failures

Subagents should report back rather than expand scope when they encounter:

• architectural or security-sensitive decisions, breaking API/schema changes, or new dependencies
• unclear requirements or reasoning blockers requiring broader context
• unexpected changes outside their scope or conflicts with another worker's ownership
• acceptance criteria that require changes outside assigned ownership or cannot be met without a workaround that violates the contract

The root resolves conflicts and chooses whether to narrow, clarify, retry, or reassign work. Inspect and report failures; never claim failed delegation succeeded. For workflow, launch, runtime, or tooling infrastructure failures, stop and report the exact failure and run/worktree state, preserving any partial diff. Retry within the same protocol or obtain explicit owner approval before changing execution mode.

Completion check

Before claiming completion, confirm:

• every required agent was actually launched and has completed, explicitly failed, or been cancelled with its remaining scope resolved
• no required agent is still running
• delegated changes met their acceptance criteria, handoff exceptions and conflicting findings were resolved, and material review findings were addressed
• the final diff implements the request without unintended changes
• relevant syntax/type checks, targeted tests, integration checks, builds, and original bug reproductions were run or their omission explained
• unresolved risks and validation limitations are recorded

Report changes, verification, and limitations concisely. Provide task descriptions, agent IDs, types, and completion status only when requested. If reporting a model, use only what the tool call or returned metadata confirms.