Worktree Per Feature (User Story): One Task, One Isolated Checkout

Before changing anything, move the work into a dedicated git worktree on its own branch. The main checkout stays untouched, and parallel work stays possible.

Workflow

1. Confirm the repo and check its state.

   git rev-parse --show-toplevel
   git status --porcelain

   If the main checkout has uncommitted changes, do not drag them into the feature, tell the user and ask how to proceed.

2. Name the branch after the feature: feature/<slug> (e.g. feature/rate-limit-login). If a spec exists (see the spec-first skill), reuse its slug so branch, spec, and PR line up.

3. Create the worktree as a sibling folder, never nested inside the repo:

   git worktree add ../<repo-name>-<slug> -b feature/<slug>

   Example, repo shop, feature rate-limit-login:

   git worktree add ../shop-rate-limit-login -b feature/rate-limit-login

4. Handle errors, never force through them.
   • "branch already exists": attach to it without -b: git worktree add ../<dir> feature/<slug>, or pick a new slug if that branch belongs to other work. Never -B (force-reset) an existing branch.
   • "already checked out in another worktree": that feature is live elsewhere. Run git worktree list, then either continue there or choose a new branch name.
   • Target directory already exists: choose another path. Never delete a directory you did not create.
5. Work only inside the worktree. cd into it and stay there: every edit, build, and test run happens under the worktree path. Commit to the feature branch as you go. The main checkout is read-only for you from now on.
6. Report the path. Tell the user the absolute worktree path and branch name as soon as they exist, and repeat both in your final summary.

Cleanup (after the branch is merged, not before)

git worktree remove ../<repo-name>-<slug>
git branch -d feature/<slug>     # -d refuses unmerged work; that is the point
git worktree prune

If git worktree remove refuses because of modified files, show the user what is dirty instead of reaching for --force.

Edge cases

• Not a git repo: say so and ask whether to git init or proceed without isolation, never pretend the isolation exists.
• Dependencies do not follow: node_modules, virtualenvs, and ignored .env* files are not copied into a new worktree. Re-run the installer (npm install, uv sync, ...) and copy env files only with the user's consent.
• Shared state is still shared: databases, dev-server ports, and global caches are not isolated between worktrees. Flag collisions (two servers on one port) instead of silently debugging them.

Boundaries

• Never modify files, commit, or switch branches in the main checkout while a feature worktree exists for this task.
• Never use --force variants of worktree or branch commands to bypass an error you have not explained to the user.
• Never delete a worktree or branch containing unmerged work without explicit confirmation.