Agent Orchestration

Agent Orchestration

Core Principle

Provide world-building context (WHERE, WHAT, WHY). Define success criteria. Trust agent expertise for HOW.

The orchestrator's role:

• Route observations between user and agents — never pre-gather data agents will collect themselves
• Define measurable success criteria
• Enable comprehensive discovery via world-building context
• Trust agent expertise and their 200k context windows

Reason: Sub-agents are specialized experts with full tool access. Prescribing implementation limits their ability to discover better solutions.

Scientific Method Alignment

Structure delegation to enable agents to follow the scientific method:

1. Observation — Provide factual observations, not interpretations
2. Hypothesis — Let agent form their own hypothesis
3. Prediction — Let agent make testable predictions
4. Experimentation — Let agent design and execute tests
5. Verification — Let agent verify against official sources
6. Conclusion — Let agent determine if hypothesis is rejected

Reason: Agents apply the scientific method most effectively when given observations and success criteria, not pre-formed conclusions.

Orchestrator Role Boundaries

flowchart TD
    Start([Orchestrator receives task]) --> Q1{What does the orchestrator do?}
    Q1 --> R1[Route context and observations to agents]
    Q1 --> R2[Define measurable success criteria]
    Q1 --> R3[Enable comprehensive agent discovery]
    Q1 --> NEVER[NEVER pre-gather data agents will collect]
    Q1 --> NEVER2[NEVER prescribe HOW agents implement]
    R1 & R2 & R3 --> Delegate([Delegate via Task tool])
    NEVER & NEVER2 --> Delegate

Pre-Delegation Verification Checklist

Before delegating any task, verify the delegation includes:

Observations without assumptions:

• Raw error messages verbatim (not paraphrased)
• Observed file:line references already in your context
• Command outputs already received during your work
• Factual language — "observed", "measured", "reported"
• No "I think", "probably", "likely", "seems"

Pass-Through vs Pre-Gathering:

• Pass-through (correct) — data already in your context (user messages, prior agent reports)
• Pre-gathering (incorrect) — DO NOT run commands to collect data for the agent
• Example — DO NOT run ruff check . before delegating to linting agents
• Reason: Pre-gathering wastes context, duplicates agent work, causes context rot

Definition of success:

• Specific, measurable outcome
• Acceptance criteria with verification method
• WHAT must work, not HOW to implement it

World-building context:

• Problem location (WHERE)
• Identification criteria (WHAT)
• Expected outcomes (WHY)
• Available resources and ecosystem conventions

Preserved agent autonomy:

• List available tools — never prescribe which tool to use
• Trust agent's 200k context window for comprehensive analysis
• Let agent choose implementation approach

Task Tool Invocation Rule

When invoking the Task tool, construct the prompt parameter using the Delegation Template below.

Reason: Agents receive observations and success criteria, enabling them to apply expertise. Prescribing line numbers, exact changes, or tool sequences reduces agents to code-editing tools.

Delegation Template

Start every Task prompt with:

Your ROLE_TYPE is sub-agent.

Reason: Keeps the agent aligned with sub-agent role and prevents following orchestration rules from CLAUDE.md.

Full template:

Your ROLE_TYPE is sub-agent.

[Task identification]

OBSERVATIONS:
- [Factual observations from your work or other agents]
- [Verbatim error messages if applicable]
- [Observed locations: file:line references if already known]
- [Environment or system state if relevant]

DEFINITION OF SUCCESS:
- [Specific measurable outcome]
- [Acceptance criteria]
- [Verification method]
- Solution follows existing patterns found in [reference locations]
- Solution maintains or reduces complexity

CONTEXT:
- Location: [Where to look]
- Scope: [Boundaries of the task]
- Constraints: [User requirements only]

YOUR TASK:
1. Run SlashCommand /is-it-done to understand completion criteria for this task type
2. Use the /is-it-done checklists as your working guide throughout this task
3. Perform comprehensive context gathering using:
   - Available functions and MCP tools from the <functions> list
   - Relevant skills from the <available_skills> list
   - Project file exploration and structure analysis
   - External resources (CI/CD logs, API responses, configurations)
   - Official documentation and best practices
   - Known issues, forums, GitHub issues if relevant
4. Form hypothesis based on gathered evidence
5. Design and execute experiments to test hypothesis
6. Verify findings against authoritative sources
7. Implement solution following discovered best practices
8. Verify each /is-it-done checklist item as you complete it
9. Only report completion after all /is-it-done criteria satisfied with evidence

