the-nexus/docs/mission-cell-spec.md

# Mission Cell Directory Specification

**Issue:** #879 - [M6-P0] Foundation — cell spec, daemon skeleton, health heartbeat  
**Status:** Specification Complete

## Overview

This document specifies the directory structure and layout for Mission Cells in the Hermes fleet.

## Directory Structure

```
/var/missions/<uuid>/
├── cell.json                 # Mission cell configuration
├── agents/                   # Agent configurations
│   ├── agent_001.json
│   ├── agent_002.json
│   └── ...
├── tasks/                    # Task definitions
│   ├── task_001.json
│   ├── task_002.json
│   └── ...
├── checkpoints/              # Agent checkpoints
│   ├── agent_001/
│   │   ├── state.json
│   │   ├── context.json
│   │   └── artifacts/
│   └── ...
├── logs/                     # Mission logs
│   ├── mission.log
│   ├── agent_001.log
│   ├── agent_002.log
│   └── ...
├── artifacts/                # Mission artifacts
│   ├── code/
│   ├── docs/
│   ├── reports/
│   └── ...
└── config/                   # Mission configuration
    ├── isolation.json
    ├── policies.json
    └── permissions.json
```

## File Specifications

### cell.json
```json
{
  "cell_id": "uuid-v4",
  "mission_name": "Mission Name",
  "created_at": "ISO-8601 timestamp",
  "created_by": "agent_id",
  "status": "active|paused|completed|failed",
  "isolation_level": "none|level_1|level_2|level_3",
  "max_agents": 10,
  "timeout": 3600,
  "policies": {
    "auto_revive": "yes|no|ask",
    "handoff_allowed": true,
    "checkpoint_interval": 300
  }
}
```

### agent_001.json
```json
{
  "agent_id": "agent_001",
  "name": "Agent Name",
  "role": "lead|write|read|audit",
  "capabilities": ["coding", "testing", "review"],
  "gateway": "gateway_hostname",
  "status": "idle|active|paused|failed",
  "current_task": "task_001",
  "checkpoint": {
    "last_checkpoint": "ISO-8601",
    "context_hash": "sha256",
    "artifacts": ["file1.py", "file2.py"]
  }
}
```

### task_001.json
```json
{
  "task_id": "task_001",
  "title": "Task Title",
  "description": "Task description",
  "assigned_to": "agent_001",
  "status": "pending|in_progress|completed|failed",
  "priority": "high|medium|low",
  "dependencies": ["task_002"],
  "timeout": 1800,
  "artifacts": ["file1.py", "file2.py"],
  "created_at": "ISO-8601",
  "completed_at": "ISO-8601"
}
```

### isolation.json
```json
{
  "level": "none|level_1|level_2|level_3",
  "mount_namespaces": true,
  "network_isolation": true,
  "resource_limits": {
    "cpu": "2 cores",
    "memory": "4GB",
    "disk": "10GB"
  },
  "security_context": {
    "user": "agent_001",
    "group": "agents",
    "capabilities": ["NET_BIND_SERVICE"]
  }
}
```

### policies.json
```json
{
  "auto_revive": "yes|no|ask",
  "revive_timeout": 300,
  "substitute_agents": ["agent_003", "agent_004"],
  "handoff_allowed": true,
  "handoff_approval": "auto|manual",
  "checkpoint_required": true,
  "max_retries": 3
}
```

### permissions.json
```json
{
  "agent_001": {
    "read": ["task_001", "task_002"],
    "write": ["task_001"],
    "execute": ["task_001"],
    "handoff_to": ["agent_002"],
    "handoff_from": ["agent_002"]
  },
  "agent_002": {
    "read": ["task_001", "task_002"],
    "write": ["task_002"],
    "execute": ["task_002"],
    "handoff_to": ["agent_001"],
    "handoff_from": ["agent_001"]
  }
}
```

## Usage

### Create Mission Cell
```bash
# Create directory structure
mkdir -p /var/missions/$(uuidgen)
cd /var/missions/$(uuidgen)

# Create configuration files
cat > cell.json << EOF
{
  "cell_id": "$(uuidgen)",
  "mission_name": "Example Mission",
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "created_by": "admin",
  "status": "active",
  "isolation_level": "level_1",
  "max_agents": 4,
  "timeout": 3600
}
EOF

# Create subdirectories
mkdir -p agents tasks checkpoints artifacts config logs
```

### Add Agent
```bash
cat > agents/agent_001.json << EOF
{
  "agent_id": "agent_001",
  "name": "Lead Agent",
  "role": "lead",
  "capabilities": ["planning", "coordination"],
  "gateway": "gateway_1",
  "status": "idle",
  "current_task": null,
  "checkpoint": null
}
EOF
```

### Add Task
```bash
cat > tasks/task_001.json << EOF
{
  "task_id": "task_001",
  "title": "Code Review",
  "description": "Review pull request #123",
  "assigned_to": "agent_001",
  "status": "pending",
  "priority": "high",
  "dependencies": [],
  "timeout": 1800,
  "artifacts": [],
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF
```

## Integration with Hermes

### Loading Mission Cell
```python
# In agent/mission_cell.py
from pathlib import Path
import json

class MissionCell:
    def __init__(self, cell_path: Path):
        self.cell_path = cell_path
        self.config = self._load_config()
        self.agents = self._load_agents()
        self.tasks = self._load_tasks()
    
    def _load_config(self):
        config_path = self.cell_path / "cell.json"
        with open(config_path) as f:
            return json.load(f)
    
    def _load_agents(self):
        agents = {}
        agents_dir = self.cell_path / "agents"
        if agents_dir.exists():
            for agent_file in agents_dir.glob("*.json"):
                with open(agent_file) as f:
                    agent = json.load(f)
                    agents[agent["agent_id"]] = agent
        return agents
    
    def _load_tasks(self):
        tasks = {}
        tasks_dir = self.cell_path / "tasks"
        if tasks_dir.exists():
            for task_file in tasks_dir.glob("*.json"):
                with open(task_file) as f:
                    task = json.load(f)
                    tasks[task["task_id"]] = task
        return tasks
```

### Exposing via MCP
```python
# In agent/mcp_server.py
server.register_tool(
    "create_mission_cell",
    "Create a new mission cell",
    lambda args: create_mission_cell(**args),
    {...}
)

server.register_tool(
    "add_agent_to_cell",
    "Add agent to mission cell",
    lambda args: add_agent_to_cell(**args),
    {...}
)
```

## Benefits

1. **Standardized structure** for all mission cells
2. **Isolation** through directory-based separation
3. **Persistence** through file-based storage
4. **Auditability** through logs and artifacts
5. **Portability** through JSON configuration

## Related Issues

- **Issue #879:** This specification
- **Issue #878:** Parent epic
- **Issue #882:** Resurrection Pool (agent management)
- **Issue #883:** Multi-Agent Teaming (mission structure)

## Files

- `docs/mission-cell-spec.md` - This specification
- `templates/cell.json` - Template for cell configuration
- `templates/agent.json` - Template for agent configuration
- `templates/task.json` - Template for task configuration

## Conclusion

This specification provides a standardized directory structure for Mission Cells, enabling:
1. **Consistent organization** across all missions
2. **Easy automation** through JSON configuration
3. **Clear separation** between agents, tasks, and artifacts
4. **Simple backup/restore** through directory operations

**Ready for implementation.**