# File Coordination Governance
**Version:** 0.7.0
**Status:** Implemented
**GitHub Issue:** [#7](https://github.com/earchibald/amicus-mcp/issues/7)
## Overview
The File Coordination Governance feature implements lightweight intent-based coordination to prevent agents from "stomping" on each other's file changes. Rather than strict file locking (which was determined to be overkill), this system uses **declared intents** with automatic expiration.
## Design Philosophy
Based on analysis (Issue #7), we chose **lightweight intent-based coordination** over strict file locking because:
1. **Low conflict rate**: Agents naturally work on different files most of the time
2. **Self-healing**: Intent expiration handles crashed agents automatically
3. **Non-blocking**: Agents can still proceed with warnings if needed
4. **Complements Code Audit**: Works alongside review workflow, not replacing it
## Workflow
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Agent A │ │ File Intents │ │ Agent B │
│ (Developer) │ │ (Shared State) │ │ (Developer) │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ declare_file_intent() │ │
│──────────────────────>│ │
│ │ │
│ intent_id + no conflicts │
│<──────────────────────│ │
│ │ │
│ │ check_file_conflicts()
│ │<──────────────────────│
│ │ │
│ │ CONFLICT: Agent A │
│ │──────────────────────>│
│ │ │
│ (Agent A works on │ │
│ files...) │ │
│ │ │
│ release_file_intent() │ │
│──────────────────────>│ │
│ │ │
│ │ check_file_conflicts()
│ │<──────────────────────│
│ │ │
│ │ No conflicts │
│ │──────────────────────>│
│ │ │
│ │ declare_file_intent()
│ │<──────────────────────│
│ │ │
```
## MCP Tools
### declare_file_intent
Declare intent to modify files before starting work.
**Parameters:**
- `agent_id` (string, required): ID of the agent declaring intent
- `files` (list[string], required): List of file paths the agent intends to modify
- `intent_type` (string, optional): "write" (exclusive) or "read" (shared) - default: "write"
- `description` (string, optional): Description of planned changes
- `ttl_seconds` (int, optional): Time-to-live in seconds (default: 300 = 5 minutes)
**Returns:** Intent ID and conflict warnings if any
**Example:**
```python
declare_file_intent(
agent_id="Node-Dev-001",
files=["src/server.py", "src/utils.py"],
intent_type="write",
description="Adding new API endpoint"
)
# Returns:
# ✅ File intent declared: intent-a1b2c3d4
# Agent: Node-Dev-001
# Files: src/server.py, src/utils.py
# Type: WRITE
# Expires in: 300s
```
### check_file_conflicts
Check if any files have conflicting intents from other agents.
**Parameters:**
- `files` (list[string], required): List of file paths to check
- `agent_id` (string, optional): Agent ID to exclude from conflict check (your own intents)
**Returns:** Conflict report or confirmation that files are clear
**Example:**
```python
check_file_conflicts(
files=["src/server.py"],
agent_id="Node-Dev-002"
)
# Returns:
# ⚠️ FILE CONFLICTS DETECTED
# ========================================
#
# 📄 src/server.py
# Held by: Node-Dev-001
# Intent: intent-a1b2c3d4 (write)
# Expires in: 245s
#
# Options:
# 1. Wait for intent to expire
# 2. Coordinate with the blocking agent
# 3. Request the agent to release intent early
```
### release_file_intent
Release file intent after completing work.
**Parameters:**
- `agent_id` (string, required): ID of the agent releasing intent
- `intent_id` (string, optional): Specific intent ID to release
- `files` (list[string], optional): Files to release intents for (alternative to intent_id)
**Returns:** Success message or error
**Constraints:**
- Must specify either `intent_id` OR `files`
- Cannot release another agent's intent
**Example:**
```python
release_file_intent(
agent_id="Node-Dev-001",
intent_id="intent-a1b2c3d4"
)
# Returns: ✅ Released 1 intent(s): intent-a1b2c3d4
```
### get_file_intents
List all active file intents with optional filtering.
**Parameters:**
- `agent_id` (string, optional): Filter by agent ID
- `file_path` (string, optional): Filter by file path
**Returns:** Formatted list of active file intents
**Example:**
```python
get_file_intents()
# Returns:
# 📋 Active File Intents
# ==================================================
#
# 🟢 intent-a1b2c3d4
# Agent: Node-Dev-001
# Type: WRITE
# Files: src/server.py, src/utils.py
# Description: Adding new API endpoint
# Expires in: 245s
#
# Total active: 1
```
## State Schema
File intents are stored in the `file_intents` field of state.json:
```json
{
"file_intents": {
"intent-a1b2c3d4": {
"id": "intent-a1b2c3d4",
"agent_id": "Node-Dev-001",
"files": ["src/server.py", "src/utils.py"],
"intent_type": "write",
"description": "Adding new API endpoint",
"created_at": 1770097411.123,
"expires_at": 1770097711.123
}
}
}
```
### Intent Types
| Type | Behavior |
|------|----------|
| `write` | Exclusive - conflicts with other write intents on same files |
| `read` | Shared - only conflicts with write intents, not other reads |
## Integration with read_state
The `read_state` tool now displays file intent summary and conflicts:
```
**File Intents (Active):**
📝 Node-Dev-001:
- src/server.py, src/utils.py [write] (245s)
📝 Node-Dev-002:
- tests/test_api.py [write] (180s)
⚠️ FILE CONFLICTS:
- src/server.py: Node-Dev-001, Node-Dev-003
```
## Automatic Expiration
Intents automatically expire after their TTL (default: 5 minutes). This handles:
1. **Crashed agents**: If an agent crashes without releasing intents, they expire automatically
2. **Forgotten releases**: If an agent forgets to release, the system self-heals
3. **Long-running work**: Agents can set longer TTLs for complex tasks
Expired intents are cleaned up during any file intent operation.
## Best Practices
### For Developers
1. **Always declare intent before starting work** on files
2. **Check for conflicts first** with `check_file_conflicts` before declaring
3. **Release intents promptly** when done, don't rely on expiration
4. **Use appropriate TTL** - extend for complex work, keep short for quick fixes
5. **Coordinate with blocking agents** rather than waiting for timeout
### For Bootstrap Managers
1. **Monitor file intents** in read_state output
2. **Watch for conflicts** and help coordinate between agents
3. **Set reasonable TTLs** based on expected task duration
4. **Consider file overlap** when assigning tasks to avoid conflicts
### Recommended Workflow
```python
# 1. Check before claiming
conflicts = check_file_conflicts(["src/main.py"], agent_id="Node-001")
if "No conflicts" in conflicts:
# 2. Declare intent
declare_file_intent("Node-001", ["src/main.py"], description="Bug fix")
# 3. Submit code audit (if required by governance)
submit_code_audit_request(...)
# 4. Wait for approval
# ... (check audit status)
# 5. Do the actual work
# ... (make file changes)
# 6. Release intent
release_file_intent("Node-001", files=["src/main.py"])
```
## Comparison with Code Audit Governance
| Feature | File Coordination | Code Audit |
|---------|------------------|------------|
| Purpose | Prevent simultaneous edits | Review before changes |
| Blocking | Soft (warnings) | Hard (must be approved) |
| Expiration | Automatic TTL | Manual approval/rejection |
| Scope | File-level | Change-level |
| Use together? | Yes - coordinate first, then audit |
## Version History
- **v0.7.0** (2026-02-02): Initial implementation of file coordination governance
- Added 4 MCP tools for intent workflow
- Integrated with state.json schema
- Added intent display and conflict warnings to read_state
- 22 tests passing
