multi-agent-vcs

# Multi-Agent Version Control

Tool-agnostic patterns for coordinating git operations across parallel AI agents.

<when_to_use>

- Dispatching subagents for parallel work
- Planning multi-branch implementations
- Recovering from parallel agent corruption
- Any workflow where multiple agents touch the filesystem

</when_to_use>

## The Problem

When parallel subagents perform git operations independently:

- **Mixed content** - Multiple features end up in wrong branches
- **Broken stacks** - Branches become siblings instead of parent-child
- **Mislabeled PRs** - PR titles don't match branch content
- **Hours of recovery** - Manual intervention required to fix structure

This happens because each agent sees the same starting state and creates branches independently, resulting in siblings instead of a proper stack.

## The Policy

> **Subagents MUST NOT perform git operations.**
>
> Only the **orchestrator** handles git state. Subagents write code to the filesystem and report completion.

<rules>

**ALWAYS:**
- Orchestrator creates branches before dispatching subagents
- Subagents write to filesystem only
- Subagents report which files they created/modified
- Orchestrator stages, commits, and pushes

**NEVER:**
- Subagents commit, push, or create branches
- Parallel git operations from different agents
- Background agents managing branch state

</rules>

## Correct Workflow

```
┌─────────────────────────────────────────────────────────────┐
│  ORCHESTRATOR (main agent)                                  │
│  - Manages git state, branches, commits                     │
│  - Dispatches subagents for CODE ONLY                       │
│  - Collects results, stages files, commits to correct branch│
└─────────────────────────────────────────────────────────────┘
         │
         ├──► [subagent-1] Write feature-a.ts → filesystem only
         ├──► [subagent-2] Write feature-b.ts → filesystem only
         ├──► [subagent-3] Write feature-c.ts → filesystem only
         │