clanker-agent/packages/companion-teams/AGENTS.md

companion-teams: Agent Guide 🤖

This guide explains how companion-teams transforms your single companion 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 companion-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 .companion/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 companion-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.