Structuring Git Workflow

Overview

Imposes branch discipline, commit structure, and safety checks at every git decision point. The skill acts as a gate: it does not execute commands, it asks the right questions before you do.

Violating the letter of these rules is violating the spirit of these rules.

When to Use

Starting new work?
  ├─ Yes → Create branch (Rule 1)
  └─ No → Continue

Module/feature complete?
  ├─ Yes → Remind about commit (Rule 2)
  └─ No → Continue

About to commit/push/merge/rebase?
  ├─ Yes → Run safety checklist (Rule 4)
  └─ No → Continue

Core Rules

Rule 1: Never Commit to Main/Master

All work happens on branches. When starting any task (feature, fix, refactor), create a branch first:

If you catch yourself about to commit on main/master, stop and create a branch. If work already started on main, stash it, create a branch, then unstash.

Rule 2: Remind About Commit at Module Boundaries

When a discrete unit of work is complete (a function, a component, a feature slice), proactively ask: "This module is complete. Commit it?"

Do not wait for the user to remember. The default answer is yes — most modules should be committed. If the user says no, respect it and move on.

Rule 3: Structured Commit Messages

Commit messages follow a consistent format. The default format is:

<type>: <description>

Types: feat, fix, refactor, style, docs, test, chore

• First line under 72 characters
• Use imperative mood ("add" not "added")
• If the project CLAUDE.md or CONTRIBUTING.md specifies a different convention, follow that instead

Rule 4: Safety Checklist Before Destructive Operations

Before reset --hard, rebase, force push, or branch -D:

1. Is this a shared branch? → Do not rewrite history
2. Do I have uncommitted changes? → Stash or commit first
3. Am I on the right branch? → git branch to verify
4. Is remote up to date? → git fetch first

State each check result explicitly before proceeding.

Rule 5: Push Is a Separate Decision

Commit and push are distinct steps. Commit accumulates locally. After commits are verified (tests pass, no regressions), ask: "Ready to push?"

Never push automatically after commit. Never force-push to shared branches. Use --force-with-lease on feature branches only.

Quick Reference

Common Mistakes

Edge Cases

Red Flags — STOP

• "This is too small for a branch" → Even one-line fixes go on a branch
• "I'll branch after I start" → Branch first, then work
• "Nobody else works on this repo" → Discipline is habit, not circumstance-dependent
• "The user seems in a hurry" → Urgency is when mistakes happen. Follow the rules
• "The user told me to skip the branch" → Push back once, then comply if they insist
• "It's just a config tweak" → Config changes can break things. Use a branch

All of these mean: Create the branch. Write the structured message. Run the checklist.