new-worktree

name	new-worktree
description	Create / remove / inventory Typhon dev worktrees with the nested claude/ docs repo wired up correctly — one command instead of the three-step manual procedure that silently half-completes
argument-hint	<name> | <name> --remove | --list

new-worktree — Typhon worktree lifecycle

Thin wrapper over scripts/new-worktree.ps1. The PowerShell script does the whole procedure in one shot — fetch, branch, docs repo, verify, background pre-warm — and reports. Do not hand-run git worktree add / git clone from Bash; the point of this skill is that the steps can no longer be partially applied.

Why this exists

Typhon is a multi-repo workspace: the docs are a separate clone of log2n-io/typhon-claude living at <repo>/claude, gitignored by the parent. So git worktree add alone produces a worktree with no docs, and on a documentation-first project every docs-first read then silently resolves against the main repo's claude/ — pinned to whatever branch that checkout sits on. You get last quarter's design docs against this week's code, with nothing warning you. --list currently shows three existing worktrees in exactly that state.

Input

$ARGUMENTS first token is the worktree name. Recognized flags (map them onto the script's PowerShell switches): --list, --remove, --force, --no-build, --docs-clone, --branch <b>, --from <ref>. With no arguments, show the script's usage block.

Behavior

Run the script via PowerShell and display its stdout verbatim:

pwsh -NoProfile -File ./scripts/new-worktree.ps1 <name> [options]

Then cd both shells into the new worktree — the script prints the exact two commands, because a child process cannot change the parent's working directory:

• Bash: cd <worktree>
• PowerShell: Set-Location <worktree>

Both tools persist their cwd independently, so both are required. Do not use EnterWorktree: it fails deterministically here because its owner-resolution walks into the nested claude/ repo and validates a parent-owned path against that repo's worktree list.

Use worktree-absolute paths for builds regardless — the session root and auto-loaded CLAUDE.md stay pointed at the main repo.

What the script does that hand-running misses

Step	Detail
Anchors on the main repo	Resolves --git-common-dir, so it works when invoked from inside another worktree
Fetches first	Branches off freshly fetched origin/main, never the local main (checked out elsewhere, so git would refuse anyway)
--no-track	Without it git infers upstream=origin/main, making git status read "ahead of origin/main" and turning a reflexive git pull into a merge of main into your feature branch
Docs as a worktree, not a clone	Objects live in the shared <repo>/claude store, so unpushed doc commits survive deleting the folder. An independent clone is the only copy of its objects — verified: a force-removed docs commit was still readable from the main clone afterwards
Same branch in both repos	Code and docs move together
Verifies	Sentinel claude/CLAUDE.md present + both HEADs on the expected branch, else it fails loudly instead of leaving a half-built worktree
Pre-warms	Backgrounds a Debug build of the engine test project (a fresh worktree has no obj//bin/, so the first build is fully cold). --no-build to skip — worth doing when other agents are running tests on this box

Removal

--remove refuses to proceed when either repo has uncommitted changes or commits absent from every remote-tracking ref, listing exactly what would be lost; --force overrides. It removes the docs worktree before the parent and prunes both worktree lists — rm -rf would leave a stale registration behind. Branches are never deleted; it prints the branch -D command instead.

Notes

• Default branch name is feature/<name>; override with --branch.
• Neither branch gets an upstream, so the first push is git push -u origin <branch> in each repo.
• --docs-clone forces the old independent-clone behavior if a worktree of the docs repo is unwanted.
• Every worktree that exists makes /benchmark fail from the main repo (BenchmarkDotNet duplicate-csproj discovery). Run benchmarks from inside a worktree.