# Amicus MCP: Comprehensive Improvement Plan
This document outlines the detailed strategies and implementation paths for the features identified in the [ROADMAP.md](ROADMAP.md).
## 1. Installation & Distribution ("Magic Install")
**Objective:** Zero-config, single-command installation that works globally.
### 1.1 Multi-Tier Configuration
* **Implementation:** Implement a cascading configuration system using `pydantic-settings` or a similar robust library.
1. **CLI Flags:** Highest precedence (e.g., `--dir /path/to/bus`).
2. **Environment Variables:** `AMICUS_DIR`, `AMICUS_CONFIG`.
3. **Local Config:** `.amicus/config.toml` in the project root.
4. **Global Config:** `~/.config/amicus/config.toml` for user-wide defaults.
* **Action:** Refactor `server.py` to use a `Config` class that merges these sources.
### 1.2 Packaging & Delivery
* **Standalone Binaries:** Use `PyInstaller` or `Nuitka` to build self-contained executables for macOS (arm64/x64), Linux, and Windows.
* **Package Managers:**
* **Homebrew:** Create and maintain an official Tap (`brew install amicus-mcp/tap/amicus`).
* **PyPI:** Ensure the package is easily installable via `pipx install amicus-mcp`.
* **Universal Installer:** Provide a shell script `curl | sh` that detects the environment and chooses the best installation method.
## 2. Documentation ("Truthful & Usable")
**Objective:** Documentation that is always accurate and highly practical.
### 2.1 Self-Validating Examples
* **Strategy:** Use `phmdoctest` or similar tools to extract and run code snippets from `README.md` and `docs/*.md` during CI.
* **Pattern Library:** Document "Synapse Patterns" for common multi-agent workflows (e.g., Handoff, Peer Review, Parallel Execution).
### 2.2 CLI-Integrated Help
* **Feature:** `amicus --explain <tool_name>` should provide detailed usage guides, common pitfalls, and examples for each MCP tool, pulled directly from the source code docstrings.
## 3. Automation & "Magic" Orchestration
**Objective:** Seamless agent handoffs and autonomous long-running sessions.
### 3.1 Heartbeat & Zombie Recovery
* **Problem:** Stale "IN PROGRESS" markers block the project if an agent crashes.
* **Solution:**
* Add a `heartbeat()` tool that agents call every 30-60 seconds.
* Store a `last_heartbeat` timestamp in the state.
* Server automatically transitions "IN PROGRESS" tasks back to "TODO" if the heartbeat is missed by > 2 cycles.
### 3.2 Agent-to-Agent "Side-Channel" Messaging
* **Mechanism:** Implement `post_note(recipient, content)` and `read_notes()` tools.
* **Use Case:** Passing transient data (e.g., "Server running at PID 1234") that shouldn't clutter the main `summary`.
### 3.3 Structured Task Queue
* **Upgrade:** Replace the free-text `next_steps` with a structured list of task objects:
```json
{
"id": "uuid",
"task": "Implement feature X",
"status": "TODO | IN_PROGRESS | DONE | BLOCKED",
"assigned_to": "Node-ID",
"dependencies": ["uuid-1"]
}
```
* **Benefit:** Enables true parallelization and clear dependency tracking between nodes.
## 4. Sandboxing & Guardrails
**Objective:** Protect the host system and ensure project integrity.
### 4.1 Filesystem Confinement
* **Implementation:** Strictly validate all file paths provided to tools against the `workspaceRoot`.
* **Feature:** Provide a `safe_read_file` tool that automatically rejects paths outside the project or inside sensitive directories (e.g., `.git`, `.env`).
### 4.2 Sensitive Data Protection
* **Mechanism:** Implement an automated scanner that checks `summary` and `next_steps` for secrets (API keys, credentials) before saving.
* **Action:** Integrate `detect-secrets` patterns into the `update_state` validation logic.
## 5. Consensus & Collective Direction
**Objective:** Agents should move toward the same goal without manual intervention.
### 5.1 Voting & Decision Records
* **Feature:** Agents can `propose_decision(plan)` which other nodes must `vote_on(id, decision)`.
* **Rule:** High-impact tasks (marked in the queue) require at least 2 "APPROVE" votes before they can be claimed.
### 5.2 Goal Alignment Checks
* **Strategy:** The `catch_up` prompt will periodically include a "Goal Verification" step, requiring the agent to state how their current task contributes to the `Primary Objective`.
