docs: add a worktrees-pnpm skill

[thecodedrift]

A git worktree gets its own empty node_modules, and everything that goes wrong in a worktree here follows from that. lint-staged shells out to prettier and eslint from node_modules/.bin, so git commit fails at the worst possible moment — after the work is done. Every pnpm script fails too, and openspec isn't on PATH in this repo. A missing prettier already cost an agent about an hour of dead-end workarounds.

This adds a worktrees-pnpm skill so the next person or agent gets the procedure instead of rediscovering the failure, and reduces the CLAUDE.md section to a pointer plus the two rules that do the most damage when missed.

There is no pnpm worktree command, which is the thing worth checking me on. pnpm's git worktrees page uses plain git worktree add; the pnpm worktree:new it mentions is a helper script in pnpm's own repository, not a pnpm feature. So the rule isn't "use a different command" — it's that git worktree add is not finished until pnpm install has run inside the new worktree.

What pnpm does contribute is enableGlobalVirtualStore: true, which makes that install nearly instant by symlinking into one shared content-addressable store. It is deliberately not enabled here. pnpm documents it as not working with ESM when hoisted dependencies are used, since Node no longer honours NODE_PATH in ESM — and packages/cli is "type": "module". We set no hoisting config, so it's likely fine, but flipping a resolution-layer switch for the whole workspace deserves its own change with the full suite as the check. Version isn't the blocker: it needs pnpm ≥ 10.12.1 and we run 10.12.4. The skill records this as an opt-in to evaluate, so it's a decision rather than an oversight.

The skill also absorbs the background-agent delegation rules, cleanup, recovery when the main checkout gets switched onto an agent's branch, and a short note that sequential branch work is usually cheaper with plain git checkout than with a worktree.

.agents/skills/ is this repo's internal agent tooling, alongside iterate-pr and the openspec-* skills — not the skills/taskless/ tree that ships to users. Nothing here reaches the published CLI, hence skip-changeset.

[thecodedrift]

@claude /review

[claude]

Claude finished @thecodedrift's task in 1m 50s —— View job

---

Review: docs: add a worktrees-pnpm skill

• Gather context (diff, changed files)
• Read new skill file and CLAUDE.md changes
• Review for correctness, security, performance, clarity
• Verify factual/technical claims against repo state
• Post final top-level assessment

Summary

Doc-only change (.agents/skills/worktrees-pnpm/SKILL.md + condensed CLAUDE.md section). No code, no runtime surface, no security/performance implications. I verified every checkable technical claim in the new skill against the actual repo state and they all hold up:

• packages/cli/package.json and root package.json both set "type": "module" — supports the ESM/enableGlobalVirtualStore caveat.
• No .npmrc hoisting overrides in the repo — supports "likely fine, but off by default."
• packageManager is pinned to pnpm@10.12.4 in package.json, which is ≥ the stated 10.12.1 minimum for enableGlobalVirtualStore.
• packages/cli/package.json's files field is ["dist"] only, so .agents/skills/** never ships in the published package — the skip-changeset label is correctly justified.
• No other .md in the repo references the old inline CLAUDE.md worktree rules, so nothing is left dangling by the condensation.
• Content audit: every rule removed from CLAUDE.md's old "Background Agents and Worktrees" section (node_modules, main-repo-path warning, degraded-shell recovery, branch-switch recovery) reappears in the new skill file — nothing was silently dropped, only relocated.
• The worktrees-pnpm/SKILL.md frontmatter (bare name + description) matches the precedent set by iterate-pr/SKILL.md, so it's consistent with this repo's lighter-weight internal-skill convention (vs. the fuller OpenSpec-generated frontmatter).

Assessment

No correctness, security, or clarity issues found — this is a well-researched writeup and the self-flagged uncertainty in the PR body (no pnpm worktree command; enableGlobalVirtualStore deliberately left off pending ESM verification) is accurate and appropriately hedged rather than asserted as fact. Nothing to request changes on.

Two very minor, non-blocking observations (not requesting changes):

• .agents/skills/worktrees-pnpm/SKILL.md:53-56 attributes the enableGlobalVirtualStore + ESM incompatibility to Node "no longer honour[ing] NODE_PATH in ESM." That's pnpm's own stated rationale per the PR description, and I can't independently verify it without external access, but it's worth a skeptical read if this section is ever revisited before flipping the flag.
• The "worktree is worth it" guidance at the end (SKILL.md:97-104) is a nice addition beyond what CLAUDE.md previously had — steers away from reaching for a worktree on sequential single-branch work.

I did not run lint/typecheck/build locally per review instructions — CI will report those on the PR.