name: parallel-swarm
description: Spawn and coordinate multiple parallel agents for maximum throughput. Optimized for 64-core systems. Includes safety rules, coordination patterns, and swarm templates.
license: MIT
metadata:
author: thesimpleapp
version: "1.0"

Parallel Agent Swarm

Unleash multiple agents working in parallel. Optimized for high-core systems.

Hardware Profile

YOUR SYSTEM:
├── CPU: 64 cores → Up to 10+ parallel agents
├── RAM: 128GB → Large context windows per agent
├── GPU: 3090 → Available for local model fallback
└── Network: Fast → Parallel API calls

Core Principle

Sequential (Old Way):
Task 1 → Task 2 → Task 3 → Task 4 → Task 5
                                          ↓
                                    Total: 50 min

Parallel Swarm (New Way):
Task 1 ─┐
Task 2 ─┼─→ All complete
Task 3 ─┤        ↓
Task 4 ─┤   Total: 10 min
Task 5 ─┘

Swarm Patterns

Pattern 1: Feature Blast

Build multiple features simultaneously:

SPAWN 5 AGENTS:

Agent-1: "Build user profile component"
  └─ Files: src/features/profile/*

Agent-2: "Build settings page"
  └─ Files: src/features/settings/*

Agent-3: "Build notification system"
  └─ Files: src/features/notifications/*

Agent-4: "Build dashboard widgets"
  └─ Files: src/features/dashboard/*

Agent-5: "Build search functionality"
  └─ Files: src/features/search/*

SAFETY: Each agent owns different /features/* folder

Pattern 2: Test Blitz

Generate tests for entire codebase:

SPAWN 4 AGENTS:

Agent-1: "Write tests for /components/*"
  └─ Output: __tests__/components/*

Agent-2: "Write tests for /hooks/*"
  └─ Output: __tests__/hooks/*

Agent-3: "Write tests for /services/*"
  └─ Output: __tests__/services/*

Agent-4: "Write tests for /utils/*"
  └─ Output: __tests__/utils/*

SAFETY: Each agent writes to different test folder

Pattern 3: Codebase Analysis

Analyze entire codebase in parallel:

SPAWN 5 AGENTS:

Agent-1: "Analyze architecture and patterns"
  └─ Output: docs/analysis/architecture.md

Agent-2: "Find security vulnerabilities"
  └─ Output: docs/analysis/security.md

Agent-3: "Identify performance issues"
  └─ Output: docs/analysis/performance.md

Agent-4: "Document API contracts"
  └─ Output: docs/analysis/api.md

Agent-5: "Catalog technical debt"
  └─ Output: docs/analysis/tech-debt.md

SAFETY: Read-only analysis, separate output files

Pattern 4: Bulk Refactor

Refactor many files with same pattern:

FILES TO REFACTOR: 50 components

BATCH INTO 5 AGENTS (10 files each):

Agent-1: Files 1-10
Agent-2: Files 11-20
Agent-3: Files 21-30
Agent-4: Files 31-40
Agent-5: Files 41-50

PATTERN: "Convert class components to functional"

SAFETY: No file overlap, same transformation

Pattern 5: Documentation Sprint

Document everything simultaneously:

SPAWN 3 AGENTS:

Agent-1: "Generate API documentation"
  └─ Output: docs/api/*

Agent-2: "Generate component storybook"
  └─ Output: docs/components/*

Agent-3: "Generate architecture diagrams"
  └─ Output: docs/architecture/*

SAFETY: Different doc folders, no overlap

Safety Rules

NEVER Parallel

✗ Same file from multiple agents
✗ Shared config files (package.json, etc.)
✗ Database migrations
✗ Core type definitions
✗ Shared utilities being modified
✗ Git operations

SAFE to Parallel

✓ Different feature folders
✓ Independent test files
✓ Separate documentation
✓ Non-overlapping modules
✓ Read-only analysis
✓ Different output destinations

File Locking

# Conceptual file lock tracking
locked_files = set()

def can_agent_modify(agent_id, file_path):
    if file_path in locked_files:
        return False
    locked_files.add(file_path)
    return True

def release_lock(agent_id, file_path):
    locked_files.discard(file_path)

Coordination Patterns

Handoff Files

When agents need to share information:

Agent-1 completes → Writes HANDOFF_1.md
Agent-2 waits → Reads HANDOFF_1.md → Continues

# HANDOFF_1.md
## Completed by Agent-1
- Created user types at src/types/user.ts
- Export: User, UserProfile, UserSettings

## For Agent-2
- Import types from src/types/user.ts
- User type has id, email, name fields

Dependency Order

When tasks have dependencies:

BATCH 1 (Parallel):
├── Agent-1: Create data models
├── Agent-2: Create API client
└── Agent-3: Create UI components

WAIT FOR BATCH 1...

BATCH 2 (Parallel):
├── Agent-4: Connect UI to API
└── Agent-5: Add error handling

WAIT FOR BATCH 2...

BATCH 3 (Sequential):
└── Agent-6: Integration tests

Merge Strategy

After parallel work:

1. Each agent commits to feature branch
2. Review all changes
3. Resolve any conflicts
4. Merge to main
5. Run full test suite

Execution Templates

Quick Parallel (3 Agents)

Launch 3 agents for:
- Agent A: [specific task and files]
- Agent B: [specific task and files]
- Agent C: [specific task and files]

Wait for all to complete.
Verify no conflicts.

Full Swarm (10 Agents)

Analyze codebase → Divide into 10 modules
Spawn 10 agents → Each handles 1 module
Coordinate via handoff files
Merge results
Run verification

Claude Code Integration

Using the Task tool for parallel agents:

# Spawn parallel agents
[Use Task tool with run_in_background=true for each]

Agent 1: Task(prompt="...", subagent_type="general-purpose", run_in_background=true)
Agent 2: Task(prompt="...", subagent_type="general-purpose", run_in_background=true)
Agent 3: Task(prompt="...", subagent_type="general-purpose", run_in_background=true)

# Check progress
TaskOutput(task_id="agent-1-id", block=false)

# Wait for completion
TaskOutput(task_id="agent-1-id", block=true)

Performance Benchmarks

TASK: Analyze 100-file codebase

Sequential (1 agent):     ~25 minutes
Parallel (5 agents):      ~5 minutes
Parallel (10 agents):     ~3 minutes

TASK: Generate tests for 50 components

Sequential:               ~2 hours
Parallel (5 agents):      ~25 minutes

TASK: Refactor 100 files

Sequential:               ~3 hours
Parallel (10 agents):     ~20 minutes

Error Handling

If agent fails:
1. Log the error
2. Do NOT retry automatically (might conflict)
3. Notify user
4. Continue with other agents
5. Manual intervention for failed task

If conflict detected:
1. Stop both conflicting agents
2. Show diff of changes
3. User resolves manually
4. Resume remaining agents

Integration

/parallel-swarm       → Spawn multiple agents
       ↓
/auto-model           → Each agent gets optimal model
       ↓
/orchestrator         → Coordinates the swarm
       ↓
/full-access          → Agents have all permissions