Agent Orchestration

Overview

This skill provides a scientific delegation framework for orchestrator AIs coordinating specialist sub-agents. Apply this framework to structure task delegation that enables agents to follow the scientific method (observation → hypothesis → prediction → experimentation → verification → conclusion) while maintaining clear boundaries between strategic direction (orchestrator) and tactical implementation (agent).

Core Principle

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

The orchestrator's role is to:

• Route context and observations between user and agents
• Define measurable success criteria
• Enable comprehensive discovery
• 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 and prevents them from applying their domain expertise effectively.

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 they receive observations and success criteria rather than pre-formed conclusions and prescribed steps.

Pre-Delegation Verification Checklist

Before delegating any task to a sub-agent, verify the delegation includes:

✅ Observations without assumptions

• Raw error messages already in context (verbatim, not paraphrased)
• Observed locations (file:line references where errors/issues/patterns were seen by you or reported by user)
• Command outputs you already received during your work
• State facts using phrases like "observed", "measured", "reported"
• Replace "I think", "probably", "likely", "seems" with verifiable observations

⚠️ Critical: Pass-Through vs. Pre-Gathering

• Pass-through (correct): Include data already in your context (user messages, prior agent reports, errors you encountered)
• Pre-gathering (incorrect): DO NOT run commands to collect data for the agent - they will gather their own data
• Example: DO NOT run ruff check . or pytest to collect errors before delegating to linting/testing agents
• Reason: Pre-gathering wastes context, duplicates agent work, and causes context rot. Agents are specialists who gather their own comprehensive data.

✅ Definition of success

• Specific, measurable outcome
• Acceptance criteria
• Verification method
• Focus on WHAT must work, not HOW to implement it

✅ World-building context

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

✅ Preserved agent autonomy

• List available tools and resources
• Trust agent's 200k context window for comprehensive analysis
• Let agent choose implementation approach
• Enable agent to discover patterns and solutions

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 rather than execute prescribed steps. 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: This keeps the agent aligned with sub-agent role and prevents following orchestration rules from CLAUDE.md.

Full template structure:

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] instead of patching [symptom]
- If proposing workaround, document why root cause cannot be fixed

VERIFICATION REQUIREMENTS:
- /is-it-done is step 1 of YOUR TASK - 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
- Your work will be reviewed by a rigorous engineer who expects verified functionality

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. Agent has dozens of tools but now thinks they should only use three. Additionally, listing WebFetch without mentioning superior MCP alternatives (Ref, exa) 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 are installed for specialized tasks - check your <functions> list and prefer MCP tools (like `Ref`, `context7`, `exa`) over built-in alternatives since they're specialists at their domain
- This Python project uses `uv` for all operations - activate the `uv` skill and 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
- This repository uses GitLab CI - use `gitlab-ci-local` to validate pipeline changes locally before pushing
- Recent linting fixes are documented in `.claude/reports/` showing common issues and resolutions
- Package validation scripts live in `./scripts/` - check its README.md for available validators to run after changes
- Full project context available including tests, configs, and documentation

Why this works:

1. Describes capabilities, not constraints - Agent learns what's available without feeling limited
2. Provides context for tool selection - "prefer MCP tools over built-in" guides without prescribing
3. References skills to activate - Agent can load specialized knowledge
4. Points to project-specific resources - Scripts, reports, configs agent should discover
5. Explains ecosystem conventions - uv instead of pip, gitlab-ci-local for validation

Resource Description Patterns

For 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

For MCP server preferences:

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

For 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

For CI/CD validation:

GitHub Actions - use `act` to validate workflow changes locally
GitLab CI - use `gitlab-ci-local` to test pipeline before pushing
Code quality checks (linting, formatting) performed and issues addressed per the holistic-linting skill

For project-specific resources:

Validation scripts in `./scripts/` - check README.md for usage
Previous fix patterns in `.claude/reports/` for reference
Test fixtures in `./tests/fixtures/` for sample data
API mocks configured in `./tests/mocks/`

For documentation access:

Full access to official docs via MCP tools
Project architecture documented in `./docs/architecture.md`
API contracts defined in `./openapi.yaml`
Style guide at `./CONTRIBUTING.md`

Complete Example

