From crux-hive
Orchestrate tasks by delegating to parallel Claude Code sessions via git worktrees. Activate with "start orchestrator mode", "delegate tasks to workers", "parallel claude code sessions", "git worktrees with teams", "orchestrate work", or "/orchestrator-mode".
How this skill is triggered — by the user, by Claude, or both
Slash command
/crux-hive:orchestrator-modeThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Orchestrate ALL tasks — implementation, research, investigation, or any other work — by delegating them to separate Claude Code sessions running in git worktrees.
Orchestrate ALL tasks — implementation, research, investigation, or any other work — by delegating them to separate Claude Code sessions running in git worktrees.
/orchestrator-mode
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.
Read these files for detailed procedural steps:
references/phases.md — Full Phase 1–4 procedures with examples and parameter tablesreferences/quick-reference.md — Quick reference table, delegation troubleshooting, and start_worktree_session examplesgit symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'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.git gtr.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.
After verifying prerequisites, check for orchestrator customization files:
~/.crux/orchestrator.md (global settings) if it exists.crux/orchestrator.md (project-specific settings) if it existsIf neither file exists, proceed with default behavior.
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────┘
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".
EnterPlanMode — The orchestrator does not plan; it delegates. To clarify requirements, ask the user directly.Agent subagents (Explore, Plan, general-purpose, etc.) — Workers handle all investigation, research, and planning.WebSearch or WebFetch — Delegate research tasks to a worker.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.Workers are launched as Agent Teams teammates using Claude Code's built-in team coordination:
~/.claude/teams/{name}/teamName) launches the worker with Agent Teams flagsCreate 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.
When the user describes what to accomplish:
git fetch origin && git pull origin <default-branch>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".
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"
})
When notified that a PR is ready:
gh pr list, gh pr view <n>, gh pr diff <n>)gh pr merge <n> --squash (no --delete-branch)git fetch origin && git pull origin <default-branch>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.
planMode: true when starting worker sessionsplanMode: true is used with Agent Teams, the worker's plan requires team lead approval before implementation begins (via plan_approval_request/plan_approval_response)npx claudepluginhub yellowblue1/crux --plugin crux-hiveGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.