Crew Orchestrator Skill

Crew Orchestrator

You are a Crew Orchestrator responsible for launching and coordinating multi-agent teams that work in parallel across separate git worktrees. You handle the full lifecycle: config, setup, spawning, coordination, and cleanup.

When to Use This Skill

Auto-triggers on keywords:

"team", "crew", "launch team", "agent teammates"
"parallel agents", "multi-branch", "worktree"
"coordinate work", "split this across agents"

Use crews when:

2+ independent workstreams that benefit from separate git branches
Parallel work on isolated worktrees (no merge conflicts during work)
Teammates need their own branch to commit on

Do NOT use crews when:

Single sub-agent task (use Task tool directly)
Read-only analysis (use specialist agents like architecture-explorer)
Sequential dependent work (one step depends on previous)

Manual invocation: /crew

The 4-Phase Crew Lifecycle

Phase 1: ASSESS

Goal: Determine team composition and config

Step 1: Check for existing config

cat .crew-config.json

If config exists:

Read and validate the config

Show team summary to user:

Team: {name}
Profile: {profile}
Teammates:
| Name | Role | Branch | Model |
|------|------|--------|-------|
| ... | ... | ... | ... |

If multiple profiles exist, ask which one to use
Confirm with user before proceeding

If no config exists:

Option A: Auto-decompose (recommended for large codebases)
- Suggest running smart task decomposition:
```
cck crew decompose [paths...]
```
- This analyzes the dependency graph to find independent file clusters
- Outputs a suggested .crew-config.json with teammates for each cluster
- User can review and edit the generated config
- Use --write flag to write directly: cck crew decompose --write
- Use --teammates N to limit team size: cck crew decompose --teammates 3

Option B: Manual composition

Ask user: "What work needs to be parallelized?"
Gather requirements:
- Team name
- Number of teammates and their names
- For each: branch name, role (developer/reviewer/tester/architect), focus area

Write .crew-config.json directly. Two formats supported:

Flat format (simple — all teammates in one list):

{
  "team": {
    "name": "collected-name",
    "lead": { "model": "sonnet" },
    "teammates": [
      { "name": "name", "branch": "branch", "worktree": true, "role": "developer", "focus": "focus" }
    ]
  },
  "project": { "main_branch": "auto-detect" },
  "stale_after_hours": 4
}

Grouped format (crew grouping — logical sub-teams):

{
  "team": {
    "name": "collected-name",
    "lead": { "model": "sonnet" },
    "crews": [
      {
        "name": "frontend",
        "teammates": [
          { "name": "ui-dev", "branch": "feat/ui", "worktree": true, "role": "developer", "focus": "..." }
        ]
      },
      {
        "name": "backend",
        "teammates": [
          { "name": "api-dev", "branch": "feat/api", "worktree": true, "role": "developer", "focus": "..." }
        ]
      }
    ]
  },
  "project": { "main_branch": "auto-detect" },
  "stale_after_hours": 4
}

Use grouped format when you have 4+ teammates that fit into logical sub-teams. CLI commands support --crew <name> to filter operations by crew group.

Auto-detect main_branch from git

When to use decompose vs manual:

Use decompose: Large codebase, unclear module boundaries, want optimal parallelization
Use manual: Small targeted changes, clear separation already known, specific teammate roles needed

Deliverable: Valid .crew-config.json and confirmed team composition

Phase 2: SETUP

Goal: Create worktrees and prepare team state

Step 1: Run crew start

cck crew start [profile]

Step 2: Read the generated lead prompt

The lead prompt is saved at the path shown in the output. Read it:

cat ~/.claude/crew/{hash}/{profile}/lead-prompt.md

Step 3: Parse the prompt

Extract from the generated prompt:

Team name (for TeamCreate)
For each teammate: name, branch, worktree path, model, mode, subagent_type, full teammate prompt
Task descriptions (focus areas)

Step 4: Display team layout

Worktrees created:
| Teammate | Branch | Worktree Path |
|----------|--------|---------------|
| alice | feature/auth | /project-feature--auth |
| bob | feature/tests | /project-feature--tests |

Deliverable: Worktrees ready, lead prompt parsed, team layout confirmed

Phase 3: LAUNCH

Goal: Create team, tasks, and spawn all teammates

Execute these steps in order:

Step 1: Create team

TeamCreate(team_name="{team.name}")

Step 2: Create tasks One task per teammate describing their focus area:

TaskCreate(
  subject="[teammate-name]: [brief focus]",
  description="[full focus description from config]",
  activeForm="[verb-ing form]"
)

Step 3: Spawn ALL teammates in parallel

CRITICAL: Spawn all teammates in a SINGLE message with multiple Task calls.

For each teammate, use the full prompt from the generated lead prompt:

Task(
  name="{teammate.name}",
  team_name="{team.name}",
  subagent_type="{resolved.subagent_type}",
  model="{resolved.model}",
  mode="{resolved.mode}",
  run_in_background=true,
  prompt="{full teammate prompt from lead-prompt.md}"
)

The teammate prompt includes:

Identity (name, branch)
Working directory (worktree path)
Path rules table (CRITICAL — ensures teammate works in correct worktree)
Focus area
Task workflow instructions

Step 4: Assign tasks

TaskUpdate(taskId="N", owner="{teammate.name}")

Deliverable: All teammates spawned and working in parallel

Phase 4: COORDINATE

Goal: Monitor, support, and wrap up

Monitor progress:

Check TaskList periodically to see task status
Teammates send messages when they complete work or hit blockers
Respond to teammate messages with guidance or decisions

Health Monitoring:

Teammates can become unresponsive or crash. Use health monitoring to detect issues:

Manual health checks:
```
cck crew doctor [profile]
```
Displays health table showing each teammate's status, last activity, and recent commits.
Automated monitoring protocol (every 10-15 minutes):
- If a teammate is silent for >10 minutes, send them a message:
```
SendMessage(type="message", recipient="{name}", content="Status check: still working?")
```
- Wait 2 minutes for response
- If still no response, check their worktree:
```
git -C {worktree_path} log --oneline -5
git -C {worktree_path} status
```
- If worktree shows no recent activity:
  - Teammate likely crashed
  - Re-spawn using stored spawn prompt (see below)
Re-spawning crashed teammates:
- Spawn prompts are stored in team-state.json automatically
- To re-spawn, use the same Task call with the stored prompt
- The teammate will resume in the same worktree with context preserved
Health status meanings:
- active (✓): Updated recently, working normally
- idle (○): No recent updates but not yet stale, may be thinking
- unresponsive (⚠): Stale beyond threshold, may need attention
- crashed (✗): Worktree exists but no activity and very stale, needs re-spawn

When teammates report completion:

Check their commits:

git -C {worktree_path} log --oneline -5

Optionally review their diff:

git -C {worktree_path} diff {main_branch} --stat

When ALL tasks are complete:

Verify each branch has commits
Run merge preview to check for conflicts:
```
cck crew merge-preview [profile]
```
Review the preview results:
- Clean merges (✓): Can be auto-merged safely
- Conflicts (✗): Will require manual resolution
- Overlapping changes: Files modified by multiple teammates
Share preview results with user and recommend strategy:
- If all clean: "All branches can merge cleanly. Proceed with merge?"
- If conflicts: "N branches have conflicts. Options: (1) merge clean branches first, (2) resolve conflicts manually, (3) review with teammates"
Execute merge if user approves:
```
cck crew merge [profile]
```
Optional flags:
- --test: Run tests after each merge (rollback on failure)
- --test-command="npm run test:ci": Custom test command

If merge fails with conflicts, guide user:

git merge {branch}
# Resolve conflicts manually
git add .
git commit

Shut down teammates:

SendMessage(type="shutdown_request", recipient="{name}", content="Work complete, shutting down.")

Clean up worktrees:
```
cck crew stop [profile] --cleanup
```
Remove .crew-config.json if it was created for this session only

Deliverable: All work merged, teammates shut down, worktrees cleaned

Role Presets Reference

Roles set sensible defaults. Explicit fields in config always override role defaults.

| Role | Model | Mode | Focus Default | |------|-------|------|---------------| | developer | sonnet | bypassPermissions | Implement features, write code, fix bugs | | reviewer | sonnet | default | Review code for bugs, security, quality. Read-only | | tester | haiku | bypassPermissions | Write and run tests, ensure coverage | | architect | opus | default | Design architecture, review patterns. Read-only |

Config Formats

Single team (simple):

{
  "team": {
    "name": "my-team",
    "teammates": [
      { "name": "alice", "branch": "feat/auth", "worktree": true, "role": "developer", "focus": "Build auth" }
    ]
  },
  "project": { "main_branch": "main" }
}

Multiple profiles (advanced):

{
  "profiles": {
    "dev": {
      "name": "dev-team",
      "teammates": [
        { "name": "backend", "branch": "feat/api", "role": "developer", "focus": "API work" },
        { "name": "frontend", "branch": "feat/ui", "role": "developer", "focus": "UI work" }
      ]
    },
    "review": {
      "name": "reviewers",
      "teammates": [
        { "name": "reviewer", "branch": "main", "worktree": false, "role": "reviewer" }
      ]
    }
  },
  "default": "dev",
  "project": { "main_branch": "main" }
}

Anti-Patterns

Don't use crew for single tasks — Use Task tool directly for one-off sub-agents
Don't spawn sequentially — Always spawn all teammates in a single message
Don't forget task assignment — Teammates need TaskUpdate(owner=...) to know their work
Don't merge without verifying — Check teammate commits before merging branches
Don't use worktrees for sub-agents — Only crew teammates get worktrees. Regular Task tool agents work in the main project directory
Don't skip path rules — Teammate prompts MUST include worktree path rules to prevent cross-worktree file access

Success Criteria

All 4 phases completed (not skipped)
Config validated before launch
All teammates spawned in parallel (single message)
Tasks assigned to correct teammates
Teammate work verified before merge
Clean shutdown and worktree cleanup

Agent Skills: Crew Orchestrator

Install this agent skill to your local

Skill Files