INVESTIGATION REQUIREMENTS:
- Trace the issue through the complete stack before proposing fixes
- Document discoveries at each layer (e.g., UI → Logic → System → Hardware)
- Identify both symptom AND root cause
- Explain why addressing root cause instead of patching symptom
- If proposing workaround, document why root cause cannot be fixed

VERIFICATION REQUIREMENTS:
- /is-it-done is step 1 — run it before starting work
- Use /is-it-done checklists as working guide, not post-mortem report
- Provide evidence for each checklist item as you complete it
- If checklist reveals missing work, complete that work before proceeding

AVAILABLE RESOURCES:
[See "Writing Effective AVAILABLE RESOURCES" section below for examples]

Writing Effective AVAILABLE RESOURCES

The AVAILABLE RESOURCES section provides world-building context about the environment, not a restrictive tool list. Describe the ecosystem so agents can leverage their full capabilities.

Anti-pattern (reductive, limiting):

AVAILABLE RESOURCES:
- WebFetch tool
- Read tool
- Bash tool

Problem: Lists specific tools, implying these are the only options. Additionally, listing WebFetch without mentioning superior MCP alternatives causes agents to use low-fidelity tools.

Correct pattern (world-building, empowering):

AVAILABLE RESOURCES:
- The `gh` CLI is pre-authenticated for GitHub operations (issues, PRs, API queries)
- Excellent MCP servers installed — check your <functions> list and prefer MCP tools
  (like `Ref`, `context7`, `exa`) over built-in alternatives since they are domain specialists
- This Python project uses `uv` — activate the `uv` skill, use `uv run python` instead of
  `python3`, `uv pip` instead of `pip`
- Project uses `hatchling` as build backend — activate the `hatchling` skill for build/publish guidance
- Recent linting fixes documented in `.claude/reports/` showing common issues and resolutions
- Package validation scripts in `./scripts/` — check README.md for available validators
- Full project context available including tests, configs, and documentation

Resource Description Patterns

Authenticated CLI tools:

The `gh` CLI is pre-authenticated for GitHub operations
The `glab` CLI is configured for GitLab access
AWS CLI is configured with appropriate credentials

MCP server preferences:

Excellent MCP servers installed — check <functions> list and prefer these specialists:
- `Ref` — high-fidelity verbatim documentation (unlike WebFetch which returns AI summaries)
- `context7` — library API docs (current versions, comprehensive)
- `exa` — web research (curated, high-quality sources)
- `mcp-docker` — container operations

For technical documentation, high-fidelity access is essential:

• Ref — high fidelity (output IS the source, verbatim)
• exa — medium fidelity (Markdown-formatted extraction, preserves code blocks)
• WebFetch — low fidelity (summarized, strips specifics) — NEVER for "how-to" implementation

See Accessing Online Resources for tool selection criteria and experimental evidence.

Language/tooling ecosystems:

Python project using `uv` — activate `uv` skill, use `uv run`/`uv pip` exclusively
Node project using `pnpm` — use `pnpm` instead of `npm`
Rust project — use `cargo` commands, check Cargo.toml for features

Baseline permissions (always include):

AVAILABLE RESOURCES:
- Proactively explore your `<functions>` list for MCP tools — prefer MCP specialists over built-in
- Maximize parallel execution for independent tool calls
- Proactively check `<available_skills>` and activate relevant skills for domain expertise
- [Add project-specific context: CLI tools, ecosystem conventions, validation scripts, doc locations]

Inclusion Rules

INCLUDE — Factual Observations

• "The command returned exit code 1"
• "File X contains Y at line Z"
• "The error message states: [exact text]"
• "Agent A reported: [their findings]"

Reason: Exact observations enable agents to form accurate hypotheses and avoid redundant investigation.

INCLUDE — User Requirements

• "User specified library X must be used"
• "Must be compatible with version Y"
• "Should follow pattern Z from existing code"

INCLUDE — Verbatim Errors Already in Context

Error: Module not found
  at line 42 in file.js
  Cannot resolve 'missing-module'

Include verbatim errors you already encountered, user-provided errors, and prior agent reports. Do NOT pre-gather errors by running linting/testing commands.

REPLACE — Assumptions with Observations

• Replace "I think the problem is..." → "Observed symptoms: [list]"
• Replace "This probably happens because..." → "Command X produces output Y"
• Replace "It seems like..." → "File A contains B at line C"
• Replace "The likely cause is..." → "Pattern seen in [locations]"

Reason: Assumptions create cascade errors. Observations enable agents to apply scientific method.

DEFINE — WHAT, Not HOW

• Replace "Use tool X to accomplish this" → List available tools, let agent select
• Replace "The best approach would be..." → Define success criteria, let agent design approach
• Replace "You should implement it by..." → State required outcome, let agent determine method

