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.

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, validate, 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 (Task Tool)

Delegate to subagents:

• Independent research or codebase exploration
• File search across many files
• Validation and lint checks
• 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

Parallel vs Sequential

Model Assignment in Task Tool

model: "haiku"   → Explore agents, file search, grep, validation
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.

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 (Task tool, 2-3 parallel agents): find relevant files
3. Implementation - sonnet (main context): write code
4. Write tests - sonnet (Task tool): 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 (Task tool): 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)

Last Updated: 2026-02-07 Version: 1.0.0