Worktree isolation

Skill niksavis/basicly/.agents/skills/worktree-isolation

Isolate non-trivial work in a sibling git worktree using `basicly worktree`, covering sibling placement on a harness branch, dependency + git-hook provisioning, and safe cleanup. Use when starting a unit of work that should not touch the main checkout, when parallel tracks would collide, or when deciding whether a change needs its own worktree.From its SKILL.md

Install

npx -y skills add niksavis/basicly --skill worktree-isolation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.2 KB, 733 tokens by cl100k_base, as published. Nobody here has run it

Worktree Isolation

Scope

Owns running a unit of work in an isolated sibling git worktree via the basicly worktree commands: where the worktree goes, how it is provisioned so its gates actually run, and how it is torn down without endangering the main checkout.

It is not for:

Merging a finished worktree branch back or resolving conflicts (that is the merge orchestrator's job — not yet part of basicly worktree).
Creating or claiming the beads issue the work tracks (see tool-br).
Git staging, diffing, or commit-message formatting (see tool-git, conventional-commits).

When to isolate

Isolate any non-trivial change: multi-file work, anything that runs the gates, or work that could run in parallel with another track.
Skip trivial mechanical edits (a typo, a one-line doc fix) — those go straight to the source branch. A worktree has a real setup cost; do not pay it for throwaway work.

Placement rule (non-negotiable)

A worktree lives at the sibling path <repo>.worktrees/<name> on branch harness/<name>, forked from the configured base branch ([worktree].base_branch in basicly.toml, or the current branch).

Never create work worktrees inside the repo (e.g. in-repo .claude/worktrees/): an in-repo worktree pollutes the repo's own file walk and is not provisioned, so its git hooks fall back to a system toolchain and run no gates — the exact failure that lets unguarded commits through.

Lifecycle

Create + provision — basicly worktree create <name> [--base <branch>]. This adds the sibling worktree, provisions its own standalone .venv (uv sync) and node_modules (npm install), and installs the repo's git hooks for every stage. The dependency trees are freshly installed (never symlinked to main), so the worktree is self-contained and teardown is safe. Creation is refused once [worktree].concurrency (default 4) is reached.
Work — do the change in the worktree; its hooks gate commits exactly as on main.
Cleanup — basicly worktree cleanup <name> removes the worktree, prunes the registry, and deletes the harness/<name> branch once it is merged. The base branch is never touched. An unmerged branch is kept (with a note) unless you pass --force; a worktree whose directory vanished is still reclaimable.

Use basicly worktree list to see active sessions (stale ones are marked).

Claude Code note

Claude Code's worktree.bgIsolation guard (default on) would force a background agent into its own .claude/worktrees/ before editing, conflicting with this sibling-worktree scheme. Run basicly worktree bg-isolation once per repo to set it to none (consent-gated; writes the committed .claude/settings.json). Codex and Copilot have no equivalent setting.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.