# AI Collaboration Protocols - Agent Orchestration Platform
## Multi-Agent Coordination System
This document defines collaboration protocols for the **Agent Orchestration Platform** where multiple Claude Code agents operate concurrently within managed iTerm2 sessions.
## Agent Interaction Model
### **Primary Agent Roles**
- **Administrator**: Claude Desktop client managing the orchestration
- **Worker Agents**: Claude Code instances executing ADDER+ workflows
- **Session Coordinator**: MCP server managing agent lifecycle and communication
### **Communication Patterns**
```
Administrator (Claude Desktop)
↓ MCP Tools
MCP Server (FastMCP)
↓ iTerm2 API + Process Management
Worker Agents (Claude Code with ADDER+)
↔ Task Files (TODO.md, TASK_X.md, TESTING.md)
Worker Agents (Inter-Agent Communication)
```
## Claude Code Integration
### **CLI Command Integration**
The MCP server leverages Claude Code's comprehensive CLI capabilities:
**Process Management**:
```bash
# Agent activation (run from session root directory)
claude # Start interactive mode in current directory
# Agent startup with custom configuration
claude --model sonnet-3.5 --no-color --dangerously-skip-permissions
# Session management
claude --continue # Resume existing session
claude --resume # Resume interrupted session
# Single prompt execution
claude -p "your prompt" # Non-interactive single prompt
```
**Built-in Slash Commands Available to Agents**:
- **Project Management**: `/init`, `/permissions`, `/git`, `/test`, `/build`, `/deploy`
- **File Operations**: `/read`, `/write`, `/edit`, `/create`, `/delete`, `/search`, `/find`
- **Advanced Features**: `/web`, `/image`, `/shell`, `/context`, `/reset`
- **Debug & Diagnostics**: `/debug`, `/logs`, `/mcp-debug`, `/permissions`, `/config`
- **Custom Commands**: Project-level and personal command extensions
**iTerm2-Specific Features**:
- **Drag & Drop**: Files and images directly into Claude Code sessions
- **Split Panes**: Multiple agent instances in coordinated panes
- **Session Restoration**: Automatic recovery of agent sessions
- **Shell Integration**: Enhanced terminal integration capabilities
## System Prompt Integration
### **ADDER+ Prompt Prepending**
Every message sent to Worker Agents is automatically prepended with the complete **ADDER+ (Advanced Development, Documentation & Error Resolution)** system prompt, ensuring:
- **Consistent Workflow**: All agents follow identical task management protocols
- **Quality Standards**: Comprehensive technique integration (contracts, types, defensive, testing, functional)
- **Inter-Agent Coordination**: Standardized communication through documentation files
- **Error Resolution**: Systematic error handling with automatic task generation
### **Agent Naming Convention**
- **Unique Identification**: Each agent assigned `Agent_#` identifier (e.g., Agent_1, Agent_2)
- **Session Scope**: No duplicate agent numbers within the same session/codebase
- **Persistent Identity**: Agent numbers maintained across iTerm restarts
## Task-Based Communication Protocol
### **Primary Communication Channels**
1. **TODO.md**: Master task tracker with agent assignments and progress
2. **TASK_X.md**: Detailed implementation specifications with subtask tracking
3. **TESTING.md**: Live test status and results across all agents
4. **ABOUT.md**: Contextual documentation for directory understanding
### **Agent Coordination Workflow**
```
1. Administrator assigns tasks via TODO.md updates
2. Agents discover assignments through TODO.md reading
3. Agents execute TASK_X.md specifications with real-time updates
4. Agents communicate progress through checkbox completion
5. Agents coordinate through shared documentation files
6. Session status reflects aggregate agent progress
```
### **Claude Code Command Integration**
Agents can use all built-in Claude Code capabilities:
```
# File operations through Claude Code
/read development/TODO.md
/edit development/tasks/TASK_1.md
/search "contract violations" --type py
# Project management
/test # Run project tests
/git status # Check Git status
/build # Build project
# Debug and diagnostics
/debug # Show debug information and system state
/logs # View recent error logs and activity
/mcp-debug # Debug MCP server connection issues
/permissions # Check current file and tool permissions
/config # Verify Claude Code configuration
# Custom project commands
/project:setup # Custom setup routines
/project:deploy-staging # Deployment automation
```
## Security and Isolation
### **Process Separation**
- **Isolated Execution**: Each agent runs in separate Claude Code process
- **Codebase Boundaries**: Agents cannot access files outside assigned session root
- **Memory Isolation**: No shared memory between agent processes
- **Communication Constraints**: Only file-based communication through task documents
### **Claude Code Security Integration**
- **Permission Management**: Leverage `/permissions` command for access control
- **Dangerous Operations**: Use `--dangerously-skip-permissions` only in controlled environments
- **File Access**: Respect Claude Code's built-in file access patterns
- **Shell Integration**: Secure shell command execution through `/shell`
### **State Persistence**
- **Session Recovery**: Agent assignments and progress persist across restarts
- **Claude Code Continuity**: Use `--continue` and `--resume` for session restoration
- **Encrypted Storage**: Agent configurations and state encrypted at rest
- **Audit Trail**: All agent interactions logged with cryptographic integrity
## Error Handling and Recovery
### **Agent Failure Scenarios**
- **Process Termination**: Automatic agent restart with state recovery
- **iTerm Session Loss**: New tab creation with context restoration
- **Communication Failure**: Fallback to direct file monitoring
- **Corruption Detection**: Automatic task file validation and repair
### **Claude Code Error Integration**
- **Debug Mode**: Use `--mcp-debug` and `--verbose` for troubleshooting
- **Cost Monitoring**: Track token usage via `/cost` command
- **Context Management**: Monitor context size via `/context` command
- **Log Analysis**: Leverage `/logs` for debugging agent behavior
### **Recovery Protocols**
1. **Health Monitoring**: Continuous agent process and session health checks
2. **Automatic Restart**: Failed agents restarted with preserved context
3. **State Validation**: Task file integrity verified before agent assignment
4. **Conflict Resolution**: Merge conflicts in shared files resolved automatically
## Performance and Scalability
### **Concurrent Agent Limits**
- **Per Session**: Maximum 8 agents per codebase session
- **Total System**: Maximum 32 concurrent agents across all sessions
- **Resource Monitoring**: CPU and memory usage tracked per agent
- **Dynamic Scaling**: Agent creation throttled based on system resources
### **Claude Code Optimization**
- **Model Selection**: Use appropriate models (`--model`) based on task complexity
- **Output Format**: JSON output (`--output-format json`) for automation
- **Color Optimization**: Disable colors (`--no-color`) for performance
- **Context Optimization**: Regular `/compact` operations for long conversations
### **Optimization Strategies**
- **Lazy Loading**: Agent processes created on-demand
- **Resource Pooling**: Shared iTerm sessions for efficiency
- **Intelligent Scheduling**: Task assignment based on agent specialization
- **Batch Operations**: Multiple task updates processed atomically
## Integration Guidelines
### **MCP Tool Usage with Claude Code Integration**
```python
# Create session for new codebase with Claude Code optimization
create_session(
root_path="/path/to/project",
session_name="ProjectX",
claude_config={
"model": "sonnet-3.5",
"no_color": True,
"skip_permissions": False # Security-conscious
}
)
# Spawn specialized agents with Claude Code capabilities
create_agent(
session_id="ProjectX",
agent_name="Agent_1",
specialization="backend",
system_prompt_suffix="Focus on API development. Use /git and /test commands frequently.",
claude_commands=["/init", "/permissions allow-all"] # Initial setup commands
)
# Monitor progress including Claude Code metrics
status = get_session_status(session_id="ProjectX")
# Returns: {
# agents: [{
# name: "Agent_1",
# status: "working",
# needs_input: false,
# context_size: 12000,
# cost_tokens: 15000
# }]
# }
# Send message with Claude Code command integration
send_message_to_agent(
agent_name="Agent_1",
message="Implement user authentication system. Use /search to find existing patterns first."
)
```
### **Best Practices**
- **Clear Task Definitions**: Ensure TASK_X.md files contain comprehensive specifications
- **Claude Code Leverage**: Use built-in commands for efficiency (`/read`, `/write`, `/test`)
- **Regular Status Checks**: Monitor agent progress and context size
- **Conflict Prevention**: Coordinate file access through task dependencies
- **Resource Management**: Monitor system resources and Claude Code costs
- **Custom Commands**: Develop project-specific slash commands for repeated operations
This collaboration model enables sophisticated multi-agent development workflows while leveraging Claude Code's full capabilities, maintaining strict security, comprehensive audit trails, and seamless inter-agent coordination through standardized documentation protocols.
