Orchestrator Directives Skill

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

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 (MUST prevent failures from compounding in your context)
• Parallel efficiency (MUST run multiple subagents simultaneously)
• Cost optimization (ALWAYS use cheaper subagents than Claude Code)
• Error isolation (MUST keep failures 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, ALWAYS 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=[...])

HtmlGraph CLI operations (create features, spikes, bugs):

• htmlgraph feature create "title"
• htmlgraph spike create "title"
• htmlgraph bug create "title"

Everything else MUST be delegated.

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:

• gemini - FREE, 2M tokens/min, exploration & research
• codex - Cheap code specialist, implementation & testing
• copilot - Cheap git specialist, GitHub integration
• haiku - Generic Claude Haiku (use as fallback or when spawners fail)

Gemini Spawner (FREE - Exploration)

Task(
    subagent_type="gemini",
    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="codex",
    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="copilot",
    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" for deep reasoning
)

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

Simple exploration:

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

Code implementation:

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

Git operations:

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

MANDATORY: All git write operations must be delegated to the copilot-operator agent.

# For commits, pushes, PRs, and code generation
Agent(
    subagent_type="htmlgraph:copilot-operator",
    description="Commit and push changes",
    prompt="Commit all staged files with message: 'feat: add X'. Then push to origin main.",
)

The copilot-operator agent:

1. Tries GitHub Copilot CLI first (cost-optimized, external AI)
2. Falls back to direct git/gh if copilot unavailable
3. Hook enforcement verifies copilot was attempted before allowing git-write

Never run git commit/push directly from the orchestrator. The PreToolUse hook will deny it in strict mode.

For implementation, refactoring, and structured output tasks:

Agent(
    subagent_type="htmlgraph:codex-operator",
    description="Implement feature X",
    prompt="Add OAuth authentication to the login endpoint. Use gpt-4.1-mini.",
)

The codex-operator agent:

1. Tries OpenAI Codex CLI first (structured JSON output, sandboxed)
2. Falls back to direct implementation if Codex unavailable
3. Always uses -m gpt-4.1-mini (never expensive gpt-5.4 default)

For codebase exploration, documentation research, and large-context analysis:

Agent(
    subagent_type="htmlgraph:gemini-operator",
    description="Research auth patterns",
    prompt="Analyze all authentication patterns in this codebase. Find security gaps.",
)

The gemini-operator agent:

1. Tries Google Gemini CLI first (2M context window, FREE)
2. Falls back to direct Read/Grep/Glob exploration if Gemini unavailable
3. Ideal for tasks requiring full codebase context

MANDATORY: Always analyze parallelizability when 2+ tasks are identified.

Before presenting recommendations or starting multi-task work, ALWAYS:

1. Check dependency graph — do any tasks depend on outputs of others?
2. Check file overlap — do tasks touch the same files/modules?
3. If independent → propose parallel worktree execution as the DEFAULT
4. If dependent → identify the critical path and parallelize what you can

Decision matrix:

Pattern: Spawn all at once in isolated worktrees

# Launch parallel agents in worktrees — one per feature
Agent(
    subagent_type="htmlgraph:sonnet-coder",
    description="Feature A",
    prompt="Implement feature A...",
    isolation="worktree",
    run_in_background=True,
)

Agent(
    subagent_type="htmlgraph:sonnet-coder",
    description="Feature B",
    prompt="Implement feature B...",
    isolation="worktree",
    run_in_background=True,
)

Agent(
    subagent_type="htmlgraph:haiku-coder",
    description="Feature C (simple)",
    prompt="Implement feature C...",
    isolation="worktree",
    run_in_background=True,
)

Benefits:

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

After completion: Merge worktree branches to main, run quality gates, clean up.

Pattern: Chain dependent tasks in sequence

# 1. Research existing patterns
Task(
    subagent_type="gemini",
    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="codex",
    description="Implement OAuth based on research",
    prompt=f"""
    Implement OAuth using discovered patterns:
    {research_findings}
    """
)

# 3. Wait for implementation, then commit
Task(
    subagent_type="copilot",
    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 available via CLI:

# Check recent spikes
htmlgraph spike list

# View specific spike
htmlgraph spike show <id>

Pattern: Read findings after Task completes

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

# 2. The subagent creates a spike with findings
# Read findings via: htmlgraph spike list (then spike show <id>)

# 3. Use findings in next delegation
Task(
    subagent_type="htmlgraph:codex-operator",
    description="Implement based on findings",
    prompt="Implement authentication based on auth pattern research 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="copilot",
    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

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

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 CLI to track delegations
• Features, spikes, bugs created for all work
• Clear record of who did what

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