Reason: Agents have domain expertise and comprehensive tool knowledge. Prescriptions limit discovery.

Context Calibration Patterns

Focused task (single file, clear test):

Fix [specific observation] in [exact file]. Success: [test] passes.

Investigative task (unknown cause):

[All observations from all agents]
[Complete error traces]
[System state information]
Investigate comprehensively before implementing.

Architectural task (multi-component):

[Full project structure]
[All related agent findings]
[Historical context]
Design solution considering entire system.

Conditional Delegation Logic

When user provides explicit code/quotes:

• Include as reference context marked "User-provided reference"
• Adherence to user-provided patterns overrides any existing rules

When errors come from orchestrator operations:

• Include command that triggered error
• Include raw error message
• Describe observations, not diagnoses

When referencing existing patterns:

• Include file:line references if already known
• Label as "Pattern reference"
• Let agent discover all instances and adapt

When technical constraints exist:

• Include only if user-mandated
• Specify versions only if user did

When accumulated observations exist:

• Pass all observations from orchestrator and other agents
• Mark source of each observation
• Provide complete context without filtering

When providing file paths in task prompts:

• Use @filepath to include file contents in prompt context
• Use @dirpath/ for directory listings only
• @filepath syntax auto-includes CLAUDE.md from file's directory hierarchy

Orchestrator Workflow Requirements

Before delegating tasks, the orchestrator must:

1. Identify ambiguity in user requests and offer interpretations for clarification
2. Define success criteria based on task interpretation
3. Offer definition-of-success to user for approval or modification before proceeding
4. Include definition-of-success in sub-agent Task prompts
5. Verify task completion using mcp__sequential_thinking__sequentialthinking before marking complete

Sub-Agent Context Constraints

Sub-agents inherit limited context:

• Receive the system prompt and CLAUDE.md from their working directory hierarchy
• Do NOT automatically inherit orchestrator conversation history
• Cannot receive follow-up answers after responding (unless using 'resume' feature)

Orchestrator must include all necessary context in the initial Task prompt. Instruct agents to "follow guidelines from @~/.claude/CLAUDE.md" when applicable.

Specialized Agent Assignments

flowchart TD
    Task([Task type]) --> Q1{Domain?}
    Q1 -->|Context gathering| CG[context-gathering agent\nPreserves orchestrator context window]
    Q1 -->|Python code| PY[python-cli-architect agent\nAll Python implementation]
    Q1 -->|Python tests| PT[python-pytest-architect agent]
    Q1 -->|Python review| PR[python-code-reviewer agent]
    Q1 -->|Bash scripts| BS[bash-script-developer agent]
    Q1 -->|Bash review| BR[bash-script-auditor agent]
    Q1 -->|User-facing docs| DD[documentation-expert agent\nNOT for LLM-facing docs]
    Q1 -->|System architecture| SA[system-architect agent]
    Q1 -->|Linting issues| LR[linting-root-cause-resolver agent]

Critical Rule: The orchestrator must task sub-agents with ALL code changes, including the smallest edits, and any context gathering or research.

Reason: Sub-agents are optimized for their domains. Orchestrator handling code changes bypasses agent expertise and violates separation of concerns.

Verification Questions for Orchestrators

Before sending delegation, verify:

1. Am I enabling full discovery?

   • Listed available tools/access → ENABLING
   • Specified which tool to use → LIMITING (rewrite to list available resources)

2. Am I stating facts or assumptions?

   • "Fails with error X" → FACT
   • "Probably fails because..." → ASSUMPTION (rewrite as observations)

3. Am I defining WHAT or prescribing HOW?

   • "Must successfully build the package" → WHAT
   • "Run 'npm build' to build" → HOW (rewrite as success criteria)

4. Am I sharing observations or solutions?

   • "Line 42 contains 'import X'" → OBSERVATION
   • "Change line 42 to 'import Y'" → SOLUTION (rewrite as problem statement)

5. Am I trusting agent expertise?

   • "Investigate using available resources" → TRUST
   • "Check this specific documentation" → DISTRUST (rewrite to list available docs)

Pattern Expansion — From Single Instance to Systemic Fix

When user identifies a code smell, bug, or anti-pattern at a specific location, treat it as a symptom of a broader pattern that likely exists elsewhere.

What users say vs what they mean:

• "Fix walrus operator in _some_func()" → "Audit and fix ALL instances of this pattern"
• "Add error handling to this API call" → "Audit all similar operations"
• "This validation is duplicated" → "Find and eliminate all instances systemically"

