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#

text

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:

Task typeBranch patternExampleFeaturefeature/<name>``feature/user-loginBug fixfix/<name>``fix/login-timeoutRefactorrefactor/<name>``refactor/auth-middleware

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:

text

<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#

TriggerActionStarting new workCreate feature/ or fix/ branch from mainModule completeRemind user about commitAbout to commitUse structured message formatAbout to pushVerify first, ask userForce push needed--force-with-lease on feature branches onlyDestructive operationRun 4-point safety checklistWork accidentally on mainStash → create branch → unstash

Common Mistakes#

MistakeFixCommitting directly to mainAlways create a branch firstCommit message "fix stuff"Describe the specific changePushing immediately after commitAccumulate, verify, then pushForce push without checkingRun safety checklist firstSkipping branch for "small fix"Small fixes go on fix/ branches tooAmend pushed commitsOnly amend local, unpushed commits

Edge Cases#

ScenarioHandlingUser insists on committing to mainPush back once: "This should go on a branch. Sure you want it on main?" If they confirm, comply.Project initialization (first commit)The initial commit (README, scaffold) is the only exception to Rule 1Collaborating on an existing branchNo need to create a new branch — commit to the existing feature/fix branchLocal repo, no remoteRules 1-3 still apply. Rules 4-5 (push safety) are dormant until a remote is addedUser's CLAUDE.md specifies different conventionFollow the project convention. This skill is the default, not an override

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.