Conventional Commits

Conventional Commits Skill

CRITICAL: All commits must follow Conventional Commits format: <type>(<scope>): <description>

When to Use This Skill

Use this skill when:

• Creating commit messages
• Formatting commits
• Understanding commit types
• Writing commit descriptions

Commit Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Types

Scope Guidelines

Scopes identify the affected area:

API Scopes

feat(api): add new endpoint
fix(api): resolve endpoint error
refactor(api): restructure controllers

Module Scopes

feat(auth): add authentication
fix(llm): resolve provider issue
chore(mcp): update MCP tools

Feature Scopes

feat(agents): add new agent type
fix(webhooks): resolve status tracking
perf(orchestration): optimize execution

Commit Examples

Simple Commit

feat(auth): add JWT token authentication

Commit with Body

feat(auth): add JWT token authentication

Implement JWT token generation and validation.
- Add token generation service
- Add token validation middleware
- Update auth controller

Commit with Footer

fix(api): resolve memory leak

The service was holding references to completed requests.
Now properly cleans up after request completion.

Closes #123

Breaking Change

feat(api)!: change authentication endpoint

BREAKING CHANGE: Authentication endpoint moved from /​auth/​login to /​api/​auth/​login

Common Patterns

Feature Development

feat(user-dashboard): add user dashboard component

- Create dashboard Vue component
- Add user stats API endpoint
- Implement real-time updates

Bug Fixes

fix(login): resolve authentication error

The login was failing due to incorrect token validation.
Fixed by updating token validation logic.

Fixes #456

Chores

chore(deps): update NestJS to v10

- Update @nestjs/​core to 10.0.0
- Update @nestjs/​common to 10.0.0
- Resolve breaking changes

Documentation

docs(api): update API documentation

- Add endpoint documentation
- Update examples
- Fix formatting issues

Tests

test(auth): add unit tests for auth service

- Test login functionality
- Test token generation
- Test error handling

Refactoring

refactor(api): restructure service layer

- Extract common service logic
- Improve dependency injection
- Update module structure

❌ Bad Commit Messages

❌ fix stuff
❌ update
❌ changes
❌ WIP
❌ asdf
❌ fixed bug
❌ add feature
❌ work in progress
❌ commit
❌ test

✅ Good Commit Messages

✅ feat(auth): add user authentication
✅ fix(api): resolve memory leak in service
✅ chore(deps): update dependencies
✅ docs(readme): update installation guide
✅ test(auth): add unit tests for login
✅ refactor(api): restructure service layer
✅ perf(db): optimize query performance
✅ style: format code with prettier

Multi-Line Commit Messages

Format

<type>(<scope>): <short description>

<detailed description>

<footer>

Example

feat(agents): add new API agent type

This commit adds support for API agents that wrap external HTTP services.
API agents use request/​response transforms to adapt between Orchestrator AI
format and external service format.

Changes:
- Add API agent runtime dispatch service
- Add request/​response transform logic
- Update agent registry to support API agents
- Add API agent validation

Closes #789

Commit Message Guidelines

✅ DO

• Use imperative mood ("add" not "added")
• Keep first line under 50 characters
• Use body for detailed explanation
• Reference issues in footer
• Use breaking change notation for breaking changes

❌ DON'T

• Don't use past tense ("fixed" use "fix")
• Don't use first person ("I added" use "add")
• Don't write vague messages
• Don't commit unrelated changes together
• Don't use abbreviations

Commit Message Templates

Feature Template

feat(<scope>): <description>

<what was added>

<why it was added>

<how to test>

Fix Template

fix(<scope>): <description>

<what was broken>

<how it was fixed>

<how to verify fix>

Fixes #<issue-number>

Refactor Template

refactor(<scope>): <description>

<what was refactored>

<why it was refactored>

<what changed>

Git Commit Commands

Simple Commit

git commit -m "feat(auth): add user login"

Multi-Line Commit

git commit -m "feat(auth): add user login" -m "Implement JWT token authentication with middleware validation"

Commit with Editor

git commit
# Opens editor for multi-line message

Checklist for Conventional Commits

When creating commits:

• Commit message follows format: <type>(<scope>): <description>
• Type is correct (feat, fix, chore, etc.)
• Scope identifies affected area
• Description is clear and concise
• Description uses imperative mood
• Body included if needed for context
• Footer included if referencing issues
• Breaking changes marked with !

Related Documentation

• Git Standards: See Orchestrator Git Standards Skill
• GitHub Workflow: See GitHub Workflow Skill
• Quality Gates: See Quality Gates Skill