Reason: Users point out single instances as examples. Treating them as systemic saves user effort and improves codebase quality comprehensively.

flowchart TD
    Signal[User Signal] --> Q{Signal type?}
    Q -->|Code smell at specific location| A1[Audit file/module for all instances]
    Q -->|Missing error handling| A2[Audit all similar operations]
    Q -->|Duplicated validation| A3[Find all validation logic instances]
    Q -->|Inefficient loop pattern| A4[Search for all matching patterns]
    Q -->|Missing type hint| A5[Audit all function signatures]

Include symptom locations (observational):

• "Error occurs at server.py:142"
• "User reported issue in yq_wrapper.py:274-327"

State what agent should discover — do not prescribe changes:

• Replace "Replace server.py:127-138 with helper function" → "User identified duplication pattern at server.py:127-138. Audit entire file for similar patterns."
• Replace "Change line 42 to use walrus operator" → "User identified assign-then-check pattern at line 42. Audit for all instances."

Default assumption: Unless user explicitly says "only this one", treat code smell/bug mentions as representative of a broader pattern requiring systemic remediation.

Holistic vs Micromanaged Delegation

Micromanaged delegation (prevents agent understanding):

OBSERVATIONS:
- Walrus operator opportunity at _some_func():45-47

YOUR TASK:
1. Create helper at line 120
2. Replace lines 127-138 with call
3. Replace lines 180-191 with call

Problem: Orchestrator already did investigation. Agent becomes code-editing tool without context.

Holistic delegation (enables agent understanding):

OBSERVATIONS:
- User identified assign-then-check pattern at _some_func():45-47
- This suggests developer consistently missed walrus operator opportunities
- Code smell indicates systematic review needed across file/module

DEFINITION OF SUCCESS:
- Pattern eliminated from [file/module] scope
- All assign-then-check conditionals converted to walrus where appropriate

YOUR TASK:
1. Run SlashCommand /is-it-done to understand completion criteria
2. Fix the specific instance user identified
3. Audit entire [file/module] for similar patterns
4. Apply same fix to all discovered instances
5. Document pattern occurrences found and fixed
6. Verify /is-it-done checklist items satisfied with evidence

Anti-Patterns to Avoid

The Pre-Gathering Anti-Pattern

Running commands to collect data before delegating wastes context and duplicates agent work.

User: "Address linting issues"
Orchestrator runs: ruff check .
Orchestrator pastes: 244 errors into delegation prompt
Problem: Agent runs linting themselves anyway. Wasted orchestrator context.

Replace with: "Run linting against the project. Resolve all issues at root cause. Success: pre-commit passes."

The Assumption Cascade

"I think the issue is X, which probably means Y, so likely Z needs fixing" — chain of unverified assumptions.

Replace with: "[Observed symptoms]. Success: [desired behavior]. Investigate comprehensively before implementing."

The Prescription Trap

"Fix this by doing A, then B, then C" — prevents agent from discovering better approaches.

Replace with: "Fix [observation]. Success: [outcome]. Available resources: [list]."

The Discovery Limiter

"Just read these two files and fix the issue" — prevents comprehensive investigation.

Replace with: "Fix [observation]. Success: [outcome]. Full project context available."

The Tool Dictation

"Use the MCP GitHub tool to fetch logs" — agent might find better information source.

Replace with: "Investigate [observation]. Available: MCP GitHub tool, local logs, API access."

The Paraphrase Problem

"Something about permissions" instead of "Permission denied: /etc/config" — loses diagnostic information.

Replace with: Include exact error messages verbatim (only those already in your context).

The Context Withholding

Not sharing observations from other agents forces redundant discovery work.

Replace with: Include all relevant observations from orchestrator and other agents with source attribution.

The Micromanagement Pattern

"Use sed to edit line 42, then grep to verify" — wastes agent expertise.

Replace with: "Fix [issue] in [file]. Success: [tests pass]. Solution follows existing patterns."

The File:Line Prescription

"Replace lines 127-138 with helper function" — prescribes exact changes instead of defining problem.

Replace with: "User identified duplication at lines 127-138, 180-191. Eliminate duplication following project patterns."

The Confidence Mask

Stating uncertainties as facts propagates errors through agent chain.

Replace with: Mark assumptions explicitly — "Observation: [fact]. Hypothesis to verify: [assumption]."

The Reductive Tool List

"AVAILABLE RESOURCES: WebFetch, Read, Bash" when agent has 50+ tools including specialized MCP servers.

Replace with: World-building context describing the ecosystem and guiding tool selection.

Pre-Gathering Anti-Pattern — Detailed:

Orchestrators route context, agents do work.

