skill-finish-branch

Host：Codex CLI — 此技能最初为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前激活的 Codex shell 和子 Agent 工具。在当前会话未提供相关能力之前，不要声称某个提供商、模型或 Host 子 Agent 可用。 有关 Host 工具的对应项，请参阅 skills/blocks/codex-host-adapter.md。

执行约定（强制 — 不可跳过）

此生成的 Codex 技能保留了源技能中强制执行的工作流约定。

禁止：

• 此技能要求执行所引用的工作流命令时，不要总结、模拟或跳过。
• 未检查实际文件或命令输出前，不要声称提供商输出或验证产物已存在。
• 必需的提供商、命令或 Host 功能不可用时，不要悄然继续；应报告不可用的依赖项，并使用受支持的替代方案。

完成开发分支

你的首行输出必须是： 🐙 **CLAUDE OCTOPUS ACTIVATED** - Branch Completion

概述

完整的发布流程：测试 → 多提供商审查 → 版本升级 → 更新变更日志 → 提交 → 推送 → PR。

核心原则： 验证测试 → 审查差异 → 升级版本 → 更新变更日志 → 提供选项 → 执行选择 → 清理。

流程

步骤 1：验证测试通过

首先，验证测试通过：

# Detect and run project's test suite
if [[ -f "package.json" ]]; then npm test
elif [[ -f "pytest.ini" ]] || [[ -f "pyproject.toml" ]]; then pytest
elif [[ -f "Cargo.toml" ]]; then cargo test
elif [[ -f "go.mod" ]]; then go test ./...
elif [[ -f "Makefile" ]] && grep -q '^test:' Makefile; then make test
fi

如果测试失败： 停止。显示失败信息。不要继续。

如果测试通过： 继续步骤 2。

步骤 2：多提供商差异审查

发布前，对更改进行快速的多提供商审查。 这能在问题到达 PR 审查者之前发现它们。

# Get the diff summary
DIFF_STAT=$(git diff --stat $(git merge-base HEAD main)..HEAD)
DIFF_FILES=$(git diff --name-only $(git merge-base HEAD main)..HEAD)

始终执行快速审查——这是自动步骤，不可跳过：

# Quick review via orchestrate.sh (uses available providers)
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh spawn reviewer "Review this diff for bugs, security issues, and code quality problems. Be concise — only flag real issues, not style preferences.

$(git diff $(git merge-base HEAD main)..HEAD | head -500)"

如果发现严重问题： 呈现问题，并询问是修复还是仍然发布。 如果没有问题： 继续步骤 3。简要显示 ✓ Review clean — no issues found。

步骤 3：确定基准分支和版本

# Identify the base branch
BASE_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
[[ -z "$BASE_BRANCH" ]] && BASE_BRANCH="main"

# Check for VERSION file
VERSION_FILE=""
for f in VERSION version.txt package.json; do
  [[ -f "$f" ]] && VERSION_FILE="$f" && break
done

步骤 4：升级版本和更新变更日志（可选）

如果存在 VERSION 文件或 package.json，则询问是否升级：

AskUserQuestion({
  questions: [{
    question: "Version bump?",
    header: "Version",
    multiSelect: false,
    options: [
      {label: "Patch (Recommended)", description: "Bug fixes, minor changes (1.2.3 → 1.2.4)"},
      {label: "Minor", description: "New features, backward compatible (1.2.3 → 1.3.0)"},
      {label: "Major", description: "Breaking changes (1.2.3 → 2.0.0)"},
      {label: "Skip", description: "Don't bump version"}
    ]
  }]
})

如果要升级： 更新版本文件，并在变更日志顶部添加一条概述差异的记录：

# Generate changelog entry from commits
COMMITS=$(git log --oneline $(git merge-base HEAD $BASE_BRANCH)..HEAD)
# Prepend to CHANGELOG.md if it exists

步骤 5：提供选项

只提供以下 4 个选项：

✅ Ship ready. Tests passing. Review clean. What would you like to do?

1. **Create PR** (Recommended) - Push and create a Pull Request for review
2. **Merge locally** - Merge back to <base-branch> on this machine
3. **Keep as-is** - Leave the branch, I'll handle it later
4. **Discard** - Delete this work permanently

Which option? (1-4)

选项应简洁。 除非用户询问，否则不要添加说明。

步骤 4：执行选择

选项 1：在本地合并

# Get current branch name
FEATURE_BRANCH=$(git branch --show-current)
BASE_BRANCH="main"  # or detected base

# Switch to base branch
git checkout $BASE_BRANCH

# Pull latest
git pull origin $BASE_BRANCH

# Merge feature branch
git merge $FEATURE_BRANCH

# Verify tests on merged result
npm test  # or appropriate test command

# If tests pass, delete feature branch
git branch -d $FEATURE_BRANCH

报告：

