{
  "id": "2026-05-07-openclaw-multi-agent-coordination-design-e19feca025",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/superpowers/specs/2026-05-07-openclaw-multi-agent-coordination-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.778Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "OpenClaw Multi-Agent Coordination Plugin Design",
  "summary": "OpenClaw Multi Agent Coordination Plugin Design Purpose Create a public OpenClaw plugin that turns OpenClaw from a personal assistant runtime into a parallel multi agent work system. OpenClaw already has strong distribution, channels, tools, sessions, subagents, cron, webhooks, background tasks, and local first UX. The missing primitive is a shared coordinat...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Purpose",
      "level": 2,
      "body": "Create a public OpenClaw plugin that turns OpenClaw from a personal assistant runtime into a parallel multi-agent work system.\n\nOpenClaw already has strong distribution, channels, tools, sessions, subagents, cron, webhooks, background tasks, and local-first UX. The missing primitive is a shared coordination layer that lets multiple independent agents pull from the same ordered queue, claim work safely, hand off outputs, wait on dependencies, and advance repeatable workflows without sharing one chat context.\n\nThe product frame is:\n\n```text\nOpenClaw gives agents tools.\nRedKey gives agents a shared queue they can pull from in parallel.\n```\n\nThe public plugin should make this feel native to OpenClaw. The paid RedKey layer provides the real verified coordination bus."
    },
    {
      "title": "Core Thesis",
      "level": 2,
      "body": "The power is not \"one agent delegates to five agents.\"\n\nThe power is:\n\n```text\nfive agents can all pull from the same queue\n```\n\nThat is what creates scale.\n\nIn a delegation model, the parent agent remains the bottleneck. It has to decide what to send, who to send it to, when to check back, and how to merge results. That works for small jobs, but it still behaves like one busy manager.\n\nIn a pull-based coordination model, work is published once. Any eligible agent can see it. The first valid claim wins. As soon as one task completes, dependent tasks open. More agents can join the queue without rewriting the workflow.\n\nScale comes from queue depth and agent availability, not from a single model deciding every handoff.\n\nThis should be the lead use case:\n\n```text\nOne queue.\nFive agents.\nParallel claims.\nOrdered handoffs.\nMore throughput without more chat management.\n```"
    },
    {
      "title": "What OpenClaw Has Today",
      "level": 2,
      "body": "OpenClaw already has a real concept of multiple agents. It is not only one giant agent doing different things.\n\nOpenClaw supports:\n\n- **Isolated agents:** each `agentId` can have its own workspace, persona files, auth profiles, model config, and session store.\n- **Channel/account routing:** inbound messages can route to different agents based on channel, account, peer, team, guild, or thread bindings.\n- **Subagents:** an agent can spawn isolated child sessions for background work through `sessions_spawn`.\n- **Background task tracking:** subagent, ACP, cron, and CLI runs create task records with status.\n- **Task Flow:** durable multi-step flow tracking above background tasks.\n\nThat is useful, but it is not the same as a shared multi-agent operating queue.\n\nOpenClaw's current multi-agent model is mainly:\n\n```text\nroute this message to the right isolated agent\nor\nlet this agent spawn a child run for a delegated task\n```\n\nThe RedKey plugin adds:\n\n```text\npublish work to a shared queue\nlet multiple eligible agents pull work in parallel\norder competing claims\nrecord handoffs\nopen dependent tasks\nadvance workflow state\nmake task receipt visible outside any one chat/session\n```\n\nThis distinction should be central in public messaging. We are not saying OpenClaw lacks agents. We are saying OpenClaw lacks a verified pull-based coordination bus for agents that need to work as a team."
    },
    {
      "title": "Product Positioning",
      "level": 2,
      "body": "Public name:\n\n```text\nOpenClaw Multi-Agent Coordination\n```\n\nPossible repo names:\n\n```text\nopenclaw-coordination\nopenclaw-multi-agent\nopenclaw-workflows\n```\n\nRecommended repo name:\n\n```text\nopenclaw-coordination\n```\n\nPublic description:\n\n> Parallel multi-agent coordination for OpenClaw. Give independent OpenClaw agents a shared queue where they can pull work, claim tasks, hand off outputs, and advance workflows together.\n\nAvoid leading with \"workflow engine.\" Workflows are the outcome. Coordination is the missing primitive."
    },
    {
      "title": "Strategic Split",
      "level": 2,
      "body": "The product has two layers."
    },
    {
      "title": "Public OpenClaw Plugin",
      "level": 3,
      "body": "The public plugin provides:\n\n- Agent-facing coordination tools.\n- Workflow and task template definitions.\n- Local simulator mode for development and demos.\n- RedKey bus adapter for verified coordination.\n- CLI commands for status, start, approve, and inspect.\n- Minimal status UI if OpenClaw plugin surfaces make that practical.\n\nThe public plugin does not expose HCS implementation details."
    },
    {
      "title": "RedKey Verified Coordination",
      "level": 3,
      "body": "RedKey provides:\n\n- Hosted claim bus.\n- Verified event ordering.\n- RedKey-managed HCS topics and operator account for hosted plans.\n- Customer-owned HCS account/topics for enterprise.\n- Metering, billing, usage limits, and receipts.\n- Team cockpit, approval inbox, analytics, template marketplace, and support.\n\nInternal truth:\n\n```text\nHCS is the claim and queue mechanism.\n```\n\nPublic language:\n\n```text\nRedKey Verified Coordination provides a hosted coordination bus with ordered task claims and durable handoffs.\n```"
    },
    {
      "title": "Core User Story",
      "level": 2,
      "body": "A user has multiple OpenClaw agents:\n\n- researcher\n- writer\n- reviewer\n- producer\n\nThey start a workflow:\n\n```text\nPodcast prep -> script -> approval -> clips -> publish checklist\n```\n\nEach task is published to a shared bus. Eligible agents see work for their role. Several agents can pull from the same workflow at once. The bus resolves claim order, so only one agent owns each task. Completion opens the next task. The user can see the current workflow state and approve gates.\n\nThe user does not need to manually copy context between agents.\n\nScale example:\n\n```text\nOne podcast workflow creates 12 tasks.\nFive eligible agents watch the same queue.\nThree independent tasks open after guest intake.\nResearcher, writer, and producer claim different tasks at the same time.\nThe workflow moves faster because work is pulled in parallel.\n```"
    },
    {
      "title": "Use Cases",
      "level": 2,
      "body": "The cleanest use cases are ones where multiple agents can own different roles, but the work needs shared state."
    },
    {
      "title": "Personal Multi-Agent Workbench",
      "level": 3,
      "body": "A solo OpenClaw user has several specialist agents:\n\n- research agent\n- writing agent\n- coding agent\n- QA agent\n- admin agent\n\nToday, the user can talk to each agent or ask one agent to spawn subagents. With coordination, the user can start a workflow and let each specialist pull the next eligible task from the shared queue.\n\nExample:\n\n```text\nresearch -> write brief -> user approval -> generate assets -> publish checklist\n```"
    },
    {
      "title": "Creator and Podcast Operations",
      "level": 3,
      "body": "Podcast production needs repeated handoffs:\n\n```text\nguest intake -> research -> episode script -> host approval -> clips -> show notes\n```\n\nEach step can be owned by a different agent. The queue makes it clear what is waiting, who claimed it, what output was produced, and what opens next."
    },
    {
      "title": "Spec To Build",
      "level": 3,
      "body": "Software work needs role separation:\n\n```text\nintake -> product spec -> implementation plan -> build -> QA -> approval\n```\n\nOpenClaw can run the agents. RedKey coordination gives the agents shared task state and ordered handoffs."
    },
    {
      "title": "Team Assistant Network",
      "level": 3,
      "body": "A company can run several OpenClaw agents for different departments or people:\n\n- sales assistant\n- support assistant\n- ops assistant\n- finance assistant\n- executive assistant\n\nRouting gets messages to the right assistant. Coordination lets those assistants hand off cross-functional work without one chat thread becoming the process owner.\n\nExample:\n\n```text\ncustomer asks about invoice -> support agent triages -> finance agent claims billing task -> sales agent gets account-risk follow-up\n```"
    },
    {
      "title": "Verified Agent Marketplace",
      "level": 3,
      "body": "If OpenClaw users install third-party specialist agents, coordination becomes the trust boundary.\n\nThe user can see:\n\n- what task was offered\n- which agent claimed it\n- when it completed\n- what artifact it produced\n- whether the handoff opened the next task\n\nThis creates the base layer for paid workflow packs and specialist agent teams."
    },
    {
      "title": "Coordination Model",
      "level": 2,
      "body": "The bus is append-only from the plugin's point of view.\n\nImportant event types:\n\n- `workspace.created`\n- `workflow.started`\n- `task.published`\n- `task.claimed`\n- `task.started`\n- `task.progressed`\n- `task.completed`\n- `task.blocked`\n- `task.failed`\n- `artifact.written`\n- `approval.requested`\n- `approval.approved`\n- `approval.rejected`\n- `step.advanced`\n- `workflow.completed`\n- `workflow.cancelled`\n\nThe bus resolves the actual state by ordered events.\n\nFor verified mode, ordered events are written through RedKey to HCS. The first valid claim by consensus order wins.\n\nFor local simulator mode, ordered events are written to SQLite. This is useful for demos and single-machine testing, but it is not the verified coordination product."
    },
    {
      "title": "Parallel Pull Model",
      "level": 2,
      "body": "The default execution model is pull-based.\n\nAgents do not wait for a parent agent to assign them work. They watch the queue for tasks that match their eligibility:\n\n- role\n- capability\n- tool access\n- workspace\n- model requirement\n- priority\n- dependency state\n\nWhen a task becomes available, every eligible agent can attempt to claim it. The bus orders those claim attempts and accepts the first valid claim. Later claims are rejected with a clear reason.\n\nThe state machine is:\n\n```text\npublished -> available -> claimed -> running -> completed\n                                      -> blocked\n                                      -> failed\n```\n\nDependencies are opened by state, not by conversation:\n\n```text\nTask A completed\n  -> Task B and Task C become available\n  -> writer and researcher both pull in parallel\n  -> Task D waits until B and C complete\n```\n\nThis lets a five-agent team work like a queue-driven operation:\n\n```text\nresearcher pulls research tasks\nwriter pulls draft tasks\nreviewer pulls review tasks\nproducer pulls asset tasks\nadmin pulls publish/checklist tasks\n```\n\nThe queue is the manager. Agents are workers with eligibility rules.\n\nThis is the difference between \"spawn a subagent\" and \"run an agent team.\""
    },
    {
      "title": "Claim Bus Interface",
      "level": 2,
      "body": "The plugin should depend on a neutral bus interface.\n\n```ts\nexport interface ClaimBus {\n  publishTask(task: PublishTaskInput): Promise<CoordinationReceipt>;\n  claimTask(input: ClaimTaskInput): Promise<ClaimResult>;\n  startTask(input: StartTaskInput): Promise<CoordinationReceipt>;\n  completeTask(input: CompleteTaskInput): Promise<CoordinationReceipt>;\n  blockTask(input: BlockTaskInput): Promise<CoordinationReceipt>;\n  failTask(input: FailTaskInput): Promise<CoordinationReceipt>;\n  requestApproval(input: ApprovalRequestInput): Promise<CoordinationReceipt>;\n  resolveApproval(input: ApprovalDecisionInput): Promise<CoordinationReceipt>;\n  appendEvent(event: CoordinationEvent): Promise<CoordinationReceipt>;\n  listEvents(scope: EventScope): Promise<CoordinationEvent[]>;\n  getWorkflow(runId: string): Promise<WorkflowState>;\n  watchTasks(filter: TaskWatchFilter): AsyncIterable<CoordinationEvent>;\n}\n```\n\nInitial adapters:\n\n```text\nlocal-sqlite-bus\nredkey-verified-bus\n```\n\nFuture adapters:\n\n```text\npostgres-bus\ncustomer-hcs-bus\n```\n\nThe public plugin includes local SQLite and RedKey API adapters. It does not include direct HCS logic in V1."
    },
    {
      "title": "RedKey Bus API",
      "level": 2,
      "body": "The plugin talks to RedKey over HTTPS.\n\nExample endpoints:\n\n```text\nPOST /v1/workspaces\nPOST /v1/workflows/start\nGET  /v1/workflows/:runId\nPOST /v1/tasks\nPOST /v1/tasks/:taskId/claim\nPOST /v1/tasks/:taskId/start\nPOST /v1/tasks/:taskId/complete\nPOST /v1/tasks/:taskId/block\nPOST /v1/approvals/:approvalId/decision\nGET  /v1/events?runId=...\nGET  /v1/usage\n```\n\nThe RedKey API handles:\n\n- HCS topic creation.\n- HCS message submission.\n- Mirror node reads or equivalent event reconstruction.\n- Claim race resolution.\n- Usage metering.\n- Receipt generation.\n- API keys and workspace identity.\n\nThe plugin sees receipts, not raw HCS mechanics."
    }
  ],
  "html_path": "artifacts/2026-05-07-openclaw-multi-agent-coordination-design-e19feca025.html",
  "json_path": "artifacts/2026-05-07-openclaw-multi-agent-coordination-design-e19feca025.json"
}