完成开发分支
- 作者仓库星标 0
- 作者更新于 2026年8月12日 16:53
- 作者仓库 superpowers
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @obra · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:验证测试
运行项目的完整测试套件(`npm test` / `cargo test` / `pytest` / `go test ./...`)。如果测试失败,报告失败并停止 — 菜单出现在绿色套件之后: 如果测试通过:继续执行步骤 2。
第2步:检测环境
这决定了要显示的菜单以及清理的工作方式:状态·菜单·清理`GIT_DIR == GIT_COMMON`(正常存储库)·标准3个选项·没有要清理的工作树`GIT_DIR != GIT_COMMON`,命名分支·标准3个选项·基于来源(参见步骤6)`GIT_DIR != GIT_COMMON`,分离的HEAD·减少2个选项(无合并)·外部管理-保留在原处
第三步:确定基础分支
基础分支是该工作的分支——通常在计划、对话或分支的上游中命名。如果还不知道,请问:“这个分支是从<你的最佳猜测>中分离出来的 - 这是正确的吗?”合并前确认:合并到错误的碱基中,撤消代价高昂。
第四步:提出选项
普通存储库和命名分支工作树 — 准确地显示这 3 个选项: 分离的 HEAD — 准确地显示这 2 个选项: 准确地显示所写的菜单 — 简洁,每个选项都来自上面的列表。仅当您的人类合作伙伴明确要求时,才会放弃工作(请参阅“如果您的人类合作伙伴要求
第 6 步:清理工作区
运行选项 1 并确认弃牌。选项 2 和 3 始终保留工作树。两个调用者都已将目录更改为主存储库根目录 - 工作树删除必须从工作树外部运行 - 并使用步骤 2 中捕获的目录更改之前的 `GIT_DIR`/`GIT_COMMON`/`WORKTREE_PATH` 值。
# 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 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
```bash
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
```bash
# 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:
```bash
git branch -d <feature-branch>
```
### Option 2: Push and Create PR
```bash
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>
```
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:
```bash
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:
```bash
git branch -D <feature-branch>
```
## Step 6: Cleanup Workspace
**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/`:** Superpowers
created this worktree — we own cleanup:
```bash
git worktree remove "$WORKTREE_PATH"
git worktree prune # Self-healing: clean up any stale registrations
```
**If removal is refused** (`contains modified or untracked files`): the
worktree holds files that exist nowhere else — uncommitted plans, notes,
or scratch work. Never `--force` on your own initiative. Show your human
partner what is at stake and ask:
```bash
git -C "$WORKTREE_PATH" status --porcelain -uall
```
```
Worktree removal refused — these files were never committed:
<file list>
1. Commit them to <branch> before cleanup
2. Move them into <main repo root>
3. Delete them (unrecoverable)
Which?
```
Carry out the choice, then remove the worktree.
**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. |
| "Removal refused — `--force` is just finishing the cleanup" | The refusal means files exist only in that worktree. `--force` destroys them permanently. Show your human partner and ask. |
| "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. |
章节与文件索引
按说明文件中的顺序排列。
概述
第 1 步:验证测试
第2步:检测环境
第三步:确定基础分支
第四步:提出选项
文件/命令 -> npm test · cargo test · pytest · go test ./... · GIT_DIR == GIT_COMMON · GIT_DIR != GIT_COMMON · GIT_DIR · GIT_COMMON
内容校验值 -> cda5995c6a51
设计思路
finishing-a-development-branch是 superpowers 的「开发完成扫尾」skill——按一份精确的 4 选项菜单完成分支收尾,避免「合并到主分支后 CI 挂」「worktree 残留」「分支白白挂着」这类常见烂尾。作者把它做成 mechanical 的决策树,每一步都对应明确条件,不留发挥空间。4 选项(detached HEAD 时降到 3 选项)
关键纪律:
git branch -d在 worktree 还引用这个分支时会失败。cd回主仓再跑git worktree remove——在 worktree 内部跑会静默失败。git worktree prune自愈清理 stale 注册。Worktree 归属判断
只清理
.worktrees//worktrees//~/.config/superpowers/worktrees/这三种自创的 worktree。harness 创的(IDE / 平台拥有的)绝不动——会留下幻影状态。常见错误(按作者原文摘录)
branch -d失败。git worktree remove:静默失败——必须cd回主仓再跑。Red Flags(永远不做)
适合谁
不适合
配套
writing-plans(开始)→executing-plans(执行)→finishing-a-development-branch(收尾);多 worktree 时用using-git-worktrees协同。