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

Inspect current changes (git status --short, git diff, git diff --staged). Identify the active feature PRD when applicable.
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)
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)
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
After each accepted commit:
- commit immediately
- report commit hash + title + short "what changed" summary
- propose the next atomic group until done
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.

Confirm preconditions:
- working tree clean
- on feature branch (not base)
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
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
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
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
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
Merge feature branch into the target branch using the confirmed strategy.
If push-after-merge is yes, push target branch to remote; if no, skip and state that remote update is pending.
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
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.

Confirm on the default branch (not a feature branch).
Require review approval before committing.
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).
Record hotfix rationale in tasks/context.md (what broke, why the hotfix was necessary, follow-up actions).
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