| name | finishing-a-development-branch |
| description | Use after all work on a feature branch is complete and verified. Pushes the branch and creates a PR targeting main. |
Finishing a Development Branch
Workflow position: Final step after all beads are closed and build-and-test passes. See BEADS_WORKFLOW.md.
Announce at start: "I'm using the finishing-a-development-branch skill to push and create a PR."
Prerequisites
Before invoking this skill, ensure:
- All beads for this work are closed
build-and-test passes- All changes are committed on the feature branch
Steps
1. Verify clean downstream state
bd where
git status
git log --oneline main..HEAD
- Working tree must be clean (no uncommitted changes)
- There must be commits ahead of main
bd where must succeed in the current checkout- If dirty, stop and ask the user to commit or stash
2. Push the branch
git push -u origin HEAD
If push fails (e.g., no remote, auth issues), report the error and stop.
3. Create a pull request
gh pr create --base main --fill
- Use
--fill to auto-populate title and body from commits
- If the user has provided a PR title or description, use
--title and --body instead
- Report the PR URL to the user
4. Report completion
PR created: <url>
Branch: <branch-name>
Hard Rules
- Never force-push unless the user explicitly asks
- Never delete the remote branch — let the PR merge process handle that
- Never merge locally — the PR is the merge mechanism
- If
gh is not available, push the branch and report the branch name for manual PR creation
Quick Reference
| Situation | Action |
|---|
| Uncommitted changes | Stop, ask user to commit |
| No commits ahead of main | Stop, nothing to PR |
| Push fails | Report error, stop |
gh not installed | Push branch, report for manual PR |
| PR creation fails | Report error, branch is pushed |
Beads Runtime Discipline
- Treat Beads as local runtime. Do not try to publish live
.beads state through Git during normal branch completion.
- Workflow scaffold files are committed to this repo's git and are pushed with the feature branch like any other tracked file.
- Plan files under
docs/plans/ are the exception: they are git-ignored local scratch, written fresh per bead and never committed or pushed — don't expect a plan to appear in the PR or reach another machine. To carry a plan across machines, inline it into the bead's notes (Dolt-synced).
- If
bd where fails, stop and repair the checkout with bd bootstrap --yes before pushing or creating a PR.
Integration
Called by:
executor-task / executor-task-worktree — after the bead is closed and committed- Any workflow that completes work on a feature branch
Pairs with:
build-and-test — must pass before invoking this skill
