Worktree isolation

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

One-command harness distribution for coding agents — a versioned YAML catalog projected into agent instructions, skills, and deterministic git gates.

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.

2 things to look at

25 days oldThe repository was created 25 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
1 stars1 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.

What its author says it does

Copied from the file, not written here

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.

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.