| name | conventional-commits |
| description | Git commit management following Conventional Commits specification for Aurora projects. Trigger: When creating commits, analyzing git history, or reviewing commit messages.
|
| license | MIT |
| metadata | {"author":"aurora","version":"1.0","auto_invoke":"Creating commits, git operations, analyzing commit history"} |
When to Use
- User asks to create a commit or "commit changes"
- User asks to review git status or diff
- User wants to analyze commit history
- After completing features/fixes that need to be committed
- User mentions "conventional commits" or asks about commit format
Critical Patterns
Commit Format
<type>(<scope>): <subject>
[optional body]
[optional footer]
Types (in order of usage frequency)
| Type | Description | Example |
|---|
feat | New functionality | feat(library/book): add ISBN validation |
fix | Bug fix | fix(auth): resolve token refresh race condition |
refactor | Code refactoring, no functional change | refactor(core): extract validation logic to service |
test | Add or modify tests | test(book): add unit tests for create handler |
docs | Documentation changes | docs(readme): add installation instructions |
chore | Maintenance tasks | chore(deps): update nestjs to v10 |
style | Formatting, semicolons, etc. | style(api): apply prettier formatting |
perf | Performance improvements | perf(query): optimize book search with index |
ci | CI/CD changes | ci(github): add deployment workflow |
build | Build system or dependencies | build(docker): optimize production image |
revert | Revert previous commit | revert: feat(book): add ISBN validation |
Length Limits (from commitlint.config.js)
| Rule | Limit | What it covers |
|---|
header-max-length | 100 chars | Entire first line: type(scope): subject |
body-max-line-length | 100 chars | Each line in the body |
CRITICAL: The header is the ENTIRE first line including type, scope, colon, and subject.
With a long scope like resource-planning/allocation, the subject has fewer available characters.
Always count the full header length.
Subject Rules
- ✅ Use imperative mood: "add" NOT "added" or "adds"
- ✅ Lowercase first letter
- ✅ No period at the end
- ✅ Keep header under 100 characters total
- ✅ Describe WHAT, not HOW
Good:
feat(book): add publication date validationfix(auth): resolve token refresh issue
Bad:
feat(book): Added publication date validation (past tense)fix(auth): Resolve token refresh issue (uppercase)feat(book): add publication date validation. (period)
Body Rules (Optional)
- Separate from subject with blank line
- Explain WHY, not WHAT
- Wrap at 100 characters per line (matches
body-max-line-length)
- Can use bullet points with
-
Footer Rules (Optional)
- Reference issues:
Closes #123, Fixes #456
- Breaking changes:
BREAKING CHANGE: <description>
- ❌ NEVER add "Co-Authored-By" or AI attribution
Commit Workflow
1. Analyze Changes
git status
git diff
git diff --staged
git log --oneline -10
2. Group Related Changes
Rules:
- One commit = one logical change
- ❌ Don't mix features with fixes
- ❌ Don't mix multiple unrelated modules
- ✅ Multiple files are OK if they implement one feature
3. Generate Message
Analyze the changes and determine:
- Type: feat, fix, refactor, etc.
- Scope: Which module/component is affected?
- Subject: What does this change do?
- Body (if needed): Why was this change necessary?
- Footer (if needed): Issue references, breaking changes
4. Execute Commit
git add <files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>
<body>
<footer>
EOF
)"
Code Examples
Simple Feature
feat(library/book): add publication date validation
Validate that publication date is not in the future
when creating or updating a book.
Closes #234
Bug Fix with Context
fix(auth): resolve token refresh race condition
Multiple simultaneous requests could trigger parallel
token refreshes, causing some requests to fail.
- Add mutex lock during refresh
- Queue pending requests until refresh completes
- Add retry logic for failed requests
Fixes #567
Refactor (No Functional Change)
refactor(library/book): extract ISBN validation to service
Move ISBN validation logic from command handler to
dedicated IsbnValidatorService for reusability.
No functional changes.
Breaking Change
feat(api)!: change pagination response format
BREAKING CHANGE: Pagination response now uses cursor-based
format instead of offset-based.
Before: { items: [], total: 100, page: 1 }
After: { items: [], nextCursor: "abc", hasMore: true }
Migration guide in docs/migration/v2-pagination.md
Aurora YAML Changes
feat(aurora): add category entity to library module
Define new Category aggregate with:
- id, name, description fields
- many-to-many relation with Book
Run: aurora load back module -n=library/category
Dependency Update
chore(deps): update @nestjs packages to v10.2.0
- @nestjs/core: 10.1.0 -> 10.2.0
- @nestjs/common: 10.1.0 -> 10.2.0
- @nestjs/platform-express: 10.1.0 -> 10.2.0
No breaking changes in this update.
Multiple Modules (Related Change)
feat(tesla): add maintenance validation across models
- Add validation in Model aggregate
- Update MaintenanceHistory to check model status
- Add integration tests for both modules
This ensures consistency when creating maintenance records.
Commands
git status
git diff
git diff --staged
git diff --cached
git add <file>
git add -p
git commit -m "message"
git commit
git log --oneline -20
git log --pretty=format:"%h %s" -20
git log --graph --oneline --all
git commit --amend -m "new message"
git commit --amend --no-edit
Anti-Patterns to Avoid
| ❌ Bad | ✅ Good |
|---|
git commit -m "fix" | fix(auth): resolve token expiration bug |
git commit -m "WIP" | Finish the work or use feature branch |
git commit -m "changes" | refactor(core): extract common validation logic |
git commit -m "update files" | feat(book): add ISBN field to entity |
git commit -am "everything" | Split into logical commits |
| Mix feat + fix + refactor | Separate commits for each type |
| Commit generated files only | Commit YAML changes + explain regeneration |
Aurora-Specific Notes
1. YAML Changes
feat(aurora): add category entity to library module
Define new Category aggregate with id, name, description.
Run: aurora load back module -n=library/category
2. Custom Logic in Generated Files
feat(library/book): add complex ISBN validation logic
Implement custom validation in CreateBookHandler:
- Validate ISBN format (10 or 13 digits)
- Check checksum digit
- Verify not in blacklist
This logic is in a generated file marked as custom.
3. Multiple Related Modules
feat(tesla): integrate maintenance history with models
- Update Model aggregate with maintenance status
- Add validation in MaintenanceHistory creation
- Add integration tests
Changes span tesla/model and tesla/maintenance-history.
4. Test Commits
Option A: Combined with feature
feat(book): add ISBN validation with tests
- Add ISBN validation in CreateBookHandler
- Add unit tests for validation logic
- Add e2e tests for create endpoint
Option B: Separate commit
test(book): add unit tests for ISBN validation
Add comprehensive test coverage for:
- Valid ISBN-10 and ISBN-13 formats
- Invalid formats and checksums
- Edge cases (empty, null, special chars)
Decision Trees
Should I commit now?
Has code changed? ────NO───> No commit needed
│
YES
│
Is it a logical unit? ────NO───> Break into smaller commits
│
YES
│
Do tests pass? ────NO───> Fix tests first
│
YES
│
Create commit
What type should I use?
New functionality? ────YES───> feat
│
NO
│
Fixing a bug? ────YES───> fix
│
NO
│
No functional change? ────YES───> refactor
│
NO
│
Only tests? ────YES───> test
│
NO
│
Dependencies? ────YES───> chore(deps)
│
NO
│
Documentation? ────YES───> docs
│
NO
│
Default: chore
How to scope?
Single module changed? ────YES───> Use <bc>/<module>
│
NO
│
Multiple related modules? ────YES───> Use common <bc> or higher scope
│
NO
│
Infrastructure? ────YES───> Use: ci, docker, config, deps
│
NO
│
Core/API/GraphQL? ────YES───> Use: core, api, graphql
│
NO
│
Omit scope or use project name
Related Skills
This skill works with:
- aurora-cli: Commit YAML changes and regenerated code
- aurora-development: Commit business logic implementations (feat commits)
- jest-nestjs: Commit test files (test commits or include with feat)
- logger: Log commit information in session reports
Workflow:
- Make changes (YAML modifications, business logic, tests)
- Use aurora-cli to regenerate code (if YAML changed)
- Use conventional-commits to create proper commit
- Use logger to document the session (optional)
Resources
- Specification: https://www.conventionalcommits.org/
- Aurora Config:
commitlint.config.js (read this for project-specific rules)
- Git Hooks: Pre-commit hooks may enforce format validation
