agentleFS
jnsfhrmnnjnsfhrmnn/jf-agentic-coding-starter-kit/.claude/skills/finish-branch/SKILL.md

finish-branch

Skill1 starsChanged 4 months agoMITView on GitHub

Safely complete a feature, fix, or release branch after its work is verified. Use when productive work on a non-default Git branch is ready to be intentionally committed, pushed, reviewed, merged, and optionally cleaned up; when the user asks to finish, close, merge, publish, or wrap up a branch; or when a CSK skill exits with verified branch work. Handles dirty trees, detached HEAD, worktrees, base drift, checks, pull requests, partial failures, and task closure without force-pushing or silently deleting branches. Protected worker branches from .csk/worktrees.json are never deleted; they integrate through a real merge commit and are re-synced onto the new default branch instead.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 17 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 17

    Distinctive

    This author's own choices. Worth a look.

  • 2

    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
  1. Distinctive:

    When this skill starts, first give the user one or two plain-language sentences in the user's language explaining the step, for example: …

    line 12
  2. Distinctive:

    Stop before mutation when any of these applies:

    line 60
  3. Very specific:

    When using the GitHub CLI, verify that it resolves to the project origin (for example gh repo view --json nameWithOwner).

    line 81
  4. Distinctive:

    commit-only handoff when integration is intentionally deferred.

    line 94
  5. Distinctive:

    Do not rewrite published history.

    line 96
  6. Distinctive:

    Run the exact project-native format, lint, type, unit, integration, build, and acceptance checks required by architecture and feature scope.

    line 110
  7. Distinctive:

    If the target may have advanced, propose a fetch before claiming the branch is current.

    line 114
  8. Distinctive:

    Ask one consolidated approval for the exact commit, push, pull-request, and merge actions in scope.

    line 138
  9. Distinctive:

    Commit with the repository convention.

    line 146
  10. Distinctive:

    Create or reuse one pull request when that is the chosen strategy.

    line 150
  11. Distinctive:

    Wait for required checks with a bounded timeout: default 15 minutes, or the repository's documented CI budget when one exists.

    line 152
  12. Distinctive:

    Delete only explicitly approved branch targets and only after proving the integration contains the finished commit.

    line 159
  13. Distinctive:

    After every external step, inspect actual state before continuing.

    line 165
  14. Very specific:

    Verify: worktree still registered, local branch tip equals <remote>/<target>, remote ref exists with the same tip.

    line 184
  15. Distinctive:

    Commit fails: leave paths and index visible.

    line 195
  16. Distinctive:

    Pull request is closed but unmerged: do not delete branches or close the task.

    line 200
  17. Distinctive:

    Checks fail or time out: keep the branch open and route findings to the owning implementation/QA skill.

    line 202
  18. Distinctive:

    Merge conflict: leave a clearly reported operation state.

    line 205
  19. Distinctive:

    Do not close a task for commit-only or pushed-only work when merge/integration was its acceptance condition.

    line 228

“Common” is measured: kept by at least 6 in 10 of the 6 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

Finish Branch

Complete one Git branch with evidence and explicit action boundaries. Start read-only. Never equate "tests passed" with permission to commit, push, merge, open a pull request, tag, or delete a branch.

When this skill starts, first give the user one or two plain-language sentences in the user's language explaining the step, for example: "Wir schließen jetzt den Arbeits-Branch kontrolliert ab — committen, prüfen, zusammenführen — damit nichts Ungeprüftes auf dem Hauptstand landet."

Plain-language rule for the whole skill: every approval question and every stop is accompanied by one plain sentence in the user's language - what is about to happen (or what happened), why, and what happens if the user declines. Do not present raw Git states to a beginner without that sentence; docs/git-basics.md is the shared reference for the terms.

Entry contract

  • The repository onboarding gate passes.
  • Live Git state proves which branch and worktree own the requested changes.
  • The integration target is known or can be resolved unambiguously.
  • Product/feature work has passed the applicable implementation, review, and QA gates. If not, return to the owning skill instead of bypassing it.

This skill is the normal exit after verified work on a non-default branch. A CSK skill should recommend it automatically, but must not execute its mutations without authority.

Phase 1: Inspect without mutation

