Orchestrator Directives Skill

What this skill does

# 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?

Delegate tactical work to specialized subagents while you focus on strategic decisions. Save Claude Code context (expensive) by using FREE/CHEAP AIs for appropriate tasks.

**Basic pattern:**
```python
Use Gemini agent invocation with:
    workflow="gemini",  # FREE - use for exploration
    description="Find auth patterns",
    message="Search codebase for authentication patterns..."
```

**When to use:** ALWAYS use for 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.

---

## Batching wipnote CLI Calls (IMPERATIVE)

Each Bash tool call spends one agent turn from the user's quota. **Chain wipnote bookkeeping commands with `&&` into a single Bash invocation whenever possible.** wipnote exists to reduce agent overhead — do not add it back by issuing one Bash call per `wipnote link add`.

**Do this (1 tool call):**
```bash
wipnote bug create "A" --track trk-xxx --description "..." && \
wipnote bug create "B" --track trk-xxx --description "..." && \
wipnote link add feat-aaa feat-bbb --rel blocks && \
wipnote link add feat-ccc feat-ddd --rel relates_to
```

**Never 4 separate Bash calls for the same thing.**

**When NOT to chain:** only when a downstream command must parse the ID printed by an earlier command. Chain the creators into one call, then chain the dependents into a second call. Two calls, not eight.

Applies to `feature/bug/spike/track/plan create|start|complete|add-step`, `link add|remove`, `feature edit`, and any other wipnote bookkeeping.

---

## Step Tracking via Task Tool (Orchestrator Only)

The active work item's step checklist is updated automatically when the orchestrator calls `TaskCreate` and `TaskUpdate`. wipnote's `TaskCreated` hook (`internal/hooks/task_tracking.go`) shells out to `wipnote feature add-step` on every TaskCreate; the `TaskCompleted` hook increments the step counter on TaskUpdate(status="completed").

**Important: subagents do NOT have `TaskCreate`/`TaskUpdate` in their tools allowlist.** These are MCP/agent-teams tools available only to the orchestrator. Telling a subagent "use the Task tool" in its prompt does nothing — the tool isn't there.

**Use TaskCreate when:**
- Dispatching subagent work that maps to a step on the active work item
- Starting any multi-step task with 3+ distinct sub-steps you can name in advance
- About to spawn multiple parallel subagents — one TaskCreate per dispatched subagent

**Use TaskUpdate(status="completed") when:**
- A subagent returns with the step done
- You verify quality gates pass for that step
- The unit of work matches a slice in the work item's design

**Skip TaskCreate when:**
- The work is a single trivial action (one Bash call, one file read)
- You're in conversation/clarification mode, not execution mode
- The user's request is purely informational

**Concrete pattern:**

```
TaskCreate(subject="Strip skills frontmatter from 5 agent files",
           description="Edit plugin/agents/{patch,feature,architect,researcher,test-runner}.md")
→ subject + task ID become a step on the active feature
→ dispatch the subagent
→ on return, TaskUpdate(taskId, status="completed")
→ wipnote step counter increments
```

Verify via `wipnote feature show <id>` — `Steps: N/M complete` should reflect the TaskUpdate calls. Steps remain unchecked if you skipped TaskCreate.

---

## CRITICAL: Cost-First Delegation (IMPERATIVE)

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

<details>
<summary><strong>Cost Comparison & Pre-Delegation Checklist</strong></summary>

### 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 patch-coder

2. **Is this code work?** → Implementation, fixes, tests, refactoring
   - YES = MUST try `Bash("codex ...")` first (70% cheaper than Claude), fallback to feature-coder

3. **Is this git/GitHub?** → Commits, PRs, issues, branches
   - YES = MUST try `Bash("copilot ...")` first (60% cheaper, GitHub-native), fallback to patch-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

| Task | WRONG (Cost) | CORRECT (Cost) | Savings |
|------|-------------|----------------|---------|
| Search 100 files | use the appropriate Gemini agent invocation ($15-25) | Gemini spawner (FREE) | 100% |
| Generate code | use the appropriate Gemini agent invocation ($10) | Codex spawner ($3) | 70% |
| Git commit | use the appropriate Gemini agent invocation ($5) | Copilot spawner ($2) | 60% |
| Strategic decision | Direct task ($20) | Claude Opus ($50) | Must pay for quality |

### WRONG vs CORRECT Examples

```
WRONG (wastes Claude quota):
- Code implementation → use the appropriate Gemini agent invocation               # USE Bash("codex ..."), fallback feature-coder
- Git commits → use the appropriate Gemini agent invocation                       # USE Bash("copilot ..."), fallback patch-coder
- File search → use the appropriate Gemini agent invocation                       # USE Bash("gemini ...") (FREE!)
- Research → use the appropriate Gemini agent invocation                          # USE Bash("gemini ...") (FREE!)

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

</details>

---

## Core Concepts

<details>
<summary><strong>Orchestrator vs Executor Roles</strong></summary>

**Orchestrator (You):**
- Makes strategic decisions
- Delegates tactical work
- Tracks progress with SDK
- Coordinates parallel subagents
- Only executes: use the appropriate Gemini agent invocation, 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)

</details>

<details>
<summary><strong>Why Delegation Matters: Context Cost Model</strong></summary>

**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):
  use the appropriate Gemini agent invocation → 1 tool call
  Read result → 1 tool call
  = 2 t