Git Workflow

Git Workflow

Opinionated, safe Git operations that match this repository's conventions. Every action defaults to non-destructive. Destructive operations (force-push, reset --hard, branch -D) require explicit user confirmation.

Commit Style — This Repo

Recent history reveals the project uses Conventional Commits with optional scope:

<type>(<scope>): <summary> (#<issue-number>)

• Scope in parentheses when the change is localised to a subsystem (e.g. fix(cli):, fix(compaction):)
• Issue number appended at end when work closes a tracked issue
• Imperative present tense: "add", "fix", "remove" — not "added", "fixes"
• Max ~72 chars on the subject line

Workflows

1. Quick Commit (/commit)

When to use: Staged or unstaged changes ready to land on the current branch.

Steps:

1. Run git status and git diff HEAD to understand the full changeset
2. Run git log --oneline -10 to match commit message style
3. Draft a Conventional Commit message
4. Stage the relevant files (avoid .env, credentials, lock files unless intentional)
5. Commit via heredoc to preserve formatting

Safety checks:

• Never commit secrets (.env, *.pem, credentials.json)
• Never use --no-verify
• If hook fails → fix the issue, stage again, create a NEW commit (never amend)

2. Full Branch → PR (/commit-push-pr)

When to use: Feature or fix is complete and ready for review.

Steps:

1. Check current branch — if on main, create a feature branch first:

   git checkout -b <type>/<short-description>
   

2. Stage and commit (follow Workflow 1 rules)
3. Push with tracking:

   git push -u origin <branch>
   

4. Create PR via gh pr create:
   • Title: mirrors commit subject (≤70 chars)
   • Body: Summary (1-3 bullets) + Test plan checklist
   • Base branch: main

Requirements: gh CLI installed and authenticated (gh auth login)

3. Code Review a PR (/code-review <PR-number>)

Multi-agent deep review. Run on any open, non-draft PR.

Phase 1 — Eligibility (Haiku agent):

• Skip if: closed, draft, automated, already reviewed, or trivially simple

Phase 2 — Context gathering (Haiku agent):

• Fetch PR diff: gh pr diff <number>
• Collect relevant CLAUDE.md files from modified directories

Phase 3 — Summary (Haiku agent):

• Summarise the change in 2-3 sentences

Phase 4 — Parallel review (5 Sonnet agents):

Phase 5 — Confidence scoring (parallel Haiku per issue): Score 0–100. Filter out anything below 80.

Phase 6 — Post comment via gh pr comment:

### Code review

Found N issues:

1. <description> (CLAUDE.md says "...")
   <github.com/owner/repo/blob/<full-sha>/path/file.ext#L10-L15>

4. Branch Cleanup (/clean_gone)

Remove local branches whose remote tracking branch has been deleted.

Steps:

# Update remote refs
git fetch --prune

# List [gone] branches
git branch -v | grep '\[gone\]'

# For each [gone] branch:
# 1. Check for associated worktrees → git worktree list
# 2. Remove worktree first if present → git worktree remove --force <path>
# 3. Delete branch → git branch -D <branch>

Safety: Only deletes branches already removed from the remote. Never touches main.

5. Interactive Branch Management

Common patterns available on request:

6. Stash Operations

Safety Protocol (always enforced)

• Never force-push to main or master
• Never reset --hard without explicit user confirmation
• Never git clean -f without explicit user confirmation
• Never --no-verify (bypass hooks) — fix the hook instead
• Never amend a published commit; create a new one
• Never commit .env, secrets, or binary blobs unless user explicitly confirms
• Never auto-push; confirm push intent first unless running a /commit-push-pr workflow

Reference Files

• Conventional Commits spec
• PR template
• Branch naming conventions