git-workflow

git-workflow: git lifecycle workflow / Git Lifecycle Workflow

This is a phased reference for the auriga workflow's git lifecycle requirements. Each phase explains what to do, the exact commands, and the constraints that must be followed. Hooks in the same plugin mechanically enforce some of these rules; this skill covers the parts that hooks cannot cover.

When to Use / When to Use

Create a branch for new work (any task that will produce code or content changes)
Determine whether to commit now or keep working
Write a commit message
Clean up branch history before opening a PR
Create a PR (Draft or Ready)
Handle review feedback after PR Ready

When NOT to Use / When NOT to Use

Ordinary shell operations unrelated to commit / branch / PR semantics (file operations, build commands, etc.)
When only inspecting git history for debugging; use directly git log / git bisect

Phase 1: Create branch (before changing code) / Phase 1: Branch creation

Do not commit directly to main. All work should be placed on a feature branch.
From origin/main current tip create the branch:

git fetch origin main --quiet
git switch -c <branch-name> origin/main

Parallel isolation: git worktree / Parallel isolation: git worktree

When multiple agents or tasks run in parallel, assign a separate worktree to each task. Always pass an explicit base ref (for example origin/main); if you do not pass one, the new branch will be cut from the current HEAD , and the current HEAD may already be on another feature branch:

git worktree add -b <branch-name> ../<task-dir> origin/main
git worktree list
git worktree remove ../<task-dir>

Phase 2: Commits during development / Phase 2: Commits during development

Atomic commit discipline / Atomic commit discipline

Each commit must:

Express one logical change
Be able to build and pass tests at that point in history
Not mix refactoring and feature work
Not mix changes from unrelated modules

Splitting example (one feature, four commits):

feat(auth): add RefreshToken domain model and repository interface
feat(auth): implement JWT refresh token issuance in AuthService
feat(auth): expose POST /auth/refresh endpoint
test(auth): add unit tests for refresh token rotation logic

Commit message format / Commit message format

<type>(<scope>): <summary>

<body: motivation, key design decisions, known limitations>

type Follows Conventional Commits; accepted types include:feat / fix / docs / refactor / chore / test / perf / style / build / ci / revert。pr-create-guard Uses the same list to check the PR title (see Phase 5)
scope Optional (anything non- ) characters can be inside the parentheses, for example feat(api): ... or fix(deep/scope): ...）
Optional before the colon ! indicates a breaking change:feat!: ... or feat(api)!: ...
The body is a natural-language paragraph; it explains why, not restating what (the diff already shows what)
Task ID (Jira / Linear) can be written in the body or the PR description

checkpoint commits / Checkpoint commits

Trigger by semantic units, not by time. When you finish something that can be described in one sentence, commit. If you cannot clearly say "this commit does X," keep going or split it.

Supplementary risk-driven trigger conditions: commit before high-risk operations so the previous state can be preserved, for example large-scale deletions, cross-module refactors, dependency upgrades, automated batch renames.

Mark checkpoint commits with a recognizable prefix (for example wip:), or use git commit --fixup=<hash>to make later squashes easier. The exact prefix does not matter; the key is that it can be recognized during the rebase pass.

What never to commit / What never to commit

API keys / tokens / passwords (use environment variables)
Build artifacts、node_modules、__pycache__
Local config（.env、*.local）
Large binaries (use Git LFS when necessary)

`commit-reminder` hook (mechanism reminder) / `commit-reminder` hook

When the uncommitted diff relative to HEAD exceeds 200 lines or 8 files, and at least 5 minutes have passed since the last reminder, thecommit-reminder hook injects a reminder message through additionalContext . It does not block execution. It is a safety net to prevent the working tree from getting out of control; but the boundary of each commit is still judged by the agent.

This hook triggers on Edit / Write / MultiEdit(Claude Code's file-edit tool_names) and apply_patch(Codex's standard file-edit tool_name), at the PostToolUse of

Phase 3: Pre-PR self-check, optional history cleanup / Phase 3: Pre-PR self-check, optional history cleanup

The goal is to make every commit on the PR atomic, independently revertable, and passing tests. Cleanup is a means, not an end; whether to squash depends on the current state and the repo's merge strategy.

git log --oneline main..HEAD

Current state	Action
Each commit is already atomic, messages are clear	Keep as is
Branch contains `wip:` / `--fixup` checkpoints	Use `git rebase -i --autosquash main` to fold them
The number of commits is appropriate, but one message is unclear	Use `git rebase -i main` and run `reword`
The repo merge strategy is squash-on-merge	Local cleanup has no extra benefit; keep as is

Interactive rebase verbs：

pick — keep
squash / s — fold into the previous commit and combine messages
fixup / f — fold into the previous commit and discard the current message
reword / r — only modify the message
drop / d — remove

Constraints:

Do not squash just for surface-level tidiness. Large projects (Linux kernel, Postgres) deliberately keep every atomic commit to support git bisect in locating problems.
Do not force-push a branch that has already been shared to the remote, unless the team has explicitly agreed.

Phase 4: PR creation / Phase 4: PR creation

PR description: five elements / PR description: five elements

The PR description must cover all five elements:

Scope — what was done, and why
Acceptance Criteria — product-level verifiable conditions
Design Decisions — why choose A over B; what trade-offs were considered
Risks — boundary conditions, known limitations, modules that may be affected
Remaining TODOs — follow-up items; when there are none, explicitly write None

