git-branch

Branch lifecycle

When to use and when not to use

This skill is not intended to replace CodeGuard quality, platform protection, or deployment acceptance. It can be installed on its own; without the GitFlow plugin, use read-only Git observation and rule-by-rule verification. It does not depend on adjacent skill files or assume that the host automatically loads other skills.

Prerequisites and authorization

• Git is available and the project directory is clear. First confirm the real root of the parent repository and the project instructions, and preserve user modifications.
• Existing specifications take precedence; no Git, no specifications, detached, shallow history, and unknown origins need to be clearly reported.
• Read-only observation and preview may be executed; Git initialization, branch creation/switching, commits, pushes, integration, cleanup, Hook installation, and rule activation are executed within the user's existing authorization scope.
• Project rules and evidence is a self-contained reference for this skill;authoritative directory is used for model and source verification.

Execution steps

Step 1

First discover the repository and read the rules already in effect; record HEAD and uncommitted modifications, and do not create a feature branch first for unknown specifications.

Step 2

When creating, double-validate with git check-ref-format --branch and the project role pattern; reject dynamic previous-branch syntax such as @{-n}.

Step 3

Query the exact local source refs/heads and OID, and check the create_from role; do not use the common ancestor to infer past creation sources.

Step 4

List the creation/switching plan and execute it after obtaining the corresponding authorization; the plugin create does not automatically switch, and switching is a separate operation.

Step 5

Protect dirty state before switching; if modifications need to be carried over, use the recovery path, and do not automatically stash/drop. Query worktree list to avoid contending for other worktree branches.

Step 6

Renaming keeps the original role, rejects overwriting existing branches and renaming fixed protected roles; update provenance.

Step 7

Before cleanup, check that the real target fully contains the source branch, the merge direction, and current/worktree occupancy; do not force-delete unmerged history. reconcile only fills in long-lived fixed roles.

Standalone tool and plugin paths

First locate this skill's scripts/inspect_repository.py, and read the status according to the commands in contract . Python 3.11+ standard library, read-only and does not initialize. The actual command uses the current skill's directory; a mount example is:

python3 /mnt/skills/user/git-branch/scripts/inspect_repository.py /absolute/project

When the GitFlow plugin is available, call the command corresponding to its actual path; see operation examples. Do not treat a CLI name that is not installed as an existing command.

Verification and output

After execution, verify the old and new refs, current branch, HEAD, and origin records; do not fabricate main/develop pointers for empty history.

Output must distinguish: facts, rule sources, suggestions, user authorization, and unverified items. After write operations, check the current refs/HEAD/status; plans and previews are not completion evidence. Security boundaries: do not leak credentials, do not upload the worktree; do not expose credentials, entire worktree contents, or sensitive remote URLs in logs.

Positive example

classic feature/123-login is created from develop and records the source OID, then work begins after an explicit switch.

Negative example

A feature starts from main but passes just because the naming is correct; when cleaning up release, the unfinished develop back-merge is ignored.

Gotchas (situations prone to misjudgment)

• .git When it is a file, it may still be a valid work tree; query Git/common-dir first.
• Matching the branch pattern does not prove the source is correct; manually created but lacking records should be listed separately as unknown.
• Remote tracking and protection configuration text cannot prove that the live remote has implemented it.
• For a new project with empty history, do not pre-create false long-term refs; the initial commit must have a clear bootstrap plan.
• Before defining changes, re-review the active revision; passing quality checks does not exempt branch rules.
• Do not blindly replay steps that have already been completed just because of a timeout with no response; check Git status and operation logs first.

Exception Handling

Missing/drifted/corrupted rules, unclear identity, interrupted operations, or insufficient source evidence: stop the related write actions, report unverified and the specific information needed, and continue read-only work that can be completed independently. Clearly named/flow violations: deny and provide a conservative remediation direction. Git unavailable or network failure: do not auto-install, and do not treat failure as success. For conflicts, preserve the real state and handle according to recovery steps.

Optional Handoff

When other responsibilities are needed, invoke them by name; do not assume that skill is installed. For example, workflow selection can be handed off to git-workflow；Install: npx skills add full-stack-skills/git-skills --skill git-workflow. Any handoff must not expand the user's authorization.