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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
| references/hooks.md | markdown | 3.4 KB |
| references/worktree-setup.mts | other | 4.5 KB |
| references/worktree-setup.sh | script | 2.7 KB |
references/worktree-setup.mts
View on GitHub#!/usr/bin/env node
// Example only: adapt the file list and setup steps to the target repository.
//
// Makes a new git worktree of this repository usable straight away. Both
// worktrunk (.config/wt.toml pre-start) and Orca (orca.yaml scripts.setup)
// call this, so every worktree gets the same setup however it was created.
// Safe to re-run: existing files are never replaced, and a repeat install
// is a no-op.
//
// It runs before dependencies are installed, so it uses only Node
// built-ins. Node >= 22.18 strips TypeScript types natively, so no tsx is
// needed: keep to erasable syntax (no enums, namespaces or parameter
// properties). The .mts extension makes it ESM without Node's
// typeless-package warning.
//
// Usage: node scripts/worktree-setup.mts
import { execFileSync, spawnSync } from "node:child_process";
import { existsSync, mkdirSync, realpathSync, symlinkSync } from "node:fs";
import path from "node:path";
import { pathToFileURL } from "node:url";
// Gitignored files the app reads at runtime. Each is linked, not copied, so
// a rotated secret reaches every worktree from one source of truth.
const LOCAL_FILES = [".env.local"];
export type LinkResult = "linked" | "present" | "no-source";
function git(cwd: string, args: string[]): string {
// Piped stderr keeps an expected failure (see primaryCheckout) quiet.
return execFileSync("git", args, {
cwd,
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
}).trim();
}
/**
* The first `git worktree list` entry is the main worktree, under worktrunk,
* Orca and plain `git worktree add` alike. For a bare repository, or one
* made with --separate-git-dir, that entry is the metadata directory rather
* than a checkout, so it is trusted only if it is its own work tree.
* Otherwise this returns null rather than guessing: a guessed directory,
* such as the parent of a bare repo, could hold an unrelated .env.local.
*/
export function primaryCheckout(cwd: string): string | null {
const [entry] = git(cwd, ["worktree", "list", "--porcelain", "-z"]).split(
"\0",
);
const candidate = entry.replace(/^worktree /, "");
try {
const top = git(candidate, ["rev-parse", "--show-toplevel"]);
return realpathSync(top) === realpathSync(candidate) ? candidate : null;
} catch {
return null;
}
}
export function linkLocalFile(
primary: string,
worktree: string,
file: string,
): LinkResult {
const source = path.join(primary, file);
if (!existsSync(source)) {
return "no-source";
}
const target = path.join(worktree, file);
mkdirSync(path.dirname(target), { recursive: true });
try {
// symlinkSync refuses any existing path, dangling links included, so
// "never replace" needs no separate, racy existence check.
symlinkSync(source, target);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "EEXIST") {
return "present";
}
throw error;
}
return "linked";
}
export function install(
cwd: string,
platform: NodeJS.Platform = process.platform,
): number {
// Replace with this repository's own install and build steps. Windows
// needs a shell to resolve the npm.cmd shim, and since CVE-2024-27980
// Node refuses to spawn a .cmd file without one, so naming npm.cmd is
// no fix. A shell is safe here only because the arguments are constant.
const { status, error } = spawnSync("npm", ["install"], {
cwd,
stdio: "inherit",
shell: platform === "win32",
});
if (error) {
throw error;
}
return status ?? 1;
}
interface MainOptions {
cwd?: string;
runInstall?: (cwd: string) => number;
}
/** Returns the install's exit code. */
export function main({
cwd = process.cwd(),
runInstall = install,
}: MainOptions = {}): number {
const worktree = git(cwd, ["rev-parse", "--show-toplevel"]);
const primary = primaryCheckout(cwd);
if (primary === null) {
console.log(
"No primary checkout (bare repository or separate git dir); skipped linking local files.",
);
} else if (realpathSync(primary) === realpathSync(worktree)) {
console.log("In the primary checkout; skipped linking local files.");
} else {
for (const file of LOCAL_FILES) {
console.log(`${file}: ${linkLocalFile(primary, worktree, file)}`);
}
}
return runInstall(worktree);
}
if (
process.argv[1] &&
import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
) {
process.exitCode = main();
}
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |