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

Install Python & pipx

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

bash

# macOS
brew install python pipx && pipx ensurepath

# Ubuntu / Debian
sudo apt update && sudo apt install python3 python3-pip pipx && pipx ensurepath

Install Claude Code CLI

Download and install the Claude Code command-line interface.

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 creates skill stubs, templates, and configures the MCP server. See flag options below.

bash

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

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

Install Python & pipx

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

bash

# macOS
brew install python pipx && pipx ensurepath

# Ubuntu / Debian
sudo apt update && sudo apt install python3 python3-pip pipx && pipx ensurepath

Install Claude Code CLI

Download and install the Claude Code command-line interface.

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

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
    estimated_hours: 24
    dependencies: []

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

  - slug: seo-optimization
    title: SEO Audit & Fixes
    tier: complete
    status: completed
    completed_date: "2026-03-15"
    estimated_hours: 12
    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 29 tools organized into seven categories. Agents discover and invoke these automatically during epic planning, execution, and validation.

Epic Management9 tools

Map Management8 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, effort estimates, 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

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 estimate:   ~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.

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`