Recommended body structure (keep ## heading level；pr-create-guard hook scans headings):

## Summary
<what was done + why (not a file list)>

## Acceptance Criteria
- [ ] verifiable item 1
- [ ] verifiable item 2

## Design Decisions
- Chose X over Y because ...
- Known trade-off: ...

## Risks
- Boundary conditions / known limits / modules potentially affected

## Test plan
- [ ] unit / integration tests
- [ ] manual / UI / browser verification: ...

## Remaining TODOs
- None | [ ] follow-up item

Why use this structure:

Acceptance Criteria and Test plan separated：Acceptance Criteria indicates "what must hold" (product perspective);Test plan indicates "how to confirm it holds" (execution checklist).
Design Decisions as its own section, do not stuff it into Risks. Agents tend to write "no risks identified" and skip alternatives; making it a standalone section forces both to be filled in.
Summary must include why, not just "edited a/b/c three files". The diff already shows the what.
Even an empty list must be written as None; a missing section will look like an omission in pr-create-guard 's heading scan.

Open as Draft / Open as Draft

Open the PR as a Draft as early as possible so scope alignment and incremental feedback become possible. Only mark it Ready after verification is complete and the body covers all five elements.

gh pr create --draft --title "<type>: <subject>" --body-file <body.md>

--draft is enforced by a mechanism:pr-ready-guard also runs on gh pr create 's PreToolUse ; when --draft is missing, it runs the Ready PR structural documentation checks, such as stray planning docs in the repo root and docs/specs/ unfinished active specs.--draft and the shorthand -d both skip this path; truthy values in the explicit --draft=<value> form (=1 / =t / =true, case-insensitive) are also skipped. Falsy values (=false / =0) are treated as creating a Ready PR and are blocked by the same structural documentation checks.gh pr ready additionally checks whether the current branch has unpushed commits; thegh pr create path does not perform this check.

Phase 5: Post-create reflection / Phase 5: Post-create reflection

pr-create-guard hook runs at gh pr create 's PostToolUse . It will:

via gh pr view --json body,title fetch the just-created PR body and title
list the ## headings it found, as well as the number of TODO checkboxes
check the title with the Conventional Commits format (<type>(<scope>)?(!)?: <subject>; the type list is the same as Phase 2); if the title does not match, it will inject a line Title format: ⚠ ...suggesting a fix using gh pr edit --title "<type>: ..." . This is only a soft reminder
remind you to confirm that all five elements are covered

It does not block. If a heading is missing or the title does not conform to Conventional Commits, fix it with gh pr edit --title "<type>: ..." and/or gh pr edit --body-file <new-body.md> .

Note: another guard (pr-ready-guard, see Phase 4) also runs at gh pr create 's PreToolUse , to, before the PR is created,blockstructural issues. Phase 5 only covers post-create informational reminders; the pre-create blocking logic belongs to Phase 4.

Phase 6: After PR Ready — tracking review feedback / Phase 6: After PR Ready — tracking review feedback

After the PR is marked Ready, all changes addressing review feedback (reviewer comments,deep-review findings, CI failures) should bein batchesreported back to the PR conversation, so reviewers know "this PR is ready for another look."

Batch status comment / Batch status comment

After completing a batch of fixes:

gh pr comment <pr-number-or-url> --body-file <status.md>

Recommended format:

Addressed N items in <sha-range>:

- ✅ <issue description> — fixed in <commit-sha>
- ✅ <issue description> — fixed in <commit-sha>
- ⏭️ <issue description> — deferred to follow-up: <issue link or rationale>
- ❌ <issue description> — won't fix: <rationale>

Three statuses:

fixed — completed; include the commit SHA
deferred — move to a follow-up PR or issue; must include a link or a clear reason
won't fix — state the reason clearly (out of scope / disagree with reviewer / false positive)

What NOT to do / What NOT to do

Do not reply to every review comment individually.Resolve conversation is the reviewer's action, not the author's work.
Do not use batch comment to replace commit-message rationale. Each fix commit's message still needs to clearly state its own why。

Update PR description / PR description updates

When a fix exposes new risks, new TODOs, or revised design trade-offs, update the PR description directly:

gh pr edit <pr> --body-file <updated-body.md>

The comment stream records "what we did"; the PR body remains the "current state" of this PR. Do not confuse the two.

Phase 7: Merge

Merge is the final gate.pr-merge-guard The hook triggers at gh pr merge of PreToolUse ; if the PR body's Acceptance Criteria or Test plan section still has unchecked - [ ] checklist items, it willblockthe merge.

Check the Acceptance Criteria and Test plan sections: the former is the outcome that must hold before merge, and the latter is the verification steps that should be completed before merge.Remaining TODOs Unchecked items in other sections do not block, because those sections may inherently record deferred work.
Checked items (- [x]) and ordinary non-task bullets (- ...) do not block.
If an item truly cannot be verified or completed before merge (for example, "confirm after the next release", "run automatically after CI integration"), then it is not a pre-merge gate item for this PR; before merge, move it to Remaining TODOs, and write it as an ordinary bullet.

The guard fails open: if gh cannot read the PR body, the merge will continue and will not be blocked just because the guard itself cannot check.