# Agent Swarm Methodology
*Derived from Elvis (@elvissun) article + our own OpenClaw setup. Updated 2026-02-25.*

## Core Principle: Two-Tier Architecture
Context windows are zero-sum. Fill with code = no room for business context. Fill with business context = no room for codebase.

**Tier 1 (Orchestrator - Max/OpenClaw):** Holds all business context, customer data, meeting notes, past decisions. Translates context into precise prompts for coding agents.

**Tier 2 (Coding Agents - Claude Code/Codex):** See only code + task-specific context. Stay focused on implementation.

## What We Already Do
- OpenClaw as orchestrator (Max = Zoe equivalent)
- Sub-agents for parallel work (Sonnet for batch, Claude Code for coding)
- Memory system (daily logs, MEMORY.md, knowledge files)
- Telegram notifications on completion
- Cron-based monitoring (heartbeats, health checks)
- Model tiering (Opus strategy, Sonnet execution, Claude Code development)

## What We Should Adopt

### 1. Git Worktrees for Parallel Feature Work
Instead of one branch, each coding agent gets an isolated worktree:
```bash
git worktree add ../feat-name -b feat/feature-name origin/main
cd ../feat-name && pnpm install
```
**Why:** No merge conflicts between parallel agents. Each has clean state.

### 2. Task Registry (JSON Tracking)
Track all active agent tasks in a structured file:
```json
{
  "id": "feat-custom-templates",
  "agent": "claude-code",
  "description": "Custom email templates",
  "branch": "feat/custom-templates",
  "status": "running",
  "startedAt": 1740268800000,
  "notifyOnComplete": true
}
```
**Our equivalent:** We partially do this with HEARTBEAT.md and daily logs. Should formalise into `projects/<name>/tasks.json`.

### 3. Multi-Model Code Review (Before Merge)
Every PR reviewed by 3 models:
- **Codex/Claude Code:** Edge cases, logic errors, race conditions (thorough)
- **Gemini Code Assist:** Security, scalability (free, install on GitHub)
- **Third reviewer:** Validation layer

**Action:** Set up Gemini Code Assist on our GitHub repos (free). Use Claude Code for primary review.

### 4. Definition of Done (Strict)
PR is NOT done until:
- Branch synced to main (no conflicts)
- CI passing (lint, types, tests)
- AI code review passed
- Screenshots included (if UI changes)

**Action:** Add this to our coding-agent skill prompts.

### 5. Deterministic Monitoring (Not Polling Agents)
Don't poll agents (expensive). Instead, check:
- Is the tmux/process alive?
- Is there an open PR on the branch?
- CI status via `gh cli`
- Auto-respawn failed agents (max 3 attempts)

**Our equivalent:** Sub-agents auto-announce completion. We could add CI checks.

### 6. Proactive Task Discovery
Orchestrator finds work without being asked:
- Morning: Scan error logs, spawn fix agents
- After meetings: Extract action items, spawn feature agents
- Evening: Update docs, changelog

**Our equivalent:** Heartbeats partially do this. Should expand to scan Sentry/error logs if available.

### 7. Agent Selection by Task Type
- **Backend logic, complex bugs, multi-file:** Codex / Claude Code (thorough)
- **Frontend, UI, git operations:** Claude Code (faster)
- **Design/UI spec:** Gemini (design sensibility) then hand to Claude Code to implement

### 8. Failure Recovery with Context
When agent fails, don't respawn with same prompt. Analyse failure with business context:
- Out of context? "Focus only on these three files."
- Wrong direction? "Customer wanted X not Y. Here's what they said."
- Missing info? Provide the specific data needed.

**Our equivalent:** We do this manually. Should codify retry patterns.

## Cost Reference (Elvis's Setup)
- ~$100/month Claude API
- ~$90/month Codex
- Can start with $20/month
- His bottleneck: RAM (16GB Mac Mini tops out at 4-5 parallel agents)
- Upgrading to Mac Studio M4 Max 128GB ($3,500)

## Our Setup Comparison
- Intel Mac (limited parallel agents due to CPU/RAM)
- Mac Mini M4 on Rob's radar (EUR979, 2-3 week delivery)
- Current cost: Anthropic subscription (OAuth, compliance risk) -- moving to API

## Next Steps to Implement
1. [ ] Install Gemini Code Assist on GitHub repos (free)
2. [ ] Formalise task registry JSON for coding projects
3. [ ] Add "Definition of Done" checklist to coding-agent skill
4. [ ] Add screenshot requirement for UI PRs
5. [ ] Consider worktree pattern when Mac Mini arrives (needs RAM)
