Multi-Agent Coordination

Multi-Agent Coordination

Multi-agent coordination is the PopKit pattern for dividing work across executor, reviewer, coordinator, and human-owner lanes while keeping the handoff visible.

This is the canonical product language for new planning. Existing Power Mode commands can stay as compatibility entry points while they are renamed, retired, or wired into the same contract.

The Core Loop

Plan -> Claim -> Execute -> Handoff -> Review -> Continue, merge, or ask the owner

The loop only works when every lane has enough context to continue without rereading a full transcript. PopKit uses handoff packets for that boundary.

Roles

Role	Responsibility
Coordinator	Splits work, assigns lanes, watches conflicts, and routes handoffs.
Executor	Makes the bounded change and reports evidence, validation, and blockers.
Reviewer	Checks executor claims against the code, tests, docs, or live system.
Human owner	Makes product, security, cost, credential, or merge-gate decisions.

The human owner is not a silent fallback. When a lane needs a decision, the handoff should name the configured owner display name and state the decision in one place.

Handoff Contract

The durable artifact is CoordinationHandoff, defined by packages/popkit-core/output-styles/schemas/coordination-handoff.schema.json.

Every handoff records:

• handoff_id and coordination_id for traceability.
• from and to participants, including role, lane, provider, and session reference when available.
• objective, status, and summary.
• claims with evidence instead of unsupported assertions.
• artifacts such as files, commits, PRs, checks, logs, screenshots, or notes.
• review when a reviewer lane is producing the handoff.
• human_callout when owner input is required.
• requested_actions and a verbatim next_message for the next participant.

Human Callouts

Human callouts are part of the schema because they change routing. A lane that needs the owner should not continue automatically.

{
  "display_name": "Project owner",
  "decision_needed": "Choose whether Lane B should merge before Lane C starts the follow-up refactor.",
  "why_now": "Both lanes edit the same workflow surface and automatic continuation could create conflicts.",
  "options": ["Merge Lane B first, then rebase Lane C", "Pause Lane B and let Lane C finish first"],
  "default_if_unanswered": "Stop and leave the handoff in needs-human status."
}

In a local setup, the display name should come from project or user config. Public package docs should not hard-code a specific person’s name.

Example Packet

{
  "schema_version": 1,
  "handoff_id": "handoff-docs-lane-b-2026-05-21T01-30-00Z",
  "coordination_id": "coord-popkit-docs-refresh-2026-05-21",
  "created_at": "2026-05-21T01:30:00Z",
  "from": {
    "role": "executor",
    "lane_id": "lane-b",
    "provider": "codex"
  },
  "to": {
    "role": "reviewer",
    "lane_id": "lane-b-reviewer",
    "provider": "claude-code"
  },
  "objective": "Clarify Windows VS Code MCP setup docs.",
  "status": "needs-review",
  "summary": "Docs now use the primary popkit-mcp binary, a near-real Windows Scripts path, and a literal health_check smoke prompt.",
  "claims": [
    {
      "claim": "The docs use popkit-mcp as the primary binary and mention popkit-mcp-server only as an alias.",
      "evidence": [
        {
          "kind": "file",
          "ref": "packages/docs/src/content/docs/guides/mcp-providers.md"
        }
      ]
    }
  ],
  "artifacts": [
    {
      "kind": "pr",
      "ref": "https://github.com/jrc1883/popkit-ai/pull/436"
    }
  ],
  "requested_actions": [
    {
      "actor": "reviewer",
      "action": "Verify the Windows setup wording and smoke predicate against the MCP server registration.",
      "required": true
    }
  ],
  "next_message": "Review PR #436 for Windows VS Code MCP setup accuracy. Check the binary names, Scripts path fallback, MCP Connected predicate, and health_check prompt."
}

What This Does Not Promise Yet

This contract does not mean PopKit can already send messages between every open Claude Code, Codex, VS Code, or terminal session. It creates the shared packet those integrations should emit, validate, and exchange.

The next implementation step is a local command or MCP tool that creates a CoordinationHandoff packet from the current lane state and validates it before another lane consumes it.