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.0.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.0.0
File Size Uploaded Provenance Actions
spoq-1.0.0.tar.gz 452.3 kB Without provenance Details for spoq-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 754.3 kB

Release files / spoq-1.0.0.tar.gz

Download URL spoq-1.0.0.tar.gz
Size 452.3 kB
Tags Source
SHA-256 checksum
How to use checksums
529c4c8924f630b7ad1ecf34ece4f95b1d6829069c9f8bac604cce1a7302dfb4
BLAKE2b-256 checksum
How to use checksums
c459a1668676a8961f3e940ee2eb5b661a3455661d299725d65e726dfc4bc2b4
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.0.0-py3-none-any.whl

Download URL spoq-1.0.0-py3-none-any.whl
Size 302.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
84017a0ccf3d12a1286633f19e268a42676e1a4dc66db521dcd99e43b2ea41c6
BLAKE2b-256 checksum
How to use checksums
e8760e923766746aa95d0755b22980e8269272cbcd15bbd745b7605884c7a38c
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.0.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