Swarm Coordination

Protocols and patterns for consistent, conflict-free multi-agent development. Follow these guidelines when working alongside other Claude Code agents in the same codebase.

Core Principles

1. Two-Tier Task Tracking: Durable work items live in GitHub Issues (or a committed ISSUES.md); in-flight work lives in the orchestrator's native task list (TaskCreate/TaskUpdate/TaskList)
2. File Locking: Hooks automatically manage file locks - respect them
3. Session Isolation: Each agent has a unique session ID for tracking
4. Clean Handoffs: Always leave state — and an artifact reference — that another agent can continue from

Two-Tier Task Tracking

• Tier 1 — Durable record: GitHub Issues (or ISSUES.md for repos without a tracker) hold the permanent history of work items: what was requested, why, and its final disposition.
• Tier 2 — In-flight work: The orchestrator owns a native task list (TaskCreate/TaskUpdate/TaskList). One task per work item, each with explicit acceptance criteria. Workers do not maintain their own task lists (see .claude/rules/agent-constraints.md for the no-shared-state rule).
• Handoffs: see Core Directives §7 "Follow Command Protocols" — every handoff needs a verifiable artifact reference.

File-Based Output