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

Command	Description
`cpo init <dir> -t <tech-spec> -n <name>`	Initialize parallel directory
`cpo validate <dir>`	Validate manifest and structure
`cpo run <dir>`	Execute parallel agents
`cpo status <dir>`	Check execution status

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:

Skill	Purpose
parallel-decompose	PRD decomposition workflow, task generation, contracts
parallel-prompt-generator	Generate agent prompts from task specs
parallel-execution	Git worktrees, parallel execution patterns, scripts
parallel-task-format	Task spec YAML format, scope notation, agent selection
agent-tools	Tool permissions, CLI syntax for agent restrictions

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",
  "dependencies": {
    "python": {
      "add": ["pydantic==2.5.3", "sqlalchemy[asyncio]==2.0.25"],
      "upgrade": [],
      "remove": [],
      "add_dev": ["pytest==7.4.3", "pytest-asyncio==0.21.1"]
    }
  },
  "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"]
  }
}

Dependencies Section

The dependencies section declares packages to install before task execution. Versions are pinned (resolved during parallel-decompose using the dependency-alignment skill) to ensure reproducibility and avoid conflicts between parallel agents.

{
  "dependencies": {
    "python": {
      "add": ["pydantic==2.5.3"],
      "upgrade": ["requests==2.31.0"],
      "remove": ["deprecated-lib"],
      "add_dev": ["pytest==7.4.3"]
    }
  }
}

Field	Description	uv Command
`add`	Packages to add (if not present)	`uv add <packages>`
`upgrade`	Packages to upgrade to specified version	`uv add --upgrade <packages>`
`remove`	Packages to remove from project	`uv remove <packages>`
`add_dev`	Dev-only packages to add	`uv add --dev <packages>`

Execution order: remove → upgrade → add → add_dev

Commit strategy: Dependencies are installed and committed to the feature branch before any task execution begins. This ensures all parallel tasks have access to the same dependencies without conflicts.

Minimal example (add only):

{
  "dependencies": {
    "python": {
      "add": ["pydantic==2.5.3"]
    }
  }
}

All fields are optional. Omit sections you don't need (except versions must be pinned).

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

Command	Purpose
`/parallel-setup`	One-time project initialization
`/parallel-decompose`	Per-spec decomposition with prompts
`/parallel-run`	Execute and monitor parallel agents
`/parallel-integrate`	Post-execution verification
`/create-tech-spec`	Create Tech Spec before decomposition

parallel-agents