commit

Commit changes in atomic steps, then finalise and clean up the feature branch when requested.

Guardrails

• Require user confirmation before every commit.
• For every atomic commit proposal, provide a proposed title.
• Provide a proposed body before asking for approval.
• When asking for a single user decision, provide numbered short-reply options (for example: 1, 2, 3, 4).
• For bundled finalise decisions, use field+choice codes (for example: 1A, 2B, 3A) so users can reply in one line.
• Keep commits atomic; if a title needs "and", split the change set.
• Never mix unrelated files in one commit.
• Determine commit type from the actual diff intent, not from branch name, file paths, or habit.
• Never use chore for behaviour changes (flow, API/data semantics, bug fixes, or security fixes).
• If a change group contains multiple intents, split it before proposing.
• Examples: feat + fix, fix + chore.
• Never add AI attribution or Co-authored-by trailers unless the user explicitly asks.
• Do not push to remote without explicit user confirmation.
• In finalise mode, collect merge target, merge strategy, push choice, and local/remote branch deletion choices in one decision prompt.
• Treat explicit yes/no decisions from that prompt as confirmation; only ask follow-ups for missing or conflicting inputs.
• Do not assume main; it may be dev or another branch.
• Before final merge, sync with the target branch and resolve any conflicts.
• Use review as a quality gate before commit/finalise when needed.
• Capture context inline: update tasks/context.md during commit/finalise when durable info appears.
• Do not add a separate context-only step.
• Keep PRD checklist updates inside the atomic commit that completes that work.
• Never make a trailing commit only to catch up PRD checklist or context updates.
• In finalise, bundle tracking updates into one pre-merge commit.
• Include PRD archive and context updates as needed.
• If no tracking changes are needed, skip the finalise commit and state why.
• Use finalise tracking for closeout only.
• Do not retroactively log completed atomic work unless the user explicitly asks.
• Follow the merge strategy resolution order in references/finalise-policy.md.
• Never delete the base/default branch.
• Never delete the currently checked-out branch.
• Require explicit user confirmation before deleting local or remote branches.
• Do not claim tests passed or checks succeeded without actually running them; if you didn't run it, say so.

Commit Message Rules

Title format (required)

<emoji> <type>: <imperative summary>

• type must be one of: feat, fix, chore
• Summary must be short, specific, and imperative (e.g., "add", "fix", "remove", "refactor")
• Avoid vague summaries like "update code" or "fix stuff"

Finalise title (required)

For a finalise commit, require:

🧹 chore: finalise f-## <short-summary>

Keep the summary short and imperative.

Emoji mapping (default)

• feat → ✨
• fix → 🐛
• chore → 🧹

Use a different emoji only if it more precisely matches the change.

Type and body guidance (required)

Use the detailed rubric and templates in references/commit-rules.md for:

• selecting feat vs fix vs chore
• classifying mixed-intent diffs
• writing standard commit bodies
• writing finalise commit bodies

Read this reference before proposing the first commit in a session, and revisit it whenever classification is ambiguous.

Modes

• commit mode: propose and execute one atomic commit at a time.
• finalise mode: merge/close the completed branch and delete feature branches.
• hotfix mode: for urgent fixes committed directly to the default branch.
• Requires review approval and a tasks/context.md hotfix rationale update.

Workflow

1. Inspect current changes (git status --short, git diff, git diff --staged). Identify the active feature PRD when applicable.
2. Partition changes into atomic commit groups and map each group to:
   • PRD checklist/user-story items completed by that group (if any)
   • context-worthy outcomes produced by that group (if any)
3. For the next group, propose:
   • files/hunks included
   • type rationale (why this is feat / fix / chore, citing concrete diff intent)
   • PRD checklist lines to update in this same commit (or explicit none with reason)
   • context updates to include in this same commit (or explicit none with reason)
   • commit title (emoji + type + imperative summary)
   • commit body (Summary/Why/Context/Alternatives/Trade-offs/Consequences)
4. Ask for a decision (accept number or keyword):
   • 1 (yes): stage only that group and commit
   • 2 (edit): revise message/scope and ask again
   • 3 (skip): leave group uncommitted and move on
   • 4 (split): break the group into smaller commits and repropose
5. After each accepted commit:
   • commit immediately
   • report commit hash + title + short "what changed" summary
   • propose the next atomic group until done
