---
name: ao-parallel
description: "Dispatch parallel agents for independent issues. Use for concurrent multi-issue resolution."
category: core
invokes: [ao-state, ao-task]
invoked_by: []
state_files:
  read: [constitution.md, baseline.md, focus.json, issues/*.md]
  write: [focus.json, issues/*.md]
---

# Parallel Agent Dispatch Skill

> **Credit**: Parallel agent dispatch adapted from obra/superpowers by Jesse Vincent (MIT License). See `.agent/ops/references/superpowers-analysis.md` and obra/superpowers `skills/dispatching-parallel-agents/SKILL.md`.

## Purpose

Dispatch parallel agents to handle multiple independent issues simultaneously. Each agent works on one problem domain concurrently, with conflict detection and result aggregation.

## When to Use Parallel Dispatch

**Use `/ao-parallel` when:**
- 3+ independent issues in queue
- Issues affect different subsystems
- No shared state between issues
- Sprint deadline approaching

**Don't use when:**
- Issues are related (fixing one might fix others)
- Issues share code/files
- Need full system context
- Issues have dependencies

## Procedure

### 1) Identify Independent Issues

```
Analyze issues in critical.md and high.md:

For each issue:
    Check dependencies
    - Does this issue depend on others?
    - Will fixing this break others?

    Check shared state
    - Do issues touch same files?
    - Do issues affect same components?

    Check problem domain
    - Are issues in different subsystems?
    - Can they be worked on independently?

    Classify as:
    - INDEPENDENT: Safe for parallel work
    - BLOCKING: Must fix first
    - CONFLICTING: Cannot work in parallel
```

### 2) Create Focused Agent Tasks

Each parallel agent gets:
- Specific scope: One issue or subsystem
- Clear goal: Resolve the issue
- Constraints: Don't change unrelated code
- Expected output: Summary of changes

**Agent Task Template:**
```
You are implementing Agent #{N} for Issue: {ISSUE-ID}

Issue: {title}
Type: {BUG/FEAT/CHORE}
Priority: {priority}

Your Job:
1. Read the full issue from .agent/ops/issues/{priority}.md
2. Implement exactly what the issue specifies
3. Follow TDD discipline if FEAT (test-first)
4. Use systematic debugging if BUG
5. Verify your work before claiming complete
6. Return summary of changes

Constraints:
- Don't modify files touched by other agents
- Don't change issues not in your scope
- Report any dependencies you discover
- Stop and ask if unclear

Return: Summary of what was implemented and verification results
```

### 3) Dispatch in Parallel

```
/ao-parallel dispatch

Issue analysis:
- BUG-0015: API authentication error (independent)
- BUG-0016: Frontend styling issue (independent)
- BUG-0017: Database connection timeout (independent)

Dispatching 3 agents in parallel...
Agent 1 → BUG-0015 (API auth)
Agent 2 → BUG-0016 (Frontend)
Agent 3 → BUG-0017 (Database)

[Progress tracking]
Agent 1 (BUG-0015): ████████░░ 80% - Testing fix
Agent 2 (BUG-0016): ██████████ 100% - Complete
Agent 3 (BUG-0017): ██████░░░ 60% - Implementing

[Results collection]
```

### 4) Conflict Detection

**Python Pseudocode:**
```python
def detect_conflicts(agent_results):
    """Check if agents edited same files."""
    file_changes = {}
    for result in agent_results:
        for file in result.modified_files:
            if file in file_changes:
                return Conflict(file, [result.agent_id, file_changes[file]])
            file_changes[file] = result.agent_id
    return None
```

**If conflict detected:**
- STOP all remaining agents
- Report conflict to user
- Require manual resolution
- Re-run in correct order if needed

### 5) Reviews and Integrates

```
Results:
✓ BUG-0015 - Fixed (commit: a1b2c3)
✓ BUG-0016 - Fixed (commit: b2c3d4)
✓ BUG-0017 - Fixed (commit: c3d4e5)

Conflict check: None detected
Full test suite: 47/47 passing

All issues resolved in parallel. Time saved: ~3 hours vs sequential.
```

## Conflict Detection Logic

| Conflict Type | Detection | Resolution |
|---------------|-----------|------------|
| **Same file edited** | Multiple agents modified same file | Manual merge required |
| **Shared state modified** | Agents modified shared config/data | Sequential work required |
| **Broken dependency** | One agent changed code another depends on | Re-run in dependency order |

## Safety Considerations

- **Never dispatch parallel agents on `main` branch**
- **Require worktree for each agent**
- **Lock issue status during parallel execution**
- **Rollback capability** if conflicts detected

## Integration with AO Workflow

### Auto-suggest Parallel Mode

```
5 independent critical issues detected.

Would you like to dispatch parallel agents? (y/n)
```

### Manual Dispatch Commands

```
/ao-parallel --issues BUG-0015,BUG-0016,BUG-0017
/ao-parallel --priority critical
/ao-parallel --count 3  # Auto-select 3 independent issues
```

### Integration with ao-ui

- Show parallel execution status
- Visualize agent progress
- Display conflicts if detected

## Example Workflow

```
User: /ao-parallel dispatch

AO: Analyzing independent issues...

Found 4 independent critical issues:
1. BUG-0020 - API rate limiting (api/)
2. BUG-0021 - UI button alignment (frontend/)
3. BUG-0022 - Config parsing error (config/)
4. BUG-0023 - Cache invalidation (cache/)

Creating worktrees and dispatching agents...

[Progress]
Agent 1 (BUG-0020): ████████░░ 80% - Testing fix
Agent 2 (BUG-0021): ██████████ 100% - Complete
Agent 3 (BUG-0022): ██████░░░ 60% - Implementing
Agent 4 (BUG-0023): ███████░░░ 70% - Debugging

Results:
✓ BUG-0020 - Fixed (commit: a1b2c3)
✓ BUG-0021 - Fixed (commit: b2c3d4)
✓ BUG-0022 - Fixed (commit: c3d4e5)
✓ BUG-0023 - Fixed (commit: d4e5f6)

Conflict check: None detected
Full test suite: 47/47 passing

All issues resolved in parallel. Time saved: ~3 hours vs sequential.
```

## Performance Metrics

Track parallel vs sequential execution time:

```
Sequential Estimate: (Issue 1 time + Issue 2 time + Issue 3 time)
Parallel Actual: max(Issue 1 time, Issue 2 time, Issue 3 time)
Time Saved: Sequential Estimate - Parallel Actual
Efficiency Gain: Time Saved / Sequential Estimate
```

## Acceptance Criteria

From issue FEAT-0012:
- [x] Create `/ao-parallel` skill with dispatch capability
- [x] Implement issue dependency analysis
- [x] Add parallel agent execution
- [x] Create conflict detection and resolution
- [x] Add result aggregation and presentation
- [x] Integration with ao-ui for visual status
- [x] Safety checks (don't run on main branch, require worktree)
- [x] Performance metrics (time saved vs sequential)
