Skill: simoncatbot/caid-multi-agent (version 1.2.0)

--- name: caid-multi-agent description: Coordinate multiple sub-agents to collaboratively complete long-horizon software engineering tasks using the CAID (Centralized Asynchronous Isolated Delegation) paradigm. Use when tasks require complex multi-file edits, interdependent subtasks, parallelizable work, or when a single agent would take too long. This skill implements branch-and-merge coordination with git worktree isolation, dependency-aware task delegation, and structured integration. CRITICAL: Never use CAID as a fallback after single-agent failure; use from the outset. Max 2-4 engineers (8 absolute max). Physical git worktree isolation is mandatory; soft isolation degrades performance. --- # CAID Multi-Agent Coordination This skill implements the **Centralized Asynchronous Isolated Delegation (CAID)** paradigm for coordinating multiple agents working on shared artifacts. > ⚠️ **CRITICAL WARNINGS FROM PAPER:** > - **Use CAID from the outset** — Don't run single-agent first as fallback. Sequential strategy costs nearly 2x with minimal gain. > - **Physical worktree isolation is mandatory** — Soft isolation (instruction-only) degrades performance on complex tasks. > - **Engineer limits are strict** — 2 for PaperBench-style, 4 for Commit0-style, never exceed 8. > - **Higher cost/runtime trade-off** — CAID improves accuracy, not speed. Integration is sequential/test-gated. ## Core Principles 1. **Centralized Task Delegation** — A manager agent decomposes tasks into dependency-aware units 2. **Asynchronous Execution** — Multiple engineer agents work concurrently 3. **Isolated Workspaces** — Each agent works in its own isolated branch/worktree 4. **Structured Integration** — Progress is merged via git commit/merge with test verification ## When to Use This Skill **Use CAID from the outset for:** - Long-horizon tasks with multiple interdependent files - Clear dependency structure (imports, test mappings) - Parallelizable work exists - Integration can be verified by executable tests **Don't use as fallback:** Running single-agent first then CAID is inefficient (cost/runtime nearly additive, minimal performance gain). **Use single-agent for:** - Isolated, single-file changes - No clear parallelization opportunities - Exploratory/research-oriented tasks ## Coordination Workflow ### 0. Manager Pre-Setup (CRITICAL) **Before ANY delegation, the manager must:** 1. **Prepare runtime environment** - Ensure dependencies installed - Set up virtual environment 2. **Organize entry points** - Create main entry files - Ensure import paths work 3. **Add minimal function stubs** - Empty function definitions so imports don't fail - Type signatures if available 4. **Commit to main branch** - All engineer branches created from consistent base - Without this, engineers start from divergent states ```bash # Pre-setup commit git add . git commit -m "setup: initial stubs and entry points" git push origin main ``` ### 1. Task Analysis & Dependency Graph Creation **Manager's role:** Before delegating, analyze the task structure: - Identify atomic units of work (files, functions, modules) - Build a dependency graph: G=(V,E) where edges indicate dependencies - Define Ready(v) ⇔ all dependencies of v are completed - Only delegate tasks that are Ready (all dependencies satisfied) **Commit0-style tasks (clear file structure):** 1. Check import statements to identify file-level dependencies 2. Collect executable test cases from repository 3. Examine which files tests exercise 4. Identify components to implement earlier (upstream dependencies) 5. **Delegate at file level first** — only split to function level if file has many unimplemented functions **PaperBench-style tasks (inferred structure):** 1. Read paper to identify main contribution 2. Infer implementation order from contribution 3. **Use max 2 engineers** — manager task is harder, more agents destabilize **Dependency graph construction:** ``` Ready_t(v_j) ⇔ ∀(v_i, v_j) ∈ E, v_i ∈ Completed_t Only delegate tasks from {v ∈ V | Ready_t(v)} ``` ### 2. Workspace Isolation Setup **Create PHYSICALLY isolated worktrees (not soft isolation):** ```bash # Main branch is the single source of truth git worktree add ../workspace-engineer-1 <branch-name-1> git worktree add ../workspace-engineer-2 <branch-name-2> # etc. ``` > ⚠️ **WARNING:** Soft isolation (same workspace, instruction-level constraints) degrades performance to below single-agent on PaperBench. Physical `git worktree` isolation is **mandatory**. **Key isolation principles:** - Each engineer operates in its own git worktree (physical filesystem isolation) - All worktrees are derived from the main branch - Engineers modify files only within their assigned workspace - **Restricted files** (shared across engineers): `__init__.py`, config files, global constants — engineers must NOT commit changes to these ### 3. Dependency-Aware Task Delegation **STRICT Engineer Limits:** | Task Type | Max Engineers | Why | |-----------|--------------|-----| | PaperBench-style | 2 | Inferred dependencies; more destabilizes | | Commit0-style | 4 | Clear file structure; test-guided | | General SWE | 2-4 | Balance parallelism vs integration overhead | | Absolute max | 8 | Beyond this, coordination tax exceeds gains | > ⚠️ **Critical:** Increasing engineers beyond optimal degrades performance due to integration overhead and conflict resolution costs. **Task prioritization heuristics:** Manager should prioritize tasks that: 1. **Enable earlier test execution** (expose evaluation signals sooner) 2. **Lie closer to upstream** of dependency chain 3. **Are simpler functions** before complex ones **Round definition:** > One round = complete cycle of **delegation → implementation → dependency update** **Recommended iteration limits (from paper experiments):** | Role | Max Iterations | |------|---------------| | Manager | 50 | | Each Engineer | 80 | | Total Rounds | ~22 (varies by task) | **Delegation algorithm:** ``` At round t: 1. Ready_Set = {v ∈ V | Ready_t(v)} // all dependencies satisfied 2. Select up to N tasks from Ready_Set (N = max parallel engineers above) 3. Apply prioritization heuristics 4. Delegate to available engineers 5. Wait for completion signals 6. Update dependency state after each successful integration ``` **Task assignment JSON format (structured communication — NO free-form dialog):** ```json { "task_id": "string", "task_description": "string", "target_files": ["path/to/file.py"], "target_functions": ["function_name"], "dependencies": ["task_id_1", "task_id_2"], "expected_outcome": "description of success criteria", "verification_command": "pytest tests/test_file.py -v", "restricted_files": ["src/__init__.py", "src/config.py"], "priority": "high|medium|low" } ``` > **Key:** All communication uses structured JSON, not free-form dialog. This prevents inter-agent misalignment (primary failure mode in multi-agent systems). ### 4. Asynchronous Execution Loop **Event loop pattern:** 1. **Delegate** → Manager assigns tasks to available engineers 2. **Execute** → Engineers work concurrently in isolated worktrees 3. **Self-Verify** → Engineer runs tests, fixes failures 4. **Complete** → Engineer submits commit when ALL tests pass 5. **Integrate** → Manager attempts merge to main 6. **Conflict Resolution** (if needed) → Responsible engineer resolves 7. **Update** → Manager updates dependency graph 8. **Repeat** → Continue until all tasks complete or limits reached **Engineer self-verification (MANDATORY before submission):** - Run relevant tests that import/reference modified files - If no explicit mapping, run repository's default test command - Any failed test or runtime exception MUST be resolved - Use concrete error logs and tracebacks for iterative refinement - **Only submit commit after ALL tests pass** ### 5. Integration via Merge **Merge workflow:** ```bash # Manager attempts merge git checkout main git merge <engineer-branch> # If conflict: # 1. Engineer who produced conflicting commit is RESPONSIBLE for resolution # 2. Engineer pulls latest main: git pull origin main # 3. Resolves conflicts locally # 4. Re-runs tests to ensure resolution didn't break anything # 5. Resubmits commit # 6. Manager retries merge ``` **Main branch is single source of truth** throughout execution. ### 6. Context Management for Manager To prevent context explosion, manager uses **LLMSummarizingCondenser** pattern: ``` Periodically: 1. Summarize prior interaction rounds 2. Preserve structured artifacts: - Dependency graph (current state) - Completed tasks (with commit hashes) - Unresolved errors (with traceback summaries) 3. Discard detailed conversation history 4. Maintain execution traceability without bloat ``` **Compressed execution history format:** ```json { "round": 5, "completed": ["task-1", "task-2", "task-3"], "ready": ["task-4", "task-5"], "blocked": ["task-6: waiting for task-5"], "active_engineers": 2, "main_branch_commits": ["abc123", "def456"], "unresolved_errors": [] } ``` ### 7. Worktree Synchronization & Cleanup **State synchronization when main advances:** ```bash # Engineer syncs to latest integrated state cd ../workspace-engineer-1 git fetch origin git reset --hard origin/main # Sync worktree to latest main ``` **Worktree cleanup (after completion or limit reached):** ```bash # Remove worktree when engineer finishes or hits iteration limit git worktree remove ../workspace-engineer-1 rm -rf ../workspace-engineer-1 # Clean up directory ``` > Worktrees are deleted after all assigned tasks are completed or when the engineer reaches the predefined iteration limit. ### 8. Termination Conditions - **Success:** All units completed and integrated into main - **Failure:** Maximum rounds/iterations reached with unresolved tasks - **Incomplete:** Task considered incomplete if any units remain unresolved **Manager iteration limits (from paper):** - Manager: `max_iterations=50` - Each engineer: `max_iterations=80` - Total rounds: ~22 (varies by task) ### 9. Manager Final Review > **After the asynchronous loop completes, the manager does a final review before submitting the final product.** **Final review checklist:** 1. Verify all tasks from dependency graph are completed 2. Run full test suite: `pytest tests/ -v` 3. Check integration completeness (all commits merged) 4. Review any unresolved errors or warnings 5. Validate final state matches expected outcome 6. Submit final product only after verification ```bash # Manager final verification git checkout main pytest tests/ -v # Full test suite python -m mypackage --version # Smoke test # Review any integration gaps ``` ## Implementation Guidelines ### Using OpenClaw Sub-agents For OpenClaw, the `sessions_spawn` tool enables parallel agent execution: **Spawn engineer agents:** ```javascript // For each task in Ready_Set, spawn an engineer { "runtime": "subagent", "task": "<task specification with context>", "agentId": "<engineer-agent-id>", "mode": "run", "runTimeoutSeconds": 300 } ``` **Check progress:** ```javascript // Poll for completion { "action": "list" } ``` ### Worktree Synchronization **When main advances, update worktrees:** ```bash # Engineer pulls latest main before continuing cd ../workspace-engineer-1 git fetch origin git reset --hard origin/main # Or rebase ``` This ensures engineers work from latest integrated state. ### Verification Intensity vs Efficiency Trade-off From paper analysis (Section 4.4): | Strategy | Pass Rate | Runtime | When to Use | |----------|-----------|---------|-------------| | Round-Manager Review | 60.2% | 3689s | Maximum correctness required | | Engineer Self-Verification | 55.1% | 2244s | **Default - balanced** | | Efficiency-Prioritized | 54.0% | 1909s | Time-critical, acceptable risk | **Default:** Engineer self-verification without repeated manager review. ## Common Pitfalls & Solutions | Pitfall | Solution | |---------|----------| | Using CAID as fallback after single-agent fails | Use from outset; sequential costs ~2x with minimal gain | | Soft isolation (instruction-only) | Mandatory `git worktree` physical isolation | | Too many engineers (>4-8) | Strict limits: 2 PaperBench, 4 Commit0, 8 absolute max | | Skipping manager pre-setup | Always prepare runtime/stubs/entry points first | | Skipping manager final review | Always do final verification before submission | | Merge conflicts from concurrent edits | Group dependent files; engineer resolves own conflicts | | Not cleaning up worktrees | Delete worktrees after completion/limit reached | | Agents develop inconsistent views | Structured JSON only; no free-form dialog | | Silent interference between agents | Explicit merge with test verification | | Tasks not clearly defined | Build dependency graph before ANY delegation | | Integration failures discovered late | Self-verification mandatory before commit | | Context explosion | Use LLMSummarizingCondenser pattern | | Missing restricted files | Mark `__init__.py`, configs as restricted | ## Cost/Runtime Expectations **CAID trade-offs (vs single-agent):** - **Higher API cost** — Multiple agents = more LLM calls - **Similar or longer wall-clock time** — Integration is sequential/test-gated - **Substantially higher accuracy** — +26.7% PaperBench, +14.3% Commit0 **When worth it:** Long-horizon shared-artifact tasks where correctness matters more than speed. ## Example Workflows See [references/examples.md](references/examples.md) for concrete implementation examples including: - Commit0-style library implementation - PaperBench-style paper reproduction - Bug fixing (single-file vs multi-file) - Feature addition with API and frontend ## References - Paper: "Effective Strategies for Asynchronous Software Engineering Agents" (arXiv:2603.21489v1) - GitHub: https://github.com/JiayiGeng/async-swe-agents - Built on OpenHands agent SDK principles

path: references/examples.md
content: # CAID Multi-Agent Examples

## Example 1: Python Library from Scratch (Commit0-style)

> **Engineer limit:** Max 4 engineers for Commit0-style tasks (clear file structure, test-to-file mappings)

### Phase 0: Manager Pre-Setup

```bash
# BEFORE any delegation, manager prepares the environment

# 1. Ensure runtime environment
cd /path/to/repository
python -m venv venv
source venv/bin/activate
pip install -e . 2>/dev/null || pip install pytest

# 2. Add minimal function stubs so imports work
mkdir -p src/mylib
cat > src/mylib/__init__.py << 'EOF'
"""MyLib package."""
from .utils import validate_input, format_output
from .core import CoreClass
from .api import APIClient
from .cli import main

__version__ = "0.1.0"
EOF

# Create stub files with empty functions
touch src/mylib/utils.py src/mylib/core.py src/mylib/api.py src/mylib/cli.py

# 3. Commit to main so engineers start from consistent base
git add .
git commit -m "setup: initial stubs and package structure"
git push origin main
```

### Phase 1: Analyze and Build Dependency Graph

```python
# Manager analyzes repository structure
import_statements = analyze_imports("src/mylib/")
test_files = discover_tests("tests/")

# Build dependency graph from imports and test mappings
dependency_graph = {
    "nodes": {
        "utils": {"file": "src/mylib/utils.py", "deps": [], "tests": ["tests/test_utils.py"]},
        "core": {"file": "src/mylib/core.py", "deps": ["utils"], "tests": ["tests/test_core.py"]},
        "api": {"file": "src/mylib/api.py", "deps": ["core"], "tests": ["tests/test_api.py"]},
        "cli": {"file": "src/mylib/cli.py", "deps": ["api"], "tests": ["tests/test_cli.py"]},
    },
    "parallel_groups": [
        ["utils"],  # Round 1: No dependencies
        ["core"],   # Round 2: Depends on utils
        ["api"],    # Round 3: Depends on core
        ["cli"],    # Round 4: Depends on api
    ]
}

# Ready condition: Ready(v) ⇔ all deps completed
```

### Phase 2: Create PHYSICALLY Isolated Worktrees

```bash
# Manager creates worktrees for engineers (PHYSICAL isolation, not soft)
git worktree add ../workspace-engineer-1 feature/utils
git worktree add ../workspace-engineer-2 feature/core

# Each engineer gets own directory with full copy of repo
# ls -la ..
# workspace-engineer-1/  workspace-engineer-2/
```

### Phase 3: Delegate Tasks (Round 1)

**Engineer 1 (utils) - NO dependencies:**
```json
{
  "task_id": "implement-utils",
  "task_description": "Implement utility functions: validate_input(), format_output(), sanitize_string()",
  "target_files": ["src/mylib/utils.py"],
  "target_functions": ["validate_input", "format_output", "sanitize_string"],
  "dependencies": [],
  "expected_outcome": "All utility functions implemented with type hints, docstrings, and passing tests",
  "verification_command": "pytest tests/test_utils.py -v",
  "restricted_files": ["src/mylib/__init__.py", "src/mylib/core.py", "src/mylib/api.py", "src/mylib/cli.py"],
  "priority": "high"
}
```

### Phase 4: Spawn Engineers (OpenClaw)

```javascript
// Manager spawns Engineer 1
const eng1 = await sessions_spawn({
  runtime: "subagent",
  task: formatTask(utilsTask),
  agentId: "coding-agent",
  mode: "run",
  runTimeoutSeconds: 400
});

// Wait for completion
const result = await pollForCompletion(eng1.sessionKey);
```

### Phase 5: Engineer Self-Verification and Commit

**Engineer 1 in `../workspace-engineer-1/`:**
```bash
# Implement functions...
# Run self-verification (MANDATORY before submission)
pytest tests/test_utils.py -v

# If tests fail, iterate until pass:
# 1. Fix implementation
# 2. Re-run tests
# 3. Repeat until all pass

# Only submit when ALL tests pass
git add src/mylib/utils.py
git commit -m "implement: utility functions with validation"
```

### Phase 6: Manager Integration

```bash
# Manager attempts merge to main
cd /path/to/repository
git checkout main
git merge feature/utils

# Success! Update dependency graph:
# utils: ✓ COMPLETED
# core: Ready (all deps satisfied)
```

### Phase 7: Round 2 - Delegate Dependent Task

**Engineer 2 (core) - NOW Ready:**
```json
{
  "task_id": "implement-core",
  "task_description": "Implement CoreClass with process_data() using utils.validate_input()",
  "target_files": ["src/mylib/core.py"],
  "target_functions": ["CoreClass", "process_data", "initialize"],
  "dependencies": ["implement-utils"],
  "expected_outcome": "CoreClass validates input via utils and processes data correctly",
  "verification_command": "pytest tests/test_core.py -v",
  "restricted_files": ["src/mylib/__init__.py", "src/mylib/utils.py"],
  "priority": "high"
}
```

### Phase 8: Handle Merge Conflict (Example)

Scenario: Engineer 2's branch diverged while Engineer 1 was finishing.

```bash
# Manager attempts merge
git merge feature/core
# CONFLICT in pyproject.toml

# Engineer 2 is RESPONSIBLE for resolution
cd ../workspace-engineer-2
git pull origin main              # Gets Engineer 1's changes

# Resolve conflicts in pyproject.toml
# Editor: fix merge markers

# Verify resolution didn't break anything
pytest tests/test_core.py -v

# Re-commit
git add pyproject.toml
git commit --amend -m "implement: CoreClass with dependency resolution"

# Manager retries merge
git checkout main
git merge feature/core  # Success!
```

### Phase 9: Continue Until Complete

Rounds 3-4: api → cli (same pattern)

Final state:
```
Dependency graph:
┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
│  utils  │─→│  core   │─→│   api   │─→│   cli   │
│   ✓     │  │   ✓     │  │   ✓     │  │   ✓     │
└─────────┘  └─────────┘  └─────────┘  └─────────┘

All tasks completed and integrated!
```

---

## Example 2: Paper Reproduction (PaperBench-style)

> **Engineer limit:** Max 2 engineers for PaperBench-style tasks (inferred dependencies, no test mappings)

### Phase 0: Manager Pre-Setup

```bash
# Setup project structure
mkdir reproduction-paper
cd reproduction-paper
git init

# Create minimal structure with stubs
mkdir -p src/models src/data src/training src/evaluation
touch src/__init__.py src/models/__init__.py src/data/__init__.py

git add .
git commit -m "setup: initial project structure"
```

### Phase 1: Read Paper and Infer Dependencies

```python
# Manager reads paper to understand main contributions
paper_analysis = {
    "title": "Novel Architecture for X",
    "main_contribution": "Section 3: Proposed Model Architecture",
    "implementation_order": [
        ("data_preprocessing", "Section 4.1: Data loading and preprocessing"),
        ("model_architecture", "Section 3: Neural network architecture"),
        ("training_loop", "Section 4.2: Training procedure with custom loss"),
        ("evaluation", "Section 5: Metrics and evaluation protocol"),
    ],
    "dependencies": {
        "data_preprocessing": [],
        "model_architecture": [],  # Can parallel with data
        "training_loop": ["data_preprocessing", "model_architecture"],
        "evaluation": ["training_loop"],
    }
}

# Note: Max 2 engineers for PaperBench - manager task is harder
```

### Phase 2: Create Worktrees (2 max)

```bash
git worktree add ../workspace-eng1 feature/data-pipeline
git worktree add ../workspace-eng2 feature/model-arch
```

### Phase 3: Delegate Round 1 (Parallel)

**Engineer 1 (data) - NO dependencies:**
```json
{
  "task_id": "data-pipeline",
  "task_description": "Implement data preprocessing as described in Section 4.1. Load dataset, apply normalization per Equation 1.",
  "target_files": ["src/data/loader.py", "src/data/preprocess.py"],
  "dependencies": [],
  "expected_outcome": "Data pipeline loads dataset and outputs normalized tensors",
  "verification_command": "python -c 'from src.data.loader import load_data; d = load_data(); print(d.shape)'",
  "restricted_files": ["src/__init__.py", "src/models/", "src/training/"],
  "paper_sections": ["4.1"],
  "equations": ["Equation 1: Normalization"],
  "priority": "high"
}
```

**Engineer 2 (model) - NO dependencies:**
```json
{
  "task_id": "model-arch",
  "task_description": "Implement neural network architecture from Section 3. Include all layers shown in Figure 2.",
  "target_files": ["src/models/network.py", "src/models/layers.py"],
  "dependencies": [],
  "expected_outcome": "Model instantiates and runs forward pass successfully",
  "verification_command": "python -c 'from src.models.network import Model; import torch; m = Model(); print(m(torch.randn(1,3,224,224)).shape)'",
  "restricted_files": ["src/__init__.py", "src/data/", "src/training/"],
  "paper_sections": ["3.1", "3.2", "3.3"],
  "figure": "Figure 2",
  "priority": "high"
}
```

### Phase 4: Both Engineers Self-Verify and Commit

**Engineer 1:**
```bash
cd ../workspace-eng1
python -c 'from src.data.loader import load_data; d = load_data(); print(f"Data shape: {d.shape}")'
# Output: Data shape: (1000, 3, 224, 224)
git add src/data/
git commit -m "implement: data preprocessing pipeline (Section 4.1)"
```

**Engineer 2:**
```bash
cd ../workspace-eng2
python -c 'from src.models.network import Model; import torch; m = Model(); print(f"Output shape: {m(torch.randn(1,3,224,224)).shape}")'
# Output: torch.Size([1, 10])
git add src/models/
git commit -m "implement: neural network architecture (Section 3)"
```

### Phase 5: Manager Integrates Both

```bash
# Merge data pipeline first
git checkout main
git merge feature/data-pipeline  # Success

# Merge model architecture
git merge feature/model-arch  # Success

# Both complete! Update dependency graph
```

### Phase 6: Round 2 - Training Loop (now Ready)

```bash
# Create new worktree for training
git worktree add ../workspace-eng3 feature/training
```

**Engineer 3:**
```json
{
  "task_id": "training-loop",
  "task_description": "Implement training loop with custom loss from Section 4.2. Use data pipeline and model.",
  "target_files": ["src/training/trainer.py", "src/training/loss.py"],
  "dependencies": ["data-pipeline", "model-arch"],
  "expected_outcome": "Training loop runs for 1 epoch without errors",
  "verification_command": "python src/training/trainer.py --epochs 1 --dry-run",
  "restricted_files": ["src/__init__.py", "src/data/loader.py", "src/models/network.py"],
  "paper_sections": ["4.2", "4.3"],
  "priority": "high"
}
```

### Comparison: Why PaperBench is Harder

| Aspect | Commit0 | PaperBench |
|--------|---------|------------|
| Dependency clarity | Explicit (imports, tests) | Inferred (paper text) |
| Engineer limit | 4 | 2 |
| Test mappings | Clear | None |
| Manager task | File-level analysis | Semantic understanding |
| Risk of miscoordination | Low | High |

---

## Example 3: Context Management for Manager

### The Problem

After 10 rounds, manager's context explodes with:
- Full conversation history
- All git diffs
- All test outputs
- Error tracebacks

### The Solution: LLMSummarizingCondenser

```python
# Every 5 rounds, compress context
if round_number % 5 == 0:
    compressed_state = {
        "round": round_number,
        "summary": "Rounds 1-5 completed. Implemented utils (✓), core (✓), 
                    api (✓). Training in progress.",
        "completed_tasks": {
            "implement-utils": {"commit": "abc123", "tests": "5/5 passed"},
            "implement-core": {"commit": "def456", "tests": "12/12 passed"},
            "implement-api": {"commit": "ghi789", "tests": "8/8 passed"},
        },
        "ready_tasks": ["implement-training"],
        "blocked_tasks": ["implement-evaluation: waiting for training"],
        "current_dependency_graph": {
            "utils": "completed",
            "core": "completed",
            "api": "completed",
            "training": "in_progress",
            "evaluation": "blocked"
        },
        "unresolved_errors": [],
        "main_branch_commits": ["abc123", "def456", "ghi789"]
    }
    
    # Replace full history with compressed state
    context = compressed_state
```

### Preserved vs Discarded

| Preserved | Discarded |
|-----------|-----------|
| Dependency graph (current) | Old versions of graph |
| Completed task IDs + commits | Full task descriptions |
| Commit hashes | Full diffs |
| Error summaries | Full tracebacks |
| Test pass/fail counts | Full test output |
| Blocked tasks list | Why they were blocked |

---

## Example 4: Complete OpenClaw Implementation

```javascript
// Complete CAID implementation for OpenClaw

class CAIDManager {
  constructor(config) {
    this.maxEngineers = config.maxEngineers || 4; // 2 for PaperBench, 4 for Commit0
    this.round = 0;
    this.completed = new Set();
    this.dependencyGraph = null;
  }

  async run(projectPath, tasks) {
    // Phase 0: Pre-setup
    await this.preSetup(projectPath);
    
    // Phase 1: Build dependency graph
    this.dependencyGraph = await this.buildDependencyGraph(tasks);
    
    // Main loop
    while (this.hasReadyTasks()) {
      this.round++;
      
      // Get Ready tasks
      const readyTasks = this.getReadyTasks()
        .slice(0, this.maxEngineers);
      
      if (readyTasks.length === 0) break;
      
      // Phase 2: Create worktrees
      const worktrees = await this.createWorktrees(readyTasks);
      
      // Phase 3-4: Spawn engineers and execute
      const engineers = await this.spawnEngineers(readyTasks, worktrees);
      const results = await this.waitForCompletion(engineers);
      
      // Phase 5-6: Integrate and update
      for (const result of results) {
        if (result.success) {
          const mergeResult = await this.mergeToMain(result.taskId);
          if (mergeResult.success) {
            this.completed.add(result.taskId);
            this.updateDependencyGraph();
          } else {
            // Conflict resolution
            await this.resolveConflict(result.taskId, mergeResult.conflicts);
          }
        }
      }
      
      // Phase 7: Context compression
      if (this.round % 5 === 0) {
        this.compressContext();
      }
    }
    
    return this.getFinalStatus();
  }

  async preSetup(projectPath) {
    // Prepare runtime
    await exec(`cd ${projectPath} && pip install -e .`);
    
    // Create stubs
    await this.createStubs(projectPath);
    
    // Commit to main
    await exec(`cd ${projectPath} && git add . && git commit -m "setup: initial"`);
  }

  async createWorktrees(tasks) {
    const worktrees = [];
    for (let i = 0; i < tasks.length; i++) {
      const branch = `feature/${tasks[i].id}`;
      const path = `../workspace-eng-${i}`;
      await exec(`git worktree add ${path} ${branch}`);
      worktrees.push({ taskId: tasks[i].id, path, branch });
    }
    return worktrees;
  }

  async spawnEngineers(tasks, worktrees) {
    const engineers = [];
    for (let i = 0; i < tasks.length; i++) {
      const result = await sessions_spawn({
        runtime: "subagent",
        task: this.formatTask(tasks[i]),
        agentId: "coding-agent",
        mode: "run",
        runTimeoutSeconds: 400
      });
      engineers.push({
        taskId: tasks[i].id,
        sessionKey: result.sessionKey,
        worktree: worktrees[i]
      });
    }
    return engineers;
  }

  formatTask(task) {
    return `
