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
• Use agents liberally to keep the orchestrator's context window clean
• When a problem is hard, throw more compute at it — spawn agents in parallel rather than working sequentially in the orchestrator

Reason: Sub-agents are specialized experts with full tool access. Prescribing implementation limits their ability to discover better solutions. The orchestrator's context window is finite and shared across the whole session — agents get fresh context per task. Parallel dispatch solves more, faster, without accumulating context debt.

Scientific Method Alignment

Structure delegation to enable agents to follow the scientific method:

1. Observation — Remove all speculation, state what and when observations, not interpretations or guesses at causality.
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"]) --> Classify{"Does this actiongather data the agentwill collect itself?"}

    Classify -->|"No — orchestrator action"| subDo
    Classify -->|"Yes — pre-gathering"| subNo

    subgraph subDo["DO — orchestrator responsibilities"]
        R1["Route context and observationsalready in scope to agents"]
        R2["Define measurable success criteriafor what DONE looks like"]
        R3["Enable comprehensive agent discoveryby providing world-building context"]
    end

    subgraph subNo["DO NOT — prohibited actions"]
        N1["Pre-gather data agentswill collect themselves"]
        N2["Prescribe HOW agentsshould implement"]
    end

    subDo --> Delegate(["Delegate via Agent tool"])
    subNo --> Rewrite(["Rewrite prompt to remove pre-gatheringor prescription before delegating"])

Pre-Delegation Verification Checklist

Before delegating any task, verify the delegation includes:

1. Observations without speculation on causality.

Here are different examples of how you can share observations:

• You can say 'When , I observed .' i.e. When using the Bash tool with "grep -s 'error' some/output/log.txt" it exited with non-zero.
• You can provide Raw error messages verbatim (not paraphrased)
• You can provide the url or path to the raw error messages or logs
• You can provide console command outputs already received during your work
• You only use language that describes reality such as — "observed", "measured", "reported"
• You do not use hedging language or speculation such as — "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 or Definition of Done:

• 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:

• Describe the ecosystem and available environment — never prescribe which tool to use
• Trust agent's empty context window for comprehensive analysis
• Let agent choose implementation approach

Task Tool Invocation Rule

When invoking the Agent 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. Use the `/am-i-complete` checklist as your working guide throughout this task
2. Perform comprehensive context gathering using:
   - Available functions and MCP tools from the  list
   - Relevant skills from the  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
3. Form hypothesis based on gathered evidence
4. Design and execute experiments to test hypothesis
5. Verify findings against authoritative sources
6. Implement solution following discovered best practices
7. Verify each `/am-i-complete` checklist item as you complete it
8. Only report completion after all `/am-i-complete` 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:
- `/am-i-complete` is the verification check — run it before claiming done
- Use `/am-i-complete` 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

ECOSYSTEM CONTEXT:
- [Authenticated CLIs available: e.g., "`gh` CLI is pre-authenticated for GitHub operations"]
- [Session-specific access: e.g., "CI logs for PR #42 accessible via MCP GitHub tool"]
- [Non-obvious doc locations: e.g., "linting reports in `.tmp/reports/`"]
- [Omit anything already in CLAUDE.md — agents inherit CLAUDE.md and do not need it repeated]

Writing Effective ECOSYSTEM CONTEXT

ECOSYSTEM CONTEXT belongs ONLY in the delegation prompt when it contains information the agent cannot find in CLAUDE.md, the project files it will read, or its own tool descriptions.

The inheritance rule: Agents automatically inherit both CLAUDE.md files, MEMORY.md, rules files, git status, and all tool descriptions. Do not repeat any of that in ECOSYSTEM CONTEXT — it is noise that displaces real context.

What belongs in ECOSYSTEM CONTEXT

Include only session-specific or task-specific facts that exist nowhere the agent can see:

Authenticated CLIs — whether a CLI is authenticated varies per session; agents cannot assume it:

- The `gh` CLI is pre-authenticated for GitHub operations (issues, PRs, API queries)
- The `glab` CLI is configured for GitLab access
- AWS CLI is configured with credentials for the staging account

Session-specific access — CI logs, PR context, external resources relevant to this specific task:

- CI logs for PR #42 are accessible via the MCP GitHub tool
- The staging deployment at staging.example.com is available for testing

Non-obvious document locations — file locations the agent would not discover without a hint:

- Recent linting reports in `.tmp/reports/` document previously resolved issues
- Package validation scripts in `./scripts/` — see README.md for usage

Credentials or runtime state that varies — anything that depends on the current session environment:

- Docker daemon is running and accessible
- The database seed data is loaded at localhost:5432

What does NOT belong in ECOSYSTEM CONTEXT

These items are inherited from CLAUDE.md or tool descriptions — do not repeat them:

