# Parallel Agent Protocol

**CRITICAL: When spawning parallel agents, follow this EXACT protocol.**

## When to Use Parallel Agents

| Condition | Action |
|-----------|--------|
| Single domain | Sequential OK |
| Multiple domains / repos / subsystems | **MUST use parallel Task agents** |

**Domain = separate repos, services, languages, or unrelated subsystems.** Same repo across files = single domain (sequential).

| Separate Domains (→ Parallel) | Same Domain (→ Sequential) |
|------|------|
| Different repos (react vs vue) | Same repo, different files |
| Different services (auth vs payments) | Same service, different modules |
| Different runtimes (JS frontend vs Python backend) | Same language, different packages |

**Agent selection**: Deep exploration → `Explore`/`opus`. Quick lookup → `Explore`/`haiku`.

---

## Spawn Phase

**Step 1**: Generate session ID and prepare output directory
```bash
mkdir -p .octocode/research/{session-id}/
```

**Step 2**: For each domain, spawn an agent with this template:

### Agent Template

```markdown
# Research Agent - Domain: {DOMAIN_NAME}

## Mission
You are researching ONE specific domain as part of a larger investigation.
Other agents are researching other domains in parallel.
DO NOT duplicate work outside your boundaries.

## Main Research Goal
{MAIN_RESEARCH_GOAL}

## Your Specific Scope
- **Domain**: {DOMAIN_NAME}
- **Repository**: {owner}/{repo} (if GitHub) OR {path_prefix} (if local)
- **Boundaries**: ONLY research within this scope

## Constraints
- Maximum tool calls: 10
- Timeout: 5 minutes
- You MUST write findings to output file

## Output File
Write to: `.octocode/research/{SESSION_ID}/domain-{DOMAIN_NAME}.md`

## Required Output Format
```markdown
# Domain: {DOMAIN_NAME}

## Summary
[2-3 sentence TL;DR]

## Key Files
| File | Line | Description |
|------|------|-------------|
| path/to/file | 42 | What it does |

## Findings
### Finding 1: {title}
- Evidence: {file:line}
- Code snippet (≤10 lines)

## Gaps
- [What couldn't be determined]

## Answer
[Direct answer to mainResearchGoal from this domain]
```
```

**Step 3**: Launch agents in parallel
```
Task(subagent_type="Explore", model="opus", prompt=AGENT_PROMPT_A, run_in_background=True)
Task(subagent_type="Explore", model="opus", prompt=AGENT_PROMPT_B, run_in_background=True)
```

**Step 4**: Tell user
> "Spawning {N} parallel agents for domains: {list}. Will merge findings when complete."

---

## Barrier Phase (Wait)

**WAIT for all agents** to complete or timeout (5 min max).

Track status:
```
Agent A: Complete (domain-auth.md written)
Agent B: Running...
Agent C: Timeout (partial results)
```

**IF agent times out**: Collect partial results if output file exists.

---

## Merge Phase

<merge_gate>
**HALT. Before merging, verify ALL conditions:**

- [ ] All agents completed OR timed out (5 min max)?
- [ ] All expected domain-*.md files exist (or noted as missing)?
- [ ] No agent still running in background?

**IF ANY condition not met → WAIT or collect partial results.**
**IF ALL conditions met → PROCEED with merge steps.**
</merge_gate>

**Step 1**: Read all output files
```
.octocode/research/{session}/domain-auth.md
.octocode/research/{session}/domain-payments.md
```

**Step 2**: Check for conflicts

| Conflict Type | Detection | Resolution |
|---------------|-----------|------------|
| Contradictory facts | Same topic, different claims | **STOP.** Ask user to resolve. |
| Overlapping findings | Both found same file | Deduplicate |
| Missing coverage | Gap between domains | Note in output |

**Step 3**: Synthesize unified answer
- Combine findings from all domains
- Note which domain each finding came from
- Highlight cross-domain connections

**Step 4**: Present merged result
> "Merged findings from {N} agents. Domain A found X, Domain B found Y. Together, this shows..."

<merge_complete_gate>
**HALT. Before proceeding to Phase 5 (OUTPUT), verify:**

- [ ] All domain findings incorporated?
- [ ] Conflicts resolved (or user acknowledged)?
- [ ] Deduplication complete?
- [ ] Cross-domain connections noted?

**IF ANY condition not met → Complete missing items.**
**IF ALL conditions met → PROCEED to Phase 5 (OUTPUT) in main SKILL.md.**
</merge_complete_gate>

---

## Failure Handling

| Scenario | Detection | Action |
|----------|-----------|--------|
| One agent fails | No output file after timeout | Use partial results, note gap |
| One agent finds answer | Complete answer in one domain | Cancel others, proceed to OUTPUT |
| All agents timeout | No complete results | **STOP.** Offer: retry with smaller scope? |
| Contradictory findings | Conflicting claims | **STOP.** Present both, ask user to resolve |

### Example: Partial Failure

```markdown
## Merged Findings

### From Domain: auth (complete)
- Auth uses JWT tokens
- Implementation at auth/jwt.ts:42

### From Domain: payments (partial - timeout)
- Found payment gateway integration
- [Incomplete: couldn't trace full flow]

### Gaps
- Payments domain research incomplete due to timeout
- Consider: "Continue researching payments domain?"
```

### Example: Conflict Resolution

```markdown
## Conflict Detected

**Topic**: Authentication method

**Domain A says**: "Uses JWT tokens" (evidence: auth/config.ts:15)
**Domain B says**: "Uses session cookies" (evidence: api/middleware.ts:23)

**Asking user**: Which is correct, or should I investigate further?
```
