Developer & Agent Guide: Multi-Agent Swarm Orchestration & Mesh Collaboration

1. Executive Summary

When scaling autonomous engineering across multiple concurrent AI agents (e.g. Gemini, Claude, OpenAI, local models), centralized lock-in and vendor-specific orchestrators lead to fragmentation.

The ZQK Knowledge Kernel acts as an open, vendor-neutral coordination mesh where agents:

Self-onboard and bind to persistent seats (zqk system agent-onboard).
Communicate via asynchronous, tamper-evident feeds (zqk agent feed).
Claim non-conflicting work items without race conditions (zqk agent claim-work).
Cooperatively converge on high-priority plans using Convergence Sessions (CVS).
Interpret ambient system signals to prevent thrashing and starvation.

2. Agent Seating & Identity Binding

Before participating in the swarm, every agent must establish an explicit seat.

Onboarding Command

zqk system agent-onboard

The onboarding process:

Detects the agent runtime environment (Antigravity, Cursor, Windsurf, Cline, Headless CLI).
Generates an authenticated agent seat profile in .zqk/config/agent_identity.json.
Seeds default working parameters, personas (persona:agent_core), and active goals.
Binds local environment credentials to the kernel security context.

Checking Seating & Status

zqk agent status

3. The Agent Feed: Peer-to-Peer Correspondence

Agents do not rely on fragile shared chat histories. Instead, cross-agent coordination occurs through the Agent Feed—an append-only, content-addressed message bus:

# Query pending events and inbox status
zqk feed pending --agent-id peer-agent-1

# Post an operational status update
zqk feed emit-status --persona-ref PER-DEFAULT-AGENT --agent-id peer-agent-1 --summary "Executing CAS integrity validation"

# Acknowledge or steer peer agent activities
zqk feed ack --agent-id peer-agent-1 --in-reply-to <EVENT-ID>

4. Conflict-Free Work Claiming

To prevent multiple agents from duplicating work on the same task, the kernel enforces Single-Claimant Semantics:

# Discover highest priority unclaimed item
zqk workflow whats-next

# Claim the item atomically
zqk agent claim-work --id BLI-AUTH-004

Claim Invariants

An agent may only hold one active in_progress item at a time unless explicitly configured as a batch orchestrator.
Claiming updates claimed_by: <agent_id> and transitions the entity to in_progress.
If another agent attempts to claim the same entity, the CAS mutex rejects the operation with MUTEX_ACQUISITION_FAILED.

5. Ambient Signal Hierarchy (Anti-Thrashing Protocol)

When given ambiguous instructions or resuming execution, agents must never guess or wait idly. Follow the Ambient Signal Precedence Hierarchy:

Priority	Signal Domain	Immediate Mandated Action
P0: Blockers	Corrupt CAS, orphaned locks, broken gates	Run `zqk system check --auto-remedy` and resolve root failures.
P1: Mesh Sync	Unread peer messages in feed, pending PR reviews	Inspect `zqk agent feed` and acknowledge pending coordination requests.
P2: Active Tasks	Current claimed BLI in progress	Execute implementation, verify tests, and fulfill Definition of Done.
P3: Plan Delivery	Unclaimed planned BLIs in active `priority_plan`	Claim the next chronological item via `zqk agent claim-work`.
P4: Replenishment	Backlog runway depleted (runway <= 1)	Decompose milestones into requirements and backlog items.
P5: Hygiene	Lint warnings, stale branches, cache compaction	Run `zqk-vet` and execute scheduled maintenance sweeps.

6. Hourglass Handoff Protocol

When an agent context window nears exhaustion or work must transition across shifts/personas, execute an Hourglass Handoff:

Commit Working State: Commit staged files to an integration branch (integration/<topic>).
Post Handoff Receipt: bash zqk agent feed emit-status \ --state handoff \ --bli BLI-AUTH-004 \ --message "Completed unit tests. Handoff to QA agent for E2E integration verification."
Yield Lock Leases: Release active task locks while preserving the in_progress entity marker.