Structure git work with atomic commits, conventional messages, short-lived branches, and pre-commit hygiene. Load when committing, branching, resolving merge conflicts, organizing parallel work, or reviewing git history. Also triggers on "git workflow", "commit message", "conventional commits", "atomic commit", "branch strategy", "git worktree", "how should I commit this". Does not replace project-specific hook policies — complements them.
Structure git work with atomic commits, conventional messages, short-lived branches, and pre-commit hygiene. Load when committing, branching, resolving merge conflicts, organizing parallel work, or reviewing git history. Also triggers on "git workflow", "commit message", "conventional commits", "atomic commit", "branch strategy", "git worktree", "how should I commit this". Does not replace project-specific hook policies — complements them.
You keep git history reviewable, reversible, and honest. Commits are save points; messages document intent.
Hard Rules
One logical change per commit — never mix feature + refactor + formatting.
Commit messages explain why, not only what the diff shows.
Never commit secrets — scan staged diff for password, secret, api_key, token patterns.
Never force-push to shared main/master without explicit user request.
Tests should pass before commit when the project has a test command.
Workflow
Step 1 — Review what's changing
Run git status and git diff (staged if committing). Confirm scope matches one logical change.
Step 2 — Pre-commit hygiene
Run project tests/lint if applicable. Reject staged secrets. Split if mixed concerns.
Step 3 — Write the message
<type>: <short imperative description>
<optional body — why, tradeoffs, links to spec/task>
If the user's environment allows commits, commit. Otherwise output the exact message for them to run.
Step 5 — Summarize for reviewers
Emit a short change summary (see Output Format).
Step 6 — Finish the branch (when the task is complete)
Verify tests are green before offering to finish. Present exactly these options: 1) merge locally, 2) push and open a PR, 3) keep the branch as-is, 4) discard. Destructive cleanup (branch delete, worktree removal) requires the user to explicitly confirm the discard choice — never delete on an inferred or unconfirmed "yes."
Parallel agents: prefer git worktree add over constant branch switching.
Incomplete features: feature flags on main beat month-long branches.
Gotchas
Squashing everything at the end destroys the slice narrative — commit incrementally.
Formatting-only commits mixed with behavior changes make review and bisect painful.
Missing .gitignore until .env lands in history.
git reset --hard on shared branches loses others' work — warn first.
Never delete a branch or worktree as part of "finishing up" without the user explicitly picking that option — an assumed cleanup can discard unmerged work.
Common Rationalizations
Excuse
Reality
"I'll commit when the feature is done"
One giant commit can't be reviewed or reverted safely.
"Message doesn't matter"
History is documentation for future you and agents.
"I'll squash later"
Prefer clean incremental commits from the start.
"Branches are overhead"
Short-lived branches isolate work; long-lived branches are the cost.
"Tests pass, I'll just clean up the branch"
Cleanup (merge/discard) is the user's call — present options, don't act unilaterally.
Output Format
## Git summary
Commits recommended:
-`<type>: <description>`
CHANGES:
- path: one-line what/why
NOT TOUCHED (intentional):
- path: reason out of scope
CONCERNS:
- [risk or question for human]
Examples
I'm done with the validation endpoint. Ready to commit.
Staged review: one logical change (POST /validate + tests).
Message:
```
feat: add skill validation endpoint
Exposes validate-skills checks for CI; refs task validate-api.
Run: `npm test` → pass, then commit.
</output>
</example>
</examples>
---
## Verification
- [ ] Commit message follows convention
- [ ] Scope is single logical change
- [ ] Handoff completed if user triggered via commit/push
- [ ] No secrets in committed files
## Red Flags
- All work squashed into one commit losing slice narrative
- Formatting-only changes mixed with behavior commits
- .env or secrets committed before gitignore exists
- Conventional commit type mismatches actual change nature
## Prune Log
Last pruned: 2026-07-09
- Added branch-finishing flow (merge/PR/keep/discard) with confirm-before-destroy gate (agent-loom Phase 4, obra/superpowers)
## Impact Report
Git workflow: [commit advised / committed / review-only]
Commits: N | Concerns flagged: N
