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

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

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