Git Worktree Setup

What this skill is / is not

Produces: a tailored scripts/setup-worktree.sh (or similar) for the current repo + the matching agent-tool hook config that auto-invokes it + a manual entry-point as a safety net.

Is NOT: the thing that runs every time a new worktree is created. That's the hook. This skill only runs when the user explicitly asks for it:

• "Set me up worktree auto-bootstrap"
• "Every git worktree add requires me to manually install / copy .env — automate it"
• "Project structure changed — update the worktree init script"

Core working style: audit the repo yourself → put a concrete draft on the table → ask only the questions you couldn't infer → land it.

Don't dump 7 questions on the user upfront — that's annoying. Read the code, read the configs, infer everything inferable, walk in with a draft proposal, and let the user adjust.

4-step workflow

Step 1: Audit the repo yourself (do not ask the user)

This is dynamic inference, not checking boxes off a static list. The table below is examples of common signals — you must expand the investigation based on what you actually find. Any tool, any stack, any project-specific convention is fair game. Read unfamiliar config files; grep for unknown CLI names; if the README / CONTRIBUTING / Makefile / justfile / Taskfile mentions "setup" / "bootstrap" / "install" steps, read them — they often hold the repo's own definition of "what a fresh machine needs."

Starting signals (examples, not exhaustive):

Expand actively: each of the above can lead to further investigation. Reading package.json, you spot husky → check whether .husky/ should be shared. You spot playwright → check whether browser cache (~/.cache/ms-playwright) should be shared. Reading pyproject.toml, you find [tool.uv] → where does uv put its cache. Don't skip just because something isn't in the table.

By the end of audit you should have:

• a resource candidate list pre-classified into Share / Copy / Generate, each item with its source evidence
• the inferred agent tool (based on config dir presence)
• whether a script already exists (decides new vs update)
• the open questions worth asking (items audit can't decide but are decision-critical)

Step 2: Walk in with a concrete draft (don't bombard with questions)

Aggregate the audit into a resource list proposal, three tiers laid out. Give a concrete recommendation for what you can infer; mark "needs confirmation" for what you can't. Example:

I went through the repo: looks like an npm-workspaces monorepo (apps/api, apps/web, packages/*), Cloudflare Workers + Vite. .claude/settings.json exists, so Claude Code.

Here's what I'd configure for worktree auto-init:

• Share (symlink): node_modules, apps/*/node_modules, packages/*/node_modules
• Copy: apps/api/.dev.vars (saw .dev.vars.example)
• Hook: .claude/settings.json add SessionStart calling bash $(...)/scripts/setup-worktree.sh
• Manual entry point: bash scripts/setup-worktree.sh always works

A few I need to confirm:

1. .wrangler/state (Cloudflare local D1/R2 state): share across worktrees? Share = all worktrees see same local DB; isolated = each its own. Depends on whether you'll run dev in multiple worktrees concurrently.
2. Besides Claude Code, do you / your team also use Codex / Cursor / Gemini CLI? Want hooks for those too?
3. Didn't see custom reference-repo / build-output sharing needs — confirm none?

Look right?

Step 3: Tighten with 1-2 follow-ups based on the answer

After the user answers, only ask the necessary follow-ups based on what they said. Common follow-ups:

• User says "yes, I run multiple worktrees concurrently" → "For stateful services (pgdata, SQLite WAL), do you want concurrent isolation (Copy) or sharing (Share)? Default recommendation is Copy to prevent corruption."
• User says they also use Codex/Cursor/Gemini → "I'm not familiar with X's hook mechanism — could you point me at the docs / how do you expect it to auto-run? Worst case I can hook in via git's post-checkout."
• User mentions a custom resource → "Share or Copy? Is it written to often?"

Don't open another round of questions — decide what you can decide.

Step 4: Generate + verify

1. Copy setup-worktree.sh template into \x3Crepo>/scripts/
2. Fill in the "resource declarations" block at the bottom per the agreed plan (leave the helper functions block as-is)
3. Merge the matching hook config (from hook-config.json) into .claude/settings.json (or whatever the tool's config location is; multiple tools = multiple hooks)
4. Run twice to verify idempotency: first run links, second run skips everything
5. In a freshly-created worktree, actually run dev / test end-to-end
6. Report back: what was installed, what files changed, how to invoke manually

When updating an existing script: use Edit to diff-edit the resource declarations block. Don't touch the helper functions unless they're genuinely outdated.

Three-tier strategy (the agent's classification framework)

Stateful data: in single-writer concurrent mode, must be Copy (Postgres, SQLite WAL are single-writer); for sequential use, can be Share. This must be in Step 2's "needs confirmation" list — don't decide it for the user.

Agent tool trigger reference

Key principles:

• For tools you don't know, don't make up hook configs. Ask the user.
• Always preserve the manual entry point bash scripts/setup-worktree.sh. Any hook breaking or tool-switching shouldn't leave you stuck.
• Multi-tool? Hook them all to the same script — the script itself is idempotent.

Quick reference: common resources → default tier

Common mistakes (self-check while writing the script)

• Linking only root node_modules, missing workspaces: symptom Could not read from file: .../zod/v4. Loop both apps/* and packages/*.
• git worktree add polluting stdout (under WorktreeCreate hook): redirect with >/dev/null 2>&1, send progress to /dev/tty.
• Symlinking single-writer stateful directories: concurrent dev corrupts. Step 2 must list as needs-confirmation.
• Not idempotent: re-runs must skip everything. Template's link_resource handles this.
• Dead symlinks: check [ -e "$target" ] before linking.
• Hardcoding the main repo path: derive with git rev-parse --git-common-dir.
• Symlinking .env: must be Copy (symlink edits leak across worktrees).
• Skipping audit and bombarding the user with questions: audit first, infer what's inferrable; questions to the user are judgement calls, not facts.
• Deciding stateful policy for the user: Step 2 must ask.

Implementation resources

• Script template: setup-worktree.sh
• Hook config candidates: hook-config.json
• Per-stack snippets: recipes.md

Verification checklist (run after generate / update)

• Script runs on fresh git worktree add and exits 0
• Re-run = no-op (all "skip — already linked")
• npm run dev (or stack equivalent) actually starts, no "module not found"
• Tests / typecheck pass in the new worktree
• Removing main-repo's optional resource → script logs "skip" not error
• Under WorktreeCreate: stdout contains only the worktree path
• Manual entry point (bash scripts/setup-worktree.sh) also runs
• Confirmed resource list matches what got generated