Read:

  1. git status --short --branch and git status --porcelain=v2;
  2. current branch or detached-HEAD state;
  3. staged, unstaged, and untracked paths plus git diff and git diff --cached;
  4. remotes and their URLs, upstream tracking, and the remote default branch;
  5. linked worktrees with git worktree list --porcelain;
  6. merge, rebase, cherry-pick, revert, bisect, or sequencer state;
  7. commits unique to the branch and its merge base with the proposed target;
  8. repository instructions, owning feature/task records, and required checks;
  9. protected-branch detection: the branch is protected when its name ends in -workbench (name-bound, works even before the config is committed or visible in this worktree) or when it appears in protectedBranches / belongs to a registered worker in .csk/worktrees.json where that file exists. Record the detection ("protected worker branch detected: <name>")
    • it changes the strategy (real merge commit required) and replaces cleanup with the re-sync path below.

Classify every changed path as in-scope, unrelated user work, generated output, secret/sensitive, or uncertain. Never stage unknown or unrelated paths.

Phase 2: Resolve blockers and strategy

Stop before mutation when any of these applies:

  • An unresolved Git operation is active. Continue or abort it only after showing the exact state and obtaining authority for that operation.
  • HEAD is detached. Identify the containing branch or propose a named rescue branch. Creating it requires approval; never commit new work while detached.
  • The current branch is the default branch. There is no branch to close; offer a scoped commit/publish workflow only if the user requests it.
  • Target branch is ambiguous, absent, or checked out in another worktree whose state has not been inspected.
  • In-scope and unrelated changes cannot be safely separated.
  • Secrets, credentials, oversized artifacts, conflict markers, or validation failures are present.
  • The feature/task status does not satisfy .claude/rules/workflow-state.md.

Resolve the default branch from origin/HEAD, repository configuration, or clear local convention. Ask when evidence conflicts. A remote named upstream is a template/source remote, never a publish target for project changes. If no safe origin exists, use a local integration strategy or explain that publication is unavailable.

When using the GitHub CLI, verify that it resolves to the project origin (for example gh repo view --json nameWithOwner). With an upstream remote present, gh may silently resolve to the template repository. Pin the target with --repo on every call or gh repo set-default before any pull-request action.

Choose and state one strategy:

  • existing repository pull-request workflow (preferred when configured);
  • push branch to origin, open/reuse a pull request, wait for required checks, then merge;
  • local integration into the target branch when no hosting workflow exists or the user explicitly chooses it;
  • commit-only handoff when integration is intentionally deferred.

Do not rewrite published history. Never force-push. Do not rebase, squash, fast-forward, or create a merge commit merely by preference; follow repository policy or ask the user when the choice materially affects history.

Protected worker branch: the merge method MUST be a real merge commit (--merge) - never squash or rebase. Only a merge commit keeps the branch tip an ancestor of the target, which makes the later re-sync a clean fast-forward and lets /pull-main-ff's merge-commit gate recognize the pull-request signature. If the user requested squash/rebase or repository policy forbids merge commits, stop and explain this constraint instead of silently switching methods.

Phase 3: Verify before proposing mutation

Run the exact project-native format, lint, type, unit, integration, build, and acceptance checks required by architecture and feature scope. Review the final diff and verify that generated artifacts and documentation are current.

If the target may have advanced, propose a fetch before claiming the branch is current. Fetch is a network action and requires authority. After current target state is available, determine ahead/behind/diverged and test the actual integration result where practical. Base drift, conflicts, timeouts, or failing checks block completion and remain durable through /csk-start if not resolved in the current session.

Phase 4: Obtain explicit action authority

Present a compact execution proposal containing:

  • branch and target;
  • exact paths to commit and proposed commit message;
  • verification evidence;
  • remote/PR/merge strategy;
  • whether local and remote cleanup are proposed (for a protected worker branch: state that no deletion is proposed and a re-sync follows instead).

Open the proposal with one plain-language sentence per proposed action so a user without Git knowledge can decide (for example: "Committen sichert den Stand lokal; Pushen lädt ihn zu deinem Projekt auf GitHub hoch; der Pull Request ist die kontrollierte Tür nach main."). Declining any action is safe and must be described as safe.

Ask one consolidated approval for the exact commit, push, pull-request, and merge actions in scope. Treat local-branch deletion and remote-branch deletion as two separate optional cleanup targets; neither is implied by merge approval. If the user authorizes only part, perform only that part and report the remaining state.

