am2rican5:parallel-agent-orchestration

What this skill does

# Parallel Agent Orchestration

## Critical Rules

- NEVER spawn parallel agents without explicit user confirmation of the work plan
- NEVER allow two agents to work on the same file simultaneously — verify file-level independence first
- ALWAYS set up a task-locking mechanism before launching parallel work
- ALWAYS verify task independence before parallelizing — if tasks share state, they must run sequentially
- WHEN a merge conflict occurs, STOP and ask the user how to resolve — do not auto-resolve
- WHEN an agent finishes, it MUST release its lock before picking up new work

## Instructions

### Step 1: Assess Task Decomposability

Analyze the work the user wants to parallelize:

1. List all subtasks or work items
2. For each pair of tasks, check: do they touch the same files? Do they depend on each other's output?
3. Classify each task as **independent** (can run in parallel) or **dependent** (must run after another task)
4. Present the dependency graph to the user for confirmation

IF all tasks touch the same files or share heavy state → recommend sequential execution and **stop**.
IF tasks are clearly independent → proceed to Step 2.

### Step 2: Set Up Task Locking Directory

Create a locking mechanism to prevent duplicate work:

1. Create a `_tasks/` directory in the working area (or use an existing task tracking system)
2. Create one file per task in `_tasks/available/` with the task description
3. Apply the lock-file protocol: agents claim tasks before starting, release on completion or failure. See `references/lock-protocol.md` for the full protocol (lock file format, claim-before-start, completion, failure, stale lock recovery).

### Step 3: Configure Conflict Avoidance Strategy

Choose an isolation strategy based on the work:

**Option A: Git Worktrees (Recommended for file-heavy work)**
- Create one worktree per agent: `git worktree add ../agent-<n> -b agent-<n>/work`
- Each agent operates in its own worktree on its own branch
- Merge results back to main branch after all agents complete
- Best when agents touch many files across the codebase

**Option B: Branch-Per-Agent (Lightweight)**
- Each agent works on its own branch: `agent-<n>/<task-name>`
- Agents commit and push to their branches independently
- Merge branches sequentially after all agents complete
- Best when tasks are well-scoped to specific directories

**Option C: File-Level Partitioning (Simplest)**
- Assign specific files to each agent upfront — no overlap allowed
- Agents work in the same branch but never touch each other's files
- Best when tasks map cleanly to distinct files

Present options to the user and let them choose.

### Step 4: Set Up the Autonomous Loop

Configure each agent to run the autonomous loop: scan for tasks → claim → execute → complete/fail → repeat. See `references/lock-protocol.md` for the full loop definition.

Launch agents using Claude Code's Task tool with `run_in_background: true` for parallel execution. Each agent gets:
- A clear system prompt describing its role and the task format
- The path to the `_tasks/` directory
- The conflict avoidance strategy from Step 3

### Step 5: Monitor Progress

While agents run:
1. Periodically check `_tasks/` directory for progress
2. Report: `N completed / M total (K in progress, F failed)`
3. IF any agent has been locked on a task for >30 minutes → flag it
4. IF all tasks are complete or failed → proceed to Step 6

### Step 6: Merge and Verify

After all agents finish:
1. If using worktrees or branches → merge all agent branches back
2. Run the project's test suite to verify nothing broke
3. Report final status: what was completed, what failed, any conflicts

## Examples

### Example: Parallelizing Test Fixes

User says: "Fix all failing tests in the auth, billing, and notifications modules"

Result: Three agents launched with file-level partitioning, each owning one module directory. All modules fixed in parallel, merge back cleanly.

### Example: Parallel Code Migration

User says: "Migrate all API endpoints from Express to Fastify"

Result: Shared middleware migrated sequentially first (dependency), then route files parallelized with branch-per-agent strategy.

See `references/examples.md` for detailed walkthroughs of both scenarios.

## Troubleshooting

### Merge conflicts after parallel work
**Cause:** Two agents edited the same file or adjacent lines.
**Solution:** This shouldn't happen if file-level independence was verified in Step 1. Review the dependency analysis. For future runs, use stricter file partitioning.

### Stale lock files
**Cause:** An agent crashed or timed out without releasing its lock.
**Solution:** Check the lock file timestamp. If >30 minutes old and the agent is no longer running, manually move the lock file to `_tasks/failed/` and reassign the task.

### Two agents picked the same task
**Cause:** Race condition — both checked availability simultaneously.
**Solution:** The lock-file protocol should prevent this. If it happens, check that agents are using atomic file operations. The second agent should detect the existing lock and skip to the next task.

### Agent stuck in a loop
**Cause:** Agent keeps failing the same task and reclaiming it.
**Solution:** After 2 failures on the same task, the agent should mark it as `blocked` and move to the next task. Review blocked tasks manually.