git-branch-lifecycle
Skill9 starsChanged 7 months agoMITView on GitHub
Orchestrate the autonomous branch automation (auto-git.sh + auto-pr.sh hooks) from a model-driven control layer. Use to start an isolated parallel workstream in its own git worktree (`work`), to finish a branch NOW with an agent code-review before arming auto-merge (`finish`), to RECONCILE every branch (`cleanup` — merged→prune, unmerged→auto-PR+merge-on-green, escalate only CI-red/strategic), or to see the live branch/PR/merge state (`status`). The hooks handle the unattended path automatically; this skill is the judgment layer for parallel isolation, in-session review, and conflict handling.
- Commits and pushes
In this repository44 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anthropic-multi-agent-research-system-skillSkill
- apply-selectionsSkill
- bootstrap-dogfood-projectSkill
- brainstormSkill
- branch-choiceSkill
- cc-adoption-scoutSkill
- claude-guardianSkill
- continueSkill
- end-sessionSkill
- executing-plansSkill
- five-advisorsSkill
- get-work-doneSkill
- 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
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 11 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
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
- could be automatic: a setting could enforce it
- Distinctive: line 83
Use when you want the work merged immediately rather than waiting for SessionEnd, AND you want a real code review (the unattended path is …
- Distinctive: line 97
Do NOT arm merge over a dissent.
- Very specific: line 98
Ensure committed + pushed: If the tree is dirty, let auto-git commit, or commit here.
- Distinctive: line 101
Accrue one honest calibration run (#196): After the review passes, run
- Distinctive: line 144
Only escalate (leave open, report for a human) a branch whose auto-PR is CI-RED (e.g.
- Distinctive: line 171
After it runs, report the disposition per branch.
- Very specific: line 181
Always run the code-reviewer-agent review in finish BEFORE arming auto-merge — the author is never the sole verifier.
- Very specific: line 182
Always base a new work worktree on the latest origin/main, in a SIBLING folder (never nested in the repo).
- Very specific: line 183
Always confirm a MERGED PR via gh before deleting any local branch (or that it has 0 commits ahead).
- Distinctive: line 185
Always treat the hooks as the SSOT for the unattended path — this skill complements, never duplicates, them.
- Distinctive: line 189
MUST NOT arm auto-merge over a reviewer dissent or failing CI — a stalled PR is safe.
- Distinctive: line 190
MUST NOT git branch -D a branch that has unmerged commits and no merged PR — PR it instead (let CI decide).
- Distinctive: line 191
MUST NOT bounce a mechanical land-or-delete decision to the human when an auto-PR + CI gate can decide it — that is the gap this skill …
- Distinctive: line 192
MUST NOT create a worktree inside the repo working tree — it pollutes status and git operations.
- Distinctive: line 193
MUST NOT push to or merge into main directly — everything lands via a PR + CI gate.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Git Branch Lifecycle — the control layer over autonomous git
Two layers run the branch lifecycle. Know which owns what before acting:
| Layer | Trigger | Does |
auto-git.sh hook | SessionStart + Stop (automatic) | commit + push each turn's work to a task branch; keep main clean; never stack onto a merged branch |
auto-pr.sh hook | SessionEnd (automatic) | open the PR, arm CI-gated auto-merge (squash), prune merged branches |
| this skill | you invoke it | parallel worktrees, in-session agent review before merge, conflict handling, manual finish/cleanup |
The hooks already make the unattended path work — you can close any session and the work lands when CI is green. Use this skill only when you want the judgment layer.
Command: $ARGUMENTS
STEP 0: Route on the sub-command
- starts with
status→ STEP 1 - starts with
work→ STEP 2 - starts with
finish→ STEP 3 - starts with
cleanup→ STEP 4 - empty / unknown → run STEP 1 (status) and show this command list.
STEP 1: status — show the live picture
echo "== current branch =="; git rev-parse --abbrev-ref HEAD
echo "== open PRs (head : state : auto-merge) =="
gh pr list --state open --json number,headRefName,autoMergeRequest \
--jq '.[] | "#\(.number) \(.headRefName) auto-merge:\(if .autoMergeRequest then "ARMED" else "off" end)"' 2>/dev/null
echo "== local branches with a gone (merged+deleted) upstream — prune candidates =="
git for-each-ref --format '%(refname:short) %(upstream:track)' refs/heads/ | awk '$2=="[gone]"{print $1}'
echo "== worktrees =="; git worktree listSummarize: which branch is active, which PRs are armed for auto-merge, what is prunable.
STEP 2: work <name> — isolated parallel workstream (own worktree)
Two sessions in the SAME folder share one HEAD and CANNOT be on different branches. For
TRUE parallel work, give each workstream its own worktree (a separate folder with its
own checked-out branch). This is the only real multi-session isolation.
NAME="$2" # the <name> argument
[ -z "$NAME" ] && { echo "usage: /git-branch-lifecycle work <name>"; exit 1; }
SLUG="$(echo "$NAME" | tr ' /' '--' | tr -cd '[:alnum:]-' | tr '[:upper:]' '[:lower:]')"
ROOT="$(git rev-parse --show-toplevel)"
git fetch origin main >/dev/null 2>&1 || true
WT="$ROOT/../$(basename "$ROOT")-wt-$SLUG" # sibling folder, never nested inside the repo
git worktree add -b "feat/$SLUG" "$WT" origin/main
echo "Worktree ready: $WT (branch feat/$SLUG, based on latest main)"
echo "Open a NEW Claude session in that folder to work on it in parallel."Tell the user the exact folder path and that the auto-git/auto-pr hooks operate per-worktree, so that workstream lands independently when its session closes.
STEP 3: finish [branch] — land it NOW, with an independent agent review first
Use when you want the work merged immediately rather than waiting for SessionEnd, AND you want a real code review (the unattended path is CI-gated only — a bash hook cannot dispatch a reviewer; this skill can).
- Resolve target.
BR="${2:-$(git rev-parse --abbrev-ref HEAD)}". Refuse ifmain/master. - Independent review (mandatory before arming merge). Dispatch
code-reviewer-agenton the branch diff vsmain:
PerAgent(code-reviewer-agent): "Review the diff of branch <BR> against main (`git diff main...<BR>`). Report blocking issues (correctness, security, scope creep, out-of-brief files) vs non-blocking. Return a structured verdict."independent-test-verification.md/supervisor-verification.md, the author is never the sole verifier. If the reviewer reports blocking issues → STOP, fix them, re-review. Do NOT arm merge over a dissent. - Ensure committed + pushed. If the tree is dirty, let auto-git commit, or commit here.
git push -u origin "HEAD:$BR".
<!-- DUAL-SYNC:HUB-ONLY -->Accrue one honest calibration run (#196). After the review passes, run
PYTHONPATH=. python scripts/record_task_run.py --stage reversible --reviewed — this is
the explicit per-task completion point for the trust-score walk-phase MVP: it auto-derives
real signals (tests, secret-scan, the reviewer signal from this very step) plus an honest
git-history human_had_to_fix proxy, and appends ONE shadow-mode run to the ATLAS ledger
(idempotent per branch, never lands anything). Broadening this hook to auto-pr.sh (the
unattended path) is a future option, not done here.
<!-- DUAL-SYNC:END -->- Open PR + arm auto-merge (idempotent — reuse existing PR):
gh pr view "$BR" >/dev/null 2>&1 || gh pr create --base main --head "$BR" --fill gh pr merge "$BR" --auto --squash
<!-- DUAL-SYNC:HUB-ONLY -->GitHub merges when the required CI checks (validate, test) pass, then deletes the branch.
Mark independent verification (for the merged-PR trust recorder). Since the review in step 2 already passed, append a machine-readable line to the PR body:
gh pr edit "$BR" --body "$(gh pr view "$BR" --json body --jq .body)"$'\n\nVerified-by: code-reviewer-agent'scripts/record_merged_prs.py (swept by auto-pr-reconcile.sh at SessionStart) scores
independent_verification=1.0 only on this kind of machine-readable evidence (a
Verified-by: body line or an APPROVED review) — without it, a merged PR honestly scores
0.0 on that signal even though a review actually happened.
<!-- DUAL-SYNC:END -->- Report the PR URL and that it is armed. Do not block waiting for CI.
STEP 4: cleanup — RECONCILE every branch (merged→prune, unmerged→land-or-escalate)
"Clean up" MUST leave zero dangling branches WITHOUT losing work AND without handing the
human a mechanical decision. So cleanup is a full reconcile, not just a prune. For EACH local
branch (skip main/master and the current branch), classify by commits ahead of main +
PR state, and act:
| Branch state | Action (autonomous) |
gh confirms a MERGED PR | git branch -D — content is on main, safe |
| 0 commits ahead of main | git branch -D — empty/stale, nothing to lose |
| Commits ahead, no PR / open PR | open a PR (idempotent) + arm --auto --squash → CI-green lands it automatically; CI-red leaves it open |
Only escalate (leave open, report for a human) a branch whose auto-PR is CI-RED (e.g. breaks a required gate) OR whose diff asserts a public/strategic surface (README positioning, a NEW governance rule). Even then, prefer opening the PR and letting the human veto via the open PR over blocking on a question — do NOT ask the human a land-or-delete question for content CI can adjudicate.
git fetch --prune >/dev/null 2>&1
cur="$(git rev-parse --abbrev-ref HEAD)"
for b in $(git for-each-ref --format '%(refname:short)' refs/heads/ | grep -vxE 'main|master'); do
[ "$b" = "$cur" ] && continue
state="$(gh pr view "$b" --json state --jq '.state' 2>/dev/null)"
if [ "$state" = "MERGED" ]; then
git branch -D "$b" && echo "PRUNED (merged): $b"; continue
fi
ahead="$(git rev-list --count origin/main..$b 2>/dev/null)"
if [ "${ahead:-0}" = "0" ]; then
git branch -D "$b" && echo "PRUNED (empty): $b"; continue
fi
git push -u origin "$b" >/dev/null 2>&1
gh pr view "$b" >/dev/null 2>&1 || gh pr create --base main --head "$b" --fill >/dev/null 2>&1
gh pr merge "$b" --auto --squash >/dev/null 2>&1 \
&& echo "PR'D + auto-merge armed: $b (lands on green CI)" \
|| echo "ESCALATE: $b — PR open but auto-merge could not arm (CI red / conflict); human decides"
doneAfter it runs, report the disposition per branch. The ONLY branches left for the human are CI-red or strategic ones — never a branch whose content CI could have adjudicated.
A branch is hard-deleted ONLY when gh confirms MERGED or it has zero commits ahead — never
guess. Unmerged work is never deleted; it is PR'd so CI (not a human, not a guess) decides.
MUST DO
- Always run the
code-reviewer-agentreview infinishBEFORE arming auto-merge — the author is never the sole verifier. - Always base a new
workworktree on the latestorigin/main, in a SIBLING folder (never nested in the repo). - Always confirm a MERGED PR via
ghbefore deleting any local branch (or that it has 0 commits ahead). - In
cleanup, always AUTO-PR an unmerged branch and let CI decide — never ask the human a land-or-delete question that CI can adjudicate. Escalate ONLY CI-red or genuinely-strategic (public/governance) branches, and prefer a veto-via-open-PR over a blocking question. - Always treat the hooks as the SSOT for the unattended path — this skill complements, never duplicates, them.
MUST NOT DO
- MUST NOT arm auto-merge over a reviewer dissent or failing CI — a stalled PR is safe; a wrong merge is not.
- MUST NOT
git branch -Da branch that has unmerged commits and no merged PR — PR it instead (let CI decide); only hard-delete on a confirmed MERGED PR or 0 commits ahead. - MUST NOT bounce a mechanical land-or-delete decision to the human when an auto-PR + CI gate can decide it — that is the gap this skill exists to close.
- MUST NOT create a worktree inside the repo working tree — it pollutes status and git operations.
- MUST NOT push to or merge into
maindirectly — everything lands via a PR + CI gate.
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.

