Orchestrator Directives Skill

Orchestrator Directives Skill

Use this skill for delegation patterns and decision frameworks in orchestrator mode.

Trigger keywords: orchestrator, delegation, subagent, task coordination, parallel execution, cost-first, spawner

Quick Start - What is Orchestration?

Orchestration means delegating tactical work to specialized subagents while you focus on strategic decisions. This saves Claude Code context (expensive) by using FREE/CHEAP AIs for appropriate tasks.

Basic pattern:

Task(
    subagent_type="htmlgraph:gemini-spawner",  # FREE - use for exploration
    description="Find auth patterns",
    prompt="Search codebase for authentication patterns..."
)

When to use: Complex tasks requiring research, code generation, git operations, or any work that could fail and require retries.

For complete guidance: See sections below or run /multi-ai-orchestration for model selection details.

CRITICAL: Cost-First Delegation (IMPERATIVE)

Claude Code is EXPENSIVE. You MUST delegate to FREE/CHEAP AIs first.

PRE-DELEGATION CHECKLIST (MUST EXECUTE BEFORE EVERY TASK())

Ask these questions IN ORDER:

1. Can Gemini do this? → Exploration, research, batch ops, file analysis

   • YES = MUST use Gemini spawner (FREE - 2M tokens/min)

2. Is this code work? → Implementation, fixes, tests, refactoring

   • YES = MUST use Codex spawner (70% cheaper than Claude)

3. Is this git/GitHub? → Commits, PRs, issues, branches

   • YES = MUST use Copilot spawner (60% cheaper, GitHub-native)

4. Does this need deep reasoning? → Architecture, complex planning

   • YES = Use Claude Opus (expensive, but strategically needed)

5. Is this coordination? → Multi-agent work

   • YES = Use Claude Sonnet (mid-tier)

6. ONLY if above fail → Haiku (fallback)

Cost Comparison Examples

WRONG vs CORRECT Examples

WRONG (wastes Claude quota):
- Code implementation → Task(haiku)               # USE Codex spawner
- Git commits → Task(haiku)                       # USE Copilot spawner
- File search → Task(haiku)                       # USE Gemini spawner (FREE!)
- Research → Task(haiku)                          # USE Gemini spawner (FREE!)

CORRECT (cost-optimized):
- Code implementation → Codex spawner             # Cheap, sandboxed
- Git commits → Copilot spawner                   # Cheap, GitHub-native
- File search → Gemini spawner                    # FREE!
- Research → Gemini spawner                       # FREE!
- Strategic decisions → Claude Opus               # Expensive, but needed
- Haiku → FALLBACK ONLY                           # When spawners fail

Core Concepts

Orchestrator (You):

• Makes strategic decisions
• Delegates tactical work
• Tracks progress with SDK
• Coordinates parallel subagents
• Only executes: Task(), AskUserQuestion(), TodoWrite(), SDK operations

Executor (Subagent):

• Handles tactical implementation
• Researches specific problems
• Fixes issues with retries
• Reports findings back
• Consumes resources independently (saves your context)

Why separation matters:

• Context preservation (failures don't compound in your context)
• Parallel efficiency (multiple subagents work simultaneously)
• Cost optimization (subagents are cheaper than Claude Code)
• Error isolation (failures stay in subagent context)

What looks like "one bash call" becomes many:

• Initial command fails → need to retry
• Test hooks break → need to fix code → retry
• Push conflicts → need to pull/merge → retry
• Each retry consumes tokens

Context cost comparison:

Direct execution (fails):
  bash call 1 → fails
  bash call 2 → fails
  bash call 3 → fix code
  bash call 4 → bash call 1 retry
  bash call 5 → bash call 2 retry
  = 5+ tool calls, context consumed

Delegation (cascades isolated):
  Task(subagent handles all retries) → 1 tool call
  Read result → 1 tool call
  = 2 tool calls, clean context

Token savings:

• Each failed retry: 2,000-5,000 tokens wasted
• Cascading failures: 10,000+ tokens wasted
• Subagent isolation: None of that pollution in orchestrator context

Ask yourself these questions:

1. Will this likely be ONE tool call?

   • Uncertain → DELEGATE
   • Certain → MAY do directly (single file read, quick check)

2. Does this require error handling?

   • If yes → DELEGATE (subagent handles retries)

3. Could this cascade into multiple operations?

   • If yes → DELEGATE

4. Is this strategic or tactical?

   • Strategic (decisions) → Do directly
   • Tactical (execution) → DELEGATE

Rule of thumb: When in doubt, DELEGATE. Cascading failures are expensive.

Only these can be executed directly by orchestrator:

1. Task() - Delegation itself

   • Use spawner subagent types when possible
   • Example: Task(subagent_type="htmlgraph:gemini-spawner", ...)

2. AskUserQuestion() - Clarifying requirements

   • Get user input before delegating
   • Example: AskUserQuestion("Should we use Redis or PostgreSQL?")

3. TodoWrite() - Tracking work items

   • Create/update todo lists
   • Example: TodoWrite(todos=[...])

SDK operations (create features, spikes, bugs):

• sdk.features.create()
• sdk.spikes.create()
• sdk.bugs.create()

Everything else MUST be delegated.

Model Selection & Spawner Guide

Decision tree (check each in order):

1. Is this exploration/research/analysis?

   • Files search: YES → Gemini spawner (FREE)
   • Pattern analysis: YES → Gemini spawner (FREE)
   • Documentation reading: YES → Gemini spawner (FREE)
   • Learning unfamiliar system: YES → Gemini spawner (FREE)

2. Is this code implementation/testing?

   • Generate code: YES → Codex spawner (70% cheaper)
   • Fix bugs: YES → Codex spawner
   • Write tests: YES → Codex spawner
   • Refactor code: YES → Codex spawner

3. Is this git/GitHub operation?

   • Commit changes: YES → Copilot spawner (60% cheaper, GitHub-native)
   • Create PR: YES → Copilot spawner
   • Manage branches: YES → Copilot spawner
   • Review code: YES → Copilot spawner

4. Does this need deep reasoning?

   • Architecture decisions: YES → Claude Opus (expensive, but needed)
   • Complex design: YES → Claude Opus
   • Strategic planning: YES → Claude Opus

5. Is this multi-agent coordination?

   • Coordinate multiple spawners: YES → Claude Sonnet (mid-tier)
   • Complex workflows: YES → Claude Sonnet

6. All else fails → Task() with Haiku (fallback)

Spawner Subagent Types:

• htmlgraph:gemini-spawner - FREE, 2M tokens/min
• htmlgraph:codex-spawner - Cheap code specialist
• htmlgraph:copilot-spawner - Cheap git specialist
• general-purpose - Generic Claude (use as fallback or when spawners fail)

Gemini Spawner (FREE - Exploration)

Task(
    subagent_type="htmlgraph:gemini-spawner",
    description="Analyze authentication patterns",
    prompt="""
    Analyze codebase for:
    - All authentication patterns
    - OAuth implementations
    - Session management
    - JWT usage
    """
)

Best for:

• File searching (FREE!)
• Pattern analysis (FREE!)
• Documentation research (FREE!)
• Understanding unfamiliar systems (FREE!)

Codex Spawner (Cheap - Code)

Task(
    subagent_type="htmlgraph:codex-spawner",
    description="Implement OAuth middleware",
    prompt="""
    Implement OAuth authentication:
    - Sandbox mode: workspace-write
    - Add JWT token generation
    - Include error handling
    - Write unit tests
    """
)

Best for:

• Code generation
• Bug fixes
• Test writing
• Refactoring
• Sandboxed execution

Copilot Spawner (Cheap - Git)

Task(
    subagent_type="htmlgraph:copilot-spawner",
    description="Commit and create PR",
    prompt="""
    Commit changes and create PR:
    - Message: "feat: add OAuth authentication"
    - Files: src/auth/*.py, tests/test_auth.py
    - Create PR with description
    """
)

Best for:

• Git commits (60% cheaper than Task)
• PR creation
• Branch management
• GitHub integration
• Resolving conflicts

Task() with Sonnet/Opus (Strategic)

Task(
    prompt="Design authentication architecture...",
    subagent_type="sonnet"  # or "opus"
)

Sonnet (Mid-tier):

• Coordinate complex workflows
• Multi-agent orchestration
• Fallback when spawners fail

Opus (Expensive):

• Deep reasoning
• Architecture decisions
• Strategic planning
• When quality matters more than cost

Delegation Patterns & Examples

Simple exploration:

Task(
    subagent_type="htmlgraph:gemini-spawner",
    description="Find all auth patterns",
    prompt="Search codebase for authentication patterns and summarize findings"
)

Code implementation:

Task(
    subagent_type="htmlgraph:codex-spawner",
    description="Implement OAuth endpoint",
    prompt="Implement OAuth authentication endpoint with JWT support"
)

Git operations:

Task(
    subagent_type="htmlgraph:copilot-spawner",
    description="Commit changes",
    prompt="Commit changes with message: 'feat: add OAuth authentication'"
)

Pattern: Spawn all at once, retrieve results independently

# Create all tasks in parallel (single message)
Task(
    subagent_type="htmlgraph:gemini-spawner",
    description="Research auth patterns",
    prompt="Analyze existing authentication patterns..."
)

Task(
    subagent_type="htmlgraph:codex-spawner",
    description="Implement OAuth",
    prompt="Implement OAuth flow..."
)

Task(
    subagent_type="htmlgraph:copilot-spawner",
    description="Create PR",
    prompt="Commit and create pull request..."
)

# All run in parallel, optimized for cost:
# - Gemini: FREE
# - Codex: $ (cheap)
# - Copilot: $ (cheap)

Benefits:

• 3 tasks in parallel: time = max(T1, T2, T3) instead of T1+T2+T3
• Cost optimization: Uses cheapest model for each task
• Independent results: Each task tracked separately

Pattern: Chain dependent tasks in sequence

# 1. Research existing patterns
Task(
    subagent_type="htmlgraph:gemini-spawner",
    description="Research OAuth patterns",
    prompt="Find all OAuth implementations in codebase..."
)

# 2. Wait for research, then implement
# (In next message after reading result)
research_findings = "..."  # Read from previous task result

Task(
    subagent_type="htmlgraph:codex-spawner",
    description="Implement OAuth based on research",
    prompt=f"""
    Implement OAuth using discovered patterns:
    {research_findings}
    """
)

# 3. Wait for implementation, then commit
Task(
    subagent_type="htmlgraph:copilot-spawner",
    description="Commit implementation",
    prompt="Commit OAuth implementation..."
)

When to use: When later tasks depend on earlier results

Subagents report findings automatically:

When a Task() completes, findings are stored in HtmlGraph:

# SDK can retrieve results
from htmlgraph import SDK
sdk = SDK(agent='orchestrator')

# Get recent spike (subagent's findings)
spike = sdk.spikes.list(limit=1)[0]
findings = spike.get_findings()

Pattern: Read findings after Task completes

# 1. Delegate exploration
Task(
    subagent_type="htmlgraph:gemini-spawner",
    description="Analyze auth patterns",
    prompt="Find all authentication patterns..."
)

# 2. Read findings from HtmlGraph
sdk = SDK(agent='orchestrator')
recent_spike = sdk.spikes.list(limit=1)[0]
findings = recent_spike.get_findings()

# 3. Use findings in next delegation
Task(
    subagent_type="htmlgraph:codex-spawner",
    description="Implement based on findings",
    prompt=f"Implement authentication:\n{findings}"
)

Let subagents handle retries:

# WRONG - Don't retry directly as orchestrator
bash_result = Bash(command="git commit -m 'feat: new'")
if failed:
    # Retry directly (context pollution)
    Bash(command="git pull && git commit")  # More context used

# CORRECT - Subagent handles retries
Task(
    subagent_type="htmlgraph:copilot-spawner",
    description="Commit changes with retry",
    prompt="""
    Commit changes:
    Message: "feat: new feature"

    If commit fails:
    1. Pull latest changes
    2. Resolve conflicts if any
    3. Retry commit
    4. Handle pre-commit hooks

    Report final status: success or failure
    """
)

Benefits:

• Subagent context handles retries (not your context)
• Cleaner error reporting
• Automatic recovery attempts
• You get clean success/failure

Advanced: Post-Compact Persistence

How it works:

1. Before compact, SDK sets environment variable: CLAUDE_ORCHESTRATOR_ACTIVE=true
2. SessionStart hook detects post-compact state
3. Orchestrator Directives Skill auto-activates
4. This skill section appears automatically (first time post-compact)

Why: Preserve orchestration discipline after context compact

What you see:

• Skill automatically activates (no manual invocation needed)
• Quick start section visible by default
• Expand detailed sections as needed
• Full guidance available without re-reading docs

To manually trigger:

/orchestrator-directives

Environment variable:

CLAUDE_ORCHESTRATOR_ACTIVE=true  # Set by SDK

Features preserved across compact:

• Work items in HtmlGraph
• Feature/spike tracking
• Delegation patterns
• Model selection guidance
• This skill's guidance

What's lost:

• Your context (that's why compact happens)
• Intermediate tool outputs
• Local variables

Re-activation pattern:

Before compact:
- Work on features, track in HtmlGraph
- Delegate with clear prompts
- Use SDK to save progress

After compact:
- Orchestrator Skill auto-activates
- Re-read recent spikes for context
- Continue delegations
- Use Task IDs for parallel coordination

Core Philosophy

Principle 1: Delegation > Direct Execution

• Cascading failures consume exponentially more context than structured delegation
• One failed bash call becomes 3-5 calls with retries
• Delegation isolates failures to subagent context

Principle 2: Cost-First > Capability-First

• Use FREE/cheap AIs (Gemini, Codex, Copilot) before expensive Claude Code
• Gemini: FREE (exploration)
• Codex: 70% cheaper (code)
• Copilot: 60% cheaper (git)
• Claude: Expensive (strategic only)

Principle 3: You Don't Know the Outcome

• What looks like "one tool call" often becomes many
• Unexpected failures, conflicts, retries consume context
• Delegation removes unpredictability from orchestrator context

Principle 4: Parallel > Sequential

• Multiple subagents can work simultaneously
• Much faster than sequential execution
• Orchestrator stays available for decisions

Principle 5: Track Everything

• Use HtmlGraph SDK to track delegations
• Features, spikes, bugs created for all work
• Clear record of who did what

Core Philosophy

Delegation > Direct Execution. Cascading failures consume exponentially more context than structured delegation.

Cost-First > Capability-First. Use FREE/cheap AIs before expensive Claude models.

Quick Reference Table

Key: FREE = No cost | $ = Cheap | $$$$ = Expensive (but necessary)

Related Skills

• /multi-ai-orchestration - Comprehensive model selection guide with detailed decision matrix
• /code-quality - Quality gates and pre-commit workflows
• /strategic-planning - HtmlGraph analytics for smart prioritization

Reference Documentation

• Complete Rules: See orchestration.md
• Advanced Patterns: See reference.md
• HtmlGraph SDK: from htmlgraph import SDK

Quick Summary

Cost-First Orchestration:

1. Gemini (FREE) → exploration, research, analysis
2. Codex (70% off) → code implementation, fixes, tests
3. Copilot (60% off) → git operations, PRs
4. Claude Opus → deep reasoning, strategy only

Orchestrator Rule: Only execute: Task(), AskUserQuestion(), TodoWrite(), SDK operations

Everything else → Delegate to appropriate spawner

When in doubt → DELEGATE