branch-choice
Skill9 starsChanged 7 months agoMITView on GitHub
Present the once-per-session branch menu at the FIRST file edit of a session (new from main / keep existing / switch / merge-then-new / stash) and handle owner-approved landing of stale (>24h) branches reported by the stale-branch reaper. Use before the first file change of a session, or when the reaper reports STALE_BRANCH lines needing approval.
In this repository44 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anthropic-multi-agent-research-system-skillSkill
- apply-selectionsSkill
- bootstrap-dogfood-projectSkill
- brainstormSkill
- cc-adoption-scoutSkill
- claude-guardianSkill
- continueSkill
- end-sessionSkill
- executing-plansSkill
- five-advisorsSkill
- get-work-doneSkill
- git-branch-lifecycleSkill
- githubSkill
- grill-meSkill
- hook-transcript-fixture-testSkill
- instagramSkill
- linkedinSkill
- modern-data-pipeline-diagramSkill
- pattern-qualitySkill
- platform-event-live-probeSkill
- plugin-lifecycleSkill
- promote-to-coreSkill
- prompt-auto-enhanceSkill
- provision-reportSkill
- redditSkill
- review-new-claude-featuresSkill
- save-sessionSkill
- scan-discovery-reportSkill
- scan-repoSkill
- scan-urlSkill
- self-improveSkill
- skill-evaluatorSkill
- skill-masterSkill
- ssot-workflow-auditSkill
- start-sessionSkill
- synthesize-hubSkill
- synthesize-projectSkill
- twitter-xSkill
- verify-effect-at-destinationSkill
- workflow-doc-reviewerSkill
- writing-plansSkill
- writing-skillsSkill
- youtube-transcriptSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 5 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
Before the FIRST Edit/Write/MultiEdit of a session (read-only / question / analysis turns NEVER trigger this), check THIS session's marker …
- Very specific: line 33
NEVER trigger this), check THIS session's marker .claude/.branch-choice-active.<session_id> — the gate hook (branch-choice-gate.sh) prints …
- Distinctive: line 61
If there is NO existing non-main branch, the menu collapses to option 1 (cut a fresh branch from main) — still confirm the name unless …
- Very specific: line 65
Only auto-suggest rotating off auto/work-* branches — never silently yank the owner off a hand-named branch (feat/...).
- Very specific: line 83
MUST present the menu at the first file-edit of a session when THIS session's .claude/.branch-choice-active.<session_id> marker is absent.
- Distinctive: line 85
MUST, when the gate flags a concurrent live session, isolate in a git worktree rather than two sessions sharing one checked-out branch.
- Very specific: line 86
MUST cut every NEW branch from fresh origin/main (fetch first), never from another feature branch.
- Distinctive: line 87
MUST hide "keep existing" when that branch is already merged.
- Distinctive: line 88
MUST NOT trigger on read-only / question / analysis turns — only on a real file change.
- Distinctive: line 89
MUST get explicit owner approval before landing any stale branch.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Branch Choice — owner-driven, once-per-session
A Stop-hook shell script cannot pause for an interactive answer, so the branch decision lives at the model layer (this skill). Four companion hooks form the unattended safety net:
auto-git.shstill refuses to commit ontomain(carries work to a fresh branch as a backstop).stale-branch-reaper.sh(SessionStart) clears the per-session marker + reports stale branches + prints theBRANCH-CHOICE:nudge.branch-choice-gate.sh(PreToolUse Edit|Write|MultiEdit) re-injects this reminder at the EXACT first file edit (deterministic — survives a long session where the SessionStart nudge rots), non-blocking, silent once the marker exists.session-concurrency-guard.sh(SessionStart) warns when another session shares the working tree and recommends a worktree (two sessions = one checked-out branch = collisions).
STEP 1: Gate — ask ONCE per session
Before the FIRST Edit/Write/MultiEdit of a session (read-only / question / analysis turns
NEVER trigger this), check THIS session's marker .claude/.branch-choice-active.<session_id> — the
gate hook (branch-choice-gate.sh) prints the exact path in its reminder. The marker is keyed by
session id so concurrent sessions sharing one working tree never silence each other's menu:
- This session's marker present → a choice was already made this session. Proceed on the current branch; do NOT re-ask.
- Marker absent → run STEP 2, then create it:
touch .claude/.branch-choice-active.<session_id>(gitignored) using the exact filename from the gate's reminder. A new session has a new id, so it re-asks automatically;stale-branch-reaper.shGCs old markers. - Gate flags another live session (its reminder carries a
CONCURRENCY:note) → two sessions share ONE checked-out branch and WILL collide. Isolate this work in a git worktree first (/git-branch-lifecycle work <name>), then pick the branch there.
STEP 2: Present the menu
Show the existing branch (if any) WITH context — age · last commit subject · CI/PR state ·
ahead/behind main — then offer:
- New branch from
main(recommended for new / unrelated work) —git fetch origin mainthengit checkout -b <name> origin/main. Propose a meaningful<name>from the work (feat/...,fix/...); the owner may accept or rename. Avoid a bare timestamp when a descriptive name is derivable. - Keep the existing branch (continue the same work) — stay on it. Hide this option when that branch is already merged (reusing a dead branch is invalid → only option 1 applies).
- Switch to another existing branch — list open branches; checkout the chosen one.
- Merge the existing branch to
main, then new branch — land it viasession-git-landing.sh merge-one <branch>(CI-gated; refuses red/stale), then option 1. - Stash current changes and decide first —
git stashthe edits, present state, wait.
If there is NO existing non-main branch, the menu collapses to option 1 (cut a fresh branch from
main) — still confirm the name unless pre-authorized.
Carry any uncommitted edits onto the chosen branch; if they fail to apply cleanly, stash + warn.
Only auto-suggest rotating off auto/work-* branches — never silently yank the owner off a
hand-named branch (feat/...); offer "keep" for those.
STEP 3: Stale-branch approval (reaper)
At SessionStart, stale-branch-reaper.sh prints STALE_BRANCH | <br> | age | ahead/behind | ci | last
lines for branches idle > STALE_BRANCH_HOURS (default 24h). When such lines appear, present them
to the owner as ONE batched prompt:
- Green + clean (CI passed, no conflicts vs current
main) → offer to land viasession-git-landing.sh merge-one <br>on the owner's approval. - Red / unfinished / conflicted → FLAG only with the reason; NEVER merge broken work to
main, even if asked — surface the failing check and let the owner resume or drop it.
Merging stale work to main is consequential → it is ALWAYS owner-approved, never silent.
CRITICAL RULES
- MUST present the menu at the first file-edit of a session when THIS session's
.claude/.branch-choice-active.<session_id>marker is absent; MUST then create it so it is asked ONCE per session. - MUST, when the gate flags a concurrent live session, isolate in a git worktree rather than two sessions sharing one checked-out branch.
- MUST cut every NEW branch from fresh
origin/main(fetch first), never from another feature branch. - MUST hide "keep existing" when that branch is already merged.
- MUST NOT trigger on read-only / question / analysis turns — only on a real file change.
- MUST get explicit owner approval before landing any stale branch; MUST NOT merge red/unfinished work.
- Honors pre-authorization: if the owner delegated ("you decide" / silent mode), pick option 1
(new from
main) with a derived name and state the choice as an assumption — do not block. - A NON-INTERACTIVE session (headless
claude -p, an autonomous run — no human present to answer a menu) is pre-authorized BY DEFINITION: never render the menu; pick option 1 silently, state the assumption in the output, and continue. Dead-ending an unattended run on an interactive menu is a defect (fire-drill 2026-07-15, hub #416).
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.

