Claude Agent Orchestration

Table of Contents

1. Master Coordinator & MCP Architecture
2. Modular Markdown Skill Files
3. Five-Role Enterprise Orchestration
4. Enterprise Governance & Failure-Mode Recovery
5. Tutorial 1: Python Subagent Dispatcher
6. Tutorial 2: Master Coordinator Prompt
7. Tutorial 3: Step-by-Step Claude Desktop Setup
8. Tutorial 4: Python MCP Tool Permission & Audit Wrapper
9. Tutorial 5: Subagent Handoff & Escalation Prompt
10. Tutorial 6: Step-by-Step Orchestration Incident & Rollback Runbook
11. Live References & Documentation

Master Coordinator & MCP Architecture

Most teams struggle with AI adoption because they treat every conversation as a blank slate. Engineers paste entire codebases into chat, executives re-explain company strategy every Monday, and marketing teams lose brand voice across threads. Claude Agent Orchestration eliminates this friction by establishing a Master Coordinator pattern backed by the Model Context Protocol (MCP).

Instead of one bloated prompt trying to do everything, the Master Coordinator routes requests to focused sub-sessions and reads only the relevant Markdown skill file on demand. Context stays clean, token usage drops, and outputs remain consistent across departments.

Modular Markdown Skill Files

Instead of stuffing 4,000 tokens of instructions into every system prompt, we decompose organizational knowledge into lightweight .md skill files stored in version control. When a user invokes a workflow, Claude loads only the specific skill file required for that task, cutting system prompt bloat by over 80% and eliminating instruction drift.

Five-Role Enterprise Orchestration

Our orchestration framework is tailored for five core enterprise functions: Executives (board memos and risk matrices), Software Engineers (isolated git worktree subagents), Data Scientists (focused sub-sessions for paper and dataset synthesis), HR (objective YAML candidate rubrics), and Marketing (multi-channel campaign matrices).

Tutorial 1: Python Subagent Dispatcher

This Python script loads a role-specific Markdown skill file dynamically and dispatches a focused Claude sub-session, keeping the coordinator context clean.

import os
from pathlib import Path
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def run_skill_subagent(skill_name: str, user_task: str) -> str:
    skill_path = Path("skills") / f"{skill_name}.md"
    skill_instructions = skill_path.read_text(encoding="utf-8")
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1500,
        system=skill_instructions,
        messages=[{"role": "user", "content": user_task}],
    )
    return response.content[0].text

if __name__ == "__main__":
    output = run_skill_subagent("hr-rubric", "Score candidate against Senior Backend YAML.")
    print(output)

Tutorial 2: Master Coordinator Prompt

Place this coordinator instruction in your project root CLAUDE.md file so Claude routes tasks to the right skill without bloating context.

# Master Coordinator Instructions
You are the Master Coordinator for this workspace.
1. Identify the user's department: Executive, Engineering, Data Science, HR, or Marketing.
2. Load ONLY the matching skill file from ./skills/<role>.md before answering.
3. Never mix instructions from unrelated departments.
4. For multi-file code changes, propose a plan first and execute in an isolated git worktree.

Tutorial 3: Step-by-Step Claude Desktop Setup

1. Create Skills Directory: Initialize a ./skills/ folder in your repository with one Markdown file per team role.
2. Configure MCP Servers: Add filesystem and GitHub MCP servers in claude_desktop_config.json.
3. Test Sub-Sessions: Run a sample executive memo, engineering PR review, and HR rubric evaluation to verify isolation.

Enterprise Governance & Failure-Mode Recovery

Orchestrating multiple Claude subagents across enterprise repositories, ticketing systems, and internal APIs introduces strict governance requirements. When a Master Coordinator dispatches parallel subagents over the Model Context Protocol (MCP), each subagent must operate inside an isolated context boundary with explicit read/write permissions. Without capability scoping, a subagent tasked with summarizing customer feedback could inadvertently invoke a production database mutation tool exposed on the same MCP server.

