Metadata-Version: 2.5
Name: spoq
Version: 1.1.1
Summary: SPOQ: Multi-agent AI orchestration with wave-based parallel execution and quality gates
Project-URL: Homepage, https://spoqpaper.com
Project-URL: Repository, https://github.com/Durban-Designer/spoq
Project-URL: Documentation, https://spoqpaper.com/quickstart
Project-URL: Organization, https://testwithpinpoint.com
Author: Royce Carbowitz, Dheeraj Kumar
Maintainer-email: Pinpoint Technologies LLC <royce@testwithpinpoint.com>
License-Expression: MIT
Keywords: agents,ai,claude,mcp,orchestration,spoq
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.30
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: tomlkit<1,>=0.13
Provides-Extra: codex
Requires-Dist: websockets<17,>=14; extra == 'codex'
Provides-Extra: search
Requires-Dist: fastembed<1,>=0.9.1; extra == 'search'
Requires-Dist: pillow>=13.0.0; extra == 'search'
Requires-Dist: sqlite-vec==0.1.9; extra == 'search'
Description-Content-Type: text/markdown

# SPOQ

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

SPOQ 1.0 coordinates AI coding agents using SQLite, structured validation history,
and the hierarchy **Project Plan → Feature → Task**. Features contain task DAGs;
Project Plans contain Feature DAGs. A durable collaboration board supports peer
messages and Codex notifications, with FTS5 and optional CPU embedding search.

Upgrades prompt to convert old maps into Project Plans and epics into Features,
preserving original files and creating backups. Run `spoq migrate --dry-run`, then
`spoq init --upgrade --agents codex --with-mcp` to preview and confirm conversion.
See the repository's `documents/operational/SPOQ_1_UPGRADE.md` for the current
interface and live E2E harness. The older command reference below remains for
explicit `SPOQ_STORE=fs`/`api` legacy mode.

The public workflows are `/spoq-plan <goal>` for planning and `/spoq <goal-or-id>`
for the complete discovery-to-verification flow. Initialization installs them in
your coding agent's native format. Codex users can select `$spoq-plan` or `$spoq`
through skill mentions. The workflows use the CLI when MCP is unavailable.

## Install

```bash
pip install spoq
```

Python 3.12 or later is required. SPOQ installs the compatible MCP 1.x SDK
automatically.

To update an existing installation:

```bash
pipx upgrade spoq
# For installations managed with pip:
python -m pip install --upgrade spoq
```

Restart your coding agent after upgrading so it reloads the MCP server.

## Quick Start

### 1. Initialize a project

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

This creates the SPOQ directory structure, installs the selected agent integration, and configures MCP when requested.

### 2. Use with your coding agent

Claude and Qwen use slash commands. Codex uses skills from `.agents/skills`, so invoke them with `$skill-name` or from `/skills`.

```
/spoq                  Compose the entire flow from goal to tested completion
/spoq-plan             Save Project Plan and Feature/task DAGs; run planning gate
/spoq-plan-validation  Check planning readiness (10 metrics, 95/90 threshold)
/spoq-execution        Execute saved work; invoke code validation and bounded rework
/spoq-validation       Check delivered code (10 metrics, 95/80, passing checks)
```

Codex equivalents:

```
$spoq
$spoq-plan
$spoq-plan-validation
$spoq-execution
$spoq-validation
```

### 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 init --agents claude,qwen,codex,cursor` | Scaffold for the selected coding agents: `.claude/skills`, `.qwen/commands`, `.agents/skills`, `.cursor/commands` (default: claude) |
| `spoq template epic <name> <tasks>` | Generate an epic skeleton |
| `spoq template map <name> <epics>` | Generate a map skeleton |
| `spoq --version` | Show version |

## MCP Tools (31)

**Epic Management:** `spoq_parse_epic`, `spoq_validate_epic`, `spoq_compute_waves`, `spoq_get_wave_tasks`, `spoq_analyze_dag`, `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_get_map_status`, `spoq_list_maps`, `spoq_generate_map_skeleton`

**Feature Aliases:** `spoq_list_features`, `spoq_parse_feature`, `spoq_validate_feature`, `spoq_get_feature_status`

**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://github.com/Durban-Designer/spoq)

## License

MIT
