Claude Code Orchestration

Purpose: Guide model selection, task delegation, context management, and continuous self-improvement for efficient Claude Code usage.

Mindset: Apply /pb-design-rules thinking (Simplicity - cheapest model that produces correct results; Clarity - make delegation explicit) and /pb-preamble thinking (challenge assumptions about model choice - is opus actually needed here, or is it habit?).

Resource Hint: sonnet - reference guide for model selection and delegation patterns.

When to Use

• Starting a session with mixed-complexity tasks
• Planning workflows that involve subagent delegation
• Reviewing resource efficiency after a session
• Generating or updating CLAUDE.md templates
• After a session where model choice caused issues (wrong model, wasted tokens)

Model Tiers

Opus reasons. Sonnet builds. Haiku runs.

Harness Reality (as of 2026-09-24)

The table above is cost guidance, not a description of what the harness runs: which model a session starts on depends on plan and configuration, and /model shows it. Current at this date, from Anthropic’s docs:

• Opus 5.5 is the default Opus model and Anthropic’s recommended starting point; Fable 5.1 is the default Fable model, for demanding long-horizon work. Both, and Sonnet 5, carry a 1M context window.
• Fable 5.1 lists at 2.5x Opus 5.5 ($10/$50 vs $4/$20 per Mtok). The playbook’s own June head-to-head found the union of two models caught the most real bugs and neither alone did, so Fable is a second lens in deliberate deep audits, not a default.
• /fast speeds output on models that support it; it does not switch to a smaller model.

When cost discipline matters (routine dev loop, CI, automation), switch to Sonnet explicitly rather than relying on the harness default. Haiku remains subagent-only.

Model Selection Strategy

By Task Type

Decision Criteria

Ask these in order (first match wins):

1. Does this require architectural judgment or trade-off analysis? → opus
2. Does this require code generation or analytical reasoning? → sonnet
3. Is this mechanical (search, format, scaffold)? → haiku

When unsure, start with sonnet. Upgrade to opus if results lack depth. Downgrade to haiku if the task is mechanical.

Task Delegation Patterns

When to Delegate

Current Opus delegates more readily than earlier models, and delegation multiplies cost and time on small tasks. Delegate only large, genuinely independent tracks. Never delegate checking your own work – the model already verifies its output, and a verifier subagent is documented to add cost without adding quality. The deterministic caps are CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.

Delegate to subagents:

• Independent research or codebase exploration too wide to hold in main context
• File search across many files
• Parallel information gathering
• Work that would pollute main context with noise

Keep in main context:

• Decisions that affect subsequent steps
• Architecture and planning
• Work requiring conversational continuity with the user
• Anything where the user needs to see the reasoning

Output Discipline

When a subagent returns a summary, accept the summary as context. Do not pipe raw tool output, diffs, or file dumps back into the main conversation unless verification explicitly requires it. Context is finite; delegation is the exchange – pay for it once, not twice.

Size the Pass, Not the Agent

The subagent that has to read a whole repo before it can answer is the one that dies mid-run on an API error – and it is the expensive one to lose, because it dies late.

Inline the evidence, narrow the question. Paste the file excerpt, the failing output, the rule text you already have, and ask one specific thing. Several lean passes beat one heavy pass that reconstructs context from disk: they finish, they are cheap to retry, and a failure costs one narrow answer instead of the whole analysis.

Reserve broad exploratory delegation for when you genuinely do not know where to look. Once you know, stop delegating the search and delegate the judgment.

Parallel vs Sequential

Model Assignment for Subagents

model: "haiku"   → Explore agents, file search, grep
model: "sonnet"  → Code writing, analysis, standard reviews
(default/opus)   → Planning, architecture, complex analysis

Context Budget Management

Budget Awareness

Every unnecessary line in CLAUDE.md or MEMORY.md costs tokens on every single turn. Be ruthlessly concise in persistent files.

A 1M window does not retire this hygiene. Compaction is still lossy, every turn still pays the tokens, and Anthropic’s own guidance is that longer CLAUDE.md files reduce adherence, not only budget.

Efficiency Principles

• Subagents for exploration (separate context window, doesn’t pollute main)
• Surgical file reads (offset + limit, not full files when you know the area)
• Plans in files, not in chat (reference by path, not by pasting)
• Compact at natural breakpoints (after commit, after phase - not mid-task)
• Commit frequently (each commit is a context checkpoint)
• Reference by commit hash (not by re-reading entire files)

Playbook-to-Model Mapping

Self-Healing and Continuous Learning

The orchestrator is not static. It learns, adapts, and improves.

Operational Self-Awareness

After each significant workflow, reflect:

Auto-Memory as Learning Journal

Use the auto-memory directory (~/.claude/projects/<project>/memory/) to persist operational learnings:

MEMORY.md (loaded every session, <200 lines):

• Model selection adjustments discovered through experience
• Playbook gaps encountered and workarounds used
• Project-specific orchestration preferences
• Context management lessons learned

Topic files (referenced from MEMORY.md, loaded on demand):

• orchestration-lessons.md - Model choice outcomes, delegation pattern results
• playbook-gaps.md - Missing guidance discovered during workflows
• project-patterns.md - Project-specific efficiency patterns

Feedback Loop

Execute workflow
    |
    v
Observe outcome
    |
    v
Was it efficient? Correct? Right model?
    |           |
    YES         NO
    |           |
    v           v
Continue    Record learning in auto-memory
            Adjust approach for next time
            Surface playbook gap to user if systemic

Self-Healing Behaviors

Suggesting Playbook Improvements

When the orchestrator discovers gaps during operation:

1. Note the gap - What was missing, what workaround was used
2. Assess frequency - One-off vs recurring need
3. Propose to user - “Encountered [gap] during [workflow]. Suggest updating [playbook] with [specific addition].”
4. Don’t self-modify playbooks silently - Propose, don’t assume

This creates a virtuous cycle: use playbooks → discover gaps → propose improvements → playbooks get better → usage gets better.

Anti-Patterns

Examples

Example 1: Feature Implementation Workflow

1. /pb-plan - opus (main context): architecture decisions, trade-offs
2. Explore codebase - haiku (2-3 parallel subagents): find relevant files
3. Implementation - sonnet (main context): write code
4. Write tests - sonnet subagent: parallel test generation
5. Self-review - opus (main context): critical evaluation
6. /pb-commit - sonnet: procedural commit workflow

Post-session reflection:

• Did haiku find what was needed? (If not, adjust search prompts in memory)
• Did sonnet’s code need significant opus review fixes? (If yes, consider opus for complex implementation next time)

Example 2: Playbook Review with Model Delegation

• Phase 1 automated checks - haiku subagent: count commands, validate cross-refs
• Phase 2 category review - opus (main context): nuanced evaluation of intent, quality
• Phase 3 cross-category - opus (main context): holistic pattern recognition

Related Commands

• /pb-claude-global - Generate global CLAUDE.md (concise orchestration rules)
• /pb-claude-project - Generate project CLAUDE.md
• /pb-learn - Pattern learning from debugging (complements operational learning here)
• /pb-review-playbook - Playbook review (model delegation by phase)
• /pb-new-playbook - Meta-playbook (resource hint in scaffold)