Skip to main content

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 31 tools, a CLI for project scaffolding, and template generators for epics and maps.

Install

pip install spoq

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

To update an existing installation:

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

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.

/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
/workflow-execute       Compiled dynamic-workflow dispatch (Claude Code only)
/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

Codex equivalents:

$epic-planning
$epic-validation
$agent-execution
$agent-validation

3. Run the MCP server directly

spoq mcp

Or configure in .mcp.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

License

MIT

Metadata

Release files for spoq 0.7.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spoq 0.7.1
File Size Uploaded Provenance Actions
spoq-0.7.1.tar.gz 347.2 kB Without provenance Details for spoq-0.7.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spoq 0.7.1
File Interpreter ABI Platform Actions
spoq-0.7.1-py3-none-any.whl Python 3 none any Details for spoq-0.7.1-py3-none-any.whl

Total release size: 596.3 kB

Release files / spoq-0.7.1.tar.gz

Download URL spoq-0.7.1.tar.gz
Size 347.2 kB
Tags Source
SHA-256 checksum
How to use checksums
3538141d0f3994f06de7458157d5295dcea4b41c06c98ccc17869a2b1bfd50aa
BLAKE2b-256 checksum
How to use checksums
4f9da0f1b32978a7f459574e38745f08afbdbaf1e55bfa692bc5cf7f2b52c679
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / spoq-0.7.1-py3-none-any.whl

Download URL spoq-0.7.1-py3-none-any.whl
Size 249.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ef0bd3d332abf91080af70aaa8425b22a7c9ad162dc56bd9188fb6365e5abb57
BLAKE2b-256 checksum
How to use checksums
d52d6b4486a762b15af98742cbe567715a43b0b4373ea867ca52467a92a9921d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for spoq 0.7.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page