---
name: teamup
description: Design an agent team plan for complex tasks. Presents overall plan and team task allocation for user review before execution.
disable-model-invocation: true
argument-hint: <task-description>
---

# Agent Team Planner

Design an agent team execution plan for:

**Task:** `$ARGUMENTS`

---

## Phase 1: Analyze the Task

Before designing the team, evaluate whether an agent team is the right approach:

### When to Use Agent Teams

| Good Fit | Bad Fit |
|----------|---------|
| Multiple independent modules/files | Sequential chain where each step depends on the last |
| Parallel research or review from different angles | Same-file edits (causes overwrites) |
| Cross-layer work (frontend + backend + tests) | Simple single-module tasks |
| Competing hypotheses for debugging | Routine tasks with little parallelization benefit |

> **Rule:** If the task is mostly sequential with tight dependencies, use subagents (`Agent` tool) instead of a full team. Agent teams shine when work can genuinely run in parallel across different files.

---

## Phase 2: Overall Plan

Design a **high-level execution plan**:

| Item | Description |
|-------|-------------|
| **Goal** | What is the final deliverable? |
| **Phases** | What are the major phases/steps? |
| **Sequence** | Which phases are parallel vs sequential? |
| **Dependencies** | What must complete before what? |
| **File Ownership** | Which files belong to which phase? (no overlaps!) |
| **Risks** | Potential failure points or blockers |

### Plan Outline

```
1. [Phase Name]
   - Objective: ...
   - Key steps: ...
   - Files touched: ... (must not overlap with other parallel phases)
   - Success criteria: ...

2. [Phase Name]
   - ...
```

---

## Phase 3: Team Design

### Team Size

| Task Scope | Recommended Size | Rationale |
|------------|-----------------|-----------|
| Single module, review/research | 2-3 teammates | Distinct review angles |
| Multi-module feature | 3-4 teammates | One per domain area |
| Large cross-layer feature | 4-5 teammates | Multiple domains + synthesis |

> **Rules:**
> - 3-5 teammates is the sweet spot for most workflows
> - Each teammate should have 2-4 tasks max
> - If a teammate would have 5+ tasks, split into two teammates
> - Keep teams small — coordination overhead grows with team size

### Teammate Definition

For each teammate, define:

| Field | Description |
|-------|-------------|
| **Name** | Unique identifier (e.g., `auth-dev`, `api-reviewer`, `test-writer`) |
| **Role Type** | researcher / coder / reviewer / tester / architect |
| **Expertise** | What this teammate specializes in |
| **Responsibilities** | 2-4 distinct responsibilities max |
| **Model** | `sonnet` (routine/review), `opus` (complex reasoning), `haiku` (simple tasks) |
| **Owned Files** | Files this teammate will read/write — **no overlap with other teammates** |

### Model Selection Guide

| Task Type | Model | Rationale |
|-----------|-------|-----------|
| Code review, research, testing | `sonnet` | Good capability, cost-effective |
| Architecture decisions, complex logic | `opus` | Best reasoning for hard problems |
| Simple file reads, formatting checks | `haiku` | Fast, lowest cost |

### File Ownership — Critical Rule

**Each file must be owned by exactly one teammate.** Multiple teammates writing to the same file causes overwrites and lost work. If two teammates need to modify the same file, make it sequential: one writes, the other reviews/extends after.

---

## Phase 4: Task Allocation

### Execution Modes

| Mode | When to Use | Example |
|------|-------------|---------|
| **Parallel** | Tasks are independent, no shared files | Three reviewers examining different aspects |
| **Sequential** | Task B needs Task A's output | API spec → API implementation |
| **Hybrid** | Some parallel + some sequential | Parallel research → sequential implementation |

### Task Allocation Matrix

| Task ID | Phase/Step | Assigned To | Description | Files | Dependencies | Mode |
|---------|-----------|-------------|-------------|-------|--------------|------|
| task-1 | Phase 1, Step A | `teammate-1` | ... | ... | none | parallel |
| task-2 | Phase 1, Step B | `teammate-2` | ... | ... | none | parallel |
| task-3 | Phase 2, Step A | `teammate-1` | ... | ... | task-1 | sequential |

### Dependency Rules

- Tasks with unresolved dependencies are **blocked** and cannot be claimed
- The system automatically unblocks tasks when dependencies complete
- Sequential tasks may run on fewer teammates — no need to keep all teammates busy during wait phases
- Always define explicit task IDs for dependency tracking

---

## Phase 5: Execution Plan

### Execution Flow

```
User Approval
  → TeamCreate (spawn teammates with roles and models)
  → TaskCreate (create all tasks with dependencies)
  → Teammates self-claim unblocked tasks
  → [Parallel / Sequential / Hybrid execution]
  → Lead monitors progress via TaskList
  → Lead synthesizes results when all tasks complete
  → TeamDelete (clean up)
```

### Key Execution Notes

1. **Task creation:** Create all tasks upfront with proper `dependencies` arrays. The system manages unblocking automatically.
2. **Self-claiming:** Teammates pick up unassigned, unblocked tasks independently. Explicit assignment via `assigned_to` is optional but recommended for specialized work.
3. **Communication:** Use `SendMessage` to redirect teammates, give additional context, or ask for status. Teammates can also message each other.
4. **Monitoring:** Lead should periodically check `TaskList` to track progress. If a teammate stalls, send it a message or check its task status.
5. **Completion:** Wait for ALL teammates to complete before synthesizing. Don't shut down early.
6. **Cleanup:** Always `TeamDelete` when done to free resources and avoid orphaned processes.

### Worktree Isolation (Optional)

For teammates doing risky or experimental work, consider spawning with `isolation: "worktree"` to give them an isolated copy of the repository. Changes can be reviewed before merging.

---

## Phase 6: Cost & Risk Awareness

### Token Cost

- Each teammate maintains its own context window
- Teams use ~7x more tokens than a single session in plan mode
- **Minimize team size** — only add teammates when work genuinely benefits from parallelism

### Common Pitfalls

| Pitfall | Prevention |
|---------|------------|
| File conflicts from parallel edits | Enforce strict file ownership per teammate |
| Tasks not marked complete, blocking dependents | Lead monitors via TaskList, manually updates if needed |
| Lead shuts down before teammates finish | Explicitly wait for all tasks to complete |
| Over-parallelization of dependent work | Use sequential mode when there are real dependencies |
| Teammates going idle prematurely | Use TeammateIdle hook or send instructions via SendMessage |
| Orphaned tmux sessions | Always TeamDelete; check `tmux ls` if needed |

---

## User Review

**Please review the plan above:**

### Overall Plan
1. Is the high-level plan sound?
2. Are phases correctly sequenced?
3. Are file ownerships clear with no overlaps?

### Team Structure
4. Is the team size appropriate?
5. Are model choices cost-effective for each role?
6. Are task allocations balanced (2-4 tasks per teammate)?

### Dependencies
7. Are task dependencies correctly defined?
8. Is the parallel vs sequential split right?

**Once approved:**
- Reply **`teamup approve`** to execute the plan
- Or provide feedback for modifications