crew

# 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**
```bash
cat .crew-config.json
```

**If config exists**:
1. Read and validate the config
2. Show team summary to user:
   ```
   Team: {name}
   Profile: {profile}
   Teammates:
   | Name | Role | Branch | Model |
   |------|------|--------|-------|
   | ... | ... | ... | ... |
   ```
3. If multiple profiles exist, ask which one to use
4. Confirm with user before proceeding

**If no config exists**:
1. **Option A: Auto-decompose (recommended for large codebases)**
   - Suggest running smart task decomposition:
     ```bash
     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`

2. **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):
     ```json
     {
       "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):
     ```json
     {
       "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**
```bash
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:
```bash
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**: A