standards/CLAUDE.md: pin the main checkout to origin/main; all branch access in per-agent worktrees (+ cleanup)

Problem

Agents that only read the shared standards/CLAUDE.md are not creating worktrees — the shared standards say nothing about worktrees at all. Worktree usage exists only as a default inside the start-work skill (plugins/start-work/), behind an easy --no-worktree opt-out. Any agent that doesn't run /start-work gets no directive.

But the deeper need is workspace isolation for many concurrent agents — up to 6–7 running at once. The real hazard isn't just parallel writes; it's that if one agent checks out a branch in the shared main checkout — even just to read or analyze it — it yanks the ground out from under every other agent using that checkout. Each agent needs its own private workspace, even for reads.

The model (decided)

Anchor rule: the main checkout is permanently pinned to origin/main. Any branch other than main — for any reason, read or write — lives in that agent's own worktree.

1. Main checkout stays on origin/main. It's the shared landing pad every new agent starts from. Nothing ever git checkouts another branch there.
2. Reading another branch's files → git show <branch>:<path> or git grep <rev> -- <path>. These never touch a working tree, so they're safe under concurrency and need no worktree. Use them freely for peeks.
3. Materializing a branch on disk (building, running, editing, or grepping across the whole tree) → the agent's own worktree at .claude/worktrees/<id>-<slug>/. Never git checkout <branch> in the main checkout to do this.
4. Keep main current. Because nothing is ever worked on in the main checkout, it is always safe to fast-forward it to origin/main at any time, so new agents start from the latest code.
5. Agents clean up their own worktrees when done — from outside the worktree (you can't remove the one you're standing in — see #168). A worktree created just to read/review a branch is disposable and torn down when the analysis finishes; a worktree for active work persists until its PR merges, then is removed.
6. Bulk cleanup of abandoned worktrees — a cautious, semi-regular sweep — is handled by a separate skill, tracked in #196. This issue only requires that the standard mention such a sweep exists; the mechanics and safety gates live in #196.

Enforcement level (decided)

Standards directive — instruction-level rule in standards/CLAUDE.md, reaching every agent via the shared-standards sync. No hook-based hard block for now (possible follow-up if the directive proves insufficient).

Opt-out policy (decided)

Per-repo opt-out file, mirroring .allow-push-main. A repo carrying .allow-in-place in its root disables the worktree discipline for that repo — work proceeds in the main checkout. Intended for repos where worktrees genuinely break local tooling and concurrent-agent isolation isn't needed:

• #134 — a dev whose git GUI (GitKraken) chokes on worktrees nested under .claude/worktrees/ and who can't view uncommitted WIP across worktrees. A repo-level marker lets that person disable the default for their repos without weakening it for the multi-agent case.

Opt-out is per repo (owner's call), not per-invocation — the point is to stop casual per-task --no-worktree bypassing while honoring repos with a real incompatibility. (Marker name open: .allow-in-place vs .no-worktree vs .allow-main-checkout — pick one, use it consistently.)

Proposed content (for standards/CLAUDE.md)

New section, adjacent to Git Hygiene Before New Work / Branch Naming and PR Linking:

Worktrees and the Main Checkout

The main checkout stays permanently on origin/main. It is the shared landing pad every new
agent starts from — no branch is ever checked out there. With several agents running at once,
switching the main checkout onto a branch pulls the ground out from under every other agent
reading it, so the rule is absolute: any branch other than main, for any reason, lives in
that agent's own worktree.

• Reading another branch's files: use git show <branch>:<path> or git grep <rev> -- <path>.
  These never touch a working tree, so they're safe under concurrency and need no worktree.
• Materializing a branch on disk (building, running, editing, or grepping the whole tree):
  create your own worktree at .claude/worktrees/<id>-<slug>/ (the start-work skill does this
  automatically). Never git checkout <branch> in the main checkout to do it.
• Keeping main current: because nothing is ever worked on in the main checkout, it is always
  safe to fast-forward it to origin/main (git -C <main> fetch origin main && git -C <main> merge --ff-only origin/main) so new agents start from the latest code.
• Clean up your own worktree when done — from outside it (you can't remove the worktree you're
  standing in; see #168). A worktree spun up just to read or review a branch is disposable — tear it
  down when the analysis finishes. A worktree for active work persists until its PR merges, then is
  removed.
• Per-repo opt-out: a repo carrying .allow-in-place in its root disables this — work proceeds
  in the main checkout. Use only where worktrees break local tooling (e.g. a git GUI that can't walk
  a nested worktree's .git pointer) and concurrent-agent isolation isn't needed.

Left unmanaged, .claude/worktrees/ accumulates abandoned trees; a periodic bulk sweep
(/worktree-cleanup) reclaims them cautiously — see that skill for the safety rules.

Scope / where things live

• Discipline (rules 1–5) → standards/CLAUDE.md directive (this issue).
• Self-cleanup (rule 5) → directive; could also be wired into start-work / a small teardown helper.
• Bulk cautious sweep (rule 6) → separate skill, tracked in #196.
• start-work.sh honoring .allow-in-place → small follow-up so the script matches the standard (behave as --no-worktree when the marker is present).

Acceptance criteria

• standards/CLAUDE.md gains a Worktrees and the Main Checkout section stating: the main checkout stays on origin/main; never check out another branch there; git show/git grep for cross-branch reads; own worktree for materialized branches; fast-forward main to stay current; clean up your own worktree from outside it.
• Documents the per-repo opt-out file and when it's appropriate.
• Mentions the bulk sweep exists and points to /worktree-cleanup (#196) for its rules — without duplicating the safety gates here.
• Opt-out marker name finalized and used consistently.
• Wording is strong enough that an agent reading only the shared standards keeps the main checkout on main and uses a worktree for any other branch by default.
• Cross-references worktree-removal guidance (#168) rather than duplicating it.
• Reachable on the next setup-env sync (no code path changes required for the directive itself).

Open questions

• Opt-out marker name (.allow-in-place vs .no-worktree vs .allow-main-checkout).
• Relationship to #134 — does the per-repo marker fully satisfy it, or keep #134 open for a per-developer setting?
• Should start-work.sh honor the marker in this issue, or as a small separate follow-up?

Related

• #196 — /worktree-cleanup skill (the cautious bulk sweep this discipline relies on).
• #168 — worktree removal mechanics (can't remove the CWD; Windows CWD-lock; removal order).
• #134 — request for a per-user --no-worktree default; addressed at the repo level here.

Out of scope

• Hook-based hard enforcement (pre-commit / PreToolUse block) — possible follow-up.
• Bulk-sweep mechanics — tracked in #196.
• Worktree removal mechanics — tracked in #168.

Start with standards/CLAUDE.md and compare its adjacent Git Hygiene and Branch Naming sections with the acceptance criteria. Review #168 and #196 for the removal and cleanup references, then settle on one opt-out marker name and document the main-checkout, branch-reading, worktree, cleanup, and sync rules. Done means the section is reachable through setup-env and covers every listed criterion without implementing out-of-scope mechanics.