repo-setup
Skill3 starsChanged 50 days agoMITView on GitHub
Use at the start of /implement's repo path to land in a clean working state — fetch, fast-forward main, prune merged branches/worktrees/plan-files, then create the feature branch + worktree off fresh main and switch the session into it. Repo-only; project-overridable for deep provisioning.
- Reads credentials
9 other projects use a version of this.
Adopted by
Most recently taken up by
- smarzban/agent-skillstheir own version, first seen Nov 15, 2026
- lxsmnsyc/agent-skillstheir own version, first seen Nov 8, 2026
- newkirkjosh/skillstheir own version, first seen Nov 1, 2026
- TheAxeC/ordotheir own version, first seen Nov 1, 2026
- lggarrison/agent-skillstheir own version, first seen Oct 25, 2026
- JarvusInnovations/agent-skillstheir own version, first seen Oct 20, 2026
Used with
Projects with it also use pr-review.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
MicrosoftSkillpr-review
Verify the technical accuracy of a vscode-docs pull request against the VS Code source code in microsoft/vscode. Use when reviewing a docs PR for factual correctness: setting names, command IDs, default values, API shapes, keybindings, versioned availability, and described behavior.
Also in 3 projects that use this
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- getsentry/outpost★ 5same name
- lxsmnsyc/agent-skills★ 4same name
- polaralias/skills★ 2same name
- smarzban/agent-sdlc★ 2same name
- JarvusInnovations/agent-skills★ 1same name
- newkirkjosh/skills★ 1same name
- smarzban/agent-skills★ 1same name
- lggarrison/agent-skills★ 0same name
- TheAxeC/ordo★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository8 other files it gives its agents.
- agent-reviewSkill
- capture-to-vaultSkill
- cleanup-artifactsSkill
- dispatch-explorationSkill
- load-contextSkill
- open-draft-prSkill
- plan-fileSkill
- publish-prSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
not on main → git fetch origin main:main (fast-forward-only update of the local ref.
- Very specific: line 42
Remove its worktree if present: git worktree remove <root>/.worktrees/<branch> (--force only if an override opts in).
- Very specific: line 43
Delete its plan file: rm -f <root>/.claude/plans/<branch>.md using the /→- flattened branch name (feat/foo → .claude/plans/feat-foo.md, …
- Very specific: line 44
Delete the branch: git branch -d <branch> for merge-commit / fast-forward merges.
- Distinctive: line 57
Main session only: Run this step in the main session, not a subagent — a subagent's cwd is pinned, so the switch is rejected or affects …
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 tofeat/. - (implicit) the current repo and its
originremote.
Steps
- 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
/implementin 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 abareline, 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 -Pisn't<root>, first tryExitWorktree(action: "keep")(load viaToolSearchselect:ExitWorktreeif deferred; neverremove— that's a prior branch's work). Don't rely on remembering whether you entered one — after/clearor compaction you may not; the tool reports when no worktree session is active. Then, ifpwd -Pstill isn't<root>,cd <root>— and re-checkpwd -P: the harness may reset acdthat 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 baregit 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:
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 untrackedc='<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.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 nogitand 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-filereuses 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 (andplan-file) to skip that entry, or new plans are silently ignored. (plan-filere-checks.claude/plans/independently, so it holds when invoked standalone.)
- Resolve the root:
- Guard a dirty tree. If
git status --porcelainis non-empty, stop and surface the changes — don't fetch/prune over dirty state. (A project override may stash-and-restore instead.) A.gitignorewhose 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. - Fetch.
git fetch --prune origin— updates remote-tracking refs and drops refs for branches deleted on the remote. - Fast-forward
main. Bring localmaintoorigin/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).
- on
Prune merged work. Enumerate merged branches with
git branch --merged origin/main, add the squash-merged ones (see caveat), then dropmain, the current branch, the starting branch/worktree recorded in step 0, and the in-use candidates below.In-use exclusions. Another session's freshly cut branch has no commits yet, so its tip is at or behind
origin/main— indistinguishable from a fast-forward merge (and, atorigin/main's tip, its two-dot diff is empty too). Removing its worktree also deletes the plan fileplan-filewrote inside it, since ignored files don't blockgit worktree remove. Skip the whole candidate — worktree, plan file, and branch, whichever list (merged or squash-merged) it came from — when either holds:- Its worktree is locked — a
lockedline under its entry ingit worktree list --porcelain. Step 5 locks every worktree it creates;/implementunlocks it at a normal exit and keeps it through a kickback or pause. List each skipped locked worktree in the output with its path — it may be a live or paused session, or a stale lock left by a crashed one; flag one as "merged but locked — unlock to prune" only when the tip-matchedghcheck below confirmed its PR merged (--mergedalone also lists every fresh in-flight branch). The fix for a stale one isgit worktree unlock <path>once the user confirms that session is gone. Never unlock automatically. - Its tip equals
origin/main(git rev-parse <branch>=git rev-parse origin/main) — it has no commits of its own, so there is nothing to have merged. A real fast-forward merge caught by this survives untilorigin/mainadvances past it.
For each remaining candidate:
- Remove its worktree if present:
git worktree remove <root>/.worktrees/<branch>(--forceonly if an override opts in). - Delete its plan file:
rm -f <root>/.claude/plans/<branch>.mdusing the/→-flattened branch name (feat/foo→.claude/plans/feat-foo.md, matchingplan-file); gitignored, per-branch, safe. - Delete the branch:
git branch -d <branch>for merge-commit / fast-forward merges;git branch -D <branch>for squash-merged branches (-drefuses them —-Dis safe because the caveat's check already confirmed the content landed).
Then
git worktree pruneto clear stale administrative entries.Squash-merge caveat.
git branch --merged origin/maincatches merge-commit and fast-forward merges but not squash-merges — and/implementsquashes by default, so a just-merged branch won't show as merged (andgit branch -dwould refuse to delete it). Detect those separately, in order of reliability:gh pr list --state merged --head <branch> --json headRefOidreports a merged PR whoseheadRefOidequals the local branch tip — robust, but needs network + auth. The tip match matters: a reused branch name also matches an old merged PR.git diff origin/main..<branch>(two-dot — compares the tip trees) is empty when the branch's change already landed andmainhasn't moved since. Network-free fallback; amainthat has advanced since the squash defeats it.
Delete the matches (subject to the in-use exclusions above) with
git branch -D. Withoutghauth and with an advancedmain, a squash-merged branch may survive the prune — acceptable; the next clean run catches it. One whose PR gained commits the local branch lacks (pushed from elsewhere or via the GitHub UI) fails the tip match and survives every run — it fails safe; once confirmed merged, remove it manually:git worktree remove <path>(unlock first if locked), thengit branch -D <branch>.- Its worktree is locked — a
- Create the feature branch + worktree off fresh main.
git worktree add --lock --reason "/implement in progress" <root>/.worktrees/<branch> -b <branch> origin/main— one step: branch cut from up-to-datemain, checked out in an isolated worktree, locked so a concurrent session's step 4 skips it./implementreleases the lock at its normal exit (step 10). Enter the worktree. Switch the session's working directory into it, using the absolute path
<root>/.worktrees/<branch>:- Claude Code →
EnterWorktree(path: "<root>/.worktrees/<branch>")— thepathform accepts a worktree made bygit worktree add. Invoking/implement/repo-setupis the explicit instruction to work in a worktree that the tool's usage rule asks for; don't skip it on those grounds. If the tool is deferred, load it first (ToolSearchselect:EnterWorktree). - Harness without an equivalent tool → one persistent
cd <root>/.worktrees/<branch>. - Main session only. Run this step in the main session, not a subagent — a subagent's cwd is pinned, so the switch is rejected or affects only that agent. Subagents dispatched later get the worktree's absolute path in their prompt.
Verify the switch:
realpath "$(git rev-parse --show-toplevel)"must equalrealpath "<root>/.worktrees/<branch>"(canonicalize both — a symlinked path would otherwise mismatch) andgit branch --show-currentmust print<branch>. If either doesn't match (or the tool call was rejected), stop and surface it to the user — don't fall back to prefixing commands.From here on every command runs bare: never prefix commands with
cd .worktrees/<branch> &&orgit -C …— prefixed commands are harder to read and break hooks that match on the command's prefix or cwd.Re-entering later. To resume an existing branch's worktree (e.g. addressing human review comments after
/implementexited), don't re-run this skill — repo-setup only creates new branches. Re-enter with the same enter-and-verify as this step:EnterWorktree(path: "<root>/.worktrees/<branch>")(orcd), then the verify. Leave the worktree lock as found — a paused session's lock stays, and a worktree unlocked at a normal exit isn't re-locked (its commits already protect it).- Claude Code →
Output / contract
- In: repo state + a branch name.
- Out: the created branch name and its absolute worktree path (
<root>/.worktrees/<branch>), with the session's working directory switched into it soplan-fileand the later primitives operate inside the worktree. - Side effects: local
mainfast-forwarded; previously-merged branches + their worktrees + their plan files removed (locked worktrees skipped and listed); new branch + locked worktree created;.worktrees/and.claude/plans/ensured in the repo-localinfo/exclude(no tracked file is modified); session cwd moved out of any prior worktree (step 0) and into the new one (step 6). No pushes or other network writes; the optional squash-mergegh pr listcheck is a network read and needs auth.
Project overrides
This primitive stops at "branch + worktree exist, session inside it." 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,.envsecret-gen,compose up). - Worktree policy — a repo that doesn't want worktrees overrides step 5 with a plain
git switch -c <branch> origin/main(and drops step 6). - 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/<branch>, so compose'senv_filefails — symlink or copy them in; and compose must be run from inside the worktree dir (step 6 puts the session there), because bind-mounts are relative and running from the repo root silently exercisesmain, not your branch. Overriderepo-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, session cwd inside it" outcome) so the rest of /implement keeps working. An override that creates the worktree itself must create it locked (--lock, or git worktree lock right after) — step 4's concurrency protection and /implement's exit unlock depend on it. (Step 0 already ensures .worktrees/ and .claude/plans/ are ignored.)
Future scope
- Vault / non-repo path (deferred out of v1 —
/implementis repo-shaped for now). - Branch-name derivation from the ticket (currently the recipe's job, passed in).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

