Agent isolation
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.From its SKILL.md
npx -y skills add vmobifystudio/app-dev-team --skill agent-isolationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
11.8 KB, as published. Nobody here has run it
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 append; never edit an existing line, and appends from different agents merge cleanly. Their Markdown views (docs/31-board.md, docs/team/messages.md) are GENERATED — a hand edit is overwritten by the next render |
A shared write is safe when no other agent can write that same path. Uniquely-named files and append-only logs qualify. Anything else — source, tests, a doc two roles both edit — is worktree-only.
Observed: a developer wrote its daily fragment to the repo root instead of its worktree, because the
orchestrator's prompt named a repo-root path. The fragment then sat on main describing work that
was still on an unmerged branch. Name the worktree-relative path when you spawn.
If the project genuinely cannot use worktrees (not a git repo, or a tool that needs the canonical path), then agents that write must be serialized — one at a time, each committing before the next starts. Never run parallel writers in one tree. Say in the daily fragment that you serialized and why.
The orchestrator does not get to claim it remembered. Before the launch message:
sh "${CLAUDE_PLUGIN_ROOT}/scripts/spawn-gate.sh" APP-001 APP-002
Exit 1 = REFUSED, spawn nobody; it names which tickets lack a worktree and prints the command to
create each. Exit 0 with one ticket = the serialized path, stated in the output so it reaches the
standup. See parallel-orchestrator step 2a.
Rule 2 — never stage blindly, and never run a repo-wide destructive command
Banned, without exception:
git add -A git add . git add --all git commit -a
git reset git stash git checkout -- . git clean
The top row attributes someone else's work to your ticket. The bottom row destroys it, and none
of those four can be undone from inside your run. DR4-027: one git stash + git reset, run by an
agent that only wanted a clean tree for a check, discarded 22 files and 332 insertions of another
agent's in-progress work. It survived only because it happened to land in the stash; git checkout -- . would have made all 22 unrecoverable.
If you need a clean tree to test, copy the repo to a temp dir and dirty that — cp -R . "$TMP",
or git worktree add a scratch worktree. Never clean the tree you are standing in.
Stage by explicit path, every time:
git add android/app/src/main/java/com/sandbox/todo/ui/TodoListScreen.kt \
android/app/src/test/java/com/sandbox/todo/ui/TodoListViewModelTest.kt
Then look at what you actually staged before committing:
git diff --cached --numstat
If a path you didn't touch appears, stop and unstage it. Another agent's work, or your own accidental edit, is about to be attributed to your ticket.
Rule 3 — confirm the mutation landed
Never believe an edit worked because the tool returned success. Between "I ran the edit" and "the file changed" sits every silent no-op: a pattern that didn't match, a path that didn't exist, a write to a stale worktree.
git diff --numstat # something changed, and it is what you think
git diff -- <the one file> # the change is the change you intended
A refactor that silently matched nothing looks identical to a refactor that succeeded, and the test suite that then passes is proving nothing. This is how a pass gets read as evidence.
Corollary for destructive checks: prefer deleting a guarded call to renaming it. A rename is a
compile error the moment it is wrong. A deletion still compiles, the test runs, and 0 failures
looks exactly like success.
Rule 4 — verify agents by running their work, not by reading their reports
An agent's report is a claim about work, produced by the same agent that did the work. Reports are consistently more confident than the work justifies.
- A developer's
DONEis checked withverify-done.sh— branch, commits, files, test exit code. - A rule, guard, or test an agent wrote is checked by making it fail on purpose — see the
defect-huntingskill. A rule that cannot fail reports success forever. - An audit finding is checked by reproducing it, not by re-reading the finding.
Rule 5 — if HEAD moved under you, stop and report
You may be running without a worktree — the orchestrator failed to make one, or the project cannot use them. That is a supported state, and it is the state in which this rule is the only thing standing between you and another agent's lost work.
If HEAD is not where you left it, or files you did not write have appeared, stop. Do not
git reset --hard, do not git checkout -- ., do not git stash drop, do not delete an untracked
file to "clean up". Another agent's uncommitted work may be in that tree, and none of those
commands can be undone from inside your run.
Write a blocker naming what moved and let tech-manager resolve it. A stalled ticket is cheap; a
discarded working tree is not recoverable.
Orchestrator checklist
Before a parallel launch:
-
spawn-gate.sh <the ticket IDs>exits 0 — not "I believe each has a worktree", the gate said so - Each writing agent has its own worktree, created before spawn
- Each agent's prompt names its worktree path as the project root, not the repo root
- No two agents are assigned the same file (if unavoidable, serialize those tickets)
- Agents are told: explicit-path staging only, and confirm the mutation landed
After each agent returns:
-
verify-done.shbefore believingDONE -
git diff --cached --numstaton the branch shows only that ticket's paths - Worktree removed after merge
Output contract
Developer/fixer agents report their isolation state so the orchestrator can check it:
DONE: APP-NNN
Worktree: .agent-wt/APP-NNN
Branch: feat/APP-NNN-short-slug
Staged (explicit paths): <list>
Mutation confirmed: git diff --numstat -> <N files, +A/-B>
Files: <list>
Tests: <count> added, <command run>, exit 0
Next: code-reviewer