Git Workflow and Versioning
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>
Types: feat | fix | refactor | test | docs | chore
Step 4 — Commit or advise the user
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."
Branching defaults
- Trunk-based: keep default branch deployable; merge feature branches within 1–3 days.
- Naming:
feature/<slug>, fix/<slug>, chore/<slug>, refactor/<slug>
- 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
<examples>
<example>
<input>I'm done with the validation endpoint. Ready to commit.</input>
<output>
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