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
Links
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.