finishing-a-development-branch

Name: finishing-a-development-branch
Author: obra

140kinstalls23kforks

How to install finishing-a-development-branch?

obra/superpowers/finishing-a-development-branch

$npx -y skills add obra/superpowers --skill finishing-a-development-branch

Installs into the current project.

Summary

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

Files · 1

View on GitHub

SKILL.md

1	# Finishing a Development Branch
2
3	## Overview
4
5	Guide completion of development work by presenting clear options and handling chosen workflow.
6
7	Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.
8
9	Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."
10
11	## The Process
12
13	### Step 1: Verify Tests
14
15	Before presenting options, verify tests pass:
16
17	```bash
18	# Run project's test suite
19	npm test / cargo test / pytest / go test ./...
20	```
21
22	If tests fail:
23	```
24	Tests failing (<N> failures). Must fix before completing:
25
26	[Show failures]
27
28	Cannot proceed with merge/PR until tests pass.
29	```
30
31	Stop. Don't proceed to Step 2.
32
33	If tests pass: Continue to Step 2.
34
35	### Step 2: Detect Environment
36
37	Determine workspace state before presenting options:
38
39	```bash
40	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
41	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
42	```
43
44	This determines which menu to show and how cleanup works:
45
46	\| State \| Menu \| Cleanup \|
47	\|-------\|------\|---------\|
48	\| `GIT_DIR == GIT_COMMON` (normal repo) \| Standard 4 options \| No worktree to clean up \|
49	\| `GIT_DIR != GIT_COMMON`, named branch \| Standard 4 options \| Provenance-based (see Step 6) \|
50	\| `GIT_DIR != GIT_COMMON`, detached HEAD \| Reduced 3 options (no merge) \| No cleanup (externally managed) \|
51
52	### Step 3: Determine Base Branch
53
54	```bash
55	# Try common base branches
56	git merge-base HEAD main 2>/dev/null \|\| git merge-base HEAD master 2>/dev/null
57	```
58
59	Or ask: "This branch split from main - is that correct?"
60
61	### Step 4: Present Options
62
63	Normal repo and named-branch worktree — present exactly these 4 options:
64
65	```
66	Implementation complete. What would you like to do?
67
68	1. Merge back to <base-branch> locally
69	2. Push and create a Pull Request
70	3. Keep the branch as-is (I'll handle it later)
71	4. Discard this work
72
73	Which option?
74	```
75
76	Detached HEAD — present exactly these 3 options:
77
78	```
79	Implementation complete. You're on a detached HEAD (externally managed workspace).
80
81	1. Push as new branch and create a Pull Request
82	2. Keep as-is (I'll handle it later)
83	3. Discard this work
84
85	Which option?
86	```
87
88	Don't add explanation - keep options concise.
89
90	### Step 5: Execute Choice
91
92	#### Option 1: Merge Locally
93
94	```bash
95	# Get main repo root for CWD safety
96	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
97	cd "$MAIN_ROOT"
98
99	# Merge first — verify success before removing anything
100	git checkout <base-branch>
101	git pull
102	git merge <feature-branch>
103
104	# Verify tests on merged result
105	<test command>
106
107	# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
108	```
109
110	Then: Cleanup worktree (Step 6), then delete branch:
111
112	```bash
113	git branch -d <feature-branch>
114	```
115
116	#### Option 2: Push and Create PR
117
118	```bash
119	# Push branch
120	git push -u origin <feature-branch>
121	```
122
123	Do NOT clean up worktree — user needs it alive to iterate on PR feedback.
124
125	#### Option 3: Keep As-Is
126
127	Report: "Keeping branch <name>. Worktree preserved at <path>."
128
129	Don't cleanup worktree.
130
131	#### Option 4: Discard
132
133	Confirm first:
134	```
135	This will permanently delete:
136	- Branch <name>
137	- All commits: <commit-list>
138	- Worktree at <path>
139
140	Type 'discard' to confirm.
141	```
142
143	Wait for exact confirmation.
144
145	If confirmed:
146	```bash
147	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
148	cd "$MAIN_ROOT"
149	```
150
151	Then: Cleanup worktree (Step 6), then force-delete branch:
152	```bash
153	git branch -D <feature-branch>
154	```
155
156	### Step 6: Cleanup Workspace
157
158	Only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree.
159
160	```bash
161	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
162	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
163	WORKTREE_PATH=$(git rev-parse --show-toplevel)
164	```
165
166	If `GIT_DIR == GIT_COMMON`: Normal repo, no worktree to clean up. Done.
167
168	If worktree path is under `.worktrees/` or `worktrees/`: Superpowers created this worktree — we own cleanup.
169
170	```bash
171	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
172	cd "$MAIN_ROOT"
173	git worktree remove "$WORKTREE_PATH"
174	git worktree prune # Self-healing: clean up any stale registrations
175	```
176
177	Otherwise: The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
178
179	## Quick Reference
180
181	\| Option \| Merge \| Push \| Keep Worktree \| Cleanup Branch \|
182	\|--------\|-------\|------\|---------------\|----------------\|
183	\| 1. Merge locally \| yes \| - \| - \| yes \|
184	\| 2. Create PR \| - \| yes \| yes \| - \|
185	\| 3. Keep as-is \| - \| - \| yes \| - \|
186	\| 4. Discard \| - \| - \| - \| yes (force) \|

People who liked this also viewed

6 picks

Type

