AGENT SKILL

worktree

Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.

License 许可
MIT
所属仓库
nubjs/nub
最近更新
2026-11-14
Stars
★ 4.4k
Forks
71

01 前言 Front Matter

name
worktree
metadata
{ "internal": true }
description
Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.

03 SKILL.md 正文

Worktrees for parallel nub work

Substantive nub-repo work lands via a PR opened from an isolated git worktree; the shared working tree stays on main and is never branched, reset, or stashed. The whole setup is one command — don't hand-roll the git worktree add + target-dir recipe.

Create a worktree

The script runs under both nub (dogfood) and plain Node:

nub  scripts/new-worktree.ts <slug>
node scripts/new-worktree.ts <slug>

It performs the proven recipe, in order:

  1. git fetch origin (skip with --no-fetch).
  2. git worktree add ~/.cache/nub/worktrees/<slug> -b <slug> origin/main — tracked files only; the shared tree is untouched. vendor/aube is plain in-tree files, checked out by this step with no submodule init. (Non-temp location: not auto-swept like /tmp, out of the repo dir, same volume so APFS clonefile stays fast.)
  3. Apply .worktreeinclude — copy/symlink the listed gitignored entries in.
  4. Pre-create + print the shared CARGO_TARGET_DIR (~/.cache/nub/shared-target).

Options: --base <ref> (default origin/main), --path <dir> (default ~/.cache/nub/worktrees/<slug>), --no-fetch, --help.

Then build through the wrapper — do not export CARGO_TARGET_DIR yourself; scripts/rust-build.sh picks the right dir and CoW-seeds an isolated one when this worktree diverges a depended-on crate (see the rust-build skill):

cd ~/.cache/nub/worktrees/<slug>
scripts/rust-build.sh build -p nub-cli --profile fast

All worktrees share ONE target dir (~/.cache/nub/shared-target), so a second worktree reuses the crates.io dependency artifacts another already compiled and recompiles only the ~10 workspace crates — one target dir instead of ~30 multi-GB private ones. Tradeoff: cargo locks the target dir during a build, so two sharing worktrees serialize. Don't clean the shared dir between iterations. Build loop, profiles, and crate map: the dev-loop skill.

.worktreeinclude — bringing gitignored things in

git worktree add checks out tracked files only, so a worktree is lean by default (no target/, node_modules/, .repos/). .worktreeinclude at the repo root lists the gitignored things a worktree still needs; the script copies or symlinks each in.

Format — one entry per line, # comments and blank lines ignored:

[copy|symlink] <path>      # path is relative to the repo root, both sides

The verb is optional and defaults to copy; use symlink for large read-only things. Sources are read from the MAIN working tree even when you run the script from inside another worktree.

The shipped default symlinks .repos/ (read-only reference checkouts of Node, Bun, pnpm, …). Do NOT add target/ — the shared CARGO_TARGET_DIR is the build cache; an in-worktree target/ is exactly the disk bloat the shared dir avoids.

Eagerly pull the shared tree

The shared tree drifts behind origin/main because every landing goes worktree → push → merge and nothing pulls it back. After merging any PR or pushing to origin:

git -C <shared-tree> fetch origin && git -C <shared-tree> merge --ff-only origin/main

Never git pull --ff-only here. This repo sets pull.rebase=true, so pull runs rebase's precondition check first and aborts with cannot pull with rebase: You have unstaged changes on ANY dirty file — and the shared tree always carries some agent's WIP, so that form fails 100% of the time. merge --ff-only has no clean-tree precondition; it refuses only if the incoming commits would overwrite a locally-modified file.

Corollary: do NOT commit directly in the shared tree's checkout — a direct commit makes it diverge rather than merely fall behind, and a diverged tree cannot be fast-forwarded at all. If you take the sanctioned docs/control-surface exception, sync immediately before committing and push in the same breath; never rest with an unpushed commit there. This keeps files current; loaded .claude/ hooks still need a session restart.

Clean up after a merge

git worktree remove ~/.cache/nub/worktrees/<slug> --force   # leave ~/.cache/nub/shared-target in place

--force discards the worktree even with build artifacts present — so push your work first; anything uncommitted is thrown away. Do NOT delete ~/.cache/nub/shared-target — it's the warm cache the next worktree builds against.

Remove ONLY the EXACT worktree path you own — never hunt for one by HEAD SHA. If the stated path does not exist, STOP and report "nothing to clean." Sibling worktrees routinely share a HEAD (two branches cut from the same base, a stacked branch off another's head), so SHA-matching deletes a different agent's active worktree and --force-discards its uncommitted WIP. A dispatch prompt with a cleanup step must name the exact path and add: "remove only this path; if absent, report and stop — never match by SHA."

There is also an older bash helper, scripts/worktree.sh (worktrees under .worktrees/, branched off LOCAL main, with rm/list/reap subcommands and uncommitted/unpushed-work safety checks). new-worktree.ts is the preferred entry for landing work; reach for worktree.sh reap to prune stale dead-session worktrees.

04 同仓库更多 Skills

nubjs
nubjs/nub

nub

暂无简介

★ 4.4k
nubjs
nubjs/nub

nub

This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.

★ 4.4k
nubjs
nubjs/nub

windows-vm-test

Run ad-hoc Nub tests and debugging probes in the maintainer's existing local Windows 11 ARM64 QEMU/HVF VM when its external disk and runbook are present. Use for interactive win32-arm64 or Windows-on-ARM x64-emulation checks; use ci-adhoc-test for true x64-native behavior or when the local VM is unavailable.

★ 4.4k
nubjs
nubjs/nub

visual-review

Verify UI/layout/styling changes are correct by computing occlusion, clipping, and alignment from the browser's resolved paint order via the chrome-devtools MCP `evaluate_script` tool — instead of eyeballing a flat screenshot. Invoke BEFORE declaring any UI, site, or styling/layout change correct. Screenshots have no depth buffer, so z-index/occlusion/clip bugs are exactly where "just look at it" fails; the `evaluate_script` routines below turn those fuzzy visual judgments into deterministic measurements — including optical center-of-mass, which measures the glyph ink's true visual center so differently-sized labels can be aligned by more than eye.

★ 4.4k
nubjs
nubjs/nub

type-declarations

Add, audit, or update @nubjs/types declarations for Nub runtime APIs. Use whenever Nub adds or changes a user-visible global, built-in method, module loader type, or TC39 proposal; when TypeScript or @types/node gains an overlapping declaration; and before every release to reconcile runtime changes since the previous tag. Covers conflict-safe global augmentation, compiler-version routing, fixture matrices, and package verification.

★ 4.4k
nubjs
nubjs/nub

soak

Manages the repo's supply-chain soak window (SOAK_DAYS) — checks and fixes the derived surfaces, bumps or disables the window, adds dated per-package exclusions, and bumps pinned external tools. Use when a task touches minimumReleaseAge, min-release-age, min-publish-age, external-tools.json, renovate.json, or taze cooldowns, or when investigating why a freshly published version won't install.

★ 4.4k