Initial commit: antigravity-claudekit

skills/ck-orchestration/references/parallel-execution.md

@@ -0,0 +1,97 @@
+# Parallel Execution Patterns
+
+Dispatch multiple agents simultaneously for independent tasks. Maximize throughput when tasks don't share file ownership.
+
+## When to Parallelize
+
+### Research Fan-Out (Most Common)
+
+Dispatch multiple `ck-research` agents simultaneously on different topics, then aggregate into `ck-planning`:
+
+```
+ck-planning receives task
+      │
+      ├──► ck-research: "authentication patterns for FastAPI"
+      ├──► ck-research: "JWT vs session token trade-offs"
+      └──► ck-research: "OAuth 2.1 PKCE implementation"
+                │ (all complete)
+                ▼
+      ck-planning aggregates reports → plan.md
+```
+
+**Max parallel research agents:** 3–5 (respects the 5-query max rule per agent)
+
+### Scout Coverage
+
+Divide a large codebase among multiple `ck-scout` agents by directory:
+
+```
+ck-scout agent 1: src/features/, src/components/
+ck-scout agent 2: src/api/, src/hooks/
+ck-scout agent 3: src/utils/, tests/
+      │ (all complete, timeout 3 min each)
+      ▼
+Aggregate into single scout report
+```
+
+### Independent Feature Components
+
+When implementing a feature with truly independent parts:
+
+```
+ck-cook agent 1: phase-01-database-schema.md  (owns: migrations/)
+ck-cook agent 2: phase-02-api-endpoints.md    (owns: api/)
+ck-cook agent 3: phase-03-ui-components.md    (owns: components/)
+      │ (all complete)
+      ▼
+Integration phase (sequential)
+```
+
+**Prerequisite:** File ownership must be explicitly divided with zero overlap.
+
+### Cross-Platform Development
+
+```
+Developer agent 1: iOS-specific implementation
+Developer agent 2: Android-specific implementation
+      │ (both complete)
+      ▼
+Shared interface verification (sequential)
+```
+
+## Coordination Rules
+
+### Before Parallel Dispatch
+
+1. **Define file ownership**: Which files does each agent exclusively own?
+2. **Identify shared resources**: Are there any files both agents might write?
+3. **Plan merge strategy**: How will outputs be combined?
+4. **Set timeout expectations**: How long should each agent take?
+
+### During Parallel Execution
+
+- Agents work independently — no inter-agent communication
+- Each agent writes to its own report path (different filenames)
+- No agent reads files being written by another agent
+
+### After Parallel Completion
+
+- Wait for ALL agents to complete before proceeding
+- Read all reports before synthesizing
+- Resolve any conflicts manually before the next sequential step
+
+## Parallelization Limits
+
+| Scenario | Max Agents | Reason |
+|----------|------------|--------|
+| Research | 5 | Token budget per agent |
+| Scout | 4 | Codebase coverage vs. overlap |
+| Implementation phases | 3 | File conflict risk |
+| CI/CD verification | Unlimited | Read-only bash commands |
+
+## Anti-Patterns
+
+- **Shared file writes**: Two agents writing the same file causes corruption — assign exclusive ownership
+- **Implicit dependencies**: Agent B needs Agent A's output → must be sequential, not parallel
+- **Too many agents**: Each agent consumes context window; over-parallelizing causes resource contention
+- **No merge plan**: Spawning parallel agents without knowing how to combine results → wasted work