repo-setup

Repo Setup

First step of /implement's repo path. Takes the repo from whatever state it's in to a fresh feature branch + worktree cut off an up-to-date main — with the session standing in that worktree — clearing the debris of previously-merged work on the way. Assumes a git repo — the recipe's repo-vs-vault context branch runs before this.

Input

• branch — the feature branch to create, as <type>/<desc> (feat/, fix/, chore/, story/S-<id>-<desc>). The recipe derives it from the ticket. A bare description is acceptable — default the type to feat/.
• (implicit) the current repo and its origin remote.

Steps

1. Start from the main checkout. Steps 1–5 resolve relative paths and "current branch" against the main checkout, so get there first — a session may still be standing in a previous run's worktree (a second /implement in the same session), have been launched inside one, or sit in a subdirectory.
   • Resolve the root: git worktree list --porcelain | sed -n '1s/^worktree //p' — the first entry is the main checkout, call it <root>. If that entry is followed by a bare line, the repo is a bare-repo layout with no main working tree: stop — that layout needs a project override.
   • Record where you started: the starting worktree (git rev-parse --show-toplevel) and its branch (git branch --show-current), before moving. Step 4 must not prune them — they may be a worktree the user owns and the session was launched in.
   • Move: if pwd -P isn't <root>, first try ExitWorktree(action: "keep") (load via ToolSearch select:ExitWorktree if deferred; never remove — that's a prior branch's work). Don't rely on remembering whether you entered one — after /clear or compaction you may not; the tool reports when no worktree session is active. Then, if pwd -P still isn't <root>, cd <root> — and re-check pwd -P: the harness may reset a cd that leaves the launch directory, so if it didn't take, stop and surface it. No-op on a normal first run. Steps 4–5 anchor their file paths to <root> anyway, so they hold even if cwd drifts.
   • Ensure local ignores: make sure .worktrees/ and .claude/plans/ are in the repo-local exclude file — append each if missing, no-op if present — so the .worktrees/ dir never shows as untracked in the main checkout. Two plain commands — resolve the common git dir with a bare git rev-parse --git-common-dir (if the output is relative — typically .git — prefix it with <root>/; if absolute, use it as-is), then run the append with that absolute path substituted as a literal:

     c='<absolute common dir>'; x="$c/info/exclude"
     if [ -d "$c" ]; then mkdir -p "$c/info"
       [ -s "$x" ] && [ -n "$(tail -c1 "$x")" ] && printf '\n' >> "$x"
       for p in '.worktrees/' '.claude/plans/'; do grep -qxF "$p" "$x" 2>/dev/null || printf '%s\n' "$p" >> "$x"; done
     else echo "no git common dir at $c" >&2; false; fi
     

     The exclude file lives in the common git dir, so it applies to the main checkout and every linked worktree, and it isn't tracked — so ignoring never dirties the tree. That's why this runs before the step 1 guard: it clears an untracked .worktrees/ instead of tripping on it — and before step 6, because a worktree-isolated session refuses writes into <root>/.git. If the harness refuses the append anyway (e.g. an isolation guard still active after /clear), stop and give the user the literal command to run themselves (! <command>). The append runs no git and embeds no $(git …), so command-shape hooks can verify it; it fails loudly (without exiting a persistent shell) if the path isn't a directory; the newline guard keeps an entry from being glued onto a last line with no trailing newline. This snippet is canonical — plan-file reuses it for .claude/plans/ alone. repo-setup never edits the tracked .gitignore — a project that wants these entries there adds them through a normal PR. A project that tracks plan files under .claude/plans/ must override this step (and plan-file) to skip that entry, or new plans are silently ignored. (plan-file re-checks .claude/plans/ independently, so it holds when invoked standalone.)
2. Guard a dirty tree. If git status --porcelain is non-empty, stop and surface the changes — don't fetch/prune over dirty state. (A project override may stash-and-restore instead.) A .gitignore whose only change is adding .worktrees/ / .claude/plans/ is left over from an older repo-setup that wrote there; surface it like any other change — reverting a modified one (or deleting an untracked one holding only those lines) is safe, step 0's exclude entries now cover it.
3. Fetch. git fetch --prune origin — updates remote-tracking refs and drops refs for branches deleted on the remote.
4. Fast-forward main. Bring local main to origin/main, never a merge commit:
   • on main → git merge --ff-only origin/main
   • not on main → git fetch origin main:main (fast-forward-only update of the local ref; refuses if it would diverge).
5. Prune merged work. Enumerate merged branches with git branch --merged origin/main, add the squash-merged ones (see caveat), then drop main, the current branch, the starting branch/worktree recorded in step 0, and the in-use candidates below.