agentleFS
ethanaubuchonethanaubuchon/dossier-tradecraft/skills/repo-setup/SKILL.md

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

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.
  • MicrosoftSkill

    pr-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

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
  1. Very specific:

    not on main → git fetch origin main:main (fast-forward-only update of the local ref.

    line 34
  2. Very specific:

    Remove its worktree if present: git worktree remove <root>/.worktrees/<branch> (--force only if an override opts in).

    line 42
  3. Very specific:

    Delete its plan file: rm -f <root>/.claude/plans/<branch>.md using the /→- flattened branch name (feat/foo → .claude/plans/feat-foo.md, …

    line 43
  4. Very specific:

    Delete the branch: git branch -d <branch> for merge-commit / fast-forward merges.

    line 44
  5. Distinctive:

    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 …

    line 57

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

    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, at origin/main's tip, its two-dot diff is empty too). Removing its worktree also deletes the plan file plan-file wrote inside it, since ignored files don't block git 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 locked line under its entry in git worktree list --porcelain. Step 5 locks every worktree it creates; /implement unlocks 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-matched gh check below confirmed its PR merged (--merged alone also lists every fresh in-flight branch). The fix for a stale one is git 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 until origin/main advances past it.

    For each remaining candidate:

    • Remove its worktree if present: git worktree remove <root>/.worktrees/<branch> (--force only if an override opts in).
    • Delete its plan file: rm -f <root>/.claude/plans/<branch>.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 <branch> for merge-commit / fast-forward merges; git branch -D <branch> 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 <branch> --json headRefOid reports a merged PR whose headRefOid equals 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 and main hasn't moved since. Network-free fallback; a main that has advanced since the squash defeats it.

    Delete the matches (subject to the in-use exclusions above) 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. 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), then git branch -D <branch>.

  6. 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-date main, checked out in an isolated worktree, locked so a concurrent session's step 4 skips it. /implement releases the lock at its normal exit (step 10).
  7. 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>") — the path form accepts a worktree made by git worktree add. Invoking /implement / repo-setup is 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 (ToolSearch select: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 equal realpath "<root>/.worktrees/<branch>" (canonicalize both — a symlinked path would otherwise mismatch) and git branch --show-current must 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> && or git -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 /implement exited), 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>") (or cd), 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).

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 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 (locked worktrees skipped and listed); new branch + locked worktree created; .worktrees/ and .claude/plans/ ensured in the repo-local info/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-merge gh pr list check 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, .env secret-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's env_file fails — 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 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, 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 — /implement is repo-shaped for now).
  • Branch-name derivation from the ticket (currently the recipe's job, passed in).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.