Multi-Agent Protocol v2

OpenClaw-native multi-agent protocol. Keep the good parts from v1:

• - spec-first
• review gates
• retry with circuit breaker

Replace the brittle parts from v1:

• - no fixed sessionKey memory contract
• no INLINECODE1
• no undeclared beads or git dependency
• no prompt-only state machine
• no LangGraph

Architecture

Use the stack below and do not silently swap layers:

1. 1. INLINECODE4

Defines protocol, roles, dependency expectations, and non-negotiable rules.

1. 2. INLINECODE5

Owns orchestration flow and agent dispatch.

1. 3. INLINECODE6

Owns approval, pause/resume, and side-effect recovery templates.

1. 4. task-store plugin

Owns authoritative task state via typed tools + SQLite event log.

1. 5. INLINECODE8

Connects external coding harnesses such as Codex.

Source Of Truth

The source of truth is the task-store plugin, not prompts and not reviewer output.

• - Canonical task phase lives in SQLite.
• Every phase change is an event.
• Reviewers append findings and verdicts.
• Reviewers do not finalize phase transitions.
• The orchestrator is the only actor that decides phase movement.

Required Dependencies

Declare these dependencies explicitly in the skill or the workflow setup:

• - OpenClaw runtime with INLINECODE10
• INLINECODE11 runtime for approval/resume
• INLINECODE12 plugin enabled
• local SQLite availability
• ACP bridge when external harnesses are involved

Optional, but explicit when used:

• - INLINECODE13
• browser/runtime plugins
• language-specific build tools

Do not assume:

• - INLINECODE14
• INLINECODE15
• INLINECODE16
• persistent role memory through fixed sessions
• INLINECODE17

Core Rules

1. Spec-first

No execution phase starts before a spec record exists in task-store.

Minimum spec payload:

• - INLINECODE19
• INLINECODE20
• INLINECODE21
• INLINECODE22
• INLINECODE23
• INLINECODE24
• INLINECODE25

If acceptance criteria are weak or missing, the orchestrator keeps the task in spec_draft.

2. Phase transitions are explicit

Use a stored phase enum. Recommended baseline:

CODEBLOCK0

All transitions must be written through task_transition.

3. Reviewers are evidence producers

Reviewer output is evidence, not authority.

• - Spec reviewer answers: "Does the artifact satisfy the spec?"
• Quality reviewer answers: "Is the implementation acceptable for maintainability and risk?"
• Reviewers write findings via task_append_review.
• The orchestrator reads review state and decides the next phase.

4. Retry and circuit breaker are stored state

Retries are not tracked in free text.

• - attempt counters live in SQLite
• retry reasons are evented
• circuit state is explicit

Recommended policy:

• - attempt 1-2: retry same phase with bounded backoff
• INLINECODE30: optional stronger model/runtime
• INLINECODE31: INLINECODE32

5. Side effects require Lobster gates

Any real-world effect should pass through Lobster:

• - writing to external systems
• approvals
• irreversible file mutations outside the declared sandbox
• deployments
• notifications
• merges

Lobster pauses, requests approval, and resumes from persisted state.

6. ACP is the bridge for external harnesses

When using Codex or another external coding harness:

• - launch work through ACP, not prompt-only relays
• pass task_id, attempt_id, workspace, and allowed capabilities
• capture external session metadata as non-authoritative references

Practical note inferred from the local OpenClaw installation: parent streaming features such
as streamTo are tied to runtime=acp, not generic subagent runtime. Design the workflow
accordingly.

Role Model

Orchestrator

The orchestrator:

• - creates the task record
• validates spec completeness
• dispatches agents
• reads stored findings
• decides phase transitions
• triggers Lobster when approval or recovery is needed
• opens the circuit when retries are exhausted

The orchestrator does not become a passive message relay or free-form blackboard parser.

Executor

The executor may be:

• - a local OpenClaw worker
• an ACP-backed external harness such as Codex
• a read-only research agent

Executor responsibilities:

• - produce artifacts
• record attempt heartbeat/checkpoints through typed tools
• report structured outputs and evidence

Executor cannot finalize completed, failed, or gate transitions on its own.