• "Full project context available — explore freely" — agents always have full tool access
• "Check `` list for MCP tools" — tool descriptions already tell agents this
• "Maximize parallel execution" — CLAUDE.md already instructs this
• "Activate relevant skills for domain expertise" — CLAUDE.md already covers skill activation
• "This Python project uses uv" — CLAUDE.md already states the toolchain
• Language/toolchain conventions already in CLAUDE.md (uv, pnpm, cargo, etc.)

Anti-pattern — parroting inherited context:

ECOSYSTEM CONTEXT:
- Full project context available — explore freely with all tools
- Check  list for MCP tools — prefer MCP specialists over built-in
- This Python project uses `uv` — activate `uv` skill
- Maximize parallel execution for independent tool calls

All four lines are already in CLAUDE.md or tool descriptions. This section adds zero information.

Correct pattern — session-specific facts only:

ECOSYSTEM CONTEXT:
- The `gh` CLI is pre-authenticated for GitHub operations (issues, PRs, API queries)
- CI logs for PR #42 accessible via MCP GitHub tool
- Recent linting reports in `.tmp/reports/` show resolved issues for reference

These three lines are not in any CLAUDE.md and vary per session.

When there is nothing session-specific to add, omit ECOSYSTEM CONTEXT entirely. The section only earns its place when it contains information the agent cannot find anywhere else.

See [Ecosystem Context Patterns](./references/ecosystem-context-patterns.md) for detailed examples and the documentation fidelity hierarchy for MCP tool selection.

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" → Describe the ecosystem, let agent select tools
• 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

flowchart TD
    Start(["Building delegation prompt"]) --> Q1{"Does the current context containuser-provided code or quoted text?"}
    Q1 -->|"Yes"| A1["Include verbatim as'User-provided reference'.User-provided patterns override existing rules."]
    Q1 -->|"No"| Q2
    A1 --> Q2

    Q2{"Did an error occur duringorchestrator operationsbefore this delegation?"}
    Q2 -->|"Yes"| A2["Include the exact command that triggered the errorand the raw error message verbatim.State as observations, not diagnoses."]
    Q2 -->|"No"| Q3
    A2 --> Q3

    Q3{"Are file:line referencesto existing patternsalready known in context?"}
    Q3 -->|"Yes"| A3["Include as 'Pattern reference: file:line'.Do not prescribe changes —let agent discover all instances."]
    Q3 -->|"No"| Q4
    A3 --> Q4

    Q4{"Did the user explicitly mandatea technical constraint —a library, version, or method?"}
    Q4 -->|"Yes — user-mandated"| A4["Include the constraint exactly asthe user stated it.Do not add constraints the user did not specify."]
    Q4 -->|"No — not user-mandated"| Q5
    A4 --> Q5

    Q5{"Are there accumulated observationsfrom other agents or priororchestrator operations?"}
    Q5 -->|"Yes"| A5["Pass all observations with source attribution.Do not filter — include complete context."]
    Q5 -->|"No"| Q6
    A5 --> Q6

    Q6{"Will the prompt referenceone or more file paths?"}
    Q6 -->|"Yes — referencing a file"| A6["Use '@filepath' to include file contents.Use '@dirpath/' for directory listings only.'@filepath' auto-includes CLAUDE.md hierarchy."]
    Q6 -->|"No — no file references needed"| Done
    A6 --> Done(["Delegation prompt complete"])

Orchestrator Workflow Requirements

flowchart TD
    Start(["Orchestrator receives user request"]) --> A["Identify every ambiguous termin the user request"]
    A --> Q1{"Does the request containambiguous terms or multiplevalid interpretations?"}
    Q1 -->|"Yes — ambiguity found"| Clarify["Offer interpretations to userand ask which to proceed with"]
    Clarify --> DefineSuccess
    Q1 -->|"No — request is unambiguous"| DefineSuccess
    DefineSuccess["Define success criteria —specific measurable outcome,acceptance criteria, verification method"]
    DefineSuccess --> Q2{"Has the user confirmedthe definition of success?"}
    Q2 -->|"No — not confirmed"| Offer["Present definition of successto user for approval or modification"]
    Offer --> Q2
    Q2 -->|"Yes — confirmed"| Include["Include confirmed definition of successin sub-agent Task prompt"]
    Include --> Delegate(["Delegate task via Agent tool"])
    Delegate --> Q3{"Did sub-agent reportall acceptance criteria metwith evidence?"}
    Q3 -->|"No — criteria not met"| Follow["Follow up with agentor re-delegate with clarification"]
    Follow --> Q3
    Q3 -->|"Yes — all criteria met with evidence"| Done(["Mark task 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 m

…

Source & license

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

• Author: Jamie-BitFlight
• Source: Jamie-BitFlight/claude_skills
• License: MIT

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