# Amicus MCP Server - Project Governance
## Core Principles
### 1. Stability First
The Amicus MCP server is critical infrastructure for multi-agent coordination. Breaking changes or installation failures directly impact all connected agents and sessions.
### 2. Validation Before Deployment
**CRITICAL REQUIREMENT:** The amicus-mcp server MUST ALWAYS be validated to run correctly before replacing any installed version.
## Installation Safety Protocol
### Mandatory Pre-Installation Validation
Before ANY installation or update of amicus-mcp:
1. **Run Full Test Suite**
```bash
pytest tests/ -v
```
- All tests must pass
- No exceptions or errors
2. **Validate Server Startup**
```bash
python -m amicus --validate-startup
```
- Server must start without errors
- MCP protocol initialization must succeed
- Graceful shutdown must work
3. **Validate Tool Registration**
```bash
python scripts/validate_tools.py
```
- All expected tools must be registered
- Tool signatures must be correct
- No duplicate registrations
4. **Validate Build Package**
```bash
python scripts/validate_build.py
```
- Package must include all source files
- Entry points must be correct
- Dependencies must be resolvable
### Installation Workflow
**Step 1: Validate Current Source**
```bash
./scripts/validate_before_install.sh
```
**Step 2: Build and Test Package**
```bash
# Build package
python -m build
# Install to test environment
uv venv test-env
source test-env/bin/activate
uv pip install dist/amicus_mcp-*.whl
# Validate installation
amicus-mcp --list-tools
amicus-mcp --validate-env
```
**Step 3: Install Only if Validation Passes**
```bash
# If all validations pass:
uv tool install . --force
# Verify post-installation
~/.local/bin/amicus-mcp --list-tools
```
### Breaking the Build is Unacceptable
- **Never commit code that breaks `python -m amicus`**
- **Never commit code that reduces tool count**
- **Never commit code that changes entry points without validation**
- **Never skip the validation protocol**
### Rollback Protocol
If a broken installation is detected:
1. **Immediate Rollback**
```bash
uv tool uninstall amicus-mcp
git checkout <last-known-good-commit>
./scripts/validate_before_install.sh
uv tool install . --force
```
2. **Document the Failure**
- Create GitHub issue with error details
- Tag as `critical` and `installation-failure`
- Include full error trace and validation output
3. **Root Cause Analysis**
- Identify what broke the build
- Add validation to prevent recurrence
- Update tests to catch the issue
## Development Workflow
### Before Committing Code
1. **Run Validation Suite**
```bash
python scripts/validate_all.py
```
2. **Test Server Startup**
```bash
timeout 5 python -m amicus || echo "Startup OK"
```
3. **Verify Tool Count**
```bash
python -c "
import sys
sys.path.insert(0, 'src')
from amicus.server import mcp
import asyncio
tools = asyncio.run(mcp.get_tools())
assert len(tools) >= 15, f'Tool count dropped to {len(tools)}'
print(f'✓ {len(tools)} tools registered')
"
```
### Pull Request Requirements
All PRs must include:
1. **Validation Evidence**
- Screenshot or output of `./scripts/validate_before_install.sh`
- Confirmation that all tests pass
- Tool count verification
2. **Installation Test**
- Fresh virtual environment test
- `uv tool install` from PR branch
- Successful `--list-tools` output
3. **Rollback Plan**
- Document how to revert changes
- Identify affected systems/users
## Configuration Changes
### pyproject.toml Modifications
Changes to `pyproject.toml` require extra scrutiny:
- **[project.scripts]**: Validate entry points work
- **[tool.hatch.build.targets.wheel]**: Validate package inclusion
- **[build-system]**: Test build backend compatibility
- **dependencies**: Ensure no conflicts
**Validation Command:**
```bash
python -m build --wheel
unzip -l dist/*.whl | grep amicus/ # Verify package contents
```
## Release Process
### Version Release Checklist
Before releasing a new version:
- [ ] All tests pass (`pytest tests/ -v`)
- [ ] Validation suite passes (`./scripts/validate_all.py`)
- [ ] Server starts successfully (`python -m amicus`)
- [ ] All tools registered (verify count)
- [ ] Fresh install test in clean environment
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Git tag created
- [ ] Installation tested on target platforms (macOS, Linux)
### Post-Release Validation
After publishing to PyPI or GitHub:
- [ ] `uv tool install amicus-mcp` works
- [ ] `pip install amicus-mcp` works
- [ ] All MCP clients can connect
- [ ] No regressions in tool availability
## Enforcement
### Automated Checks
The following checks run automatically:
1. **Pre-commit hooks** (`.git/hooks/pre-commit`)
- Validate tool count hasn't decreased
- Check server can import successfully
- Run quick syntax checks
2. **CI/CD Pipeline** (GitHub Actions)
- Full test suite on every PR
- Installation validation
- Multi-platform testing
3. **Pre-release validation** (GitHub Actions)
- Build package
- Install in fresh environment
- Smoke test all tools
### Manual Verification
Developers must manually verify:
- Server startup works
- MCP protocol functions
- Tools are accessible
- Configuration loads correctly
## Recovery Procedures
### If Installation Breaks
1. **Don't panic** - we have rollback procedures
2. **Document the error** - capture full output
3. **Rollback immediately** - restore working version
4. **Fix in development** - don't fix in production
5. **Re-validate completely** - run full suite
### If Tools Disappear
1. **Check git diff** - what changed?
2. **Verify pyproject.toml** - entry points correct?
3. **Check build output** - package includes source?
4. **Test from source** - does direct import work?
5. **Compare working commit** - what's different?
## Contacts and Escalation
### Issue Priority Levels
- **P0 (Critical)**: Server won't start, all tools missing
- Response time: Immediate
- Action: Rollback and hotfix
- **P1 (High)**: Some tools missing, degraded functionality
- Response time: < 1 hour
- Action: Investigate and patch
- **P2 (Medium)**: Non-critical issues, warnings
- Response time: < 1 day
- Action: Fix in next release
- **P3 (Low)**: Enhancements, nice-to-haves
- Response time: Next sprint
- Action: Add to backlog
## Semantic Versioning (SemVer)
Amicus MCP follows [Semantic Versioning 2.0.0](https://semver.org/).
### Version Format
**`MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]`**
- **MAJOR**: Breaking changes (incompatible API changes)
- **MINOR**: New features (backwards-compatible functionality)
- **PATCH**: Bug fixes (backwards-compatible fixes)
- **PRERELEASE**: Optional pre-release identifier (alpha, beta, rc)
- **BUILD**: Optional build metadata
### Version Increment Rules
#### MAJOR Version (X.0.0)
Increment when making **incompatible** changes:
- **Breaking MCP tool signature changes**
- Removing parameters
- Changing parameter types
- Removing tools entirely
- **Breaking state schema changes**
- Removing required fields
- Changing field types incompatibly
- Breaking cluster_nodes structure
- **Breaking configuration changes**
- Removing config options
- Changing config format
- Requiring new mandatory settings
- **Breaking protocol changes**
- Incompatible SYNAPSE_PROTOCOL.md changes
- Incompatible BOOTSTRAP_MANAGER.md changes
**Example:** Removing the `update_state` tool → v0.4.0 → v1.0.0
#### MINOR Version (0.X.0)
Increment when adding **backwards-compatible** features:
- **New MCP tools**
- Adding set_agent_status → v0.3.5 → v0.4.0
- Adding assess_workload → v0.3.5 → v0.4.0
- **New optional parameters**
- Adding optional `priority` to add_task
- Adding optional `metadata` to update_state
- **New state schema fields**
- Adding cluster_metadata (optional)
- Adding work_distribution (optional)
- **New features**
- Anti-idle system → v0.3.0 → v0.4.0
- Workload assessment → v0.3.0 → v0.4.0
- **Enhanced functionality**
- Improving tool registration
- Adding new configuration options
**Example:** Adding anti-idle system → v0.3.0 → v0.4.0
#### PATCH Version (0.0.X)
Increment for **backwards-compatible** bug fixes:
- **Bug fixes**
- Fixing race conditions
- Fixing memory leaks
- Fixing incorrect calculations
- **Performance improvements**
- Optimizing file locking
- Reducing memory usage
- Improving startup time
- **Documentation fixes**
- Correcting typos
- Updating examples
- Clarifying instructions
- **Internal refactoring**
- Code cleanup
- Improving tests
- Updating dependencies (patch versions)
**Example:** Fixing heartbeat monitor race condition → v0.4.0 → v0.4.1
### Pre-Release Versions
Use for testing before official releases:
- **Alpha**: `0.4.0-alpha.1` - Early testing, unstable
- **Beta**: `0.4.0-beta.1` - Feature complete, testing
- **Release Candidate**: `0.4.0-rc.1` - Final testing before release
**Pre-release precedence:**
```
0.4.0-alpha.1 < 0.4.0-alpha.2 < 0.4.0-beta.1 < 0.4.0-rc.1 < 0.4.0
```
### Version Update Procedure
#### 1. Determine Version Bump
Ask these questions:
1. **Does it break existing functionality?** → MAJOR
2. **Does it add new features?** → MINOR
3. **Does it only fix bugs?** → PATCH
#### 2. Update Version Files
Run the version bump script:
```bash
# Automatic version bump
./scripts/bump_version.sh [major|minor|patch]
# Example: Adding new feature
./scripts/bump_version.sh minor
# 0.4.0 → 0.5.0
# Example: Bug fix
./scripts/bump_version.sh patch
# 0.4.0 → 0.4.1
```
This updates:
- `pyproject.toml` - `version = "X.Y.Z"`
- `src/amicus/__init__.py` - `__version__ = "X.Y.Z"`
- Validation checks
#### 3. Update CHANGELOG.md
Follow [Keep a Changelog](https://keepachangelog.com/) format:
```markdown
## [X.Y.Z] - YYYY-MM-DD
### Added
- New feature descriptions
### Changed
- Modifications to existing features
### Deprecated
- Features that will be removed
### Removed
- Features that were removed (MAJOR bump)
### Fixed
- Bug fixes
### Security
- Security fixes
```
#### 4. Commit Version Change
```bash
git add pyproject.toml src/amicus/__init__.py CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
```
#### 5. Create Git Tag
```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
```
### Version Storage Locations
Version number is stored in **two** canonical locations:
1. **`pyproject.toml`**
```toml
[project]
version = "0.4.0"
```
2. **`src/amicus/__init__.py`**
```python
__version__ = "0.4.0"
```
These MUST always match. The bump_version.sh script ensures synchronization.
### Breaking Change Policy
#### Before Making Breaking Changes
1. **Deprecation warning** (at least one MINOR version before removal)
```python
import warnings
warnings.warn(
"update_state parameter 'old_param' is deprecated, use 'new_param' instead",
DeprecationWarning
)
```
2. **Documentation update** explaining migration path
3. **Backwards compatibility layer** if possible
```python
def update_state(new_param=None, old_param=None):
if old_param is not None:
warnings.warn("old_param is deprecated", DeprecationWarning)
new_param = old_param
# Use new_param
```
4. **Migration guide** in CHANGELOG.md
5. **Major version bump** when finally removing
#### Example Breaking Change Timeline
**v0.4.0** - Deprecate `claim_task`, introduce `claim_best_task`
```python
@mcp.tool()
def claim_task(task_index: int, agent_id: str):
warnings.warn("claim_task is deprecated, use claim_best_task", DeprecationWarning)
# Still works
```
**v0.5.0** - Both tools available, migration guide published
**v1.0.0** - Remove `claim_task`, only `claim_best_task` available
### Version Validation
Before releasing ANY version:
```bash
# 1. Validate version consistency
./scripts/validate_version.sh
# 2. Run full validation suite
./scripts/validate_before_install.sh
# 3. Verify version command
amicus-mcp --version
# Should match pyproject.toml
# 4. Check git tag doesn't exist
git tag -l | grep "v$(cat pyproject.toml | grep version | cut -d'"' -f2)"
# Should be empty for new versions
```
### Pre-Release Testing
Before releasing MAJOR or MINOR versions:
1. **Create pre-release**
```bash
./scripts/bump_version.sh minor --pre-release alpha
# 0.4.0 → 0.5.0-alpha.1
```
2. **Test in production-like environment**
- Install on test systems
- Run full test suite
- Test with real MCP clients
3. **Progress through pre-release stages**
```bash
0.5.0-alpha.1 → 0.5.0-alpha.2 → 0.5.0-beta.1 → 0.5.0-rc.1 → 0.5.0
```
4. **Final release only after RC passes all tests**
### Version Compatibility
#### MCP Protocol Compatibility
- **Major version changes** MAY break MCP client compatibility
- **Minor version changes** MUST maintain MCP client compatibility
- **Patch version changes** MUST maintain full compatibility
#### State File Compatibility
- **Major version changes** MAY break state file compatibility
- **Minor version changes** MUST be backwards compatible with state files
- **Patch version changes** MUST maintain full state compatibility
#### Migration Scripts
For MAJOR versions breaking state compatibility:
```bash
# Create migration script
scripts/migrate_state_v0_to_v1.py
# Document in CHANGELOG
## [1.0.0] - Migration Required
See docs/MIGRATION_v0_to_v1.md for upgrade instructions.
```
### Dependency Version Policy
#### Production Dependencies
Update according to their changes:
- **Security patches** → Always update, release PATCH version
- **Bug fixes** → Update if needed, release PATCH version
- **New features** → Evaluate, may trigger MINOR version
- **Breaking changes** → Careful evaluation, may trigger MAJOR version
#### Development Dependencies
- Update freely without version bump
- Only bump version if it affects production
### Release Checklist
Before tagging any release:
- [ ] Version number follows SemVer
- [ ] Version updated in pyproject.toml
- [ ] Version updated in __init__.py
- [ ] Versions match across files
- [ ] CHANGELOG.md updated with changes
- [ ] All validation checks pass
- [ ] Tests pass
- [ ] Documentation updated
- [ ] Migration guide written (if MAJOR)
- [ ] Git tag created
- [ ] GitHub release created
### 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)]
```
**Types:** feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
**Scopes:** mcp, cluster, config, monitor, security, cli, docs, validation, prompts
**Examples:**
```
feat(mcp): add assess_workload tool for cluster intelligence
fix(monitor): resolve race condition in heartbeat cleanup
docs: add semantic versioning procedures to governance
chore: bump version to 0.4.1
```
### Commit Guidelines
1. **Use imperative mood**: "add" not "added" or "adds"
2. **Don't capitalize first letter**: "add feature" not "Add feature"
3. **No period at end**: "add feature" not "add feature."
4. **Max 72 characters** for subject line
5. **Atomic commits**: One logical change per commit
6. **Write as you go**: Commit throughout development
### Validation
Install git hooks to enforce commit standards:
```bash
./scripts/install_hooks.sh
```
This installs:
- **commit-msg**: Validates Conventional Commits format
- **pre-commit**: Checks syntax, file sizes, debug statements
- **prepare-commit-msg**: Provides commit message templates
Validate existing commits:
```bash
# Validate HEAD
./scripts/validate_commits.sh
# Validate specific commit
./scripts/validate_commits.sh abc123f
# Validate range
./scripts/validate_commits.sh main..HEAD
```
### Branch Strategy
**Branch Naming:** `<type>/<short-description>`
Examples:
- `feature/anti-idle-system`
- `fix/heartbeat-race-condition`
- `docs/versioning-guide`
**Main Branch:**
- Always deployable
- Protected (no direct commits)
- All changes via pull requests
**Pull Requests:**
- Title follows commit format
- Squash merge for features
- At least one approval required
- All checks must pass
### Complete Documentation
See [docs/GIT_WORKFLOW.md](docs/GIT_WORKFLOW.md) for:
- Detailed commit examples
- Branch workflow
- PR guidelines
- Rewriting history
- Git aliases
- Common workflows
## Version History
- **v0.4.0** (2026-02-02): Added anti-idle system, validation requirements, semver procedures, git workflow standards
- **v0.3.0** (2026-02-01): Self-managing cluster protocol, established governance framework
- **v0.2.0** (2026-02-01): CLI commands, audit framework
- **v0.1.0** (2026-02-01): Initial release, core MCP tools
---
**Remember**:
- A working server is more valuable than a feature-rich broken server. Validate first, deploy second.
- Semantic versioning is a contract with users. Never break it.
- Good commit messages are documentation. Write them for humans.