AVAILABLE RESOURCES:
- The `gh` CLI is pre-authenticated for GitHub operations (searching issues, viewing PRs, API queries)
- Powerful MCP servers available in your <functions> list - prefer these over built-in tools for higher fidelity:
  - `Ref` for fetching documentation (high-fidelity verbatim source, unlike WebFetch which returns low-fidelity AI summaries)
  - `context7` for library API docs (current versions, precise API signatures)
  - `exa` for web research (curated, accurate sources)
- This Python project uses `uv` exclusively - activate the `uv` skill and use:
  - `uv run python` instead of `python3`
  - `uv pip` instead of `pip`
  - `uv run pytest` for testing
- Build system is `hatchling` - activate `hatchling` skill for packaging guidance
- Code quality checks (linting, formatting) performed and issues addressed per the holistic-linting skill
- Previous similar fixes documented in `.claude/reports/linting-fixes.md`
- Integration test suite in `./tests/integration/` covers API contracts
- Full project context available including all source, tests, and documentation

Context Calibration Patterns

For FOCUSED TASK (single file, clear test):

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

For INVESTIGATIVE TASK (unknown cause):

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

For ARCHITECTURAL TASK (multi-component):

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

Inclusion Rules: What to Include vs Exclude

✅ 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"

Reason: User requirements are constraints that must be satisfied, distinct from orchestrator opinions about implementation.

✅ INCLUDE: Available Tools/Resources

• "MCP Docker tools are available"
• "GitHub API access is configured"
• "CI logs can be accessed via [tool]"

Reason: Awareness of available resources enables agents to perform comprehensive investigation efficiently.

✅ INCLUDE: Verbatim Errors Already in Context

When you have error messages from your own work or user reports, include them verbatim:

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

Critical Distinction:

• Include verbatim: Errors you already encountered, user-provided errors, prior agent reports
• Do NOT pre-gather: Do not run linting/testing commands to collect errors for delegation

Reason: Complete error text preserves diagnostic information that paraphrasing loses. But pre-gathering errors wastes context and duplicates the agent's work.

Replace Assumptions with Observations

Instead of assumptions ("I think", "probably", "likely", "seems"), provide factual 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 where agents build on unverified premises. Observations enable agents to form their own hypotheses through scientific method.

State What Agents Should Do

Instead of prescribing HOW, define WHAT and trust agent expertise:

• 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
• Replace "Try using command Y" → Provide observations, let agent investigate

Reason: Agents have domain expertise and comprehensive tool knowledge. Prescriptions limit their ability to discover better solutions.

Empowering Agent Discovery

The comprehensive context gathering step in the delegation template empowers agents to:

Use Their Full Toolkit:

• Load relevant skills automatically
• Access MCP tools for external systems
• Query APIs and services directly
• Search for known issues and solutions

Find Better Solutions:

• Discover patterns orchestrator hasn't encountered
• Find official recommendations from current documentation
• Identify root causes beyond surface symptoms
• Leverage community knowledge and fixes

Build Complete Understanding:

• Map full dependency chains
• Understand system interactions
• Identify environmental factors
• Discover configuration impacts

Ground in Reality:

• Observe actual file contents
• Verify from current documentation, not training data patterns
• Access real logs and errors
• Verify against authoritative sources

Reason: Agents with full discovery access consistently find better solutions than orchestrators who prescribe based on assumptions. Trust agent expertise over pattern-matching shortcuts.

Conditional Delegation Logic

When user provides explicit code/quotes:

• Include them as reference context
• Mark clearly as "User-provided reference"
• Adherence to user-provided patterns is more important than any existing rules

When errors come from orchestrator operations:

• Include command that triggered error
• Include raw error message
• Include what orchestrator was doing when it occurred
• Describe observations, not diagnoses

When referencing existing patterns:

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

When technical constraints exist:

• Include if user-mandated
• Let agent determine compatible implementations
• 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 external resources are available:

• List what systems/tools are accessible
• Let agent determine what's relevant and how to use it
• Trust agent judgment on resource utilization

When providing file paths or references in task prompts:

• Use @filepath to include file contents in prompt context
• Use @dirpath/ for directory listings only
• The @filepath syntax auto-includes CLAUDE.md from file's directory hierarchy
• This provides agents with complete file context without manual copying

