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:

bash

# 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:

bash

# 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:

bash

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:

bash

/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:

bash

/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:

bash

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

Example:

bash

/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:

bash

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

Examples:

bash

/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:

bash

/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:

bash

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

•

Message team-lead (for guidance or escalation):

bash

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

•

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

bash

/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):

bash

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

Examples:

bash

/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:

bash

/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):

bash

/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:

bash

/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

code

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:

bash

/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:

bash

/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:

bash

/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

bash

# 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

bash

# 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

bash

# 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

bash

# 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.