6. During commit mode, ensure tracking is coupled to the atomic change:
   • include PRD checklist updates for completed stories in that same commit
   • include context updates only when durable rationale/gotchas emerge from that same commit
   • if no PRD/context updates are needed for a group, explicitly mark them as none with reason

Finalise Mode

Use after all intended commits are done.

1. Confirm preconditions:
   • working tree clean
   • on feature branch (not base)
2. Determine the feature PRD path to finalise:
   • prefer active feature PRD files in tasks/ matching the feature ID (tasks/f-##-*.md)
   • if multiple matches exist or feature ID is unclear, ask the user for the exact path
3. Before merge, prepare tracking updates:
   • if the PRD path matches tasks/f-##-<slug>.md, ensure tasks/archive/ exists
   • move the PRD to tasks/archive/f-##-<slug>.md (same filename); if already archived, skip
   • if tasks/context.md exists (or should exist), update it when durable state changed:
     • add completed milestone entry for the finalised feature
     • update "Current state" (next up / blockers) if it changed
     • capture any key decisions or gotchas discovered during completion
   • stage all resulting tracking changes together
   • propose exactly one 🧹 chore: finalise f-## ... commit (use short finalise body)
   • ask for user confirmation before committing (same 1/2/3 or yes/edit/skip options as commit mode)
   • if no tracking changes are needed, explicitly state why and skip the finalise commit
   • do not use this finalise commit to catch up missed atomic PRD/context updates
   • only do that if the user explicitly approves
4. Collect one finalise decision bundle before merge/cleanup:
   • ask once for: target branch, merge strategy, push-after-merge, delete-local-branch, delete-remote-branch
   • merge strategy choices: auto (policy-resolved), merge-commit, linear-history, squash, rebase
   • present options with field+choice codes:
     • 1A/1B/... for target branch choices, and include 1X for custom branch text
     • 2A=auto, 2B=merge-commit, 2C=linear-history, 2D=squash, 2E=rebase
     • 3A=yes push-after-merge, 3B=no push-after-merge
     • 4A=yes delete-local-branch, 4B=no delete-local-branch
     • 5A=yes delete-remote-branch, 5B=no delete-remote-branch
   • accept compact replies like 1B 2A 3A 4B 5B, plus keyword/freeform equivalents
   • if any field is missing or ambiguous, ask only for the missing field(s)
   • treat explicit yes/no values in this bundle as the required confirmations for push and branch deletion
5. Confirm finalise gate before merging:
   • require review: Good to commit: Yes; if missing, run review before merging
   • ensure the branch is synced with the target; if not, sync and rerun review
6. Resolve the merge strategy per references/finalise-policy.md.
   • if bundle strategy is auto, present the resolved strategy as a suggestion and let the user confirm or override
   • if bundle strategy is explicit, use it directly unless policy/safety checks require an override
7. Merge feature branch into the target branch using the confirmed strategy.
8. If push-after-merge is yes, push target branch to remote; if no, skip and state that remote update is pending.
9. Apply branch safety checks before deletion:
   • confirm <feature-branch> is not the target branch
   • confirm <feature-branch> is not the default branch
   • confirm current HEAD is not <feature-branch> when deleting it
10. Delete completed feature branch according to bundle confirmations:

• if delete-local-branch is yes: git branch -d <feature-branch>; otherwise skip
• if delete-remote-branch is yes: git push origin --delete <feature-branch>; otherwise skip

Hotfix Mode

Use for urgent fixes committed directly to the default branch without a feature branch.

1. Confirm on the default branch (not a feature branch).
2. Require review approval before committing.
3. Follow the standard atomic commit workflow (steps 1-6 above).
   • PRD checklist: mark as none — hotfixes typically have no PRD.
   • Type: use fix unless the change is purely non-behavioural (chore).
4. Record hotfix rationale in tasks/context.md (what broke, why the hotfix was necessary, follow-up actions).
5. No finalise step needed — already on the default branch.

Output

For each proposed commit, provide:

• atomic scope (files/hunks)
• short "what changed" summary
• type rationale (1-2 lines; evidence-based)
• proposed title
• proposed body
• explicit confirmation prompt (Commit this change now?)

After execution, provide:

• created commit hash/title
• short "what changed" summary
• remaining uncommitted groups
• finalise recommendation when all groups are complete
• PRD checklist sync status (updated or none with reason)
• context sync status (updated or skipped with reason)
• End with a short status block:
  • Files changed: list of created/updated files
  • Key decisions: any assumptions or choices made (if any)
  • Next step: recommended next skill or action