worktree guidance superseded

worktrees buy isolation at the cost of one shared observable state: concurrent changes become invisible to each other, and their reconciliation happens as a late three-way merge where picking the wrong side loses work silently — often discovered weeks later in production. the shared checkout keeps every in-progress change visible in the same tree, so conflicts surface at commit time instead of as incidents.

this upstream skill is not applicable here. git worktrees are forbidden: they hide concurrent changes, split observable local state, and create late merge conflicts. work directly on the current branch in the shared checkout.

the upstream source stays recorded for provenance only; it is not an approved local procedure and must not be followed by people, agents, skills, or tooling.

1. inspect and edit the current shared checkout.
2. preserve unrelated concurrent work; make the active change visible in specifications and file headings.
3. verify from that same checkout.
4. if an external process requires a feature branch, prepare one short-lived reviewed bash handoff script after active edits stop; it declares the exact branch, files, commit, verification, merge, and cleanup.

• create, enter, adopt, repair, prune, move, or remove a worktree.
• switch branches interactively while another agent can edit the checkout.
• use isolation as a substitute for shared-tree visibility and focused verification.

bad

agent a: creates worktree feature-x, edits routes/api.ts and middleware.ts
agent b: edits the same files in main (shared checkout) for an unrelated fix
agent a finishes, merges worktree back: three-way merge conflict, resolve by
  keeping a's changes, b's changes are lost silently
discovery: three weeks later, a critical b fix is missing in production
result: incident, rollback, re-implement and re-verify b's change at double cost

divergent checkouts hide concurrent changes. merge conflicts are visible in three-way merges, but merge resolution mistakes (keeping the wrong side) are invisible until much later.

good

agent a and b start work in the same shared checkout
agent a annotates src/routes/api.ts heading: ongoing — a working on retry logic
agent b sees the heading, works on middleware.ts instead
both changes merge cleanly on git because conflicts are visible before commit
discovery: at commit time, verify the combined diff; nothing is lost
result: one visible state, one clear merge history, no silent lossy conflicts

one visible working state with in-progress intent; conflicts surface at commit time, not weeks later in production.

no git worktrees · change visibility · the skill system's local contract