You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
75 lines
4.9 KiB
75 lines
4.9 KiB
2 months ago
|
---
|
||
|
|
name: "finishing-a-development-branch"
|
||
|
|
description: "Decide how to integrate finished work once implementation is done and tests pass - verifies tests, detects the environment, determines the base branch, then presents structured options (merge, open a PR, keep the branch, or discard) and cleans up the workspace or worktree afterward. Triggers: I am done with this branch, wrap this up, merge this, should I open a PR, finish the feature, clean up the worktree, what do I do with this branch now."
|
||
|
|
---
|
||
|
|
|
||
|
|
Guide completion of development work by presenting clear options and handling the chosen workflow.
|
||
|
|
|
||
|
|
**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 1: Verify Tests
|
||
|
|
Run the project's test suite (npm test / cargo test / pytest / go test ./... as appropriate). If tests fail: report "Tests failing (<N> failures). Must fix before completing" with the failures shown, and stop — do not proceed to Step 2. If tests pass, continue.
|
||
|
|
|
||
|
|
## Step 2: Detect Environment
|
||
|
|
Determine workspace state:
|
||
|
|
```
|
||
|
|
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)
|
||
|
|
```
|
||
|
|
- `GIT_DIR == GIT_COMMON` (normal repo): standard 4 options, no worktree cleanup needed.
|
||
|
|
- `GIT_DIR != GIT_COMMON`, named branch (worktree): standard 4 options, provenance-based cleanup (Step 6).
|
||
|
|
- `GIT_DIR != GIT_COMMON`, detached HEAD: reduced 3 options (no merge), no cleanup (externally managed).
|
||
|
|
|
||
|
|
## Step 3: Determine Base Branch
|
||
|
|
Try `git merge-base HEAD main` or `git merge-base HEAD master`, or ask the user to confirm the base branch.
|
||
|
|
|
||
|
|
## Step 4: Present Options
|
||
|
|
Normal repo / named-branch worktree — present exactly these 4, no extra explanation:
|
||
|
|
```
|
||
|
|
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)
|
||
|
|
4. Discard this work
|
||
|
|
Which option?
|
||
|
|
```
|
||
|
|
Detached HEAD — present exactly these 3:
|
||
|
|
```
|
||
|
|
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)
|
||
|
|
3. Discard this work
|
||
|
|
Which option?
|
||
|
|
```
|
||
|
|
|
||
|
|
## Step 5: Execute Choice
|
||
|
|
**Merge locally:** cd to main repo root (`git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel`), checkout base branch, pull, merge feature branch, re-run tests on the merged result. Only after merge succeeds: cleanup worktree (Step 6), then `git branch -d <feature-branch>`.
|
||
|
|
**Push and create PR:** `git push -u origin <feature-branch>`. Do NOT clean up the worktree — the user needs it to iterate on PR feedback.
|
||
|
|
**Keep as-is:** report "Keeping branch <name>. Worktree preserved at <path>." Don't clean up.
|
||
|
|
**Discard:** require the user to type the exact word "discard" to confirm, after showing exactly what will be deleted (branch, commits, worktree). If confirmed: cd to main repo root, cleanup worktree (Step 6), then `git branch -D <feature-branch>` (force).
|
||
|
|
|
||
|
|
## Step 6: Cleanup Workspace (only for Merge and Discard)
|
||
|
|
```
|
||
|
|
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)
|
||
|
|
WORKTREE_PATH=$(git rev-parse --show-toplevel)
|
||
|
|
```
|
||
|
|
If `GIT_DIR == GIT_COMMON`: normal repo, nothing to clean up, done.
|
||
|
|
If the worktree path is under `.worktrees/` or `worktrees/`: you (this skill set) created it — clean it up:
|
||
|
|
```
|
||
|
|
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
|
||
|
|
cd "$MAIN_ROOT"
|
||
|
|
git worktree remove "$WORKTREE_PATH"
|
||
|
|
git worktree prune
|
||
|
|
```
|
||
|
|
Otherwise: the host/harness owns this workspace — do NOT remove it.
|
||
|
|
|
||
|
|
## Common Mistakes to Avoid
|
||
|
|
Skipping test verification before offering options. Open-ended questions instead of the exact structured menu. Cleaning up the worktree for Option 2 (PR) — user needs it alive. Deleting the branch before removing the worktree (fails because worktree still references it) — always merge first, remove worktree, then delete branch. Running `git worktree remove` from inside the worktree being removed — always cd to main repo root first. Cleaning up a harness-owned worktree — check provenance (`.worktrees/`/`worktrees/` path) first. Skipping typed confirmation for Discard.
|
||
|
|
|
||
|
|
## Red Flags
|
||
|
|
Never: proceed with failing tests, merge without verifying tests on the merged result, delete work without confirmation, force-push without explicit request, remove a worktree before confirming merge success, clean up worktrees you didn't create, run worktree remove from inside the worktree.
|
||
|
|
Always: verify tests before offering options, detect environment first, present exactly the right number of options, get typed confirmation for discard, clean up worktree only for merge/discard, cd to main root before removal, run worktree prune after removal.
|