AGENT SKILL

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

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 -d fails 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 cd to main repo root before git worktree remove

Cleaning up harness-owned worktrees

  • Problem: Removing a worktree the harness created causes phantom state
  • Fix: Only clean up worktrees under .worktrees/ or worktrees/

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 remove from 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
  • cd to main repo root before worktree removal
  • Run git worktree prune after removal

04 同仓库更多 Skills

LiamVisionary
LiamVisionary/hivemindos

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.

★ 13
LiamVisionary
LiamVisionary/hivemindos

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.

★ 13
LiamVisionary
LiamVisionary/hivemindos

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.

★ 13
LiamVisionary
LiamVisionary/hivemindos

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.

★ 13
LiamVisionary
LiamVisionary/hivemindos

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.

★ 13
LiamVisionary
LiamVisionary/hivemindos

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.

★ 13