aif-commit

name	aif-commit
description	Create conventional commit messages by analyzing staged changes. Generates semantic commit messages following the Conventional Commits specification. Use when user says "commit", "save changes", or "create commit".
argument-hint	[scope or context]
allowed-tools	Read Glob Bash(git *) AskUserQuestion Questions
disable-model-invocation	false

Conventional Commit Generator

Generate commit messages following the Conventional Commits specification.

Workflow

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, paths.rules_file, paths.roadmap, paths.rules, paths.plan, and paths.plans
• Language: language.ui for prompts and commit message conventions
• Workflow: workflow.plan_id_format for read-only active plan discovery (slug default; sequential uses numbered full-plan lookup)
• Git preference: git.enabled, git.create_branches, and git.skip_push_after_commit for active plan discovery and post-commit push behavior
• Rules hierarchy: rules.base plus any named rules.<area> entries

If config.yaml doesn't exist, use defaults:

• Paths: .ai-factory/ for context artifacts, .ai-factory/PLAN.md for paths.plan, .ai-factory/plans/ for paths.plans
• Language: en (English)
• Workflow: workflow.plan_id_format: slug
• Git: git.enabled: true, git.create_branches: true
• Git preference: skip_push_after_commit: false

Read .ai-factory/skill-context/aif-commit/SKILL.md — MANDATORY if the file exists.

This file contains project-specific rules accumulated by $aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
• When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
• Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient
• CRITICAL: skill-context rules apply to ALL outputs of this skill — including the commit message format and conventions. If a skill-context rule says "commits MUST follow format X" or "message MUST include Y" — you MUST comply. Generating a commit message that violates skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.

1. Analyze Changes

   • Run git status to see staged files
   • Run git diff --cached to see staged changes
   • If nothing staged, show warning and suggest staging

2. Resolve Active Plan Context (Read-Only, Optional)

   • Resolve active plan using this read-only priority:
     1. @<plan-file-or-directory> argument, when the argument starts with @
     2. branch-based full plan or ultra bundle in paths.plans
     3. single full plan in paths.plans, or a single ultra bundle there
     4. fast plan at paths.plan
   • If the argument does not start with @, keep treating it as commit scope/context.
   • Legacy @<plan-file> syntax remains valid; the broader form additionally accepts an ultra directory or its index.md.
   • For branch-based full plan lookup:
     • get current branch with git branch --show-current when git.enabled = true
     • replace every / with - to get <branch-stem>
     • when workflow.plan_id_format = sequential, use Glob for both paths.plans/[0-9][0-9][0-9][0-9]_<branch-stem>.md and paths.plans/[0-9][0-9][0-9][0-9]_<branch-stem>/index.md
     • Read every directory candidate and retain it only when index.md contains exactly one <!-- aif:plan-mode:ultra -->
     • use the highest-numbered valid artifact and emit WARN [aif-commit] when multiple valid candidates exist; if both shapes share the highest prefix, prefer ultra
     • if no valid sequential match exists, check paths.plans/<branch-stem>/index.md then paths.plans/<branch-stem>.md; Read the directory entrypoint before selection, ignore it unless it contains exactly one ultra marker, and warn and prefer ultra if both valid shapes exist
   • If git mode is off, branch lookup cannot resolve, or no branch-based plan exists, count root *.md full plans plus direct child */index.md entrypoints containing <!-- aif:plan-mode:ultra -->; exclude the resolved fast-plan path and do not count phase files.

Format

<type>(<scope>): <subject>

<body>

<footer>

Examples

Simple feature:

feat(auth): add password reset functionality

Bug fix with body:

fix(api): handle null response from payment gateway

The payment API can return null when the gateway times out.
Added null check and retry logic.

Fixes #123

Breaking change:

feat(api)!: change response format for user endpoint

BREAKING CHANGE: user endpoint now returns nested profile object

Behavior

When invoked:

1. Check for staged changes

2. Analyze the diff content

3. Resolve optional active plan context and use ## Commit Plan grouping when available

4. Run read-only context gates and summarize findings as WARN/ERROR

5. If commit type is feat/fix/perf and roadmap exists, check milestone linkage; if missing, warn and suggest adding linkage in commit body/footer

6. Propose a commit message

7. Confirm with the user before committing:

   AskUserQuestion: Proposed commit message:
   
   <type>(<scope>): <subject>
   
   Options:
   1. Commit as is
   2. Edit message
   3. Cancel
   

8. Handle user response:

   • Commit as is → proceed to step 9
   • Edit message → ask the user for the corrected message via AskUserQuestion, then return to step 7 with the new message
   • Cancel → stop, do NOT commit. End the workflow

9. Execute git commit with the confirmed message

10. Post-commit push handling:

• If git.skip_push_after_commit = true in resolved config:

  • Skip push prompt entirely
  • End workflow after successful local commit

• Otherwise (default behavior), offer to push:

  • Show branch/ahead status: git status -sb
  • If the branch has no upstream, use: git push -u origin <branch>
  • Otherwise: git push

  AskUserQuestion: Push to remote?
  
  Options:
  1. Push now
  2. Skip push
  

  • Push now → execute push command based on upstream status:
    • if branch has no upstream → git push -u origin <branch>
    • otherwise → git push
  • Skip push → end the workflow

If argument provided (e.g., $aif-commit auth):

• Use it as the scope
• Or as context for the commit message

Important

• Never commit secrets or credentials
• Review large diffs carefully before committing
• $aif-commit has no implicit strict mode — context gates are warning-first unless user explicitly requests blocking behavior
• Treat the resolved architecture, roadmap, RULES.md, description, and plan artifacts as read-only context in this command
• If no active plan resolves or the active plan has no ## Commit Plan, keep current staged-diff behavior unchanged.
• If staged changes contain unrelated work (e.g., a feature + a bugfix, or changes to independent modules), suggest splitting into separate commits:

  1. Show which files/hunks belong to which commit

  2. Confirm split plan with the user:

     AskUserQuestion: Split into separate commits?
     
     Options:
     1. Yes, split as suggested
     2. No, commit everything together
     3. Let me adjust the grouping
     

  3. Handle user response:

     • Yes, split as suggested → proceed to step 4
     • No, commit everything together → proceed to step 5 (propose single commit message)
     • Let me adjust the grouping → ask the user for the adjusted grouping via AskUserQuestion, then return to step 2 with the new plan

  4. Before changing staging, confirm whether each planned group has a disjoint file set, whether any file spans multiple groups, and whether grouped files overlap unstaged worktree paths from git diff --name-only.

  5. If every group has a disjoint file set and no grouped file appears in git diff --name-only, unstage all with git reset HEAD, then stage and commit each group separately using git add <files> + git commit.

  6. If grouped files overlap unstaged worktree paths, preserve each group's original cached patch before unstaging and re-apply only that patch with git apply --cached; otherwise use hunk-level staging or stop before changing staging.

  7. If one file spans multiple groups, use hunk-level staging for each group: stage only that group's hunks with git add -p or git apply --cached, commit, then repeat for the next group.

  8. If hunk-level staging or cached-patch application cannot be applied confidently, stop before changing staging and ask the user to adjust grouping or commit everything together.