name	agileflow-commit-messages
description	Formats git commit messages following Conventional Commits and respects user's attribution preferences from CLAUDE.md. Loads when creating commits or discussing code changes to commit.
allowed-tools	Read, Bash

agileflow-commit-messages

ROLE & IDENTITY

Skill ID: COMMIT-MSG
Specialization: Git commit message formatting with Conventional Commits + attribution policy compliance
Part of the AgileFlow docs-as-code system

OBJECTIVE Format git commit messages following Conventional Commits specification while respecting user's Claude Code attribution preferences from CLAUDE.md. Ensure commits are clear, concise, and follow project conventions for type, scope, and footer formatting.

INPUTS

User request to commit changes
Files staged for commit (from git status)
Change descriptions or diff context
CLAUDE.md (optional) - Attribution policy

FIRST ACTION Deterministic boot sequence:

Check if CLAUDE.md exists: [ -f CLAUDE.md ] && echo "Found" || echo "Not found"
If found, read attribution policy: grep -A 20 "Git Commit Attribution Policy" CLAUDE.md
Scan git status: git status --short to understand scope of changes
Check for staged changes: git diff --cached --stat

PROACTIVE KNOWLEDGE LOADING Before generating commit message:

Read CLAUDE.md for attribution policy (CRITICAL - respect user preference)
Read .git/config for repo context (if available)
Scan staged files to determine commit type and scope
Check recent commit history: git log --oneline -5 to match style

Attribution Policy Detection:

IF grep -q "DO NOT ADD AI ATTRIBUTION" CLAUDE.md → No attribution
ELSE → Add default attribution footer

WORKFLOW

Analyze staged changes:
- Run git diff --cached --stat to see files
- Determine primary change type (feat, fix, refactor, etc.)
- Identify affected scope (api, ui, auth, db, config, etc.)
Check attribution policy (CRITICAL):
- Read CLAUDE.md for "Git Commit Attribution Policy"
- IF "DO NOT ADD AI ATTRIBUTION" found → skip footer
- ELSE → prepare attribution footer
Format commit message following Conventional Commits:
```
<type>(<scope>): <subject>

<body>

<footer>
```
- Type: feat, fix, docs, style, refactor, perf, test, chore, ci, revert
- Scope (optional): api, ui, auth, db, config, etc.
- Subject: Imperative mood, lowercase, <50 chars, no period
- Body (optional): Explain WHAT and WHY (not HOW), wrap at 72 chars
- Footer: Issue refs (Closes #123), breaking changes, attribution

Add attribution footer (if policy allows):

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Show commit message to user for approval (diff-first pattern)

Execute commit after YES confirmation:

git commit -m "$(cat <<'EOF'
<formatted message>
EOF
)"

RELATED COMMANDS

/AgileFlow:setup - Creates CLAUDE.md with attribution policy during setup
/AgileFlow:ai-code-review - Use before committing to verify quality
/AgileFlow:generate-changelog - Parses commit messages for changelog generation
/AgileFlow:status STORY=... STATUS=in-review - Update story status after commit

When to use slash commands:

After committing code changes → /AgileFlow:status to update story
After completing story → /AgileFlow:generate-changelog for release notes

OUTPUTS

Formatted commit message (shown to user for approval)
Git commit executed (if user says YES)
Commit SHA (from git output)

HANDOFFS AgileFlow Coordination (optional - if working within AgileFlow system):

DOES NOT update docs/09-agents/status.json directly (commit is atomic)
DOES NOT append to bus/log.jsonl (commits don't trigger coordination)
Story lifecycle: Commits typically happen during in-progress phase
After commit: Dev agent should update status.json to in-review if story complete

Security Note: NEVER commit secrets to git

Check for .env, credentials.json, tokens, API keys
Warn user if sensitive files are staged
Suggest adding to .gitignore instead

QUALITY CHECKLIST Before suggesting commit message:

Type is appropriate (feat/fix/refactor/docs/chore/etc.)
Subject is imperative mood ("add" not "added" or "adds")
Subject is lowercase, <50 chars, no period at end
Body explains WHY (not just WHAT), wrapped at 72 chars
Footer includes issue references if applicable (Closes #123)
Attribution policy checked in CLAUDE.md (CRITICAL)
No secrets in staged files (.env, tokens, credentials)
Breaking changes marked with ! and BREAKING CHANGE: footer

Conventional Commits Format

Types

feat: New feature
fix: Bug fix
docs: Documentation only changes
style: Code style (formatting, missing semicolons, whitespace)
refactor: Code refactor (neither fixes bug nor adds feature)
perf: Performance improvements
test: Adding/modifying tests
chore: Build process, dependencies, tooling
ci: CI/CD configuration changes
revert: Reverts a previous commit

Scope (Optional)

(api), (ui), (auth), (db), (config), etc.
Can be omitted if change affects multiple areas

Subject Rules

Imperative mood: "add feature" not "added feature" or "adds feature"
No capitalization of first letter
No period at the end
Max 50 characters
Clear and concise

Body (Optional but Recommended)

Explain WHAT changed and WHY (not HOW - code shows that)
Wrap at 72 characters per line
Separate from subject with blank line
Use bullet points for multiple changes

Footer (Optional)

Breaking changes: BREAKING CHANGE: description
Issue references: Closes #123, Fixes #456
Attribution: Add if CLAUDE.md allows (see attribution policy)

Attribution Examples

WITH attribution (default if no policy):

feat(auth): add two-factor authentication

Implemented TOTP-based 2FA with QR code generation
for enhanced user account security.

Closes #234

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

WITHOUT attribution (if CLAUDE.md says "DO NOT ADD AI ATTRIBUTION"):

feat(auth): add two-factor authentication

Implemented TOTP-based 2FA with QR code generation
for enhanced user account security.

Closes #234

Multi-File Commits

For commits affecting multiple files:

Choose the most significant type (feat > fix > refactor > chore)
Use scope that represents the feature/module
List key changes in body as bullet points

Example:

feat(user-profile): add profile editing and avatar upload

- Implemented profile form with validation
- Added avatar upload with image cropping
- Created API endpoints for profile updates
- Added unit tests for profile service

Closes #123, #124

Breaking Changes

When introducing breaking changes, use ! and BREAKING CHANGE::

feat(api)!: change authentication endpoint structure

BREAKING CHANGE: The /auth/login endpoint now returns a different
response format. Clients must update to handle the new structure.

Old: { token: "..." }
New: { accessToken: "...", refreshToken: "...", expiresIn: 3600 }

Migration guide: docs/migrations/auth-response-v2.md

Revert Commits

revert: feat(auth): add two-factor authentication

This reverts commit abc1234def5678.

Reason: 2FA implementation caused login failures for users with
certain browser configurations. Reverting to investigate and fix.

Integration with Other Skills

agileflow-changelog: Commit messages inform changelog entries
agileflow-story-writer: Reference story IDs in commits (Closes STORY-042)
agileflow-adr-writer: Link ADRs in footer (Refs: ADR-0005)

Notes

ALWAYS check CLAUDE.md first before formatting commit message
Respect user preferences - attribution is a sensitive topic
If unsure about type, ask the user
For large commits, suggest breaking into smaller logical commits
Include context in body - future developers will thank you
Keep line lengths: subject <50 chars, body <72 chars

agileflow-commit-messages

Install Skill

SKILL.md

agileflow-commit-messages

Conventional Commits Format

Types

Scope (Optional)

Subject Rules

Body (Optional but Recommended)

Footer (Optional)

Attribution Examples

Multi-File Commits

Breaking Changes

Revert Commits

Integration with Other Skills

Notes