✅ Merged $FEATURE_BRANCH into $BASE_BRANCH
✅ Tests pass on merged result
✅ Feature branch deleted

Ready to push when you want: git push origin $BASE_BRANCH

选项 2：创建 PR

# Get branch info
FEATURE_BRANCH=$(git branch --show-current)

# Push branch
git push -u origin $FEATURE_BRANCH

# Create PR with a validated description file
REPO_SLUG=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
PR_TITLE=${PR_TITLE:?Complete PR_TITLE before creating the pull request}
CHANGE_SUMMARY=${CHANGE_SUMMARY:?Complete CHANGE_SUMMARY before creating the pull request}
CHANGE_REASON=${CHANGE_REASON:?Complete CHANGE_REASON before creating the pull request}
PR_BODY=$(cat <<EOF
## Summary
- ${CHANGE_SUMMARY}
- ${CHANGE_REASON}

## Test Plan
- [x] Unit tests pass
- [x] Manual verification done
- [ ] Code review needed
EOF
)
if ! "${CLAUDE_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}/scripts/safe-gh-comment.sh" \
    --repo "$REPO_SLUG" pr-create "$PR_TITLE" "$FEATURE_BRANCH" - <<< "$PR_BODY"; then
  echo "GitHub write state is unknown; check for an existing pull request before retrying:" >&2
  gh pr list --repo "$REPO_SLUG" --head "$FEATURE_BRANCH" --state all --json number,state,url || true
  return 1 2>/dev/null || exit 1
fi

报告：

✅ Branch pushed to origin/$FEATURE_BRANCH
✅ PR created: https://github.com/owner/repo/pull/123

Branch preserved for review process.

选项 3：保持原样

✅ Keeping branch $FEATURE_BRANCH as-is.

Current state:
- Branch: $FEATURE_BRANCH
- Commits ahead of $BASE_BRANCH: N
- Tests: Passing

When ready, you can:
- Merge: git checkout main && git merge $FEATURE_BRANCH
- PR: git push -u origin $FEATURE_BRANCH && gh pr create
- Discard: git branch -D $FEATURE_BRANCH

不要清理任何内容。

选项 4：丢弃

必须先确认：

⚠️ This will PERMANENTLY delete:
- Branch: $FEATURE_BRANCH
- All commits:
  - abc1234 feat: add user validation
  - def5678 fix: handle edge case
  - ghi9012 test: add integration tests

Type 'discard' to confirm, or anything else to cancel.

等待用户准确输入确认：discard

如果确认：

# Switch to base branch first
git checkout $BASE_BRANCH

# Force delete the feature branch
git branch -D $FEATURE_BRANCH

# If remote exists, delete it too (with confirmation)
git push origin --delete $FEATURE_BRANCH 2>/dev/null || true

报告：

✅ Branch $FEATURE_BRANCH deleted locally
✅ Remote branch deleted (if existed)

Work has been permanently discarded.

步骤 5：清理（使用工作树时）

对于选项 1、2、4： 检查当前是否位于工作树中，并进行清理：

# Check if current directory is a worktree
if git worktree list | grep -q "$(pwd)"; then
  # Get worktree path
  WORKTREE_PATH=$(pwd)
  
  # Switch to main worktree
  cd $(git worktree list | head -1 | awk '{print $(1)}')
  
  # Remove the worktree
  git worktree remove "$WORKTREE_PATH"
  
  echo "✅ Worktree cleaned up"
fi

对于选项 3： 保留工作树，不做改动。

快速参考

选项	合并	推送	保留分支	清理
1. 在本地合并	✓	-	删除	✓
2. 创建 PR	-	✓	保留	-
3. 保持原样	-	-	保留	-
4. 丢弃	-	-	删除	✓

与 Claude Octopus 集成

完成 octopus 工作流后，使用此技能：

# After tangle (develop) phase completes successfully
# After ink (deliver) phase validates the work

# User says: "I'm done, create a PR"
# → Invoke finishing-branch skill
# → Verify tests
# → Present options
# → Execute Option 2 (Create PR)

配合 Octopus 验证

# Run octopus validation before finishing
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Validate before merge"

# If validation passes, proceed with finishing-branch

危险操作——绝对不要做

操作	危险之处
未经测试就合并	会发布有问题的代码
丢弃前跳过确认	会永久丢失工作成果
未经询问就强制推送	会破坏历史记录
悄悄删除远程分支	会影响协作者
测试失败仍继续	会损坏主分支

常见错误

错误	修正方法
测试前就提供选项	始终先验证测试
未经询问就自动合并	提供 4 个选项，让用户选择
未经确认就删除	要求用户输入“discard”
选择“保持原样”时清理工作树	仅对选项 1、2、4 执行清理

The Bottom Line

Finishing branch → Tests verified AND user chose option
Otherwise → Not complete

Verify tests. Present options. Execute safely. Clean up appropriately.