finishing-a-development-branch

140kinstalls23kforks

View on GitHub

How to install finishing-a-development-branch?

obra/superpowers/finishing-a-development-branch

$npx -y skills add obra/superpowers --skill finishing-a-development-branch

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Finishing a Development Branch
2
3	## Overview
4
5	Guide completion of development work by presenting clear options and handling chosen workflow.
6
7	Core principle: Verify tests → Detect environment → Present options → Execute choice → Clean up.
8
9	Announce at start: "I'm using the finishing-a-development-branch skill to complete this work."
10
11	## The Process
12
13	### Step 1: Verify Tests
14
15	Before presenting options, verify tests pass:
16
17	```bash
18	# Run project's test suite
19	npm test / cargo test / pytest / go test ./...
20	```
21
22	If tests fail:
23	```
24	Tests failing (<N> failures). Must fix before completing:
25
26	[Show failures]
27
28	Cannot proceed with merge/PR until tests pass.
29	```
30
31	Stop. Don't proceed to Step 2.
32
33	If tests pass: Continue to Step 2.
34
35	### Step 2: Detect Environment
36
37	Determine workspace state before presenting options:
38
39	```bash
40	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
41	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
42	```
43
44	This determines which menu to show and how cleanup works:
45
46	\| State \| Menu \| Cleanup \|
47	\|-------\|------\|---------\|
48	\| `GIT_DIR == GIT_COMMON` (normal repo) \| Standard 4 options \| No worktree to clean up \|
49	\| `GIT_DIR != GIT_COMMON`, named branch \| Standard 4 options \| Provenance-based (see Step 6) \|
50	\| `GIT_DIR != GIT_COMMON`, detached HEAD \| Reduced 3 options (no merge) \| No cleanup (externally managed) \|
51
52	### Step 3: Determine Base Branch
53
54	```bash
55	# Try common base branches
56	git merge-base HEAD main 2>/dev/null \|\| git merge-base HEAD master 2>/dev/null
57	```
58
59	Or ask: "This branch split from main - is that correct?"
60
61	### Step 4: Present Options
62
63	Normal repo and named-branch worktree — present exactly these 4 options:
64
65	```
66	Implementation complete. What would you like to do?
67
68	1. Merge back to <base-branch> locally
69	2. Push and create a Pull Request
70	3. Keep the branch as-is (I'll handle it later)
71	4. Discard this work
72
73	Which option?
74	```
75
76	Detached HEAD — present exactly these 3 options:
77
78	```
79	Implementation complete. You're on a detached HEAD (externally managed workspace).
80
81	1. Push as new branch and create a Pull Request
82	2. Keep as-is (I'll handle it later)
83	3. Discard this work
84
85	Which option?
86	```
87
88	Don't add explanation - keep options concise.
89
90	### Step 5: Execute Choice
91
92	#### Option 1: Merge Locally
93
94	```bash
95	# Get main repo root for CWD safety
96	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
97	cd "$MAIN_ROOT"
98
99	# Merge first — verify success before removing anything
100	git checkout <base-branch>
101	git pull
102	git merge <feature-branch>
103
104	# Verify tests on merged result
105	<test command>
106
107	# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
108	```
109
110	Then: Cleanup worktree (Step 6), then delete branch:
111
112	```bash
113	git branch -d <feature-branch>
114	```
115
116	#### Option 2: Push and Create PR
117
118	```bash
119	# Push branch
120	git push -u origin <feature-branch>
121	```
122
123	Do NOT clean up worktree — user needs it alive to iterate on PR feedback.
124
125	#### Option 3: Keep As-Is
126
127	Report: "Keeping branch <name>. Worktree preserved at <path>."
128
129	Don't cleanup worktree.
130
131	#### Option 4: Discard
132
133	Confirm first:
134	```
135	This will permanently delete:
136	- Branch <name>
137	- All commits: <commit-list>
138	- Worktree at <path>
139
140	Type 'discard' to confirm.
141	```
142
143	Wait for exact confirmation.
144
145	If confirmed:
146	```bash
147	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
148	cd "$MAIN_ROOT"
149	```
150
151	Then: Cleanup worktree (Step 6), then force-delete branch:
152	```bash
153	git branch -D <feature-branch>
154	```
155
156	### Step 6: Cleanup Workspace
157
158	Only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree.
159
160	```bash
161	GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
162	GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
163	WORKTREE_PATH=$(git rev-parse --show-toplevel)
164	```
165
166	If `GIT_DIR == GIT_COMMON`: Normal repo, no worktree to clean up. Done.
167
168	If worktree path is under `.worktrees/` or `worktrees/`: Superpowers created this worktree — we own cleanup.
169
170	```bash
171	MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
172	cd "$MAIN_ROOT"
173	git worktree remove "$WORKTREE_PATH"
174	git worktree prune # Self-healing: clean up any stale registrations
175	```
176
177	Otherwise: The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
178
179	## Quick Reference
180
181	\| Option \| Merge \| Push \| Keep Worktree \| Cleanup Branch \|
182	\|--------\|-------\|------\|---------------\|----------------\|
183	\| 1. Merge locally \| yes \| - \| - \| yes \|
184	\| 2. Create PR \| - \| yes \| yes \| - \|
185	\| 3. Keep as-is \| - \| - \| yes \| - \|
186	\| 4. Discard \| - \| - \| - \| yes (force) \|

People who liked this also viewed

6 picks

Type