# Command: commit
> **🤖 Agent Directive**: If you are reading this file, the command `@git.commit` has been invoked. Follow the steps below to execute this command.
**Namespace**: git
**Version**: 1.0.0
**Created**: 2026-02-16
**Last Updated**: 2026-02-16
**Status**: Active
---
**Purpose**: Automate version detection, changelog updates, and git commits with proper semantic versioning
**Category**: Version Control
**Frequency**: As Needed
---
## Overview
This command intelligently detects if changes represent a version change, determines the appropriate version bump (major/minor/patch), updates version identifiers across the project, updates CHANGELOG.md, intelligently stages relevant files, and creates a properly formatted git commit.
**Key Feature**: This command automatically determines which files to stage based on the changes detected. You don't need to manually run `git add` - the command analyzes your working directory and stages the appropriate files for the commit.
## When to Use
- After completing a feature, fix, or breaking change
- When you want to commit changes with proper version management
- To ensure CHANGELOG.md stays synchronized with code changes
- To maintain consistent commit message formatting
- When you have unstaged changes that need intelligent staging
## Prerequisites
- [ ] Working directory has changes (staged or unstaged)
- [ ] Understanding of semantic versioning (major.minor.patch)
- [ ] Project uses version identifiers (package.json, AGENT.md, etc.)
- [ ] Git repository initialized
---
## Steps
### 1. Analyze Changes for Version Impact
Review the staged/unstaged changes and determine:
**Major Version (X.0.0)** - Breaking changes:
- API changes that break backward compatibility
- Removal of features or functionality
- Major architectural changes
- Changes that require users to modify their code
**Minor Version (0.X.0)** - New features:
- New features added (backward compatible)
- New commands, tools, or capabilities
- Significant enhancements to existing features
- New optional parameters or configuration
**Patch Version (0.0.X)** - Bug fixes:
- Bug fixes
- Documentation updates
- Performance improvements
- Refactoring without behavior changes
- Minor tweaks and adjustments
**No Version Change** - Non-versioned changes:
- Work in progress
- Experimental changes
- Internal development changes
- Changes that don't affect users
### 2. Detect Version Files
Search for version identifiers in the project:
```bash
# Common version files to check:
- package.json (Node.js projects)
- pyproject.toml or setup.py (Python projects)
- Cargo.toml (Rust projects)
- pom.xml (Java/Maven projects)
- build.gradle (Java/Gradle projects)
- AGENT.md (ACP version)
- version.txt or VERSION file
- Any project-specific version files
```
**Action**: List all files containing version numbers that need updating.
### 3. Calculate New Version
Based on the current version and change type:
```
Current: 1.2.3
Major bump: 2.0.0
Minor bump: 1.3.0
Patch bump: 1.2.4
```
**Action**: Determine the new version number.
### 4. Update Version Files
Update all version identifiers found in step 2:
**Example for package.json**:
```json
{
"version": "1.3.0"
}
```
**Example for AGENT.md**:
```markdown
**Version**: 1.3.0
```
**Action**: Update all version files with the new version number.
### 5. Update CHANGELOG.md
Add a new entry at the top of CHANGELOG.md following Keep a Changelog format:
```markdown
## [1.3.0] - YYYY-MM-DD
### Added
- New features added in this version
### Changed
- Changes to existing functionality
### Deprecated
- Features marked for removal
### Removed
- Features removed in this version
### Fixed
- Bug fixes
### Security
- Security fixes
```
**Guidelines**:
- Use present tense ("Add feature" not "Added feature")
- Be specific and clear
- Group related changes
- Link to issues/PRs if applicable
- Include breaking changes prominently for major versions
**Action**: Create a new CHANGELOG.md entry with all changes in this commit.
### 6. Generate Commit Message
Use Conventional Commits format:
```
<type>(<scope>): <subject>
<body>
<footer>
```
**Types**:
- `feat`: New feature (minor version bump)
- `fix`: Bug fix (patch version bump)
- `docs`: Documentation only
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
- `agent`: Changes to agent/ directory only (designs, tasks, milestones, patterns)
- `version`: Version bump only (no code changes, just version number updates)
**Breaking Changes**:
- Add `BREAKING CHANGE:` in the commit message footer for major version bumps
- Use `feat!:` or `fix!:` syntax to indicate breaking changes
**Template for Version Changes**:
```
<type>(<scope>): <short description>
<detailed description of changes>
Changes:
- Change 1
- Change 2
- Change 3
Completed:
- Task: agent/tasks/task-N-name.md
- Milestone: M1 (if milestone completed)
Tests:
- X tests passing
- Y% code coverage
Documentation:
- Design: <link to design doc or external resource>
- API Docs: <link to generated docs>
- Related: <link to related documentation>
BREAKING CHANGE: <description if major version>
Closes #<issue-number>
Related: <PR-link or issue-link>
Version: X.Y.Z
```
**Example**:
```
feat(commands): add @git.commit command for intelligent version management
Implemented automated version detection and changelog management:
- Detects version impact (major/minor/patch)
- Updates all version files automatically
- Generates CHANGELOG.md entries
- Creates properly formatted commit messages
Changes:
- Added agent/commands/git.commit.md
- Updated AGENT.md with changelog emphasis
- Enhanced version management workflow
Completed:
- Task: agent/tasks/task-1-commands-infrastructure.md
- Milestone: M1 (ACP Commands) - 75% complete
Tests:
- All existing tests passing
- No new tests required (documentation only)
Version: 1.3.0
```
**Action**: Generate a commit message following this template.
### 7. Intelligently Stage Changes
Analyze the working directory and stage relevant files:
**Actions**:
- Review `git status` to see all changes
- Stage version files that were updated (AGENT.md, package.json, etc.)
- Stage CHANGELOG.md
- Stage source files that are part of this commit
- Optionally exclude unrelated changes (use `git add <specific-files>` instead of `git add -A`)
**Decision Logic**:
- If all changes are related to this commit: `git add -A`
- If some changes are unrelated: `git add <file1> <file2> ...` (specific files only)
- Always include: version files, CHANGELOG.md, and files related to the feature/fix
**Example**:
```bash
# If all changes are related:
git add -A
# If only specific files should be committed:
git add AGENT.md CHANGELOG.md agent/commands/git.commit.md
```
**Action**: Intelligently stage files based on what's relevant to this commit.
### 8. Create Commit
```bash
git commit -m "<generated commit message>"
```
**Action**: Commit with the generated message.
### 9. Display Summary
Show what was done:
```
✓ Version bumped: 1.2.3 → 1.3.0 (minor)
✓ Updated version files:
- AGENT.md
- package.json
✓ Updated CHANGELOG.md
✓ Created commit: feat: add new feature
✓ Ready to push
Next steps:
git push
```
---
## Verification Checklist
After running this command, verify:
- [ ] Version number is correct in all files
- [ ] CHANGELOG.md has a new entry with today's date
- [ ] CHANGELOG.md entry accurately describes changes
- [ ] Commit message follows Conventional Commits format
- [ ] All changes are staged and committed
- [ ] Version bump type is appropriate (major/minor/patch)
- [ ] Breaking changes are clearly documented (if major version)
---
## Examples
### Example 1: New Feature (Minor Version)
**Context**: Added `@git.commit` command
**Detection**:
- New command file created
- New functionality added
- Backward compatible
- **Decision**: Minor version bump (1.2.3 → 1.3.0)
**CHANGELOG.md Entry**:
```markdown
## [1.3.0] - 2026-02-16
### Added
- `@git.commit` command for intelligent version management
- Automated version detection and changelog updates
- Conventional Commits format support
```
**Commit Message**:
```
feat: add @git.commit command for intelligent version management
Implemented automated version detection and changelog management.
Version: 1.3.0
```
### Example 2: Bug Fix (Patch Version)
**Context**: Fixed syntax error in update.sh
**Detection**:
- Bug fix only
- No new features
- Backward compatible
- **Decision**: Patch version bump (1.2.3 → 1.2.4)
**CHANGELOG.md Entry**:
```markdown
## [1.2.4] - 2026-02-16
### Fixed
- Syntax error in update.sh script
- Script now runs without errors
```
**Commit Message**:
```
fix: resolve syntax error in update.sh script
Fixed bash syntax error that prevented update script from running.
Version: 1.2.4
```
### Example 3: Breaking Change (Major Version)
**Context**: Changed command syntax from `AGENT.md: Initialize` to `@acp.init`
**Detection**:
- Breaking change to user interface
- Old syntax no longer works
- Requires user action
- **Decision**: Major version bump (1.2.3 → 2.0.0)
**CHANGELOG.md Entry**:
```markdown
## [2.0.0] - 2026-02-16
### Changed
- **BREAKING**: Command syntax changed from `AGENT.md: Initialize` to `@acp.init`
- All commands now use `@acp.*` format
- Old prompt format no longer supported
### Migration Guide
- Replace `AGENT.md: Initialize` with `@acp.init`
- Replace `AGENT.md: Proceed` with `@acp.proceed`
```
**Commit Message**:
```
feat!: change command syntax to @acp.* format
BREAKING CHANGE: Command syntax has changed from "AGENT.md: Initialize"
to "@acp.init" format. All commands now use the @acp.* namespace.
Migration:
- AGENT.md: Initialize → @acp.init
- AGENT.md: Proceed → @acp.proceed
Version: 2.0.0
```
### Example 4: No Version Change
**Context**: Work in progress, experimental changes
**Detection**:
- Incomplete feature
- Not ready for release
- Internal development
- **Decision**: No version bump
**Commit Message**:
```
chore: work in progress on new feature
Experimental implementation, not ready for release.
```
---
## Decision Tree
```
Is this a breaking change?
├─ Yes → Major version bump (X.0.0)
└─ No
├─ Is this a new feature?
│ ├─ Yes → Minor version bump (0.X.0)
│ └─ No
│ ├─ Is this a bug fix or improvement?
│ │ ├─ Yes → Patch version bump (0.0.X)
│ │ └─ No → No version bump
```
---
## Best Practices
1. **Be Honest About Breaking Changes**
- If it breaks existing functionality, it's a major version
- Document migration paths clearly
2. **Group Related Changes**
- Commit related changes together
- Don't mix features and fixes in one commit
3. **Write Clear CHANGELOG Entries**
- Focus on user impact, not implementation
- Include examples for complex changes
- Link to documentation
4. **Use Conventional Commits**
- Makes changelog generation easier
- Enables automated tooling
- Improves git history readability
5. **Update All Version Files**
- Don't forget any version identifiers
- Keep versions synchronized
- Verify after updating
6. **Review Before Committing**
- Check CHANGELOG.md accuracy
- Verify version bump is appropriate
- Ensure commit message is clear
---
## Troubleshooting
**Problem**: Not sure if change is major or minor
- **Solution**: If in doubt, use minor. Major should only be for clear breaking changes.
**Problem**: Multiple unrelated changes staged
- **Solution**: Unstage and commit separately, or group logically in CHANGELOG.
**Problem**: Forgot to update a version file
- **Solution**: Amend the commit: `git commit --amend`, update files, stage, and amend again.
**Problem**: CHANGELOG.md entry is unclear
- **Solution**: Rewrite focusing on user impact, not technical details.
---
## Related Commands
- [`@acp.version-check`](acp.version-check.md) - Check current version
- [`@acp.version-update`](acp.version-update.md) - Update ACP itself
- [`@acp.status`](acp.status.md) - Check project status before committing
---
## Notes
- This command is for project commits, not ACP updates
- Always review generated changelog entries
- Version bumps should be deliberate and meaningful
- Keep CHANGELOG.md user-focused, not developer-focused
- Use semantic versioning consistently
---
**Status**: Production Ready
**Last Updated**: 2026-02-16
