Simple Swarm Example

A two-agent swarm implementing a feature with coordinated file claiming.

Scenario

Task: Add user authentication to an Express API

Initial Setup

Swarm Status File

.claude/swarm-status.json:

{
  "swarm_id": "auth-feature-001",
  "task": "Add user authentication",
  "started": "2025-01-15T10:00:00Z",
  "phase": "initialized",
  "agents": {}
}

File Claims Registry

.claude/file-claims.md:

# File Claims Registry

Last updated: 2025-01-15T10:00:00Z
Swarm ID: auth-feature-001

| Agent ID | File Path | Claimed At | Status |
|----------|-----------|------------|--------|

Phase 1: Planning

Launch two planning agents:

Agent 1 Prompt:

Analyze the codebase and create an implementation plan for:
Adding JWT token validation middleware

You are in PLANNING MODE - DO NOT modify any files.
Output a structured plan with all files you need to modify.

Agent 2 Prompt:

Analyze the codebase and create an implementation plan for:
Adding user login/logout API endpoints

You are in PLANNING MODE - DO NOT modify any files.
Output a structured plan with all files you need to modify.

Agent 1 Plan Output

.claude/swarm-plans/jwt-middleware.md:

## Agent Plan: jwt-middleware

### Task Summary
Implement JWT token validation middleware for protected routes.

### Files to Modify
- `src/middleware/index.ts`: Export new auth middleware

### Files to Create
- `src/middleware/auth.ts`: JWT validation middleware
- `src/types/auth.ts`: Token payload types

### Dependencies
- Requires: None
- Blocks: Protected routes need this middleware

### Implementation Steps
1. Create auth types
2. Implement JWT validation middleware
3. Export from middleware index

Agent 2 Plan Output

.claude/swarm-plans/auth-endpoints.md:

## Agent Plan: auth-endpoints

### Task Summary
Implement login and logout API endpoints.

### Files to Modify
- `src/routes/index.ts`: Add auth routes
- `src/middleware/index.ts`: Import auth utilities

### Files to Create
- `src/routes/auth.ts`: Login/logout endpoints
- `src/services/auth.ts`: Authentication service

### Dependencies
- Requires: JWT middleware for logout validation
- Blocks: None

### Implementation Steps
1. Create auth service
2. Implement auth routes
3. Update routes index
4. Update middleware index

Phase 2: Conflict Detection

Analyzing plans:

File: src/middleware/index.ts
  - jwt-middleware: modify (export new middleware)
  - auth-endpoints: modify (import auth utilities)
  → CONFLICT DETECTED

Conflict Report

## Conflict Analysis

### Conflicts Found: 1

#### Conflict 1: src/middleware/index.ts
Agents: jwt-middleware, auth-endpoints
Nature: Both agents plan to modify this file
- jwt-middleware: Add export for auth middleware
- auth-endpoints: Import auth utilities

**Resolution Options**:
1. Sequential: jwt-middleware first, then auth-endpoints
2. Merge: Have jwt-middleware handle all middleware/index.ts changes

Phase 3: Resolution

Chosen Resolution: Option 1 - Sequential execution

Updated execution plan:

• Batch 1: jwt-middleware (no dependencies)
• Batch 2: auth-endpoints (after jwt-middleware completes)

Phase 4: File Claiming

Updated .claude/file-claims.md:

# File Claims Registry

Last updated: 2025-01-15T10:05:00Z
Swarm ID: auth-feature-001

| Agent ID | File Path | Claimed At | Status |
|----------|-----------|------------|--------|
| jwt-middleware | src/middleware/auth.ts | 2025-01-15T10:05:00Z | claimed |
| jwt-middleware | src/middleware/index.ts | 2025-01-15T10:05:00Z | claimed |
| jwt-middleware | src/types/auth.ts | 2025-01-15T10:05:00Z | claimed |
| auth-endpoints | src/routes/auth.ts | 2025-01-15T10:05:00Z | pending |
| auth-endpoints | src/routes/index.ts | 2025-01-15T10:05:00Z | pending |
| auth-endpoints | src/services/auth.ts | 2025-01-15T10:05:00Z | pending |

Note: auth-endpoints claims are "pending" until jwt-middleware completes.

Phase 5: Implementation

Batch 1: jwt-middleware

Launch jwt-middleware agent with implementation instructions:

Execute your approved plan from .claude/swarm-plans/jwt-middleware.md
Only modify files claimed by jwt-middleware in .claude/file-claims.md

Status after 45 seconds (from status-checker):

{
  "overall_health": "healthy",
  "agents": {
    "jwt-middleware": {"status": "working", "progress": "Creating middleware"}
  }
}

Status after 2 minutes:

{
  "overall_health": "healthy",
  "agents": {
    "jwt-middleware": {"status": "completed"}
  }
}

Release Claims & Activate Batch 2

Updated .claude/file-claims.md:

| jwt-middleware | src/middleware/auth.ts | 2025-01-15T10:05:00Z | released |
| jwt-middleware | src/middleware/index.ts | 2025-01-15T10:05:00Z | released |
| jwt-middleware | src/types/auth.ts | 2025-01-15T10:05:00Z | released |
| auth-endpoints | src/routes/auth.ts | 2025-01-15T10:07:00Z | claimed |
| auth-endpoints | src/routes/index.ts | 2025-01-15T10:07:00Z | claimed |
| auth-endpoints | src/services/auth.ts | 2025-01-15T10:07:00Z | claimed |
| auth-endpoints | src/middleware/index.ts | 2025-01-15T10:07:00Z | claimed |

Note: auth-endpoints now also claims middleware/index.ts after jwt-middleware released it.

Batch 2: auth-endpoints

Launch auth-endpoints agent with implementation instructions.

Status after 3 minutes:

{
  "overall_health": "healthy",
  "agents": {
    "jwt-middleware": {"status": "completed"},
    "auth-endpoints": {"status": "completed"}
  },
  "completion_percentage": 100
}

Phase 6: Verification

Checks:

• ☑ jwt-middleware completed
• ☑ auth-endpoints completed
• ☑ All files modified as planned
• ☑ No orphaned claims
• ☑ Build succeeds
• ☑ Tests pass

Phase 7: Summary

## Swarm Completion Report

### Task: Add user authentication
### Duration: 8 minutes
### Agents: 2

### Files Created
- src/middleware/auth.ts
- src/types/auth.ts
- src/routes/auth.ts
- src/services/auth.ts

### Files Modified
- src/middleware/index.ts
- src/routes/index.ts

### Conflicts Resolved
- 1 conflict on src/middleware/index.ts (sequential resolution)

### Status: SUCCESS