finishing-a-development-branch
Use after implementation and verification to present safe branch handoff choices without assuming merge, push, cleanup, or deletion authority.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 13
- Forks
- 4
01 前言 Front Matter
- name
- finishing-a-development-branch
- license
- MIT
- description
- Use after implementation and verification to present safe branch handoff choices without assuming merge, push, cleanup, or deletion authority.
02 资源文件 2
- 参考文档.hivemind-skill-source.json1.1 KB
- 许可证LICENSE1.0 KB
03 SKILL.md 正文
HivemindOS Integration
- This optional skill is a method library inside HivemindOS, not a global bootstrap or instruction override.
- HivemindOS packaged skills, the active Work Board loop contract, user instructions, and project rules remain authoritative.
- Upstream words such as MUST, always, or mandatory apply only after this skill is selected for a task where the method fits; they do not force ceremony onto small, clear, reversible work.
- Do not commit, push, merge, delete branches, create worktrees, launch subagents, or take outward actions unless the user request and active project policy authorize that exact action.
- Record evidence and gate outcomes in the HivemindOS task/loop receipts when the work runs from the Work Board.
- Present finish options without performing destructive cleanup, merge, push, or branch deletion unless explicitly authorized.
Upstream Method
Finishing a Development Branch
Overview
Guide completion of development work by presenting clear options and handling 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."
The Process
Step 1: Verify Tests
Before presenting options, verify tests pass:
# Run project's test suite
npm test / cargo test / pytest / go test ./...
If tests fail:
Tests failing (<N> failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.
Stop. Don't proceed to Step 2.
If tests pass: Continue to Step 2.
Step 2: Detect Environment
Determine workspace state before presenting options:
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)
This determines which menu to show and how cleanup works:
| State | Menu | Cleanup |
|---|---|---|
GIT_DIR == GIT_COMMON (normal repo) |
Standard 4 options | No worktree to clean up |
GIT_DIR != GIT_COMMON, named branch |
Standard 4 options | Provenance-based (see Step 6) |
GIT_DIR != GIT_COMMON, detached HEAD |
Reduced 3 options (no merge) | No cleanup (externally managed) |
Step 3: Determine Base Branch
# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
Or ask: "This branch split from main - is that correct?"
Step 4: Present Options
Normal repo and named-branch worktree — present exactly these 4 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)
4. Discard this work
Which option?
Detached HEAD — present exactly these 3 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)
3. Discard this work
Which option?
Don't add explanation - keep options concise.
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>
# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
Then: Cleanup worktree (Step 6), then delete branch:
git branch -d <feature-branch>
Option 2: Push and Create PR
# Push branch
git push -u origin <feature-branch>
Do NOT clean up worktree — user needs it alive to iterate on PR feedback.
Option 3: Keep As-Is
Report: "Keeping branch <name>. Worktree preserved at <path>."
Don't cleanup worktree.
Option 4: Discard
Confirm first:
This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
Type 'discard' to confirm.
Wait for exact confirmation.
If confirmed:
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
Then: Cleanup worktree (Step 6), then force-delete branch:
git branch -D <feature-branch>
Step 6: Cleanup Workspace
Only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree.
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, no worktree to clean up. Done.
If worktree path is under .worktrees/ or worktrees/: Superpowers created this worktree — we own cleanup.
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 # Self-healing: clean up any stale registrations
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.
Quick Reference
| Option | Merge | Push | Keep Worktree | Cleanup Branch |
|---|---|---|---|---|
| 1. Merge locally | yes | - | - | yes |
| 2. Create PR | - | yes | yes | - |
| 3. Keep as-is | - | - | yes | - |
| 4. Discard | - | - | - | yes (force) |
Common Mistakes
Skipping test verification
- Problem: Merge broken code, create failing PR
- Fix: Always verify tests before offering options
Open-ended questions
- Problem: "What should I do next?" is ambiguous
- Fix: Present exactly 4 structured options (or 3 for detached HEAD)
Cleaning up worktree for Option 2
- Problem: Remove worktree user needs for PR iteration
- Fix: Only cleanup for Options 1 and 4
Deleting branch before removing worktree
- Problem:
git branch -dfails because worktree still references the branch - Fix: Merge first, remove worktree, then delete branch
Running git worktree remove from inside the worktree
- Problem: Command fails silently when CWD is inside the worktree being removed
- Fix: Always
cdto main repo root beforegit worktree remove
Cleaning up harness-owned worktrees
- Problem: Removing a worktree the harness created causes phantom state
- Fix: Only clean up worktrees under
.worktrees/orworktrees/
No confirmation for discard
- Problem: Accidentally delete work
- Fix: Require typed "discard" confirmation
Red Flags
Never:
- Proceed with failing tests
- Merge without verifying tests on result
- Delete work without confirmation
- Force-push without explicit request
- Remove a worktree before confirming merge success
- Clean up worktrees you didn't create (provenance check)
- Run
git worktree removefrom inside the worktree
Always:
- Verify tests before offering options
- Detect environment before presenting menu
- Present exactly 4 options (or 3 for detached HEAD)
- Get typed confirmation for Option 4
- Clean up worktree for Options 1 & 4 only
cdto main repo root before worktree removal- Run
git worktree pruneafter removal
04 同仓库更多 Skills
tailscale-generation-skill-authoring
This skill should be used when the user asks to "create a Tailscale generation skill", "add a local generation skill", "document a generation endpoint", "add an image generation provider", "add a TTS provider", "add video generation", "add 3D generation", or needs guidance on where HivemindOS Tailscale or local generation providers belong in the shared skills shelf.
localtts
This skill should be used when the user asks to "generate local TTS", "use local text to speech", "use remote TTS over Tailscale", "make speech audio", "add a TTS provider", "use Qwen3-TTS", or needs TTS endpoint setup through local or HivemindOS Tailscale routes.
karpathy-guidelines
Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
comfyui-image-generation
This skill should be used when the user asks to "generate images", "generate images with ComfyUI", "use local ComfyUI", "use remote ComfyUI", "use Z-Image", "add an image generation provider", or needs image-generation endpoint setup through local or HivemindOS Tailscale routes.
wrangler
Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
workers-best-practices
Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.