Parallel Agent Development

Orchestrate massively parallel development by decomposing work into independent tasks that multiple Claude Code instances can execute simultaneously.

CLI Tool: cpo (Claude Parallel Orchestrator)

The cpo CLI tool handles parallel agent execution with git worktree isolation.

Installation

pip install claude-parallel-orchestrator
# or
pipx install claude-parallel-orchestrator

cpo Commands

Workflow Overview

/parallel-setup       -> One-time: creates parallel/ directory
         |
/parallel-decompose   -> Per Tech Spec: creates TS-XXXX-slug/ with all artifacts
         |
/parallel-run         -> Delegates to `cpo run` for execution
         |
/parallel-integrate   -> Verify & generate integration report

Directory Structure

Each decomposition creates an isolated artifact folder keyed by Tech Spec:

project/
  parallel/                           # Created by /parallel-setup (one-time)
    README.md
    .gitignore
    TS-XXXX-{slug}/                   # Created by /parallel-decompose
      manifest.json                   # Regeneration metadata
      context.md                      # Shared project context (token-efficient)
      architecture.md                 # System design from Tech Spec
      task-graph.md                   # Dependency visualization (Mermaid)
      contracts/
        types.py (or types.ts)        # Shared domain types
        api-schema.yaml               # OpenAPI specification
      tasks/
        task-001-users.md             # Compact YAML format
        task-002-products.md
        ...
      prompts/
        agent-prompts.md              # All launch commands
        task-*.txt                    # Individual agent prompts
      integration-report.md           # Post-execution report
  tech-specs/                         # Source Tech Specs
    approved/TS-XXXX-slug.md
  CLAUDE.md                           # Project conventions

Related Skills

This skill is part of a family of parallel development skills:

Quick Start

Phase 1: Setup (One-Time)

/parallel-setup --tech django

Creates parallel/ directory structure.

Phase 2: Decomposition

/parallel-decompose docs/prd.md --tech-spec tech-specs/approved/TS-0042-inventory.md

Creates parallel/TS-0042-inventory-system/ with:

• manifest.json, context.md, architecture.md
• contracts/ (types.py, api-schema.yaml)
• tasks/ (compact YAML task specs)
• prompts/ (agent launch commands)

Phase 3: Execution

# Using /parallel-run (delegates to cpo)
/parallel-run parallel/TS-0042-inventory-system/

# Or using cpo directly
cpo run parallel/TS-0042-inventory-system/

Phase 4: Integration

/parallel-integrate --parallel-dir parallel/TS-0042-inventory-system

Checks contract compliance, boundary compliance, runs tests, generates report.

manifest.json Format

{
  "tech_spec_id": "TS-0042",
  "name": "inventory-system",
  "technology": "python",
  "python_version": "3.11",
  "waves": [
    {
      "number": 1,
      "tasks": [
        { "id": "task-001", "agent": "python-experts:django-expert" },
        { "id": "task-002", "agent": "python-experts:django-expert" }
      ],
      "validation": "from apps.users.models import User; print('Wave 1 OK')"
    },
    {
      "number": 2,
      "tasks": [
        { "id": "task-003", "agent": "python-experts:django-expert" }
      ],
      "validation": "from apps.orders.models import Order; print('Wave 2 OK')"
    }
  ],
  "metadata": {
    "tech_spec": "tech-specs/approved/TS-0042-inventory.md",
    "generated_at": "2025-01-15T10:00:00Z",
    "total_tasks": 3,
    "max_parallel": 2,
    "critical_path": ["task-001", "task-003"]
  }
}

Best Practices

• Spend time on decomposition: Good decomposition is the multiplier
• Contract-first: Interfaces upfront prevent 80% of integration issues
• Explicit boundaries: Tell agents what they cannot touch
• Small tasks: Prefer more, smaller tasks (2-4 hours each)
• Tech Spec first: Create a Tech Spec before decomposition

Anti-Patterns

• Tasks that share mutable state
• Circular dependencies between tasks
• Vague scope boundaries
• Missing contract definitions
• Skipping the integration phase

Related Commands