# Project Specification: "Amicus: The Synapse Protocol"
**Objective:** Build a Python-based MCP server to act as a state persistence layer ("Context Bus") between distinct AI coding agents (Gemini, Copilot, Claude) in VS Code.
**Philosophy:**
* **Correctness:** State must never be lost or corrupted by race conditions.
* **Completeness:** The server must handle all CRUD operations for context and expose clear Prompts for "catching up."
* **Resilience:** The system must self-heal from "stale locks" caused by crashed agents.
**Implementation Requirements:**
1. **Tech Stack:**
* Language: Python 3.10+
* Framework: `fastmcp` (latest beta)
* Locking: `portalocker` (Cross-platform file locking)
* Data: JSON file storage (Default: `.ai/state.json`)
2. **Configuration:**
* Respect `CONTEXT_BUS_DIR` environment variable.
* Default to `{CWD}/.ai/` if unset.
* **Auto-Ignore:** Ensure `.ai/` is added to `.gitignore` automatically on first run.
3. **Concurrency & Safety (Critical):**
* Implement **Stale Lock Detection**: Before acquiring a lock, check if the lock file is older than **10 seconds**. If so, force delete it to prevent deadlocks.
* Use atomic writes (write to `temp`, then `os.replace`) to ensure `state.json` is never read in a partial state.
4. **Tools to Implement:**
* `update_state(summary, next_steps, active_files, ask_user: bool)`: atomic write with locking.
* `read_state()`: atomic read.
* `toggle_tracking(enabled: bool)`: Pauses updates for throwaway sessions.
5. **Prompts to Implement:**
* `catch_up`: Injects the `read_state` output into the chat with specific "Ignore previous instructions" headers to reset agent focus.
6. **Critical Logic (The "Elicitation" Pattern):**
* If `ask_user` is set to `True` in `update_state`, the `read_state` resource MUST append a high-priority string: "🚨 PREVIOUS AGENT REQUESTED HUMAN INPUT."
**Deliverables:**
* `server.py`: The executable MCP server.
* `pyproject.toml`: Dependency management (uv/poetry).
* `README.md`: Instructions for adding to `.github/mcp.json`.
## Agent Orchestration & Cluster Management
1. **Self-Managing Cluster Agent Spawn:**
* Agents should be able to dynamically spawn new agents within a cluster.
* Intelligent model selection based on role requirements (e.g., cheaper models for bootstrap, specialized models for specific tasks).
2. **Bootstrap Manager:**
* A designated "bootstrap manager" agent, initially using a least-expensive model, is responsible for initiating and overseeing the cluster.
* Mechanism for other nodes to detect bootstrap manager failure and elect/spawn a new one, injecting new instructions into the shared context.
* The primary interface for users to interact with the cluster and inject new instructions.
**Naming Selection:**
* **Amicus** (Selected)
