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

Built distribution (wheel)

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

Total release size: 1.3 MB

Release files / spoq-1.1.1.tar.gz

Download URL spoq-1.1.1.tar.gz
Size 759.9 kB
Tags Source
SHA-256 checksum
How to use checksums
788d75560bf8cbcee1f016e7da66c140f1b3f7a64af2ce2fbf0e4edfba2ca127
BLAKE2b-256 checksum
How to use checksums
8b7292f893f5cdb08cc6f64180c53111b1aab64b3a8bc64033c91a59d0541c47
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.1-py3-none-any.whl

Download URL spoq-1.1.1-py3-none-any.whl
Size 534.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eecd7a359b7761839d8eed8f916123799c53ba7f1eef7ec4ff5983e1797726b8
BLAKE2b-256 checksum
How to use checksums
74aa71aac5240cae23f9ce009e269d8c43d3a7aaef462be5a124764a690996af
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.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