Feature Branch Lifecycle

Keep feature assembly out of long-lived branches, and make promotion and cleanup explicit rather than assumed.

Read references/branching-rule.md, packaged with this skill, before you create the branch structure, open a promotion pull request, or delete anything. This file is the decision surface; that one is the procedure.

First, decide whether the model applies

This lifecycle is for repositories that already run a long-lived integration branch and a long-lived production branch. Before using it, resolve from the repository itself:

• the applicable CLAUDE.md and any release or contribution documentation
• the default branch, the current branch, and which branches are the integration and production branches
• remotes, open pull requests, branch protections, and worktrees
• active work that may still depend on a branch you would touch

Use the repository's real branch names. The examples here say staging and main because they are easy to read, not because they are correct anywhere.

If the repository has no such model, do not create one because this skill is installed. Follow the more specific repository workflow, or ask for a maintainer decision. Inventing a missing long-lived branch, renaming a permanent branch, or overriding an incompatible workflow is a maintainer's call, not yours.

The sequence, when it applies

development branches
        ↓
feature integration branch
        ↓
long-lived integration branch, for example staging
        ↓
long-lived production branch, for example main

Development branches are optional. When one feature integration branch implements the whole feature cleanly, use just that. The feature integration branch stays the promotion unit either way.

Before promoting, validate the whole feature

Run what the repository and the change actually warrant: build, lint, format, typecheck, static analysis, E2E tests of the combined flows, contracts, integrations, meaningful failures, and boundary cases, manual checks where they help, and a final review of the combined diff. Then confirm no required development work is still outstanding.

Retain E2E behavioral tests only. Every unit test created for the feature is temporary; before promotion, remove each one and its exclusive support code once passing E2E coverage carries its still-required assertions. Required repository gates stay, and existing non-E2E suites migrate only within authorized scope.

A passing subset is not evidence that the assembled feature works. Say what you ran and what it produced, and name anything you did not run.

Cleanup is gated, and the gates are not optional

Cleanup begins only after the promotion pull request has merged into the exact long-lived integration branch. Immediately before deleting any branch, verify every gate in the packaged reference: incorporation, required checks, no unique unpreserved work, no remaining dependency, no active worktree holding it, exact local and remote targets, and authority for each deletion.

A clean working tree, an old date, quiet activity, or a name that looks merged is not evidence.

When a gate fails or the deletion is not authorized, preserve the branch and report the exact blocker and the next action. Never force-delete, reset, sweep broadly, or rewrite history to get there.

This skill's boundary

The sequence tells you what order things must happen in. It grants no authority of its own. Creating remote branches, opening or merging pull requests, deleting local or remote branches, and promoting production each need the authority the task actually carries. A request to build or integrate a feature is not a request to release it.

Route these elsewhere

A branch is not a worktree, a branch is not a session, and a feature integration branch is not automatically a graph node. Keep the lifecycles separate.

What to report

• the resolved branch roles and their exact names
• each temporary branch, with its base and its permitted merge target
• the complete-feature validation you ran, and its results
• pull-request and merge state
• cleanup eligibility and the final disposition of every temporary branch
• any missing authority, failed gate, or live dependency that forced preservation