# SPOQ

**Specialist Orchestrated Queuing** for multi-agent AI development.

SPOQ coordinates AI coding agents through wave-based parallel execution with structured quality gates. It provides an MCP server with 29 tools, a CLI for project scaffolding, and template generators for epics and maps.

## Install

```bash
pip install spoq
```

## Quick Start

### 1. Initialize a project

```bash
spoq init --target /path/to/project --with-mcp
```

This creates the SPOQ directory structure, skill stubs for Claude Code, and configures `.mcp.json`.

### 2. Use with Claude Code

Once initialized, these slash commands are available in Claude Code:

```
/epic-planning          Plan an epic with atomic tasks and dependency DAG
/epic-validation        Score epic quality (10 metrics, 95/90 threshold)
/agent-execution        Execute tasks with parallel agent swarms
/agent-validation       Score delivered code (10 metrics, 95/80 threshold)
/team-execution         Persona-specialized agent teams
/epic-planning --map    Coordinate multiple epics as a program
```

### 3. Run the MCP server directly

```bash
spoq mcp
```

Or configure in `.mcp.json`:

```json
{
  "mcpServers": {
    "spoq": {
      "command": "spoq",
      "args": ["mcp"]
    }
  }
}
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `spoq mcp` | Run the MCP server (stdio transport) |
| `spoq init` | Bootstrap SPOQ in a project directory |
| `spoq init --full` | Include example epic and optional skills |
| `spoq init --with-mcp` | Configure .mcp.json |
| `spoq init --upgrade` | Upgrade existing installation |
| `spoq template epic <name> <tasks>` | Generate an epic skeleton |
| `spoq template map <name> <epics>` | Generate a map skeleton |
| `spoq --version` | Show version |

## MCP Tools (29)

**Epic Management:** `spoq_parse_epic`, `spoq_validate_epic`, `spoq_compute_waves`, `spoq_get_wave_tasks`, `spoq_analyze_dag`, `spoq_estimate_effort`, `spoq_generate_execution_plan`, `spoq_complete_epic`, `spoq_generate_skeleton` — `spoq_complete_epic` auto-updates ROADMAP.yml

**Map Management:** `spoq_parse_map`, `spoq_validate_map`, `spoq_compute_epic_waves`, `spoq_analyze_map_dag`, `spoq_estimate_map_effort`, `spoq_get_map_status`, `spoq_list_maps`, `spoq_generate_map_skeleton`

**Task Management:** `spoq_get_task`, `spoq_update_task_status`, `spoq_list_task_statuses`

**Team Execution:** `spoq_assign_personas`, `spoq_detect_conflicts`

**Lifecycle:** `spoq_list_epics`, `spoq_promote`, `spoq_demote`

**Roadmap:** `spoq_roadmap_show`, `spoq_roadmap_sync`

**Utilities:** `spoq_get_timestamp`, `spoq_ping`

## Links

- [Website](https://spoqpaper.com)
- [Quickstart Guide](https://spoqpaper.com/quickstart)
- [Methodology](https://spoqpaper.com/methodology)
- [Source Code](https://gitlab.com/kenth56/spoq)

## License

MIT
