--- name: skill-finish-branch description: "Wrap up a branch — run tests, create PR, merge or discard — use when implementation is done" disable-model-invocation: true --- > **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex. > Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands. > Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. > For host tool equivalents, see `skills/blocks/codex-host-adapter.md`. ## Execution Contract (MANDATORY - CANNOT SKIP) This generated Codex skill preserves an enforced workflow contract from the source skill. **PROHIBITED:** - Do not summarize, simulate, or skip the referenced workflow command when this skill requires execution. - Do not claim provider output or validation artifacts exist without checking the actual files or command output. - Do not continue silently when a required provider, command, or host capability is unavailable; report the unavailable dependency and use a supported fallback. # Finishing a Development Branch **Your first output line MUST be:** `🐙 **CLAUDE OCTOPUS ACTIVATED** - Branch Completion` ## Overview Full ship pipeline: tests → multi-provider review → version bump → changelog → commit → push → PR. **Core principle:** Verify tests → Review diff → Bump version → Update changelog → Present options → Execute choice → Clean up. ## The Process ### Step 1: Verify Tests Pass **Before anything else, verify tests pass:** ```bash # 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 ``` **If tests fail:** STOP. Show failures. Do not proceed. **If tests pass:** Continue to Step 2. ### Step 2: Multi-Provider Diff Review **Run a quick multi-provider review of the changes before shipping.** This catches issues before they reach PR reviewers. ```bash # 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) ``` **Always run a quick review — this is automatic, not optional:** ```bash # 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)" ``` **If critical issues found:** Present them and ask whether to fix or ship anyway. **If clean:** Continue to Step 3. Show a brief `✓ Review clean — no issues found`. ### Step 3: Determine Base Branch & Version ```bash # 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 ``` ### Step 4: Version Bump & Changelog (Optional) **If a VERSION file or package.json exists**, offer to bump: ```javascript 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"} ] }] }) ``` **If bumping:** Update the version file and prepend a changelog entry summarizing the diff: ```bash # Generate changelog entry from commits COMMITS=$(git log --oneline $(git merge-base HEAD $BASE_BRANCH)..HEAD) # Prepend to CHANGELOG.md if it exists ``` ### Step 5: Present Options Present exactly these 4 options: ```markdown ✅ 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 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) ``` **Keep options concise.** Don't add explanations unless asked. ### Step 4: Execute Choice #### Option 1: Merge Locally ```bash # 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 ``` **Report:** ``` ✅ 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 ``` #### Option 2: Create PR ```bash # 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 <&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 ``` **Report:** ``` ✅ Branch pushed to origin/$FEATURE_BRANCH ✅ PR created: https://github.com/owner/repo/pull/123 Branch preserved for review process. ``` #### Option 3: Keep As-Is ``` ✅ 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 ``` **Do NOT clean up anything.** #### Option 4: Discard **Confirm first (REQUIRED):** ``` ⚠️ 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. ``` **Wait for exact confirmation: `discard`** If confirmed: ```bash # 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 ``` **Report:** ``` ✅ Branch $FEATURE_BRANCH deleted locally ✅ Remote branch deleted (if existed) Work has been permanently discarded. ``` ### Step 5: Cleanup (If Using Worktrees) **For Options 1, 2, 4:** Check if in a worktree and clean up: ```bash # 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 ``` **For Option 3:** Keep worktree intact. ## Quick Reference | Option | Merge | Push | Keep Branch | Cleanup | |--------|-------|------|-------------|---------| | 1. Merge locally | ✓ | - | Delete | ✓ | | 2. Create PR | - | ✓ | Keep | - | | 3. Keep as-is | - | - | Keep | - | | 4. Discard | - | - | Delete | ✓ | ## Integration with Claude Octopus After completing octopus workflows, use this skill: ```bash # 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) ``` ### With Octopus Validation ```bash # Run octopus validation before finishing ${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh ink "Validate before merge" # If validation passes, proceed with finishing-branch ``` ## Red Flags - Never Do | Action | Why It's Dangerous | |--------|-------------------| | Merge without testing | Ships broken code | | Skip confirmation for discard | Loses work permanently | | Force-push without asking | Destroys history | | Delete remote branch silently | Affects collaborators | | Proceed when tests fail | Corrupts main branch | ## Common Mistakes | Mistake | Fix | |---------|-----| | Offering options before testing | Always verify tests FIRST | | Auto-merging without asking | Present 4 options, let user choose | | Deleting without confirmation | Require typed "discard" | | Cleaning up worktree on "keep" | Only cleanup for options 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.**