# Skill: Orchestrate a parallel agent swarm with isolated worktrees and a foreman

> Apply this skill when a task breaks cleanly into independent chunks and a single sequential agent would be too slow -- it sets up git worktrees, assigns one chunk per agent, and coordinates the merge.

Source: sodigi·learn -- vibecoding/roy-na-odnu-zadachu · https://sodigi.io/learn/vibecoding/roy-na-odnu-zadachu

## When to use
- A project has 3+ clearly independent sub-tasks (catalog, cart, and checkout page are separate; painting and wallpapering the same wall are not).
- A single agent is crawling through a large task sequentially and you want parallel speed.
- You want a tester/fixer loop: one agent runs tests, another fixes failures continuously.
- Using Claude DevFleet for automatic planning, task distribution, and merge orchestration.

## Core rules
- Only parallelize genuinely independent work. If task B needs the result of task A, do them in sequence -- a swarm here creates conflicts, not speed.
- Each agent must get its own isolated copy of the project via git worktree. Never let two agents edit the same file at the same time.
- Keep swarm size to 5-6 agents maximum. Every agent burns tokens; an army of 15 is 15x more expensive and produces merge chaos.
- Shared steps (final test suite, full build, integration checks) must run after all parallel chunks are merged, not during.
- Someone must act as foreman: hand out tasks, track progress, collect results. Use dmux panels for manual control or DevFleet for automatic orchestration.
- After parallel work is done, review each agent's output before merging. Do not drag bugs from an isolated branch straight into main.
- Merging is the final step -- it is easy to forget and hard to undo if done blindly.

## Procedure
1. Decompose the task. List all sub-tasks and mark which ones are independent (can start immediately) and which are dependent (wait for something else).
2. For each independent chunk: create a separate git worktree in its own folder (`git worktree add ../feature-name feature-branch`).
3. Launch one agent per worktree, each with only its own chunk assignment.
4. For dmux: split the terminal into panels (`n` for new panel), assign one task per panel, collect results with `m`.
5. For DevFleet: describe the full task; approve the generated plan; let it hand out subtasks and auto-merge completed ones.
6. Run dependent steps (shared tests, build) only after all parallel branches are merged.
7. Review the final changed-files report before considering the work complete.

## Ready-to-use prompt
```
Break this task into parallel chunks and run them as a swarm.

1. First, identify which chunks do NOT depend on each other -- those can be
   done in parallel. Set the dependent ones aside for later.
2. For each parallel chunk, create a separate copy of the project
   (git worktree) so the agents do not edit the same files.
3. Hand out the chunks: agent 1 -- [chunk A], agent 2 -- [chunk B],
   agent 3 -- [chunk C].
4. Run shared tests and the final build AFTER the chunks are ready --
   that is a dependent step, do not parallelize it.
5. Keep the agent count to 4. At the end, merge all branches and show a
   short report: what got done, what changed, where problems remain.
```

## Pitfalls
- Parallelizing dependent tasks: if step B needs step A's output, a swarm tangles things and wastes tokens.
- Letting multiple agents edit the same file without worktrees -- they overwrite each other's work silently.
- Launching too many agents (15+): this is not 15x faster, it is 15x more expensive and produces a merge disaster.
- Running no foreman: a swarm without coordination is a mob. Assign foreman duties explicitly (you, dmux, or DevFleet).
- Forgetting to merge: branches built in isolated copies must be merged back into the main project -- this is the final step and is easy to skip.
- Merging blindly without reviewing each agent's output first: bugs from an isolated branch get dragged straight into main.