finishing-a-development-branch

Overview

What this skill does

The finishing-a-development-branch skill helps you safely complete a Git development branch once the work is implemented and the test suite passes. It walks you through a clear, repeatable workflow so you can choose whether to merge locally, push and open a Pull Request, leave the branch for later, or discard it entirely.

The core principle of the skill is simple:

Verify tests → Determine base branch → Present options → Execute choice → Clean up

Instead of ad‑hoc Git commands or forgetting important checks, finishing-a-development-branch gives your agent a consistent checklist for the end of a feature or bugfix branch.

Who is finishing-a-development-branch for?

• Developers working with Git branches who want a structured “end of branch” routine
• Teams that require tests to pass before merging or opening a PR
• Users of the obra/superpowers skill set who want agents to manage Git workflows more safely
• Anyone who regularly asks “Is this branch ready to merge, and how should I integrate it?”

It fits especially well into repositories that already have automated tests and standard base branches such as main or master.

Problems this skill solves

• Forgetting to run tests before merging or opening a Pull Request
• Uncertainty about which branch a feature branch was created from
• Inconsistent decisions about whether to merge locally, use PRs, or discard work
• Leftover branches that clutter the repository because the finishing step was never clear

By enforcing a test-first check and then presenting a small set of explicit options, finishing-a-development-branch reduces mistakes and makes your Git workflow predictable.

When this skill is a good fit

Use finishing-a-development-branch when:

• A feature or fix is fully implemented
• All tests are expected to pass or you want to block integration on failing tests
• You are ready to decide how this branch should be integrated or whether it should be discarded

It is not a good fit when:

• You are still actively coding or experimenting on the branch
• The repository has no usable tests and you cannot run a meaningful test suite
• You need complex multi-branch release management beyond a straightforward feature → base branch workflow

If you primarily need help writing code or reviewing changes, consider pairing this skill with others focused on implementation or code review; finishing-a-development-branch is specifically about the final integration step.

How to Use

Installation and setup

1. Install the skill

Install finishing-a-development-branch from the obra/superpowers repository using the Skills CLI:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

This makes the skill available in your agent environment so it can apply the guided Git workflow to your current repository.

2. Confirm repository prerequisites

For the skill to behave as intended, your project should:

• Be a Git repository with a clear base branch (commonly main or master).
• Have a runnable test suite, typically via commands like:
  • npm test
  • cargo test
  • pytest
  • go test ./...

The exact command depends on your stack; the skill expects that some test command exists and can be executed before integration.

3. Announce skill usage

When you start the finishing process, the skill expects you (or your agent) to explicitly announce:

"I'm using the finishing-a-development-branch skill to complete this work."

This keeps the workflow transparent to collaborators and signals that the structured process is in effect.

Guided workflow steps

Step 1: Verify tests

Before any integration decisions are made, the skill runs or prompts you to run the project’s test suite. Typical commands include:

npm test
# or
cargo test
# or
pytest
# or
go test ./...

• If tests fail: the skill reports the number of failures, shows the failures, and stops the process. It will indicate that it cannot proceed with merge or PR until tests pass.
• If tests pass: the workflow continues to the next step.

This strict “tests first” gate helps prevent broken code from being merged or submitted in a Pull Request.

Step 2: Determine the base branch

Next, finishing-a-development-branch identifies which branch your development branch was created from, using Git commands such as:

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

If the base branch cannot be determined automatically, the skill will fall back to asking a clarifying question such as:

"This branch split from main - is that correct?"

Confirming the correct base branch matters because it determines where your work will be merged or what the Pull Request should target.

Step 3: Present integration options

Once tests pass and the base branch is known, the skill presents exactly four concise 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?

The options are deliberately short and direct, avoiding extra explanation so you can choose quickly.

Typical use cases:

• Option 1 – You want a fast local merge, often in smaller personal projects or when you are the only maintainer.
• Option 2 – You work in a team and need code review, CI, or approvals via a Git hosting platform such as GitHub.
• Option 3 – You are not ready to decide, but want confirmation that tests pass and the branch state is known.
• Option 4 – You were experimenting, or the approach is obsolete, and you want to remove the branch cleanly.

Step 4: Execute the chosen option

Based on your answer, the skill executes the corresponding Git actions and any related cleanup. While the underlying SKILL.md truncates some of the detailed commands, the intent is:

• For local merge: check out the base branch, merge the development branch, and optionally delete the finished branch if appropriate.
• For push + PR: push the branch to the remote and guide you to create a Pull Request targeting the identified base branch.
• For keep as-is: leave the current branch untouched and clearly note that you will handle integration later.
• For discard: safely discard or delete the branch after confirming that this is what you really want.

Throughout this step, the skill focuses on predictability and safety: not merging with failing tests, not merging into the wrong base branch, and avoiding accidental loss of work.

Practical usage tips

Integrate into your personal workflow

• Run finishing-a-development-branch whenever you believe a feature is “done”.
• Let the test gate be your final quality check before deciding on merge vs PR.
• Use Option 2 by default in team environments to ensure review and CI pipelines are triggered.

Use with team conventions

If your team has specific branching and review policies (e.g., always PR to develop first, or never delete branches automatically), align your use of the options with those rules. The skill’s structure makes those policies easier to follow consistently.

Combine with other superpowers skills

Within the obra/superpowers suite, finishing-a-development-branch is designed to complement skills that help with implementation, refactoring, or testing. Use those to evolve the branch, then call this skill when you are truly ready to integrate.

FAQ

When should I run the finishing-a-development-branch skill?

Run finishing-a-development-branch when your changes are implemented, you expect the tests to pass, and you are ready to decide how to integrate the branch (merge, PR, keep, or discard). It is meant as the final step in the branch’s lifecycle, not as a day‑to‑day development helper.

What happens if tests fail?

If the tests fail, the skill reports the failures and stops the process. It will not proceed to merging or creating a Pull Request. You are expected to fix the failing tests on the branch, re‑run them, and only then invoke finishing-a-development-branch again.

Can I use it without an automated test suite?

The skill is designed around a “verify tests first” principle. While you could conceptually adapt it to a project without tests, you would be bypassing one of its core safeguards. For best results, use it in repositories where you can run commands such as npm test, cargo test, pytest, or go test ./....

How does it decide which branch to merge into?

finishing-a-development-branch attempts to determine the base branch using Git’s merge-base against common branch names like main or master. If that is ambiguous, it will ask you to confirm what the base branch should be. This keeps merges and Pull Requests targeted at the correct branch.

Does it automatically create a Pull Request?

The skill’s documented behavior is to “push and create a Pull Request” when you choose Option 2. The exact mechanics depend on how your agent environment is configured with your Git hosting platform. At a minimum, it will push your branch and guide you to open a PR against the detected base branch.

Will it delete my branch automatically?

The SKILL description focuses on presenting options and executing the chosen workflow, including cleanup. The exact deletion behavior can depend on how your environment interprets the cleanup step. Treat Option 4 (discard this work) as potentially destructive and only choose it when you are sure you no longer need the branch.

Is finishing-a-development-branch suitable for complex release flows?

This skill targets straightforward feature or fix branches that merge back into a single base branch. If you manage multiple long‑lived release branches, hotfix flows, or intricate deployment pipelines, you may still use finishing-a-development-branch per branch, but you might need additional process or tools to cover the broader release strategy.

How do I install finishing-a-development-branch again?

Use the Skills CLI pointing at the obra/superpowers repository:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

After installation, follow the skill’s workflow: run tests, confirm the base branch, choose an option, and let the skill handle the integration and cleanup steps.