agentsclimarketplace

Agent isolation

Skill vmobifystudio/app-dev-team/skills/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

Install
npx -y skills add vmobifystudio/app-dev-team --skill agent-isolation

Assembled 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:

ArtifactWhereWhy
all source and test codeworktree onlytwo agents on the same file is the corruption case
docs/daily/<today>-<role>-<ticket>.mdworktree, committed on the branchreaches main at merge; a fragment for unmerged work should not appear in the standup
docs/53-reviews/APP-NNN-cycle-N.mdshared tree — safethe path is unique per (ticket, cycle); no other agent can target it, and it must outlive a rejected branch
docs/31-board.mdshared tree — generated, CLI-onlydo 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.jsonlshared tree — append-only, via their CLIboard.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 DONE is checked with verify-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-hunting skill. 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.sh before believing DONE
  • git diff --cached --numstat on 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

Keep looking

Skills are one crate of 610,220. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.