Skip to main content

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

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.

/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

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 1.1.0

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 1.1.0
File Size Uploaded Provenance Actions
spoq-1.1.0.tar.gz 757.2 kB Without provenance Details for spoq-1.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.3 MB

Release files / spoq-1.1.0.tar.gz

Download URL spoq-1.1.0.tar.gz
Size 757.2 kB
Tags Source
SHA-256 checksum
How to use checksums
d4de6d3c33dbd8e49cee0e03276203231a5e99283a84a8fe4a203b02ab55eb0c
BLAKE2b-256 checksum
How to use checksums
56ed056c38127dd49decb3504ce574b74e8178c2f341e9e4a1364daf4bc5eb57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

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

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

Security for spoq 1.1.0

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