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, 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 / (feat/, fix/, chore/, story/S--). 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. 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.)
2. Fetch. git fetch --prune origin — updates remote-tracking refs and drops refs for branches deleted on the remote.
3. 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).

1. Prune merged work. Enumerate merged branches with git branch --merged origin/main, add the squash-merged ones (see caveat), and for each — excluding main and the current branch:

• Remove its worktree if present: git worktree remove .worktrees/ (--force only if an override opts in).
• Delete its plan file: rm -f .claude/plans/.md using the /→- flattened branch name (feat/foo → .claude/plans/feat-foo.md, matching plan-file); gitignored, per-branch, safe.
• Delete the branch: git branch -d for merge-commit / fast-forward merges; git branch -D for squash-merged branches (-d refuses them — -D is safe because the caveat's check already confirmed the content landed).

Then git worktree prune to clear stale administrative entries.

Squash-merge caveat. git branch --merged origin/main catches merge-commit and fast-forward merges but not squash-merges — and /implement squashes by default, so a just-merged branch won't show as merged (and git branch -d would refuse to delete it). Detect those separately, in order of reliability:

• gh pr list --state merged --head reports it merged — robust, but needs network + auth.
• git diff origin/main.. (two-dot — compares the tip trees) is empty when the branch's change already landed and main hasn't moved since. Network-free fallback; a main that has advanced since the squash defeats it.

Delete the matches with git branch -D. Without gh auth and with an advanced main, a squash-merged branch may survive the prune — acceptable; the next clean run catches it.

1. Create the feature branch + worktree off fresh main. git worktree add .worktrees/ -b origin/main — one step: branch cut from up-to-date main, checked out in an isolated worktree.
2. Ensure ignores. From the main checkout, make sure .worktrees/ and .claude/plans/ are in the repo's .gitignore — append each if missing, no-op if present — so the .worktrees/ dir never shows as untracked here:

`` [ -s .gitignore ] && [ -n "$(tail -c1 .gitignore)" ] && printf '\n' >> .gitignore for p in '.worktrees/' '.claude/plans/'; do grep -qxF "$p" .gitignore 2>/dev/null || printf '%s\n' "$p" >> .gitignore; done ` The leading guard appends a newline first if the file doesn't end in one, so an entry isn't glued onto the last line. Idempotent — a one-time addition per repo, committed via a normal branch/PR. (.claude/plans/ is also ensured independently by plan-file in the worktree where plans are actually written — step 6 covers the root checkout; plan-file` is the real plan-leak backstop.)

Output / contract

• In: repo state + a branch name.
• Out: the created branch name and its worktree path (.worktrees/), surfaced so plan-file and the later primitives operate inside the worktree.
• Side effects: local main fast-forwarded; previously-merged branches + their worktrees + their plan files removed; new branch + worktree created; .worktrees/ and .claude/plans/ ensured in .gitignore. No pushes or other network writes; the optional squash-merge gh pr list check is a network read and needs auth.

Project overrides

This primitive stops at "branch + worktree exist." Deep, stack-specific provisioning is project-override territory, layered after the generic steps:

• Port / secret / compose setup — e.g. domainator's setup-feature.sh (slot-based ports, .env secret-gen, compose up).
• Worktree policy — a repo that doesn't want worktrees overrides step 5 with a plain git switch -c origin/main.
• Dirty-tree handling — stash-and-restore instead of stop.
• Containerized verification seam — when tests run via podman/docker compose, a bare worktree breaks two ways: the gitignored .env (and other secrets) won't exist in .worktrees/, so compose's env_file fails — symlink or copy them in; and compose must be run from inside the worktree dir, because bind-mounts are relative and running from the repo root silently exercises main, not your branch. Override repo-setup (and see /implement's execute step) to set this up.

Overrides must honor the contract (same name, same "fresh branch + worktree off updated main" outcome) so the rest of /implement keeps working. (Step 6 already ensures .worktrees/ and .claude/plans/ are gitignored.)

Future scope

• Vault / non-repo path (deferred out of v1 — /implement is repo-shaped for now).
• Branch-name derivation from the ticket (currently the recipe's job, passed in).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ethanaubuchon
• Source: ethanaubuchon/dossier-tradecraft
• License: MIT

Install and usage instructions live in the source repository linked above.