parallel-execution

# Parallel Execution

Execute multiple Claude Code agents in parallel using the `cpo` (Claude Parallel Orchestrator) CLI.

## Primary Method: cpo CLI

The `cpo` tool handles all execution complexity: git worktrees, wave dependencies, and progress monitoring.

### Installation

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

### Commands

| Command | Description |
|---------|-------------|
| `cpo validate <dir>` | Validate manifest structure and prompts |
| `cpo run <dir>` | Execute all waves (respects dependencies) |
| `cpo status <dir>` | Check execution status |

### Basic Workflow

```bash
# 1. Validate before execution
cpo validate parallel/TS-0042-inventory-system/

# 2. Execute parallel agents
cpo run parallel/TS-0042-inventory-system/

# 3. Monitor progress (in another terminal)
cpo status parallel/TS-0042-inventory-system/
```

### What `cpo run` Does

1. **Validates** manifest.json structure and prompt files
2. **Creates git worktrees** for each task (isolated workspaces)
3. **Launches agents** in parallel (respects wave dependencies)
4. **Monitors progress** with live output
5. **Collects results** in `logs/` and `report.json`

### Wave Execution

Tasks execute in waves based on dependencies:

```
Wave 1: task-001, task-002, task-003  (parallel - no deps)
         ↓ wait for completion
Wave 2: task-004, task-005            (parallel - depend on Wave 1)
         ↓ wait for completion
Wave 3: task-006                      (sequential - depend on Wave 2)
```

Each wave waits for all tasks in the previous wave to complete before starting.

### Agent Permissions

Agents run with `--dangerously-skip-permissions` because they're isolated in worktrees:
- Each agent runs in its own git worktree
- Agents can only affect files in their workspace
- Main branch remains protected until explicit merge

## Alternative: Claude Code SDK

For programmatic orchestration in CI/CD or custom workflows:

```typescript
// orchestrator.ts
import { ClaudeAgent } from '@anthropic-ai/claude-agent-sdk';
import { readdir, readFile } from 'fs/promises';
import { join } from 'path';

async function runParallelTasks(parallelDir: string) {
  const tasksDir = join(parallelDir, 'tasks');
  const contextFile = join(parallelDir, 'context.md');

  const context = await readFile(contextFile, 'utf-8');
  const tasks = await readdir(tasksDir);

  const agents = tasks
    .filter(f => f.endsWith('.md'))
    .map(async (taskFile) => {
      const taskPath = join(tasksDir, taskFile);
      const taskContent = await readFile(taskPath, 'utf-8');

      const agent = new ClaudeAgent({
        systemPrompt: `You are implementing a task.
                       Context: ${context}
                       Follow contracts in ${parallelDir}/contracts/.`,
      });

      return agent.run(`Execute this task:\n\n${taskContent}`);
    });

  const results = await Promise.all(agents);
  return results;
}

runParallelTasks('parallel/TS-0042-inventory-system');
```

## Completion Detection

Agents signal completion by creating a marker file:

```bash
touch .claude-task-complete
```

This enables:
- `cpo` to detect task completion
- Wave coordination (wait for all tasks before next wave)
- Status reporting

## Execution Patterns

| Method | Best For | Parallelism |
|--------|----------|-------------|
| **cpo CLI** | Standard workflow, most users | True parallel with wave deps |
| **Claude Code SDK** | CI/CD, custom orchestration | Fully programmable |

## Tips for Success

1. **Validate first**: Always run `cpo validate` before `cpo run`
2. **Start small**: Test with 2-3 parallel agents before scaling up
3. **Monitor resources**: Limit concurrent agents based on machine capacity
4. **Check logs**: Review `logs/task-*.log` for debugging
5. **Run integration**: Use `/parallel-integrate` after all tasks complete

## Output Files

After execution:
```
parallel/TS-0042-inventory-system/
  logs/
    task-001.log          # Agent output
    task-002.log
    ...
  report.json             # Execution summary
  integration-report.md   # Generated by /parallel-integrate
```

## Related

- `parallel-agents` skill: Overall workflow and directory structure
- `parallel-decompose` skill: Creating tasks before execution
- `parallel-prompt-generator` skill: Generate prompts from task specs
- `agent-tools` skill: Tool permissions (for granular control)
- `/parallel-integrate` command: Post-execution verification