Spec Reviewer

Reads the actual artifact and records one of:

• - INLINECODE40
• INLINECODE41
• INLINECODE42

Plus findings with file references or artifact references.

Quality Reviewer

Reads the actual artifact after spec gate passes and records:

• - maintainability concerns
• test gaps
• safety or regression risk
• approval/rework recommendation

Lobster Approver / Recovery Actor

Lobster manages:

• - approval prompts
• pause/resume after interruption
• resuming idempotent or compensating side-effect steps

Lobster does not own the business workflow phase. It only writes approval state and recovery
evidence back to task-store.

Minimal Lifecycle

CODEBLOCK1

Failure branches:

CODEBLOCK2

Protocol By Phase

spec_draft

• - Create task in task-store.
• Persist full spec content or spec reference.
• Do not spawn builders yet.

spec_review

• - Reviewer checks the spec itself for ambiguity and testability.
• Orchestrator either:

- fixes the spec and stays in spec_draft, or - transitions to INLINECODE48

execution_ready

• - Orchestrator chooses runtime:

- local worker for low-side-effect or local tasks - ACP for Codex/external harness

• - Orchestrator creates a new attempt record.

executing

• - Executor works only against declared inputs/outputs.
• Checkpoints go through typed tools.
• Side effects are declared ahead of time as planned actions.

spec_gate

• - Spec reviewer inspects produced artifact.
• Reviewer writes findings only.
• Orchestrator decides:

- pass to quality_gate - rework back to execution_ready - open circuit if repeated mismatch indicates spec or implementation collapse

quality_gate

• - Quality reviewer records findings only.
• Orchestrator decides:

- completed - execution_ready - INLINECODE57

awaiting_approval

• - Lobster requests human approval with structured context.
• Approved result becomes evidence in store.
• Orchestrator transitions to ready_to_resume.

ready_to_resume

• - Lobster or orchestrator resumes the exact side-effect step using persisted idempotency data.

circuit_open

• - Stop automatic retries.
• Surface:

- failure summary - attempts - last known good artifact - unblock options

What Goes In Storage

The task-store plugin should persist at least:

• - task header
• current phase
• spec payload or reference
• review records
• attempt records
• artifact records
• approval records
• event log
• optional external session references

The plugin storage is authoritative. Prompt text is not.

OpenProse Guidance

The .prose workflow should be minimal and boring:

• - read state
• branch on typed state
• dispatch one actor
• store result
• decide next phase

Do not encode business state only in the prose graph. The graph coordinates. The plugin stores.

Read workflows/openclaw-native-v2.prose when wiring the
workflow.

Lobster Guidance

Use Lobster only where it adds hard guarantees:

• - approval request with resumable context
• idempotent recovery after interruption
• controlled side-effect replay

Read lobster/approval-recovery.template.yaml when a
task contains side effects or human approval.

Plugin Guidance

Use the task-store plugin as the only write path for protocol state.

Read references/task-store-plugin.md when:

• - implementing the plugin
• validating tool shapes
• deciding schema changes

Permissions

Use least privilege. The matrix lives in
references/agent-permissions.md.

Key rule:

• - executors can write artifacts and attempts
• reviewers can write findings
• only orchestrator can move the phase

Migration Rules From v1

Read references/migration.md before replacing an existing v1 setup.

Summary:

• - replace fixed session identity with run-scoped attempt_id and optional INLINECODE66
• replace blackboard with typed storage
• replace beads/git buses with plugin tools
• replace reviewer-led state changes with orchestrator-led transitions

Quick Start

1. 1. Enable task-store.
2. Create a task with a full spec.
3. Run the OpenProse workflow.
4. Route external coding work through ACP.
5. Use Lobster only for approval/recovery steps.
6. Let orchestrator decide every phase transition from stored evidence.

Anti-Patterns

Do not do any of the following:

• - use fixed role sessionKey as the memory backbone
• store canonical state in INLINECODE69
• let reviewer verdict directly close the task
• let executor mutate final phase
• assume git or beads exists without declaring it
• recover from interruption by guessing from prompt history
• add LangGraph just to simulate a state machine already held in SQLite