Set Up Parallel AI Agent Orchestration in 5 Minutes

Install, plan your first epic, and dispatch parallel agents.

Prerequisites

Python 3.12+ & pipx
Required to install the SPOQ package from PyPI — installed in Step 1 below
Claude Code CLI
The AI coding assistant that powers SPOQ — installed in Step 2 below
Claude Account
A Claude account with an active subscription for Claude Code access
Git Repository
SPOQ operates within Git repositories for version control and change tracking

Installation

Agent

Install Python & pipx

Install Python 3.12+ and pipx, the recommended tool for installing Python CLI applications in isolated environments.

bash

brew install python pipx && pipx ensurepath

Install your coding agent CLI

SPOQ orchestrates Claude Code, Qwen Code, Codex, or Cursor. Pick your agent with the selector above — the command below updates to match.

bash

curl -fsSL https://claude.ai/install.sh | bash

Install SPOQ

Install the SPOQ package from PyPI. This gives you the MCP server, CLI, and project scaffolding.

bash

pipx install spoq

Bootstrap Your Project

Initialize SPOQ in your project directory. This scaffolds skills, templates, and the MCP server for your selected agent. Pass a comma-separated list (e.g. --agents claude,qwen,codex,cursor) to support several at once. See flag options below.

bash

spoq init --target /path/to/project --with-mcp --agents claude

Flag Options

Flag	Description
`--target <path>`default	Initialize SPOQ in a specific project directory
`--with-mcp`	Configure .mcp.json so Claude Code discovers SPOQ tools automatically
`--full`	Include an example epic with 4 tasks across 3 waves
`--upgrade`	Upgrade an existing SPOQ installation to latest skill definitions
`--agents claude,qwen,codex,cursor`	Scaffold for one or more coding agents — Claude, Qwen, Codex, and/or Cursor (default: claude)

Install Python & pipx

Install Python 3.12+ and pipx, the recommended tool for installing Python CLI applications in isolated environments.

bash

brew install python pipx && pipx ensurepath

Install your coding agent CLI

SPOQ orchestrates Claude Code, Qwen Code, Codex, or Cursor. Pick your agent with the selector above — the command below updates to match.

bash

curl -fsSL https://claude.ai/install.sh | bash

Install SPOQ

Install the SPOQ package from PyPI.

bash

pipx install spoq

Upgrade SPOQ

Update an existing SPOQ installation to the latest skill definitions and templates without overwriting custom configuration.

bash

spoq init --upgrade --target /path/to/project

Works With Claude, Qwen, Codex & Cursor

SPOQ is agent-agnostic. The --agents flag scaffolds each coding agent with its own native conventions — context file, command format, and MCP registration — so the same epics and quality gates run wherever you work. Pass one or more comma-separated keys (default is claude).

bash

spoq init --target /path/to/project --with-mcp --agents claude,qwen,codex,cursor

Agent	--agents key	Context file	Commands	MCP registration	Worker / Investigator
Claude	`claude`	`CLAUDE.md`	`.claude/skills/`	`.mcp.json + settings.json`	Opus / Haiku
Qwen	`qwen`	`QWEN.md`	`.qwen/commands/*.toml`	`.qwen/settings.json`	qwen3-coder-plus / qwen3-coder-flash
Codex	`codex`	`AGENTS.md`	`.agents/skills/`	`.codex/config.toml`	gpt-5.5 / gpt-5.4-mini
Cursor	`cursor`	`AGENTS.md`	`.cursor/commands/`	`.cursor/mcp.json`	composer-1 / cursor-small

For non-Claude agents the bundled SPOQ skills are translated into the agent's command format, and Claude's model hierarchy is remapped to each agent's own Worker, Reviewer, and Investigator tiers.

The 3-Tier Lifecycle

Every epic and map moves through three tiers. Ideas start in the backlog, get promoted to active when ready for execution, and land in complete once all tasks pass validation.

Backlog

Planned work that is not yet scheduled. Epics here are visible in the roadmap but excluded from wave dispatch until promoted.

spoq/epics/backlog/

Active

Work in progress. Only active epics are dispatched into execution waves by the orchestrator.

spoq/epics/active/

Complete

Finished work that passed agent validation. Moved here automatically when the final task completes.

spoq/epics/complete/

ROADMAP.yml

The machine-readable roadmap tracks every epic across all three tiers. MCP tools query and update this file automatically as epics move through the lifecycle.

yaml

version: 1
updated_at: "2026-03-27T12:00:00Z"
epics:
  - slug: mobile-redesign
    title: Mobile Redesign
    tier: backlog
    status: pending
    priority: 3
    dependencies: []

  - slug: auth-system
    title: User Authentication
    tier: active
    status: in_progress
    priority: 1
    dependencies: []

  - slug: seo-optimization
    title: SEO Audit & Fixes
    tier: complete
    status: completed
    completed_date: "2026-03-15"
    dependencies: []