Production deployments enforce a zero-trust MCP gateway between the coordinator and downstream tool servers. Every MCP tool call is authenticated via short-lived OAuth2 tokens, validated against a strict JSON Schema contract, and logged to an immutable audit trail. Sensitive operations - such as merging pull requests, modifying cloud infrastructure, or sending external client communications - trigger a mandatory human-in-the-loop (HITL) approval gate before execution.

Failure-mode recovery in Claude orchestration relies on deterministic handoff contracts and bounded retry budgets. If a subagent encounters a context-window overflow, a malformed MCP response, or an upstream rate limit, the coordinator intercepts the failure, snapshots the partial artifact to disk, and either re-routes the subtask to a fresh subagent with a pruned context or escalates to an on-call engineer with a complete OpenTelemetry trace.

Tutorial 4: Python MCP Tool Permission & Audit Wrapper

This Python wrapper enforces role-based tool allowlists and writes immutable JSON audit records before any Claude subagent invokes an MCP server tool.

import json
import datetime
from typing import Dict, Set, Any

ROLE_ALLOWLIST: Dict[str, Set[str]] = {
    "research_subagent": {"mcp_github_read", "mcp_web_fetch"},
    "engineering_subagent": {"mcp_github_read", "mcp_sandbox_test"},
    "qa_subagent": {"mcp_github_read", "mcp_lint_verify"},
}

def authorize_and_log(role: str, tool_name: str, payload: Dict[str, Any]) -> bool:
    allowed = tool_name in ROLE_ALLOWLIST.get(role, set())
    audit_entry = {
        "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
        "role": role,
        "tool": tool_name,
        "authorized": allowed,
        "payload_keys": sorted(payload.keys()),
    }
    print(json.dumps(audit_entry))
    if not allowed:
        raise PermissionError(f"Role '{role}' is not authorized to invoke '{tool_name}'.")
    return True

Tutorial 5: Subagent Handoff & Escalation Prompt

Embed this handoff contract into your Claude subagent skill files so every agent returns structured, verifiable state to the Master Coordinator.

ROLE: Specialized Claude Subagent
HANDOFF_CONTRACT:
1. Never exceed your assigned tool scope. If a task requires an unauthorized tool, return status="ESCALATE_COORDINATOR".
2. Write all intermediate artifacts to the designated workspace path before returning.
3. Summarize your execution in strictly under 200 tokens using the JSON schema below:

{
  "subagent_role": "string",
  "status": "COMPLETE | PARTIAL | ESCALATE_COORDINATOR",
  "artifact_paths": ["string"],
  "verification_passed": true,
  "blocking_issue": "null or concise description"
}

Tutorial 6: Step-by-Step Orchestration Incident & Rollback Runbook

Execute this operational runbook whenever a Claude multi-agent orchestration run fails verification or stalls at an HITL gate:

1. Halt Active Subagents: Revoke the run's short-lived MCP capability token at the gateway to prevent further tool calls.
2. Inspect Audit Logs: Filter the JSON audit stream by role and tool to pinpoint the exact failing invocation.
3. Snapshot Workspace Artifacts: Archive all partial Markdown and code artifacts generated prior to the failure.
4. Rollback Git / SaaS State: Revert any sandboxed branch commits or staging mutations using the recorded idempotency keys.
5. Re-dispatch with Pruned Context: Launch a fresh subagent referencing only the verified artifact snapshot and updated skill constraints.

Live References & Documentation

• Model Context Protocol (MCP) Official Specification
• Anthropic Claude Code & Subagents Documentation
• Anthropic Prompt Engineering Best Practices
• Anthropic Tool Use & Structured Outputs
• NIST AI Risk Management Framework
• OWASP Top 10 for LLM Applications
• OpenTelemetry Distributed Tracing Specification
• JSON Schema Official Specification
• OAuth 2.0 Authorization Framework
• Pydantic Data Validation Documentation