Phase 5: Execute incrementally and verify each boundary

  1. Stage only approved paths and reread the staged diff.
  2. Commit with the repository convention; capture the commit SHA.
  3. Rerun any checks whose result can change after formatting or generated output.
  4. Push only the named branch to the approved origin target; verify remote tracking and the pushed SHA.
  5. Create or reuse one pull request when that is the chosen strategy. Record its URL and actual state.
  6. Wait for required checks with a bounded timeout: default 15 minutes, or the repository's documented CI budget when one exists. On expiry, report the actual check state and stop; a timeout or unavailable check is not success.
  7. Merge only after required checks and review gates pass; verify the merge SHA is reachable from the target branch.
  8. For local integration, inspect the target worktree, update it safely, perform the approved merge strategy, rerun integration checks, and verify reachability.
  9. Delete only explicitly approved branch targets and only after proving the integration contains the finished commit. A protected worker branch is never a deletion target - not even on direct user request inside this skill run; removing that protection is a separate, informed decision (edit .csk/worktrees.json plus deliberate worktree teardown).

After every external step, inspect actual state before continuing. Do not assume that a successful command means the hosting service completed the operation.

Protected worker branch: re-sync instead of cleanup

For a protected branch, after the merge is verified on the target, replace every cleanup step with this re-sync so the next cycle starts clean (worktree and branch are permanent infrastructure):

  1. In the worker worktree: confirm git status --porcelain is clean; a dirty worker tree blocks the re-sync (report, never stash or reset).
  2. git fetch <remote> <target> and git merge --ff-only <remote>/<target>. Because the merge used a real merge commit, this MUST fast-forward. If it does not, stop and report the divergence - no force, no normal merge.
  3. Push the branch (a fast-forward push - no force). If the host auto-deleted the head branch after the merge ("automatically delete head branches"), this same push restores the remote ref; note it in the report and recommend disabling that host setting for repositories with worker branches (change it only with explicit user approval).
  4. Verify: worktree still registered, local branch tip equals <remote>/<target>, remote ref exists with the same tip.

Report the result as "protected branch integrated and re-synced (kept)". If any re-sync step fails, the state is "merged but re-sync incomplete" with the exact remaining command - the merge itself is safe. These steps are exactly what /pull-main-ff performs on a protected branch; recommending that skill for the recovery is equivalent.

Failure matrix

  • Commit fails: leave paths and index visible; do not push.
  • Push partially succeeds or tracking is unclear: query local/remote refs, report exact SHAs, and do not duplicate the push blindly.
  • Pull request creation fails: preserve the pushed branch and provide its recovery action; do not report a pull request URL unless verified.
  • Pull request is closed but unmerged: do not delete branches or close the task; ask whether to reopen, replace, or defer.
  • Checks fail or time out: keep the branch open and route findings to the owning implementation/QA skill.
  • Target advances: recompute merge base and rerun affected checks.
  • Merge conflict: leave a clearly reported operation state; resolve or abort only with authority, never guess conflict intent.
  • Merge succeeds but cleanup fails: report integration as complete and cleanup as incomplete; never retry destructive deletion broadly.
  • Protected-branch re-sync fails: report the merge as safe and the re-sync as incomplete with the exact remaining command; never fall back to deleting or force-updating the protected branch.
  • Multiple worktrees: operate in the worktree that owns each checked-out branch; never delete a branch still checked out anywhere.
  • Network or host unavailable: preserve a commit-only handoff and one durable recovery task when authorized.

Close state with evidence

After integration, verify:

  • working trees involved are understood and no user changes were lost;
  • the finished commit is reachable from the target;
  • remote branch, pull request, checks, and cleanup match the approved strategy;
  • feature/index state remains consistent;
  • any owning task can be closed with typed evidence such as commit:<sha> or url:<pull-request> through /csk-start.

Do not close a task for commit-only or pushed-only work when merge/integration was its acceptance condition. Persist any incomplete step as one durable task with the exact next action and blocker.

Completion report

Report branch, target, committed SHA, pushed SHA, pull-request URL/state, check result, integration SHA, local/remote cleanup state (or the protected-branch re-sync state), task/feature bookkeeping, and any remaining risk. Use not requested, not applicable, or incomplete instead of implying an action happened. Close with one plain-language sentence stating what is now true (for example: "Deine Arbeit liegt jetzt nachweislich auf main; der Arbeits-Branch wurde aufgeräumt / bleibt als Dauer-Branch bestehen.").

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.