TODO.yml

While ROADMAP.yml captures the strategic epic-level view, TODO.yml provides time-boxed task tracking for day-to-day work. It organizes items into weekly and monthly sections, supports standalone tasks with priority levels, and can reference active maps. Created automatically by spoq init.

yaml

version: 1
updated_at: "2026-03-28T10:00:00Z"

sections:
  - title: This Week
    period: weekly
    items:
      - task: Wire up auth middleware
        status: done
      - task: Add rate limiting to API
        status: in_progress
      - task: Review deployment checklist
        status: pending

  - title: March Goals
    period: monthly
    items:
      - task: Ship v1.0 public beta
        status: in_progress
      - task: Onboard two pilot teams
        status: pending

standalone:
  - task: Fix flaky CI job
    status: pending
    priority: high

maps:
  - spoq/maps/active/q1-launch

Auto-Upgrade Detection

The MCP server automatically detects outdated project structure on startup. Agents receive upgrade instructions via spoq_ping and can run spoq init --upgrade to bring the project up to date without manual intervention.

MCP Tools Reference

The SPOQ MCP server exposes 27 tools organized into seven categories. Agents discover and invoke these automatically during epic planning, execution, and validation.

Epic Management8 tools

Map Management7 tools

Task Management3 tools

Team Execution2 tools

Lifecycle3 tools

Roadmap2 tools

Utilities2 tools

Your First Epic

SPOQ follows a four-stage pipeline. Here's how it works:

Plan

Decompose a high-level goal into atomic tasks with explicit dependencies and acceptance criteria. SPOQ builds a directed acyclic graph (DAG) for parallel dispatch.

/epic-planning "Add config validation to CLI"

Epic: config-validator
Tasks: 6 atomic units identified
Dependencies: 4 edges in task DAG
Waves: 3 parallel execution waves
Critical path: 3 tasks

Wave 1: [T01] Define schema types, [T02] Create validation utils
Wave 2: [T03] Build CLI parser, [T04] Add error formatters
Wave 3: [T05] Integration tests, [T06] Documentation

Output: spoq/epics/config-validator/epic.yaml

Validate

Score the epic against 10 planning quality metrics. Both the average (>=95) and per-metric minimum (>=90) thresholds must pass before execution begins.

/epic-validation @spoq/epics/config-validator

Planning Validation Results
─────────────────────────────
Vision Clarity       98/100
Architecture Qual.   96/100
Task Decomposition   97/100
Dependency Graph     95/100
Coverage Complete.   96/100
Phase Ordering       94/100
Scope Coherence      92/100
Success Criteria     95/100
Risk Identification  97/100
Integration Strat.   93/100
─────────────────────────────
Average: 95.3  Minimum: 92
Result: PASS

Execute

Dispatch agent swarms across computed waves. Worker agents (Opus) execute tasks in parallel within each wave, respecting dependency ordering between waves.

/agent-execution @spoq/epics/config-validator

Agent Execution Started
═══════════════════════════════
Wave 1/3 - Dispatching 2 agents
  [T01] Worker-A: Define schema types .... DONE (2m 14s)
  [T02] Worker-B: Create validation utils  DONE (3m 08s)

Wave 2/3 - Dispatching 2 agents
  [T03] Worker-A: Build CLI parser ........ DONE (4m 22s)
  [T04] Worker-B: Add error formatters .... DONE (2m 47s)

Wave 3/3 - Dispatching 2 agents
  [T05] Worker-A: Integration tests ....... DONE (3m 55s)
  [T06] Worker-B: Documentation ........... DONE (1m 33s)

All 6 tasks completed in 3 waves
Total wall-clock time: 11m 09s
Sequential baseline:   ~58m
Speedup: 5.2x

Verify

Score delivered code against 10 quality metrics. The average must reach 95 and no individual metric may fall below 80. Failed validations trigger targeted rework.

/agent-validation

Code Validation Results
─────────────────────────────
Syntactic Correct.   98/100
Test Existence       96/100
Test Pass Rate       97/100
Requirements Fidel.  94/100
SOLID Adherence      92/100
Security             96/100
Error Handling       95/100
Scalability          97/100
Code Clarity         96/100
Completeness         98/100
─────────────────────────────
Average: 95.9  Minimum: 92
Result: PASS

All tasks validated. Epic complete.

Run SPOQ Against a Local Qwen Model

Local inference

Skip API costs and keep code on-prem by pointing SPOQ at a Qwen GGUF served through llama.cpp. Our benchmark paper shows SPOQ-on-Qwen3.6-35B-A3B reaches 91.2 planning coverage — within 1.8 points of Claude's unaided baseline (93.0).

Setup (one-time)

Build llama.cpp