TASK: ${task.description}
FILES: ${task.target_files.join(', ')}
DEPS: ${task.dependencies.join(', ') || 'None'}
VERIFY: ${task.verification_command}
RESTRICTED: ${task.restricted_files.join(', ')}

RULES:
1. Work in isolated worktree
2. Run verification before ANY commit
3. Only commit when ALL tests pass
4. Do NOT modify restricted files
`;
  }

  getReadyTasks() {
    return Object.values(this.dependencyGraph.nodes)
      .filter(node => 
        node.deps.every(dep => this.completed.has(dep))
        && !this.completed.has(node.id)
      );
  }
}

// Usage
const manager = new CAIDManager({ maxEngineers: 4 });
await manager.run("/path/to/repo", taskList);
```

---

## Example 6: Worktree Cleanup and State Synchronization

### Worktree Cleanup (Required)

```bash
# After engineer completes or hits iteration limit

# 1. Remove git worktree reference
git worktree remove ../workspace-engineer-1

# 2. Clean up directory
rm -rf ../workspace-engineer-1

# 3. Verify worktree list
git worktree list
# /path/to/repo         main
# /path/to/repo2        feature-x
```

### State Synchronization Pattern

```bash
# When main advances with other engineer's changes
cd ../workspace-engineer-2

# Sync to latest main
git fetch origin
git reset --hard origin/main  # OR: git rebase origin/main

# Verify sync worked
git log --oneline -3
# abc1234 Merge feature-1
# def5678 Merge feature-2  
# ghi9012 setup: initial stubs

# Continue work from latest state
```

---

## Example 7: Manager Final Review Phase

### Final Review Checklist

```javascript
class CAIDManager {
  async finalReview() {
    // 1. Verify all tasks completed
    const incomplete = this.dependencyGraph.getIncomplete();
    if (incomplete.length > 0) {
      throw new Error(`Incomplete tasks: ${incomplete.join(', ')}`);
    }
    
    // 2. Full test suite
    const testResult = await exec('pytest tests/ -v');
    if (testResult.exitCode !== 0) {
      throw new Error('Tests failed in final review');
    }
    
    // 3. Verify integration completeness
    const mainCommits = await exec('git log --oneline main');
    const expectedCommits = this.completedTasks.map(t => t.commit);
    
    // 4. Smoke test
    await exec('python -m mypackage --version');
    
    // 5. Submit final product
    return { status: 'complete', commits: expectedCommits };
  }
}
```

### Final Review Bash Script

```bash
#!/bin/bash
# final-review.sh

set -e

echo "=== CAID Final Review ==="

# 1. Checkout main
git checkout main

# 2. Full test suite
echo "Running full test suite..."
pytest tests/ -v --tb=short

# 3. Integration verification
echo "Verifying all features integrated..."
python -c "
import mypackage
from mypackage.utils import validate_input
from mypackage.core import CoreClass
print('✓ All imports successful')
"

# 4. Version check
echo "Final version check..."
python -m mypackage --version

echo "=== Final Review Complete ==="
```

---

## Key Takeaways from Paper

1. **Pre-setup is mandatory** — Don't skip runtime prep and stub creation
2. **Physical worktree isolation** — Soft isolation degrades performance
3. **Strict engineer limits** — 2 PaperBench, 4 Commit0, never 8+
4. **Self-verification mandatory** — Tests must pass before commit
5. **Use CAID from outset** — Not as fallback after single-agent failure
6. **Structured JSON only** — No free-form chat between agents
7. **Context compression** — Every 5 rounds, summarize history
8. **Engineer resolves conflicts** — Not manager
9. **Final review required** — Manager must verify before submission
10. **Cleanup worktrees** — Delete after completion or limit reached

See SKILL.md for complete coordination workflow and warnings.

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)