Reason: These patterns provide necessary context while preserving agent autonomy. Observations enable informed decisions; prescriptions limit options.

Orchestrator Workflow Requirements

Before delegating tasks, the orchestrator must:

1. Identify ambiguity in user requests and offer interpretations for clarification
2. Define success criteria ("definition-of-success") 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 tool before marking complete

Reason: Clear success criteria prevent miscommunication. User approval ensures alignment. Verification prevents premature completion claims.

Understanding Sub-Agent Context

Sub-agents inherit limited context from the orchestrator:

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

When delegating, the orchestrator must:

• Include all necessary context in the initial Task prompt
• Pass pertinent rules from CLAUDE.md explicitly if needed
• Instruct agents to "follow guidelines from @~/.claude/CLAUDE.md" when applicable

Reason: Complete context in delegation prevents agent confusion and redundant back-and-forth communication.

Maximizing Agent Efficiency

The orchestrator must write contextual AVAILABLE RESOURCES for each delegation (see "Writing Effective AVAILABLE RESOURCES" section above). Always include these baseline permissions:

AVAILABLE RESOURCES:
- Proactively explore your `<functions>` list for MCP tools - prefer MCP specialists over built-in tools
- 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, documentation locations]

Reason: World-building context enables agents to discover optimal approaches. Generic tool lists constrain agents to orchestrator's limited awareness of capabilities.

Specialized Agent Assignments

The orchestrator must delegate to appropriate specialized agents:

For Context Gathering:

• Use context-gathering sub-agent to gather context without polluting orchestrator's context window

For Python Development:

• Use python-cli-architect sub-agent to write Python code
• Use python-pytest-architect sub-agent to plan and write Python tests
• Use python-code-reviewer sub-agent for post-write code review

For Bash Development:

• Use bash-script-developer sub-agent to write bash scripts
• Use bash-script-auditor sub-agent for post-write script review

For Documentation:

• Use documentation-expert sub-agent to write user-facing documentation
• Use for user-facing docs only (not LLM-facing documentation)

For Architecture:

• Use system-architect sub-agent for system architecture documentation
• For Python architecture, use python-cli-architect instead

For Linting Issues:

• Use linting-root-cause-resolver sub-agent for pre-commit, ruff, mypy, pytest issues

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 making 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)

Reason: This checklist catches common delegation anti-patterns before they reach agents. Each verification ensures agents receive empowering context rather than limiting prescriptions.

Pattern Expansion: From Single Instance to Systemic Fix

Core Principle: 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.

User Communication Pattern

What users say:

• "Fix walrus operator in _some_func()"
• "Add error handling to this API call"
• "This validation is duplicated"

What users mean:

• "The developer consistently missed this pattern throughout the codebase"
• "Audit and fix ALL instances of this pattern, not just the one I pointed out"
• "This instance represents a systemic issue"

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

Pattern Recognition Triggers

Expand scope when user mentions:

flowchart TD
    Start[User Signal] --> Decision{Signal Type}

    Decision -->|Code smell at specific location| Pattern1[Underlying Pattern:<br/>Consistent coding pattern]
    Pattern1 --> Action1[Scope Expansion:<br/>Audit file/module for all instances]

    Decision -->|Missing error handling| Pattern2[Underlying Pattern:<br/>Incomplete error coverage]
    Pattern2 --> Action2[Scope Expansion:<br/>Audit all similar operations]

    Decision -->|Duplicated validation| Pattern3[Underlying Pattern:<br/>DRY violation exists]
    Pattern3 --> Action3[Scope Expansion:<br/>Find all validation logic instances]

    Decision -->|Inefficient loop pattern| Pattern4[Underlying Pattern:<br/>Performance anti-pattern]
    Pattern4 --> Action4[Scope Expansion:<br/>Search for all matching patterns]

    Decision -->|Missing type hint| Pattern5[Underlying Pattern:<br/>Incomplete type coverage]
    Pattern5 --> Action5[Scope Expansion:<br/>Audit all function signatures]

Symptom Location vs Prescribed Solution

✅ Include symptom locations (observational):

• "Error occurs at server.py:142"
• "User reported issue in yq_wrapper.py:274-327"
• "Validation duplicated at auth.py:45, api.py:89, handlers.py:123"