Clone and build llama.cpp from source. CUDA and Metal builds are supported via the standard CMake flags.

bash

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release -j

Download a Qwen GGUF model

Any Qwen GGUF variant works. The local SPOQ reference setup uses the Unsloth dynamic-quant Q5_K_M for the 35B A3B MoE; smaller machines can drop to Q4_K_M or pick a Qwen2.5-Coder variant.

bash

mkdir -p models
huggingface-cli download \
  unsloth/Qwen3-A3B-GGUF \
  Qwen3.6-35B-A3B-UD-Q5_K_M.gguf \
  --local-dir ./models

Start llama-server

Serve the model on the OpenAI-compatible endpoint. SPOQ defaults to port 8080; override with --port if it clashes. The --parallel flag sets the slot count; SPOQ caps wave concurrency to this number to avoid bimodal queuing regressions.

bash

./build/bin/llama-server \
  -m ./models/Qwen3.6-35B-A3B-UD-Q5_K_M.gguf \
  --host 0.0.0.0 --port 8080 \
  --ctx-size 32768 \
  --parallel 2 \
  --n-gpu-layers 999

Bootstrap your project with the Qwen templater

spoq init --qwen installs the Qwen Code variant alongside the Claude Code variant: .qwen/skills/ with the full skill set, a QWEN.md guide, and the standard 3-tier SPOQ directory structure. Add --with-mcp to wire up the SPOQ MCP server for both editors.

bash

pipx install spoq
spoq init --target /path/to/project --qwen --with-mcp --full

Pick an execution path

Both paths use the same skills and produce the same epic structure. The choice is between in-REPL serial execution and Rust-orchestrator parallel dispatch.

Path A — In-REPL with Qwen CodeSerial · single context

Drop into the qwen-code TUI and invoke SPOQ skills directly. Best for small epics, debugging plans, and single-developer flow. The skill set is byte-compatible with Claude Code, so /skills epic-planning works identically.

bash

# Install qwen-code (Alibaba's Claude-Code-style CLI)
npm install -g @qwen-code/qwen-code

# Launch against the local llama-server
qwen --auth-type openai \
     --openai-base-url http://localhost:8080/v1 \
     --openai-api-key dummy \
     --model "Qwen3.6-35B-A3B-UD-Q5_K_M.gguf" \
     --approval-mode auto-edit

# Inside the REPL
/skills epic-planning
/skills epic-validation
/skills agent-execution

Path B — Parallel waves with spoq-rsParallel · slot-bounded

Use the Rust orchestrator to dispatch wave-parallel against the OpenAI-compat endpoint. Parallelism is bounded by llama-server's --parallel slot count, which yields a stable ~1.4x speedup vs serial on a 2-slot box. Best for benchmark runs and epics with non-trivial parallelism.

bash

# Defaults: base_url=http://localhost:8080/v1, model=Qwen3.6-35B-A3B-UD-Q5_K_M.gguf
spoq-rs run --provider qwen spoq/epics/active/my-epic

# Custom endpoint + model
SPOQ_QWEN_BASE_URL=http://gpu-box:8080/v1 \
SPOQ_QWEN_MODEL=Qwen2.5-Coder-32B-Instruct.gguf \
spoq-rs run --provider qwen spoq/epics/active/my-epic

Heads up: local inference runs all three SPOQ agent roles (worker, reviewer, investigator) against the same model. Use a coder-tuned Qwen variant if you care about worker-quality output, and keep --parallel at or below your VRAM budget — the SPOQ wave dispatcher caps concurrency to the slot count to avoid overcommit regressions.

Ready for Persona-Specialized Teams?

You've seen how /agent-execution dispatches parallel swarms. Agent Teams takes it further with persona-specialized workers, inter-agent messaging, and proactive conflict detection.

Explore Agent Teams

Command Reference

Command	Description	Example
`/epic-planning`	Decompose goals into structured epics with atomic tasks, dependency graphs, and parallel execution waves	`/epic-planning "Implement user authentication system"`
`/epic-validation`	Score epic quality against 10 planning metrics with 95 average and 90 per-metric thresholds	`/epic-validation @spoq/epics/auth-system`
`/agent-execution`	Execute tasks with parallel agent swarms across topologically computed waves	`/agent-execution @spoq/epics/auth-system`
`/agent-validation`	Score delivered code against 10 quality metrics with 95 average and 80 per-metric thresholds	`/agent-validation`
`/team-execution`	Deploy persona-specialized agent teams with inter-agent messaging and conflict detection	`/team-execution @spoq/epics/auth-system`
`/epic-planning --map`	Coordinate multiple epics as a program with inter-epic dependencies and wave-based dispatch	`/epic-planning --map "Platform Migration"`
`/journal-tracker`	Record work sessions with timestamps, confidence scores, and file change provenance for explainability	`/journal-tracker`