Parallel agents in git worktrees

# AGENTS.md: parallel agents in git worktrees

Several agents may work on this repository at once, each in its own git worktree on its own branch.
These rules keep them from colliding.

## Inside a worktree
- Work only inside your worktree directory. Never edit, check out or reset files in the main checkout or another worktree.
- One task per worktree, one branch per task: `agent/<short-task-name>`.
- Never switch branches inside a worktree; finish or abandon the task instead.
- Commit small and often. Uncommitted work in a worktree is easy to lose.
- Each worktree has its own `node_modules`, `.venv` and build output. Install dependencies in the worktree.
- Dev servers: use the port the human assigned, or `3000 + N` where N is your worktree number. Never kill a process you did not start.
- Shared resources (one local database, one emulator) are single-writer. Ask before migrating or seeding a shared database.
- Secrets: do not copy `.env` files between worktrees yourself. Ask the human to provide them.

## Starting and finishing
- Start with the `start-worktree` skill. Finish with the `land-worktree` skill.
- Do not delete a worktree or its branch until its pull request is merged, or the human says to drop it.

## Tool-specific notes
- Claude Code: `claude --worktree <name>` starts a session in a new worktree. A subagent with `isolation: worktree` gets a
  temporary worktree branched from the default branch, not from your current HEAD; commit and push what it needs first.
- Codex: the app and CLI can create managed worktrees (Codex 0.162+). Treat them the same way.
- GitHub CLI: `gh issue develop <number> --worktree` creates a linked branch and a worktree for an issue (gh 2.99+).

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `start-worktree`, `land-worktree`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Parallel agents in git worktrees" v1.0.0 — https://loadout.jnw-it.com/loadouts/parallel-agents-worktrees/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `start-worktree`, `land-worktree`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Parallel agents in git worktrees" v1.0.0 — https://loadout.jnw-it.com/loadouts/parallel-agents-worktrees/ -->

---
name: start-worktree
description: Create a git worktree and branch for one task, install dependencies and pick a free port. Use before starting a task that will run alongside other agents.
---

# Start a worktree

Inputs: a short task name (kebab-case) and the base branch (default `main`; use the repo's default branch).

1. From the main checkout, update the base: `git fetch origin`.
2. Create the worktree next to the repository, never inside it:
   `git worktree add ../$(basename "$PWD")-<task> -b agent/<task> origin/<base>`
   If the branch exists already, stop and ask; another agent may own it.
3. `cd` into the new directory. Confirm with `git status` and `git branch --show-current`.
4. Install dependencies with the project's lockfile command (`npm ci`, `pnpm install --frozen-lockfile`, `uv sync`, …).
5. Environment files: list which ones the project needs (`ls ../<main-checkout>/.env*` names only) and ask the human to copy them.
6. Pick a port: `git worktree list` gives N; use `3000 + N` unless the human assigned one. Record it in your first report.
7. Run the test command once, before changing anything, so later failures are known to be yours.

Report: worktree path, branch, port, baseline test result.

---
name: land-worktree
description: Rebase a finished worktree branch, run checks, open a pull request and clean up after merge. Use when a task in a worktree is done.
---

# Land a worktree

1. Commit everything. `git status` must be clean.
2. `git fetch origin && git rebase origin/<base>`. On conflicts in files you did not change, stop and ask; another agent's work may be landing.
3. Run the full check command (tests, lint, type-check). Fix failures you caused; report others.
4. Push the branch: `git push -u origin agent/<task>`. Never push to `<base>` directly, never force-push a shared branch.
   After a rebase of your own unshared branch, `git push --force-with-lease` is the only acceptable force.
5. Open a pull request (`gh pr create --fill` then edit the body): what changed, how it was tested, anything left.
6. Stop any dev server you started in this worktree.
7. After the human merges, clean up from the main checkout:
   `git worktree remove ../<repo>-<task>` then `git branch -d agent/<task>` and `git worktree prune`.
   `git branch -d` refuses unmerged branches. After a squash or rebase merge on GitHub it refuses too, because the
   commits differ: confirm with `gh pr view --json state` that the PR is merged, then ask the human before using `-D`.