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