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 try Bash("gemini ...") first (FREE - 2M tokens/min), fallback to haiku-coder

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

   • YES = MUST try Bash("codex ...") first (70% cheaper than Claude), fallback to sonnet-coder

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

   • YES = MUST try Bash("copilot ...") first (60% cheaper, GitHub-native), fallback to haiku-coder

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 Bash("codex ..."), fallback sonnet-coder
- Git commits → Task(haiku)                       # USE Bash("copilot ..."), fallback haiku-coder
- File search → Task(haiku)                       # USE Bash("gemini ...") (FREE!)
- Research → Task(haiku)                          # USE Bash("gemini ...") (FREE!)

CORRECT (cost-optimized):
- Code implementation → Bash("codex ...")         # Cheap, sandboxed; fallback sonnet-coder
- Git commits → Bash("copilot ...")               # Cheap, GitHub-native; fallback haiku-coder
- File search → Bash("gemini ...")                # FREE!; fallback haiku-coder
- Research → Bash("gemini ...")                   # FREE!; fallback haiku-coder
- Strategic decisions → Claude Opus               # Expensive, but needed
- Coder agents → FALLBACK ONLY                    # When CLI tools fail or aren't installed

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 and bugs):

• htmlgraph feature create "title" --track <trk-id>
• htmlgraph bug create "title" --track <trk-id>

Track Assignment (MANDATORY before creating work items):

Before creating ANY new track:

1. Run htmlgraph track list to see all existing tracks
2. Match the new work against existing track titles and descriptions
3. Only create a new track if NO existing track covers the scope
4. When in doubt, ask the user which track to use

This also applies when creating bugs, features, or spikes with --track:

• Search existing tracks first, create a new track only as last resort

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)

Delegation Pattern:

• Bash("gemini ...") - FREE, 2M tokens/min, exploration & research → fallback: haiku-coder
• Bash("codex ...") - Cheap code specialist, implementation & testing → fallback: sonnet-coder
• Bash("copilot ...") - Cheap git specialist, GitHub integration → fallback: haiku-coder
• Coder agents (haiku-coder, sonnet-coder) - Fallback only when CLI tools fail

Gemini CLI (FREE - Exploration)

gemini -p "Analyze codebase for:
- All authentication patterns
- OAuth implementations
- Session management
- JWT usage" --output-format json --yolo --include-directories . 2>&1

If gemini fails/unavailable → fallback to haiku-coder

Best for:

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

Codex CLI (Cheap - Code)

codex exec "Implement OAuth authentication:
- Add JWT token generation
- Include error handling
- Write unit tests" --full-auto --json -m gpt-4.1-mini -C . 2>&1

If codex fails/unavailable → fallback to sonnet-coder

Best for:

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

Copilot CLI (Cheap - Git)

copilot -p "Commit changes:
- Message: 'feat: add OAuth authentication'
- Files: src/auth/*.py, tests/test_auth.py
- Do NOT push" --allow-all-tools --no-color --add-dir . 2>&1

If copilot fails/unavailable → fallback to haiku-coder

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 (try CLI first):

gemini -p "Search codebase for authentication patterns and summarize findings" \
  --output-format json --yolo --include-directories . 2>&1
# fallback → Agent(subagent_type="htmlgraph:haiku-coder", ...)

Code implementation (try CLI first):

codex exec "Implement OAuth authentication endpoint with JWT support" \
  --full-auto --json -m gpt-4.1-mini -C . 2>&1
# fallback → Agent(subagent_type="htmlgraph:sonnet-coder", ...)

Git operations (try CLI first):

copilot -p "Commit changes with message: 'feat: add OAuth authentication'. Do NOT push." \
  --allow-all-tools --no-color --add-dir . 2>&1
# fallback → Agent(subagent_type="htmlgraph:haiku-coder", ...)

Try the Copilot CLI directly via Bash first, then delegate to haiku-coder if unavailable.

# Priority 1: Bash-copilot (preferred)
copilot -p "Stage files: <list>. Commit with message: '<message>'. Do NOT push." \
  --allow-all-tools --no-color --add-dir . 2>&1

# Priority 2: haiku-coder fallback (if copilot fails or not installed)
Agent(
    subagent_type="htmlgraph:haiku-coder",
    description="Commit and push changes",
    prompt="Stage files: <list>. Commit with message: 'feat: add X'. Do NOT push.",
)

Pattern: orchestrator tries the CLI directly, falls back to a coder agent.

For implementation, refactoring, and structured output tasks:

# Priority 1: Bash-codex (preferred)
codex exec "TASK_DESCRIPTION" --full-auto --json -m gpt-4.1-mini -C . 2>&1

# Priority 2: sonnet-coder fallback (if codex fails or not installed)
Agent(
    subagent_type="htmlgraph:sonnet-coder",
    description="Implement feature X",
    prompt="Add OAuth authentication to the login endpoint.",
)

Pattern: orchestrator tries the CLI directly, falls back to a coder agent. Always use -m gpt-4.1-mini for codex (never expensive gpt-5.4 default).

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

# Priority 1: Bash-gemini (preferred — FREE, 2M context)
gemini -p "TASK_DESCRIPTION" --output-format json --yolo --include-directories . 2>&1

# Priority 2: haiku-coder fallback (if gemini fails or not installed)
Agent(
    subagent_type="htmlgraph:haiku-coder",
    description="Research auth patterns",
    prompt="Analyze all authentication patterns in this codebase. Find security gaps.",
)

Pattern: orchestrator tries the CLI directly, falls back to a coder agent.

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 (try gemini CLI first)
gemini -p "Find all authentication patterns..." --output-format json --yolo --include-directories . 2>&1
# fallback → Agent(subagent_type="htmlgraph:haiku-coder", ...)

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

# 3. Use findings in next delegation (try codex CLI first)
codex exec "Implement authentication based on auth pattern research findings..." --full-auto --json -m gpt-4.1-mini -C . 2>&1
# fallback → Agent(subagent_type="htmlgraph:sonnet-coder", ...)

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)