# clanker-teams: Agent Guide 🤖

This guide explains how `clanker-teams` transforms your single clanker agent into a coordinated team of specialists. It covers the roles, capabilities, and coordination patterns available to you as the **Team Lead**.

---

## 🎭 The Two Roles

In a `clanker-teams` environment, there are two distinct types of agents:

### 1. The Team Lead (You)

The agent in your main terminal window. You are responsible for:

- **Strategy**: Creating the team and defining its goals.
- **Delegation**: Spawning teammates and assigning them specific roles.
- **Coordination**: Managing the shared task board and broadcasting updates.
- **Quality Control**: Reviewing plans and approving finished work.

### 2. Teammates (The Specialists)

Agents spawned in separate panes. They are designed for:

- **Focus**: Executing specific, isolated tasks (e.g., "Security Audit", "Frontend Refactor").
- **Parallelism**: Working on multiple parts of the project simultaneously.
- **Autonomy**: Checking their own inboxes, submitting plans, and reporting progress without constant hand-holding.

---

## 🛠 Capabilities

### 🚀 Specialist Spawning

You can create teammates with custom identities, models, and reasoning depths:

- **Custom Roles**: "Spawn a 'CSS Expert' to fix the layout shifts."
- **Model Selection**: Use `gpt-4o` for complex architecture and `haiku` for fast, repetitive tasks.
- **Thinking Levels**: Set thinking to `high` for deep reasoning or `off` for maximum speed.

### 📋 Shared Task Board

A centralized source of truth for the entire team:

- **Visibility**: Everyone can see the full task list and who owns what.
- **Status Tracking**: Tasks move through `pending` ➔ `planning` ➔ `in_progress` ➔ `completed`.
- **Ownership**: Assigning a task to a teammate automatically notifies them.

### 💬 Coordination & Messaging

Communication flows naturally between team members:

- **Direct Messaging**: Send specific instructions to one teammate.
- **Broadcasts**: Announce global changes (like API updates) to everyone at once.
- **Inbox Polling**: Teammates automatically "wake up" to check for new work every 30 seconds when idle.

### 🛡️ Plan Approval Mode

For critical changes, you can require teammates to submit a plan before they start:

1. Teammate analyzes the task and calls `task_submit_plan`.
2. You review the plan in the Lead pane.
3. You `approve` (to start work) or `reject` (with feedback for revision).

---

## 💡 Coordination Patterns

### Pattern 1: The "Parallel Sprint"

Use this when you have 3-4 independent features to build.

1. Create a team: `team_create({ team_name: "feature-sprint" })`
2. Spawn specialists for each feature.
3. Create tasks for each specialist.
4. Monitor progress while you work on the core architecture.

### Pattern 2: The "Safety First" Audit

Use this for refactoring or security work.

1. Spawn a teammate with `plan_mode_required: true`.
2. Assign the refactoring task.
3. Review their proposed changes before any code is touched.
4. Approve the plan to let them execute.

### Pattern 3: The "Quality Gate"

Use automated hooks to ensure standards.

1. Define a script at `.clanker/team-hooks/task_completed.sh`.
2. When any teammate marks a task as `completed`, the hook runs (e.g., runs `npm test`).
3. If the hook fails, you'll know the work isn't ready.

---

## 🛑 When to Use clanker-teams

- **Complex Projects**: Tasks that involve multiple files and logic layers.
- **Research & Execution**: One agent researches while another implements.
- **Parallel Testing**: Running different test suites in parallel.
- **Code Review**: Having one agent write code and another (specialized) agent review it.

## ⚠️ Best Practices

- **Isolation**: Give teammates tasks that don't overlap too much to avoid git conflicts.
- **Clear Prompts**: Be specific about the teammate's role and boundaries when spawning.
- **Check-ins**: Use `task_list` regularly to see the "big picture" of your team's progress.