# mcp-supervisor-squad

Python MCP server that implements a minimal “supervisor + coder squad” workflow with brief status.

## Tools (public MCP API)

- `squad_start(cwd, query, options?)` → creates a run, writes requirements docs under repo `.codex/`, dispatches coder jobs in worktrees, returns brief status (`lines` ≤ 3).
- `squad_status(run_id, options?)` → returns brief status (`lines` ≤ 3) using cached state (no stdout tail by default).
- `squad_apply(run_id, options?)` → applies the final patch with `git apply` (`dry_run` default true).

All tool responses include:

```json
{
  "run_id": "v5-...",
  "next_action": "wait|apply",
  "recommended_poll_ms": 15000,
  "wait_reason": "agent_running|ready_to_apply|error",
  "lines": ["...<=3 lines..."]
}
```

## Storage layout (repo-local)

Under `<repo_root>/.codex/squad-v5/`:

- `runs/<run_id>/state.json` – run state and brief cache
- `runs/<run_id>/artifacts/requirements*.md` – requirements docs written before dispatch
- `runs/<run_id>/artifacts/contract.json` – dual-project contract (<=4KB)
- `runs/<run_id>/artifacts/patch.diff` – final patch to apply
- `runs/<run_id>/jobs/<job_id>/*` – codex exec stdout/stderr/meta
- `worktrees/<run_id>/<slug>` – per-task git worktrees (best-effort cleanup)
- `kb/prune_meta.json` – prune rate limit state

## Development

```bash
cd mcp-tools/mcp-supervisor-squad
poetry install
```

## Running

```bash
poetry run mcp-supervisor-squad --transport stdio
```

## Testing

```bash
python -m compileall src/mcp_supervisor_squad
```