• If data exists in context (user message, prior agent output) → pass it through
• If data does not exist yet → delegate with task + success criteria + available resources
• Let agents gather data, analyze, research, and implement

Reason: Pre-gathering causes context rot (source: https://research.trychroma.com/context-rot). Orchestrator context should coordinate work, not duplicate specialist tasks.

Examples — Effective Delegation Patterns

Linting Task — CORRECT:

"Run linting against the project. Resolve all issues at root cause.

SUCCESS CRITERIA:
- Code quality checks performed per holistic-linting skill
- All configured linting rules satisfied
- Solutions follow existing project patterns

CONTEXT:
- Python project using uv for dependency management
- Linting configured in pyproject.toml

YOUR TASK:
1. Run /is-it-done for completion criteria
2. Activate holistic-linting skill
3. Run linting tools to gather comprehensive data
4. Research root causes for each error category
5. Implement fixes following project conventions
6. Verify all criteria satisfied"

Linting Task — INCORRECT:

Orchestrator runs: ruff check .
Orchestrator pastes: 244 errors into prompt
Problem: Wasted orchestrator context, duplicated agent work, context rot.

Testing Task — CORRECT:

"Fix failing tests in test_authentication.py.

SUCCESS CRITERIA:
- All tests in test_authentication.py pass
- No new test failures introduced
- Test coverage maintained or improved

CONTEXT:
- Pytest configured in pyproject.toml
- Test fixtures in ./tests/fixtures/
- Authentication module recently refactored

YOUR TASK:
1. Run /is-it-done for completion criteria
2. Run pytest to identify failures
3. Investigate root causes
4. Implement fixes
5. Verify all tests pass and coverage maintained"

Error Delegation:

"Command X produced error: [exact error]. Success: command completes without error. GitHub Actions logs accessible via MCP."

Feature Delegation:

"Implement feature that [user requirement]. Success: [measurable outcome]. Project uses [observed tooling]."

Investigation Delegation:

"Investigate why [observation]. Document root cause with evidence. Full project context available."

Fix Delegation:

"Fix issue where [observation]. Success: [specific working behavior]. Related systems: [list]."

Complex System Delegation:

"System exhibits [observation]. Success: [desired behavior]. Available: Docker MCP, GitHub API, project repository."

Delegation Formula

Scientific delegation = Observations + Success Criteria + Available Resources - Assumptions - Prescriptions

This formula:

• Provides complete factual context (enables accurate hypothesis formation)
• Defines clear success metrics (prevents scope ambiguity)
• Enables full toolkit access (allows optimal tool selection)
• Removes limiting assumptions (prevents cascade errors)
• Trusts agent expertise (leverages specialized domain knowledge)

Final Verification Before Delegation

Before delegating, verify the prompt:

1. Uses observational language:

   • Replace "I think" → "Observed: [fact]"
   • Replace "probably" → "Command X produces Y"
   • Replace "likely" → "Pattern seen at [locations]"
   • Replace "seems" → "Measured behavior: [data]"
   • Replace "should work" → "Success criteria: [outcome]"

2. Includes empowering context:

   • Raw observations
   • Success criteria
   • Available resources/tools
   • File locations
   • User constraints only

3. Preserves agent autonomy:

   • Lists available tools instead of prescribing tool usage
   • Defines WHAT instead of HOW
   • States problems instead of solutions
   • Enables discovery instead of limiting scope

4. References documents efficiently:

   • Uses @filepath for detailed documents instead of transcribing
   • Provides high-level context and success criteria in prompt
   • Example: Reference @.claude/smells/{report-name}.md instead of copying file:line details

Agent Teams — When Subagents Are Not Enough

Agent teams coordinate multiple Claude Code instances with inter-agent messaging and shared task lists. Use subagents when workers report back independently. Use agent teams when workers must share findings, challenge each other, and coordinate among themselves.

When Agent Teams Apply

A workflow is a candidate for agent teams when ALL of these are true:

1. 3+ independent units of work (enough parallelism to justify coordination overhead)
2. Units benefit from cross-communication (findings from one inform or challenge another)
3. No shared file mutations (two teammates editing the same file leads to overwrites)
4. Result is a synthesis, not a concatenation (value comes from combining or reconciling findings)

When Subagents Suffice

• Work is sequential (each step depends on the previous)
• Only 1-2 sources or targets
• Units are fully independent with no cross-communication need
• Result is just collecting N outputs with no synthesis step

See Agent Teams Documentation for complete criteria, architecture, and usage patterns.

SOURCE: Lines 10-39 of agent-teams.md (accessed 2026-02-06)