AGENT SKILL

finishing-a-development-branch

Use when the implementation is complete, all tests pass, and the work needs to be integrated.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 0
Forks
1

01 前言 Front Matter

name
finishing-a-development-branch
triggers
[ "user", "model" ]
description
Use when the implementation is complete, all tests pass, and the work needs to be integrated.

03 SKILL.md 正文

Finishing a Development Branch

Overview

Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.

Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."

Step 0: Pre-flight verification

Before declaring the branch ready, run a gates gate: re-read the spec, run the checklist, and confirm every acceptance criterion is met. Invoke execution first if you are unsure whether the final review should be deep or light.

Step 0.5: Converge - plan vs delivered

Spec drift is a documented failure mode: agents implement ~70-90% of a spec and the missing parts stay invisible. Before the options menu, diff the artifacts against the tree:

  1. Find the plan (.devin/plans/*.md named by the work) and the ledger (.devin/ledgers/<task>.md).
  2. If scripts/spec-consistency.py exists, run it on the plan — read the findings list; errors must be resolved or explained.
  3. Walk the plan's checkboxes against the diff (git diff <base>...HEAD, git log): every ticked task needs corresponding delivered code; delivered code with no task is drift.
  4. Ledger check: no ticked gate may carry EVIDENCE: pending.
  5. Outcome is binary:
    • Converged — plan, ledger, and tree agree. Say so with evidence.
    • Drift — do NOT silently absorb it. Append the residual items to the plan as open tasks (- [ ] Residual: <what is missing>) and report them in the completion summary. The user decides whether they block the merge.

Step 1: Verify Tests

Run the project's full test suite (npm test / cargo test / pytest / go test ./...).

If tests fail, report the failures and stop — the menu comes after a green suite:

Tests failing (<N> failures). Must fix before completing:

[Show failures]

If tests pass: continue to Step 2.

Step 2: Detect Environment

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
# Capture now, while still inside the workspace — Step 5 changes directory
# before cleanup (Step 6) needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)

This determines which menu to show and how cleanup works:

State Menu Cleanup
GIT_DIR == GIT_COMMON (normal repo) Standard 3 options No worktree to clean up
GIT_DIR != GIT_COMMON, named branch Standard 3 options Provenance-based (see Step 6)
GIT_DIR != GIT_COMMON, detached HEAD Reduced 2 options (no merge) Externally managed — leave in place

Step 3: Determine Base Branch

The base branch is whatever this work forked from — usually named in the plan, the conversation, or the branch's upstream. If it is not already known, ask: "This branch split from <your best guess> - is that correct?" Confirm before merging: merging into the wrong base is expensive to undo.

Step 4: Present Options

Normal repo and named-branch worktree — present exactly these 3 options:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)

Which option?

Detached HEAD — present exactly these 2 options:

Implementation complete. You're on a detached HEAD (externally managed workspace).

1. Push as new branch and create a Pull Request
2. Keep as-is (I'll handle it later)

Which option?

Present the menu exactly as written — concise, with every option coming from the list above. Discarding the work happens only in response to your human partner explicitly asking for it (see "If your human partner asks to discard the work" below). Wait for their answer; the integration decision is theirs.

Step 5: Execute Choice

Option 1: Merge Locally

# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Merge first — verify success before removing anything
git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
<test command>

If tests fail on the merged result: stop, leave the worktree and branch in place, and investigate — nothing has been pushed, so the merge is local and recoverable.

Once the merged result is green: clean up the worktree (Step 6), then delete the branch:

git branch -d <feature-branch>

Option 2: Push and Create PR

git push -u origin <feature-branch>
# From a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-branch>

Before creating the PR, run code-review on the diff.

Then create the pull/merge request against <base-branch> with the forge's tooling — its CLI if one is available, or the creation URL most forges print when you push — following the repo's PR template and conventions if present, and report the URL to your human partner.

Keep the worktree — your human partner iterates on PR feedback there.

Option 3: Keep As-Is

Report: "Keeping branch <name>. Worktree preserved at <path>."

If your human partner asks to discard the work

This path exists only as a response to an explicit request to throw the work away. Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for that exact confirmation. When it arrives:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

Then clean up the worktree (Step 6) and force-delete the branch:

git branch -D <feature-branch>

Step 6: Cleanup Workspace

  • If the work may continue in another session (Option 2 or 3), invoke handoff before cleanup to capture remaining context.

Runs for Option 1 and confirmed discards. Options 2 and 3 always preserve the worktree. Both callers have already changed directory to the main repo root — worktree removal must run from outside the worktree — and use the GIT_DIR/GIT_COMMON/WORKTREE_PATH values captured in Step 2, from before that directory change.

If GIT_DIR == GIT_COMMON: Normal repo, no worktree to clean up. Done.

If WORKTREE_PATH is under .worktrees/ or worktrees/: Devin created this worktree — we own cleanup:

git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

Otherwise: The host environment owns this workspace — leave it in place. If your platform provides a workspace-exit tool, use it.

Quick Reference

Option Merge Push Keep Worktree Cleanup Branch
1. Merge locally yes - - yes
2. Create PR - yes yes -
3. Keep as-is - - yes -
Discard (explicit request only) - - - yes (force)

Common Rationalizations

Excuse Reality
"Tests passed earlier this session" Run the suite on the tree you are about to integrate. A green run only proves the tree it ran on.
"They obviously want it merged" Integration is your human partner's decision. Present the menu and wait.
"They seem done with this feature — I'll offer to discard it" The menu is complete as written. Discard happens only when your human partner asks for it in so many words.
"'Yeah, get rid of it' counts as confirmation" Only the typed word discard authorizes deletion.
"The PR is up, so the worktree is clutter now" PR feedback gets fixed in that worktree. It stays until the work lands.
"This other worktree looks stale — I'll clean it too" Clean up only worktrees under .worktrees/ or worktrees/. Everything else belongs to the host.
"The merged-result failure is probably flaky" A failing merged result stops everything. Branch and worktree stay put while you investigate.
"The base branch is obviously main" Confirm the fork point or ask. Merging into the wrong base is expensive to undo.
"The push was rejected — force-push will fix it" A rejected push means the remote moved. Investigate; force-push only on your human partner's explicit request.

Cross-skills

  • adaptive-agenda-calendar-routine-engine - Stage 5 versioned delivery (commits, PRs, issue wiring) delegates here together with gh, git-workflows, pr, finishing-a-development-branch.

Cross-skills

  • Use git-github-adaptive-engineering to pick the integration flow (merge, PR, hotfix) and run the Fase Zero battery (scripts/phase-zero.py) before pushing or opening the PR - it owns gh pr create --body-file and the Closes #N/Refs: #N wiring; this skill owns the merge and cleanup steps.

04 同仓库更多 Skills

Leostruka
Leostruka/devin-bundle

montador-de-ideias

Use when assembling, expanding, or elevating a raw project idea or initial prompt into an ultra-detailed, first-principles dossier and compiled master prompt with journalistic OSINT market research, Tech Lead and Staff Architect justifications, atomic and modular hardening/optimization, and high-impact contact surfaces.

★ 0
Leostruka
Leostruka/devin-bundle

git-github-adaptive-engineering

Use when any task touches git history, GitHub issues/PRs/releases/CI, repo governance, or branch and merge decisions. Runs the Fase Zero situational-awareness battery, picks one of five delivery flows via the adaptive decision engine, and enforces commit/PR information-density standards. Orchestrates the gh, git-workflows, github-actions, pr, and debug/finish skills.

★ 0
Leostruka
Leostruka/devin-bundle

adaptive-agenda-calendar-routine-engine

Use when planning or executing work across hours, days, weeks, or sprints. Turns the calendar into a strict time-blocked agenda (HH:MM-HH:MM blocks carrying a routine profile, expected inputs, and a handoff output artifact), runs the 5-stage cognitive flow (Radar and Hunt -> Triage plus Steve Jobs conception -> workbench manifest -> >=32-cycle loop -> Close plus Open-Minded Scrum), and unfolds macro calendar milestones into micro agenda blocks through extensions/gcal/wrapper.py.

★ 0
Leostruka
Leostruka/devin-bundle

demo

Use when demonstrating a skill in a fixture project.

★ 0
Leostruka
Leostruka/devin-bundle

duplicate-skill

Use when testing duplicate skill name detection.

★ 0
Leostruka
Leostruka/devin-bundle

duplicate-skill

Use when testing duplicate skill name detection.

★ 0