/agent-isolation

name: agent-isolation
description: Use before spawning any agent that writes files, and by every developer/fixer agent as its first and last action. Gives each agent its own git worktree, forbids blanket staging, and requires confirming a mutation actually landed. Triggers from /app-build, /app-audit, parallel-orchestrator, and any parallel agent launch. Prevents parallel agents corrupting each other's work.

Agent isolation

Parallel agents that share one working tree corrupt each other. Not "might" — *do*.

The default developer method is: write the files, then `git checkout -b feat/APP-NNN` and commit. Run two of those concurrently in one tree and the sequence is:

dev A writes  ui/TodoListUiState.kt          (on main, untracked)
dev B writes  data/InMemoryTodoRepository.kt (on main, untracked)
dev A runs    git checkout -b feat/APP-001   -> B's file comes along
dev A runs    git add . && git commit        -> A ships B's half-finished work
dev B runs    git checkout -b feat/APP-002   -> from A's branch, inheriting A's commit

Both branches are now wrong, and neither agent can tell. Worse, this is silent: every agent reports `DONE`, tests pass, and the review reads a diff that contains someone else's changes.

**A read-only agent is not exempt.** A verification agent sharing a working tree once left a billing file with its guest-purchase guard deleted. Only explicit-path staging kept it out of the commit. One `git add -A` ships a removed billing guard.

Rule 1 — one worktree per WRITING AGENT, always

Before spawning any agent that writes, the orchestrator leases its slot:

node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree-slot.mjs" lease --owner ios-developer --tickets APP-001,APP-002

The agent is given that path — `.agent-wt/ios-developer` — as its **project root** and never leaves it. Its `git` commands are confined there. It cuts `feat/APP-001-short-slug`, commits, then cuts `feat/APP-002-short-slug` from the same base and commits: **one branch per ticket, unchanged**. Parallel agents cannot see each other's uncommitted state, because they do not share a tree.

**The slot is keyed by the WRITER, and it used to be keyed by the ticket. That was a contradiction, not a preference.** `parallel-orchestrator` step 2 says one agent invocation per owner, batched; step 3 says each agent's prompt names *its* worktree path, singular. An `ios-developer` owning three tickets was spawned once, given three worktrees, and told to stand in one path that did not exist. Working all three in one of them makes every branch carry its siblings' files, which `code-reviewer` check 9 rejects — sending `tech-manager` to hunt a shared-tree collision the orchestrator caused.

Two agents in one tree corrupt each other. One agent working three tickets one after another in its own tree corrupts nobody. The writer was always the unit; the ticket never was. As a bonus, disk is now bounded by the parallelism cap rather than by the backlog.

Cleanup — on **every** terminal outcome, not only after a merge:

node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree-slot.mjs" release --owner ios-developer
node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree-reap.mjs" --root . --apply

**"After the merge" was the whole leak.** Removal was specified in three places and all three were the merge path, so a `rejected`, a cap-converted `blocked`, a `BLOCKED:` return or a crashed round left its tree behind forever — no cap, no disk budget, no reaper. Measured in this plugin's own repository, which contains no application code at all: 12 worktrees, 88 MB. An iOS project's worktrees also carry their own DerivedData.

`worktree-reap.mjs` derives liveness from the board (`in_progress`/`review`) so it cannot disagree with it, and it **never** runs `--force`. A worktree with uncommitted changes is reported loudly and left exactly where it is: one `git stash` in a shared tree already cost 22 files of live work (DR4-027), and an automatic cleanup is that move with better manners.

Build caches live **outside** the slots (`scripts/build-env.sh` → `.studio-cache/`), so reaping a slot never throws away a warm build, and the next ticket does not start from cold.

`.agent-wt/` sits inside the repo and **must be in `.gitignore`** — `/app-init` adds it for new projects. On an existing project, add it yourself before the first spawn: an un-ignored worktree directory shows up as untracked noise in every agent's `git status` and invites exactly the blanket `git add` this skill bans.

**Verifiers and auditors get one too.** "Read-only" describes the intent, not the guarantee.

The rule is not "never touch the shared tree" — it is "never touch a path another agent could"

Some artifacts genuinely belong outside a feature branch. A review verdict has to survive the branch being rejected; a findings register spans tickets. Forbidding all shared writes would push those back into ephemeral messages, which is the failure this whole design exists to stop.

The real test is **collision**, not location:

| Artifact | Where | Why | |---|---|---| | all source and test code | **worktree only** | two agents on the same file is the corruption case | | `docs/daily/<today>-<role>-<ticket>.md` | **worktree**, committed on the branch | reaches `main` at merge; a fragment for unmerged work should not appear in the standup | | `docs/53-reviews/APP-NNN-cycle-N.md` | shared tree — **safe** | the path is unique per (ticket, cycle); no other agent can target it, and it must outlive a rejected branch | | `docs/31-board.md` | shared tree — **generated, CLI-only** | do not append to it. `board.mjs` regenerates the whole file from `docs/31-board-events.jsonl` on every event, so a hand-appended row is silently overwritten by the next writer — mutate it with `board.mjs move`, never with an editor | | `docs/31-board-events.jsonl`, `docs/team/messages.jsonl` | shared tree — **append-only, via their CLI** | `board.mjs` / `team-message.sh` validate then ap