orchestrator-mode

Orchestrator Mode

Orchestrate ALL tasks — implementation, research, investigation, or any other work — by delegating them to separate Claude Code sessions running in git worktrees.

Trigger

/orchestrator-mode

Overview

The orchestrator delegates every task to workers. Each worker runs in an isolated git worktree as an Agent Teams teammate with built-in SendMessage for bidirectional communication. The orchestrator never executes tasks directly.

Reference Files

Read these files for detailed procedural steps:

• references/phases.md — Full Phase 1–4 procedures with examples and parameter tables
• references/quick-reference.md — Quick reference table, delegation troubleshooting, and start_worktree_session examples

Prerequisites

1. Default branch: Must be on the repository's default branch. Worktrees cannot be created for the branch currently checked out. Detect with: git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
2. tmux: The session must be running inside tmux. Detect with: tmux display-message -p '#S' (returns session name if inside tmux, fails otherwise). Do not use echo $TMUX — Bash subshells may not inherit the environment variable.
3. git-gtr: Worktree management depends on git gtr.
4. jq: Required for reliable detection of Agent Teams configuration in settings files.
5. Agent Teams: The CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable must be set to 1. Configure in any Claude settings file (~/.claude/settings.json, ~/.claude/settings.local.json, .claude/settings.json, or .claude/settings.local.json) under env. Detect with:

   jq -r '.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS // empty' ~/.claude/settings.json ~/.claude/settings.local.json .claude/settings.json .claude/settings.local.json 2>/dev/null | grep -q 1 && echo "enabled" || echo "not found"
   

Inform the user before proceeding if any prerequisite is not met.

Custom Settings

After verifying prerequisites, check for orchestrator customization files:

1. Read ~/.crux/orchestrator.md (global settings) if it exists
2. Read .crux/orchestrator.md (project-specific settings) if it exists
3. Merge: global first, then project-specific (project takes precedence on conflict)
4. Apply merged content as additional behavioral guidelines for this session

If neither file exists, proceed with default behavior.

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  Orchestrator Mode (this session)                           │
│                                                             │
│  1. TeamCreate → creates team (once per conversation)        │
│  2. Discuss task with user → start_worktree_session          │
│     (with teamName → worker joins as teammate)               │
│  3. Worker uses built-in SendMessage → auto-delivered         │
│  4. Review PR → Merge/Close → Cleanup                        │
│  (repeat 2-4 for additional tasks)                           │
└─────────────────────────────────────────────────────────────┘
         │                          ▲
         │ delegate                 │ SendMessage (built-in, auto-delivered)
         ▼                          │
┌─────────────────────────────────────────────────────────────┐
│  Worker Session (separate tmux window + git worktree)        │
│                                                             │
│  - Launched as Agent Teams teammate                          │
│  - Runs in plan mode                                        │
│  - Executes the task (implementation, research, etc.)        │
│  - Creates pull request                                      │
│  - Uses built-in SendMessage to notify orchestrator           │
└─────────────────────────────────────────────────────────────┘

Prohibited Actions

The orchestrator MUST NOT perform work directly. The only job is to delegate to workers and coordinate their output. If tempted to investigate before delegating — delegate instead. Pass the ambiguity to the worker; an ambiguous but correctly scoped delegation is better than a detailed but self-executed analysis.

Exception: If start_worktree_session fails and the user explicitly instructs direct work, proceed directly. See references/phases.md "When Delegation Fails".

1. NEVER use EnterPlanMode — The orchestrator does not plan; it delegates. To clarify requirements, ask the user directly.
2. NEVER launch Agent subagents (Explore, Plan, general-purpose, etc.) — Workers handle all investigation, research, and planning.
3. NEVER use WebSearch or WebFetch — Delegate research tasks to a worker.
4. NEVER use Read, Grep, Glob for codebase investigation — Exception: single-file lookups for writing the worker prompt (e.g., verifying a file path exists or reading a GitHub issue body). Do not read multiple files or analyze code.

How It Works

Workers are launched as Agent Teams teammates using Claude Code's built-in team coordination:

1. TeamCreate creates a team with a shared config at ~/.claude/teams/{name}/
2. start_worktree_session (with teamName) launches the worker with Agent Teams flags
3. The worker automatically has access to SendMessage (built-in) for bidirectional communication
4. Messages are auto-delivered — no polling or watcher needed

Phase 0: Create Team

Create a team before delegating any tasks.

TeamCreate({ team_name: "<repo-name>" })

This creates the team config at ~/.claude/teams/{name}/config.json with the current session as team lead.

Use the repository name as the team name (e.g., "crux"). One team per conversation — do not create separate teams per task.

Phase 1: Task Delegation (Summary)

When the user describes what to accomplish:

1. Update default branch before creating any worktree: git fetch origin && git pull origin <default-branch>
2. Delegate immediately once the theme/topic is clear — do not wait for full planning
3. One task per worker — each task gets its own worktree and PR; do not add unrelated work to a running worker
4. Never assume specifics when unsure — keep ambiguity intact or ask briefly
5. Include what is known in the handoff prompt; workers handle the rest
6. Hand off with a complete prompt containing: Objective, Context, Findings, Relevant files, Decisions made, Expected output

Delegate any task where the theme is identifiable: implementation, research, investigation, documentation.

Key principle: If the theme is identifiable, delegate it. Do not execute it directly.

See references/phases.md for full Phase 1 details including the parameter table, examples, and "When Delegation Fails".

Phase 2: Communication (Summary)

Send messages to workers via SendMessage:

SendMessage({
  type: "message",
  recipient: "worker-auth",
  content: "Please also add rate limiting to the login endpoint",
  summary: "Add rate limiting request"
})

Phase 3–4: PR Review, Merge, and Cleanup (Summary)

When notified that a PR is ready:

1. List and review the PR (gh pr list, gh pr view <n>, gh pr diff <n>)
2. Perform lightweight review — check summary, verify objective, look for obvious issues
3. ALWAYS ask the user for confirmation before merging — never merge automatically
4. Merge after user approval: gh pr merge <n> --squash (no --delete-branch)
5. Update default branch: git fetch origin && git pull origin <default-branch>
6. Cleanup: git gtr rm <branch> --yes then git push origin --delete <branch>

See references/phases.md for full Phase 3–4 procedures and references/quick-reference.md for the command table.

Important Notes

• Always use planMode: true when starting worker sessions
• When planMode: true is used with Agent Teams, the worker's plan requires team lead approval before implementation begins (via plan_approval_request/plan_approval_response)
• Workers should create PRs, not push directly to the default branch
• Review PRs and ask user before merging
• Delegate research tasks too — do not execute WebSearch or exploration directly
• Ambiguous but correct > Specific but wrong; workers can investigate