aspiers/ai-config / .agents/skills/setting-up-worktree-hooks
setting-up-worktree-hooks
VerifiedGives a repository one idempotent, repo-local worktree setup script (local env files, dependency install, build steps) that worktrunk's `.config/wt.toml` pre-start hook and Orca's `orca.yaml` scripts.setup both call, so every new git worktree is usable at once. Use when adding or fixing worktree setup hooks, writing `wt.toml` or `orca.yaml` setup, when new worktrees lack dependencies or `.env` files, or when asked to make worktrees "just work" in a repo. For creating a worktree in a repo that already has setup, use `git-branch-management` instead.
Setting up worktree hooks
A fresh worktree lacks everything git doesn't track: dependencies,
gitignored env files, generated code and caches. Each worktree tool runs
only its own hook, and raw git worktree add runs none. So give the repo
one script that owns setup, and have every tool call it:
.config/wt.toml [pre-start] ──┐
orca.yaml scripts.setup ──────┼──> scripts/worktree-setup.<ext>
by hand after git worktree add ─┘
git-branch-management covers using this setup when creating worktrees.
This skill covers adding it to a repo.
1. Survey before writing
- What a new worktree lacks. List the gitignored files in the primary
checkout, e.g.
git ls-files --others --ignored --exclude-standard --directory. Note which of them the app or tooling actually reads, plus the install, codegen and build steps a working checkout needs. - Existing hooks and scripts. Extend what is there rather than adding a parallel path.
- Repo conventions. Use its script directory, language, test framework, license headers and comment style.
- Check every precedent's stated reason before copying it. An existing
script's "plain JS because tsx isn't installed yet" may no longer hold:
Node ≥ 22.18 strips TypeScript types natively. Re-check claims about
tooling versions, missing features or platform limits against the repo's
current toolchain. Likewise, a precedent that spawns
npx.cmdwithout a shell is itself broken on Node ≥ 18.20.2 and ≥ 20.12.2 (see below).
2. Write the script
Pick the language. POSIX sh suits a script that mostly runs other
commands, and needs nothing installed. Use the repo's main language when its
interpreter is guaranteed present before install, and when the logic
deserves unit tests in the repo's own framework. Worked examples, to adapt
rather than copy:
- references/worktree-setup.sh (POSIX sh)
- references/worktree-setup.mts (Node, native TypeScript, with injectable install for tests)
The contract:
- Idempotent. Every re-run is harmless: skip what exists, and let the install itself be a no-op.
- Runs before install, so it uses built-ins or the standard library only, never the project's own dependencies.
- Finds the primary checkout itself, and never guesses. Take the first
entry of
git worktree list --porcelain -z, and trust it only ifgit -C <entry> rev-parse --show-toplevelsucceeds and equals it, comparing real paths. Otherwise there is no primary checkout: skip linking. Don't derive it from--git-common-dir: for a worktree of the bare repo/srv/project.gitthat gives/srv, and an unrelated/srv/.env.localgets linked in. Checking forbarealone is not enough either: aftergit init --separate-git-dir, the first entry is the metadata directory. Capture or discard git's stderr, so the expected failure prints nothing. This works the same under wt, Orca and plain git, and keeps the hook lines free of$VAR/%VAR%differences. - Skips file linking when it runs in the primary checkout, comparing real paths.
- Spawns package managers through a shell on Windows only, e.g.
spawnSync("npm", ["install"], { shell: process.platform === "win32" }). Node can't resolvenpm/yarn/npxshims without a shell, and since CVE-2024-27980 it refuses to spawn.cmdor.batfiles without one (EINVAL), so namingnpm.cmdis no fix. Keep the arguments constant or properly quoted, since the shell parses them. - Fails hard on steps a working tree needs (install, codegen, build). Steps that only fail on a flaky network or a private resource just warn, as long as a later step would catch a genuinely broken install. Pass the install's exit code through.
- Comments say why each step exists and why it is ordered as it is.
3. Local env and other gitignored files
- Symlink by default. Link each needed gitignored file from the primary checkout, so one source of truth serves every worktree and a rotated secret reaches them all. Copy only files a branch writes to independently, such as per-branch databases or caches that tasks modify.
- Never replace an existing path, dangling links included. In
sh, test[ -e "$f" ] || [ -L "$f" ]: a dangling link fails-e, andlnwould then abort a re-run underset -e. In Node,symlinkSyncrefuses any existing path and raisesEEXIST. Skip files missing from the primary. - Never print file contents, and don't spread secret files nothing reads.
- Where the repo tracks
*.examplefiles that map one-to-one onto the real ones, derive the list from them (git ls-files '*.env*.example'), so new packages are covered. Otherwise keep an explicit list. - Never share dependency trees such as
node_modulesor virtualenvs between checkouts. They can hold relative or absolute links back into their own checkout. - Audit
.gitignorewhile there. Make sure every local secret file is ignored. Check withgit check-ignore -v --no-index <path>, and confirm that no tracked file became ignored withgit ls-files -ci --exclude-standard.
4. Wire up the hooks
Call the interpreter directly, e.g. sh scripts/worktree-setup.sh or node scripts/worktree-setup.mts, not a package-manager script: some package
managers refuse to run scripts before the first install. A package-manager
alias is still handy for manual re-runs.
Read references/hooks.md for the wt.toml and
orca.yaml snippets and their gotchas. Two of these are the user's to
do, never the agent's:
- approving worktrunk hooks (
wt config approvals add); - setting Orca's Settings → Repository → "Command source & orca.yaml" to orca.yaml only or Run both, if a local hook would otherwise override the file.
Link to the official docs in config comments, and open every link before committing it.
If the repo's CI lints YAML or TOML, make sure it covers the new files: extend the existing workflow rather than adding another.
5. Verify
- Run the unit tests where the script has them, against real
git initplusgit worktree addrepos in temp directories, with the install stubbed. Cover:- links a file when it is missing;
- never replaces an existing file, or a dangling link;
- skips a file missing from the primary;
- skips linking in the primary checkout;
- finds the primary from a subdirectory;
- finds no primary for a worktree of a bare repo, or of a
--separate-git-dircheckout, and never links a.env.localplanted besideproject.git; - re-runs are harmless;
- passes the install's exit code through;
- spawns the install with a shell on
win32only (mocknode:child_process, and make the platform a parameter).
- Create a throwaway worktree from a branch that has the new files, with
each tool the repo uses (
wt switch --create, Orca with setup set to run). Confirm dependencies, links and builds are in place. - Run the script again by hand, and once via any package-manager alias: both must be no-ops.
- Remove the throwaways. Check that removing one didn't follow a link and delete anything in the primary checkout.
6. Document it
Add a short "Worktrees" note to the repo's AGENTS.md (or its equivalent).
Say what the script sets up, which hooks call it, and the manual command
after a plain git worktree add.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |