swarm-workflow

Split large tasks across multiple Claude Code sessions or branches. Coordinate parallel work with merge gates. Use when task is too large for one session, want parallel work, or need to split work across branches.

⭐8stars🔀0forks📁View on GitHub🕐Updated Jan 3, 2026⬇️1downloads

When & Why to Use This Skill

The Swarm Workflow skill is a sophisticated orchestration framework designed to scale Claude Code's capabilities across complex, large-scale software projects. By implementing a 'divide and conquer' strategy, it enables the decomposition of massive tasks into parallelizable units, managed through independent sessions and Git branches. This skill optimizes AI performance by preventing context window overflow and ensuring architectural consistency through predefined interfaces and rigorous merge gates, making it essential for high-velocity, multi-threaded AI development.

Use Cases

  • Complex Feature Engineering: Breaking down a multi-layered feature (e.g., Auth, API, and UI) into independent sub-tasks that multiple Claude sessions can execute simultaneously.
  • Context Window Optimization: Managing large-scale refactoring or migrations by splitting work across branches to keep the AI's context focused and prevent performance degradation on massive codebases.
  • Parallel Development Coordination: Establishing 'Merge Gates' and 'Session Handoffs' to allow multiple AI agents to work on different modules without creating merge conflicts or architectural drift.
  • Systematic Integration Testing: Using a structured integration branch strategy to validate parallel contributions from different AI sessions before merging them into the main production branch.
nameswarm-workflow
descriptionSplit large tasks across multiple Claude Code sessions or branches. Coordinate parallel work with merge gates. Use when task is too large for one session, want parallel work, or need to split work across branches.
allowed-toolsRead, Grep, Glob

Swarm Workflow

Coordinates parallel work across multiple sessions and branches.

When to Use

  • "This is too big for one session"
  • "Split this into parallel tasks"
  • "How do I swarm this?"
  • "Divide and conquer this feature"
  • "Parallel development workflow"

Swarm Strategy

When to Swarm

  • Task touches 5+ unrelated files
  • Multiple independent features in one request
  • Long-running task risks context overflow
  • Work can proceed in parallel without blocking

When NOT to Swarm

  • Simple single-file changes
  • Tightly coupled changes that must be atomic
  • Exploratory work where scope is unclear
  • Tasks requiring deep context continuity

Branch Strategy

main
├── feature/task-a-auth
├── feature/task-b-api
├── feature/task-c-ui
└── feature/integration (merge point)

Naming Convention

feature/{task-id}-{short-description}

Merge Order

  1. Independent branches merge to integration branch
  2. Resolve conflicts in integration
  3. Integration branch merges to main

Procedure

Step 1: Analyze Task

Break down the request into independent units:

## Task Decomposition

### Original Request

{user's request}

### Independent Units

1. **{Unit A}**
   - Files: {list}
   - Dependencies: none
   - Can run parallel: yes

2. **{Unit B}**
   - Files: {list}
   - Dependencies: Unit A types only
   - Can run parallel: yes (with interface)

3. **{Unit C}**
   - Files: {list}
   - Dependencies: Units A and B
   - Must wait for: A, B to complete

Step 2: Define Interfaces

For units that depend on each other, define interfaces first:

// Shared interface (commit first)
export interface UserService {
  getUser(id: string): Promise<User>;
  updateUser(id: string, data: Partial<User>): Promise<User>;
}

Step 3: Create Branch Plan

## Branch Plan

### Branch 1: feature/task-auth

- Assignee: Session 1
- Files:
  - packages/auth/src/...
  - apps/web/app/api/auth/...
- Tests: packages/tests/src/auth.\*.test.ts
- Definition of Done:
  - [ ] Auth endpoints working
  - [ ] Tests passing
  - [ ] TypeScript compiles

### Branch 2: feature/task-api

- Assignee: Session 2
- Files:
  - apps/web/app/api/users/...
- Tests: packages/tests/src/users.test.ts
- Definition of Done:
  - [ ] CRUD endpoints working
  - [ ] Tests passing
  - [ ] TypeScript compiles

### Merge Gate

- [ ] All branches pass CI
- [ ] No merge conflicts
- [ ] Integration tests pass

Step 4: Handoff Instructions

For each branch/session:

## Session Handoff: {Branch Name}

### Context

{Brief description of overall task}

### Your Assignment

{Specific work for this session}

### Files to Modify

- {file1}: {what to do}
- {file2}: {what to do}

### Interfaces to Use (Do Not Modify)

- {interface file}

### Definition of Done

1. {criterion 1}
2. {criterion 2}
3. pnpm typecheck passes
4. pnpm lint passes
5. Tests pass

### When Complete

1. Commit with message: "{conventional commit}"
2. Push to branch: {branch-name}
3. Create PR to: feature/integration

Merge Gates

Before Merge to Integration

  • CI passes on branch
  • No uncommitted changes
  • All DoD criteria met
  • PR reviewed (if required)

Before Merge to Main

  • All branches merged to integration
  • Conflicts resolved
  • Full test suite passes
  • Integration testing complete

Guardrails

  • ALWAYS define interfaces before parallel work
  • NEVER have two branches modify same file
  • Commit interfaces first, then implementations
  • Each branch must pass CI independently
  • Merge frequently to avoid drift
  • Document assumptions in PR descriptions