# Git Workflow and Commit Standards
## Commit Message Format
Amicus MCP follows [Conventional Commits](https://www.conventionalcommits.org/) specification.
### Format
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
### Type
Must be one of:
- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation only
- **style**: Code style (formatting, semicolons, etc.)
- **refactor**: Code change that neither fixes a bug nor adds a feature
- **perf**: Performance improvement
- **test**: Adding or updating tests
- **build**: Build system or dependencies
- **ci**: CI/CD configuration
- **chore**: Other changes (maintenance, tooling)
- **revert**: Revert a previous commit
### Scope (Optional)
Indicates what part of the codebase is affected:
- **mcp**: MCP tools (update_state, register_node, etc.)
- **cluster**: Cluster management (anti-idle, workload assessment)
- **config**: Configuration system
- **monitor**: HeartbeatMonitor
- **security**: Security scanner
- **cli**: Command-line interface
- **docs**: Documentation
- **validation**: Validation scripts
- **prompts**: Prompt files (SYNAPSE_PROTOCOL, etc.)
### Description
- Use imperative mood: "add" not "added" or "adds"
- Don't capitalize first letter
- No period at the end
- Max 72 characters
### Body (Optional)
- Explain what and why, not how
- Wrap at 72 characters
- Separate from description with blank line
### Footer (Optional)
- Reference issues: `Closes #123`
- Breaking changes: `BREAKING CHANGE: description`
- Co-authored by: `Co-authored-by: Name <email>`
## Examples
### Good Commit Messages
#### Simple Feature
```
feat(mcp): add assess_workload tool for cluster intelligence
Implements workload assessment that analyzes pending tasks,
active nodes, and idle nodes to generate spawn/terminate
recommendations for the Bootstrap Manager.
Closes #42
```
#### Bug Fix
```
fix(monitor): resolve race condition in heartbeat cleanup
The HeartbeatMonitor was checking node status without proper
locking, causing occasional crashes when nodes terminated
during health checks. Added file locking to _check_health().
Fixes #38
```
#### Breaking Change
```
feat(mcp)!: change update_state to require task objects
BREAKING CHANGE: next_steps parameter now requires List[Dict]
instead of List[str]. All task strings must be converted to
task objects with status field.
Migration:
- Before: next_steps=["task 1", "task 2"]
- After: next_steps=[{"task": "task 1", "status": "pending"}]
Closes #45
```
#### Documentation
```
docs: add semver procedures to governance
Added comprehensive semantic versioning documentation including
version bump procedures, breaking change policy, and validation
requirements.
```
#### Chore
```
chore: bump version to 0.4.1
```
### Bad Commit Messages
❌ **Too vague**
```
fix: fixed bug
```
Better:
```
fix(monitor): resolve race condition in heartbeat cleanup
```
❌ **Wrong mood**
```
feat: added new tool
```
Better:
```
feat(mcp): add assess_workload tool
```
❌ **Too long**
```
feat: add a new tool called assess_workload that helps the bootstrap manager determine when to spawn new nodes by analyzing the current cluster state
```
Better:
```
feat(mcp): add assess_workload tool for cluster intelligence
```
❌ **No type**
```
update readme
```
Better:
```
docs: update readme with anti-idle system documentation
```
## Commit Workflow
### 1. Make Atomic Commits
Each commit should be a single logical change:
✅ **Good:**
```bash
git commit -m "feat(mcp): add set_agent_status tool"
git commit -m "feat(mcp): add claim_best_task tool"
git commit -m "feat(mcp): add assess_workload tool"
```
❌ **Bad:**
```bash
git commit -m "feat: add all anti-idle tools and update docs and fix bugs"
```
### 2. Commit Often
Commit after each logical unit of work:
- Implemented a function? Commit.
- Fixed a bug? Commit.
- Updated documentation? Commit.
### 3. Write Commits as You Go
Don't wait until the end to commit. Commit throughout development:
```bash
# During development
git add src/amicus/server.py
git commit -m "feat(mcp): add set_agent_status tool signature"
git add src/amicus/server.py
git commit -m "feat(mcp): implement set_agent_status logic"
git add tests/test_anti_idle.py
git commit -m "test(mcp): add tests for set_agent_status"
git add docs/ANTI_IDLE_SYSTEM.md
git commit -m "docs: document set_agent_status tool"
```
### 4. Use Staging Selectively
Stage only related changes:
```bash
# Modified multiple files, commit separately
git add src/amicus/server.py
git commit -m "feat(mcp): add assess_workload tool"
git add prompts/BOOTSTRAP_MANAGER.md
git commit -m "docs(prompts): update bootstrap manager with workload assessment"
```
### 5. Review Before Committing
```bash
# Check what's changed
git status
git diff
# Stage specific files
git add <file>
# Review staged changes
git diff --staged
# Commit with message
git commit -m "type(scope): description"
```
## Branch Strategy
### Branch Naming
Format: `<type>/<short-description>`
**Types:**
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation
- `refactor/` - Code refactoring
- `test/` - Test additions/updates
- `chore/` - Maintenance tasks
**Examples:**
```
feature/anti-idle-system
fix/heartbeat-race-condition
docs/versioning-guide
refactor/cluster-state-schema
test/validate-tools
chore/update-dependencies
```
### Branch Workflow
#### Main Branch
- `main` - Production-ready code
- Always deployable
- Protected (no direct commits)
- All changes via pull requests
#### Feature Branches
```bash
# Create feature branch
git checkout -b feature/workload-assessment
# Work and commit
git commit -m "feat(cluster): add workload assessment logic"
git commit -m "test(cluster): add workload assessment tests"
# Push to remote
git push origin feature/workload-assessment
# Create pull request on GitHub
```
#### Hotfix Branches
```bash
# Critical bug in production
git checkout -b fix/heartbeat-crash main
# Fix and commit
git commit -m "fix(monitor): resolve null pointer in heartbeat check"
# Push and create PR
git push origin fix/heartbeat-crash
```
### Merging Strategy
**Use Squash Merge for Features:**
When merging feature branches, squash commits into one:
```bash
# Before merge (feature branch with 10 commits):
feat: add workload assessment skeleton
feat: implement workload calculation
fix: typo in workload function
test: add basic workload tests
refactor: improve workload calculation
test: add edge case tests
docs: add workload documentation
fix: address review comments
style: format code
docs: update examples
# After squash merge (main branch with 1 commit):
feat(cluster): add workload assessment system (#42)
Implements comprehensive workload assessment including:
- Active node counting
- Pending task analysis
- Spawn recommendations
- Idle detection
Closes #42
```
**Use Regular Merge for Releases:**
When merging release branches, preserve history:
```bash
git checkout main
git merge --no-ff release/v0.5.0
git tag -a v0.5.0 -m "Release v0.5.0"
```
## Pull Request Guidelines
### PR Title
Same format as commit messages:
```
feat(mcp): add anti-idle system tools
fix(monitor): resolve heartbeat race condition
docs: add semantic versioning procedures
```
### PR Description Template
```markdown
## Description
Brief description of what this PR does.
## Type of Change
- [ ] feat: New feature
- [ ] fix: Bug fix
- [ ] docs: Documentation
- [ ] refactor: Code refactoring
- [ ] test: Testing
- [ ] chore: Maintenance
## Changes Made
- Change 1
- Change 2
- Change 3
## Testing
- [ ] Validation suite passes
- [ ] Manual testing completed
- [ ] Tool count verified (15+)
## Checklist
- [ ] Code follows project style
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] Tests added/updated
- [ ] All tests passing
- [ ] CHANGELOG.md updated (if applicable)
## Related Issues
Closes #123
Relates to #456
## Screenshots (if applicable)
[Add screenshots]
## Breaking Changes
None / Description of breaking changes
```
### PR Size Guidelines
Keep PRs focused and reviewable:
- **Small**: < 100 lines - Ideal
- **Medium**: 100-500 lines - Acceptable
- **Large**: 500-1000 lines - Split if possible
- **Huge**: > 1000 lines - Must split
### PR Review Process
1. **Self-review first**
- Read your own PR as if you're reviewing it
- Check for typos, commented code, debug statements
2. **Request review**
- Tag relevant reviewers
- Provide context in PR description
3. **Address feedback**
- Respond to all comments
- Make requested changes
- Push new commits (don't force push during review)
4. **Get approval**
- At least one approval required
- All conversations resolved
5. **Merge**
- Squash and merge (for features)
- Update PR description if needed
- Delete branch after merge
## Commit Message Validation
### Automated Validation
Commit messages are validated by git hooks:
```bash
# Install commit message hook
./scripts/install_hooks.sh
# Hook validates:
✓ Conventional commit format
✓ Type is valid
✓ Description length (max 72 chars)
✓ Description style (imperative, lowercase)
```
### Manual Validation
```bash
# Validate commit messages in current branch
./scripts/validate_commits.sh
# Validate specific commit
./scripts/validate_commits.sh HEAD
./scripts/validate_commits.sh abc123f
```
## Rewriting History
### When to Rewrite
✅ **Allowed on feature branches:**
- Fix commit message typos
- Squash related commits
- Reorder commits logically
❌ **Never on main:**
- Don't rewrite published history
- Don't force push to main
### How to Rewrite
#### Amend Last Commit
```bash
# Fix last commit message
git commit --amend -m "feat(mcp): add assess_workload tool"
# Add files to last commit
git add forgotten_file.py
git commit --amend --no-edit
```
#### Interactive Rebase
```bash
# Rewrite last 3 commits
git rebase -i HEAD~3
# Options:
# pick - keep commit
# reword - change message
# squash - combine with previous
# drop - remove commit
```
#### Example: Squash Commits
```bash
# Before:
git log --oneline
abc123 fix typo
def456 add tests
ghi789 implement feature
# Rebase
git rebase -i HEAD~3
# In editor, change to:
pick ghi789 implement feature
squash def456 add tests
squash abc123 fix typo
# Result:
feat(mcp): implement feature with tests
```
## Commit Message Templates
### Create Template File
```bash
# ~/.gitmessage
<type>(<scope>): <description>
# Why this change is needed
# What does it do
# Any breaking changes
# Closes #
```
### Configure Git
```bash
git config --global commit.template ~/.gitmessage
```
### Use Template
```bash
git commit
# Opens editor with template pre-filled
```
## Git Aliases
Add to `~/.gitconfig`:
```ini
[alias]
# Commit shortcuts
cm = commit -m
ca = commit --amend
can = commit --amend --no-edit
# Status and log
st = status -sb
lg = log --graph --oneline --all --decorate
# Conventional commit helpers
feat = "!f() { git commit -m \"feat: $*\"; }; f"
fix = "!f() { git commit -m \"fix: $*\"; }; f"
docs = "!f() { git commit -m \"docs: $*\"; }; f"
chore = "!f() { git commit -m \"chore: $*\"; }; f"
# Branch management
branches = branch -a
cleanup = "!git branch --merged | grep -v '\\*\\|main\\|develop' | xargs -n 1 git branch -d"
```
Usage:
```bash
git feat "add workload assessment"
git fix "resolve race condition"
git docs "update readme"
```
## Tools and Automation
### Commitlint
Install commitlint for automated validation:
```bash
npm install --save-dev @commitlint/cli @commitlint/config-conventional
```
Config (`.commitlintrc.json`):
```json
{
"extends": ["@commitlint/config-conventional"],
"rules": {
"type-enum": [2, "always", [
"feat", "fix", "docs", "style", "refactor",
"perf", "test", "build", "ci", "chore", "revert"
]],
"subject-case": [2, "always", "lower-case"],
"subject-max-length": [2, "always", 72]
}
}
```
### Git Hooks
Pre-commit hook validates commits:
```bash
#!/bin/bash
# .git/hooks/commit-msg
# Install hooks
./scripts/install_hooks.sh
```
## Common Workflows
### Workflow 1: Feature Development
```bash
# 1. Create branch
git checkout -b feature/new-tool
# 2. Develop and commit atomically
git add src/amicus/server.py
git commit -m "feat(mcp): add new_tool signature"
git add src/amicus/server.py
git commit -m "feat(mcp): implement new_tool logic"
# 3. Push and create PR
git push origin feature/new-tool
# 4. Squash merge to main
# (via GitHub PR interface)
```
### Workflow 2: Bug Fix
```bash
# 1. Create fix branch
git checkout -b fix/bug-description
# 2. Fix and commit
git add file.py
git commit -m "fix(component): resolve specific bug
Detailed explanation of the bug and how it was fixed."
# 3. Push and PR
git push origin fix/bug-description
# 4. Merge to main
```
### Workflow 3: Documentation Update
```bash
# 1. Create docs branch
git checkout -b docs/update-guide
# 2. Update docs
git add docs/GUIDE.md
git commit -m "docs: update guide with new examples"
# 3. Push and merge
git push origin docs/update-guide
```
## Best Practices
1. **Write commits for humans** - Future you will read these
2. **Commit complete units of work** - Each commit should make sense standalone
3. **Test before committing** - Run validation suite
4. **Write clear descriptions** - Explain why, not what
5. **Reference issues** - Link commits to issues/PRs
6. **Use conventional format** - Enables automation
7. **Keep commits focused** - One concern per commit
8. **Review before pushing** - Check commit history
## Resources
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Git Best Practices](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project)
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
---
**Remember**: Good commit messages are documentation. They explain the evolution of the codebase.
