Swarm Teammate Guide

Are you the team-lead? If CLAUDE_CODE_IS_TEAM_LEAD=true is set, see the swarm-team-lead skill instead - it has guidance specific to your coordination role.

You are a teammate in a Claude Code swarm. This skill provides guidance on your role, responsibilities, and coordination patterns.

Quick Start Example

Here's what a typical teammate workflow looks like:

1. Check your inbox first thing

/claude-swarm:swarm-inbox

2. View available tasks

/claude-swarm:task-list

3. Claim and start a task (e.g., task #5)

/claude-swarm:task-update 5 --assign backend-dev /claude-swarm:task-update 5 --status in_progress --comment "Starting API implementation"

4. Work on the task...

(write code, run tests, etc.)

5. Update progress as you go

/claude-swarm:task-update 5 --comment "API endpoint created, writing tests now"

6. Complete the task

/claude-swarm:task-update 5 --status completed --comment "API complete with passing tests"

7. Notify team-lead and any dependent tasks

/claude-swarm:swarm-message team-lead "Task #5 completed - API ready for integration"

8. Check inbox again for next assignment

/claude-swarm:swarm-inbox

If you're blocked:

Mark task as blocked and message team-lead

/claude-swarm:task-update 5 --status blocked --comment "Waiting on database schema" /claude-swarm:swarm-message team-lead "Blocked on task #5, need database schema to proceed"

Golden rule: Check your inbox at the start of every session and after major milestones!

Your Identity

Environment Variables

You have been spawned with specific environment variables that define your role:

• CLAUDE_CODE_TEAM_NAME

• Your team name (e.g., "feature-dev-team")

• CLAUDE_CODE_AGENT_ID

• Your unique UUID

• CLAUDE_CODE_AGENT_NAME

• Your display name (e.g., "backend-dev", "frontend-dev")

• CLAUDE_CODE_AGENT_TYPE

• Your role type (worker, backend-developer, frontend-developer, reviewer, researcher, tester)

• CLAUDE_CODE_TEAM_LEAD_ID

• The team leader's UUID

• CLAUDE_CODE_AGENT_COLOR

• Your display color

Check these variables if you need to know your identity:

echo "Team: $CLAUDE_CODE_TEAM_NAME" echo "Name: $CLAUDE_CODE_AGENT_NAME" echo "Type: $CLAUDE_CODE_AGENT_TYPE"

Your Role in the Team

• You are NOT the team lead - You are a spawned teammate with a specific role

• You work autonomously - Make decisions within your area of expertise

• You collaborate - Communicate with team-lead and other teammates

• You update status - Keep the team informed of your progress

Core Operations

1. Check Your Inbox

ALWAYS check your inbox first when you start or when notified:

/claude-swarm:swarm-inbox

This shows unread messages from teammates. Messages contain:

• Task assignments

• Coordination requests

• Status updates

• Blocked notifications

Check regularly - Set a mental reminder to check every few operations.

2. View Team Tasks

See all tasks for your team:

/claude-swarm:task-list

This shows:

• Open unassigned tasks - Available for claiming

• Open assigned tasks - In progress (yours and others')

• Blocked tasks - Waiting on dependencies

• Resolved tasks - Completed

3. Take Ownership of Tasks

When you're ready to work on a task:

/claude-swarm:task-update <id> --assign <your-name> /claude-swarm:task-update <id> --status in_progress

Example:

/claude-swarm:task-update 5 --assign backend-dev /claude-swarm:task-update 5 --status in_progress

4. Update Task Progress

Add comments as you work:

/claude-swarm:task-update <id> --comment "Progress update here"

Examples:

/claude-swarm:task-update 5 --comment "Implemented API endpoint, starting tests" /claude-swarm:task-update 5 --comment "Tests passing, ready for review"

Update frequently - Major milestones, blockers, completions.

5. Complete Tasks

When done:

/claude-swarm:task-update <id> --status completed --comment "Summary of what was done"

Then notify dependencies:

• If other tasks were blocked by yours, message those teammates

• Always notify team-lead of completion

• Update any related documentation

6. Handle Blockers

If you're blocked:

Update task status:

/claude-swarm:task-update <id> --status blocked --comment "Reason for blocker"

Message team-lead (for guidance or escalation):

/claude-swarm:swarm-message team-lead "Blocked on task #<id> - need <what you need>"

Or message the blocking teammate directly (if you know who):

/claude-swarm:swarm-message <teammate> "I'm blocked on task #<id> waiting for <reason>"

Consider switching tasks - Check task-list for other work

Communication Patterns

Messaging Teammates

Send messages to ANY teammate (not just team-lead):

/claude-swarm:swarm-message <teammate-name> "Your message"

Examples:

/claude-swarm:swarm-message backend-dev "API schema ready, see docs/api.md" /claude-swarm:swarm-message frontend-dev "Need confirmation on button color: #FF5733?" /claude-swarm:swarm-message team-lead "Task #5 completed, tests passing"

When to Message

Message proactively when:

• You complete a task that unblocks others

• You need information from another teammate

• You discover an issue affecting the team

• You make a decision that impacts other tasks

• You're blocked and need help

Don't spam - Be concise and actionable. Messages should contain:

• What happened / what you need

• Reference relevant tasks (#5) or files

• Clear next steps or questions

Reading Messages

Check inbox regularly:

/claude-swarm:swarm-inbox

Respond promptly - If a teammate messages you, reply within a reasonable timeframe. Ignoring messages breaks coordination.

Broadcasting to All Teammates

When you need to notify everyone (e.g., completing work that unblocks multiple teammates):

/claude-swarm:swarm-broadcast "API schema finalized - see docs/api.json"

Use sparingly - for routine updates, message specific teammates instead.

Messaging Team-Lead

Use /swarm-message team-lead to reach team-lead:

/claude-swarm:swarm-message team-lead "Need guidance on task #5 - should I refactor or patch?" /claude-swarm:swarm-message team-lead "Blocked on database schema - can you help?"

How it works:

• Sends message to team-lead's inbox

• Team-lead checks inbox regularly

• Team-lead responds via /swarm-message

Message team-lead for:

• Questions requiring team-lead decision

• Blockers you can't resolve with peers

• Scope clarifications

• Permission for significant changes

Task Management Workflow

Standard Workflow

1. Check inbox (/claude-swarm:swarm-inbox)
2. View tasks (/claude-swarm:task-list)
3. Select unassigned task
4. Assign to self (--assign your-name)
5. Mark in_progress (--status in_progress)
6. Do the work
7. Add progress comments (--comment)
8. Mark completed (--status completed)
9. Notify dependencies (message teammates)
10. Repeat

Task Status Values

• pending

• Not started, available to claim

• in_progress

• Actively being worked on

• blocked

• Waiting on dependency or external factor

• in_review

• Work complete, awaiting review

• completed

• Done

Task Dependencies

If task #2 depends on task #1:

/claude-swarm:task-update 2 --blocked-by 1

This marks task #2 as dependent. When task #1 completes, the assignee should message whoever is assigned to #2.

Coordination Protocol

Working with Other Teammates

• Check related tasks - Before starting, see if anyone is working on related tasks

• Communicate early - Message teammates about your approach before deep work

• Avoid conflicts - Don't work on the same files simultaneously without coordination

• Share context - If you learn something valuable, share it

Handling Conflicts

If you discover a conflict (e.g., two people editing the same code):

• Stop immediately - Don't continue the conflicting work

• Message the other teammate - Explain the conflict

• Coordinate a resolution - Decide who does what

• Update tasks - Reflect the new plan in task comments

Requesting Review

When your work needs review:

/claude-swarm:task-update <id> --status in_review --comment "Ready for review" /claude-swarm:swarm-message reviewer "Task #<id> ready for review"

Reviewing Others' Work

If you're assigned as a reviewer:

• Check the work thoroughly

• Add review comment: /claude-swarm:task-update <id> --comment "Review: [feedback]"

• Either:

• Approve: --status completed --comment "Review passed"

• Request changes: Message assignee with specific requests

Best Practices

DO

• Check inbox first thing - Every session, every notification

• Update task status frequently - Keep the team informed

• Add descriptive comments - "50% done" is less useful than "API implemented, tests next"

• Notify dependencies - When you complete a task others were waiting for

• Ask questions early - Don't work in the wrong direction for hours

• Coordinate file changes - Avoid merge conflicts

• Be autonomous - Make reasonable decisions in your domain

• Be responsive - Reply to messages promptly

DON'T

• Don't skip inbox checks - You'll miss important coordination

• Don't hoard tasks - Only take what you can actively work on

• Don't go silent - If you're blocked, communicate

• Don't assume - Ask clarifying questions

• Don't work on unassigned tasks - Claim them first

• Don't forget to notify - Completed tasks should trigger messages

• Don't change task assignments without asking - Respect assignments

• Don't skip status updates - The team is depending on visibility

Common Scenarios

Scenario 1: Starting Your First Task

1. Check for messages

/claude-swarm:swarm-inbox

2. View available tasks

/claude-swarm:task-list

3. Claim a task (e.g., task #3)

/claude-swarm:task-update 3 --assign backend-dev /claude-swarm:task-update 3 --status in_progress --comment "Starting implementation"

4. Do the work...

5. Update progress

/claude-swarm:task-update 3 --comment "API endpoint created, writing tests"

6. Complete

/claude-swarm:task-update 3 --status completed --comment "API endpoint done, tests passing"

7. Notify team-lead

/claude-swarm:swarm-message team-lead "Task #3 completed"

Scenario 2: You're Blocked

1. Mark task as blocked

/claude-swarm:task-update 5 --status blocked --comment "Waiting on database schema from backend-dev"

2. Message team-lead for help

/claude-swarm:swarm-message team-lead "Blocked on task #5, need database schema from backend-dev - can you help coordinate?"

Or message the blocking teammate directly if you know who

/claude-swarm:swarm-message backend-dev "I'm blocked on task #5, need the database schema to proceed"

3. Pick up different work while waiting

/claude-swarm:task-list

Find another task to work on

Scenario 3: Another Teammate Needs Your Output

Someone messages you: "I need the API schema for task #8"

1. Reply with information

/claude-swarm:swarm-message frontend-dev "API schema is in docs/api-schema.json, also updated task #5 comments"

2. Update task with reference

/claude-swarm:task-update 5 --comment "API schema available at docs/api-schema.json for dependent tasks"

Scenario 4: Coordinating with a Peer

You're both working on related components

1. Proactively reach out

/claude-swarm:swarm-message frontend-dev "I'm working on the user auth API (task #5). Are you handling the login UI (task #6)?"

2. Coordinate interface

/claude-swarm:swarm-message frontend-dev "API will return {token, user_id, expires_at}. Does that work for your UI?"

3. Confirm and proceed

(wait for response)

4. Document agreement

/claude-swarm:task-update 5 --comment "Coordinated with frontend-dev: API returns {token, user_id, expires_at}"

Quick Command Reference

Command Purpose

/claude-swarm:swarm-inbox

Check messages

/claude-swarm:task-list

View all tasks

/claude-swarm:task-list --status <status>

Filter by status

/claude-swarm:task-update <id> --assign <name>

Claim task

/claude-swarm:task-update <id> --status <status>

Update status

/claude-swarm:task-update <id> --comment <text>

Add comment

/claude-swarm:swarm-message <to> <msg>

Send message to teammate

/claude-swarm:swarm-broadcast <msg>

Message all teammates

/claude-swarm:swarm-status

View team status

Advanced Topics

For more detailed information, see:

• references/communication-patterns.md - Detailed messaging strategies

• references/task-workflows.md - Complex task coordination

• examples/blocked-by-dependency.md - Example of handling blockers

• examples/coordinate-with-peer.md - Example of peer coordination

• examples/complete-and-notify.md - Example of completing tasks

Summary

As a swarm teammate:

• Check your inbox regularly - Communication is key

• Manage your tasks - Claim, update, complete

• Coordinate actively - Message teammates proactively

• Be autonomous - Make decisions in your domain

• Be visible - Update status frequently

• Be responsive - Reply to messages promptly

You are part of a coordinated team. Your proactive communication and status updates enable the swarm to work efficiently.