Agent Collaboration Protocol

How It Works

Three roles collaborate through a shared workspace:

The contract lives in a shared/build-{YYYYMMDD}/ directory on the filesystem. The orchestrator MUST provide the full absolute path (e.g. /home/user/project/shared/build-{YYYYMMDD}/) in all handoff messages — isolated subagent sessions do not resolve relative paths reliably. Both builders write to the same directory. The orchestrator inspects and merges when both are done.

Workflow

Step 1: Orchestrator Creates the Build Directory and Contract

shared/build-{YYYYMMDD}/
  SPEC.md          ← Integration contract
  backend/         ← Backend Engineer writes here
  frontend/        ← Frontend Engineer writes here
  integration.md   ← Both update as they work

Write SPEC.md with these sections:

# SPEC: {Feature Name}

## Contract
- API base path, auth scheme, content type
- Data models (all entities, fields, types, relationships)
- Endpoints (method, path, request/response shapes)
- Shared constants (status enums, error codes, feature flags)
- Error format

## Routes
Backend Engineer implements these. Frontend Engineer consumes them.

## UI Components
Frontend Engineer builds these. Backend Engineer doesn't touch them.

## Shared Constants
Both agents use these. Status enums, error codes, UI state labels.

## Success Criteria
Observable behavior. Not "tests pass" — "user can log in and see calendar."

For the full spec template with examples, see references/spec-template.md.

Step 2: Orchestrator Spawns Agents

Spawn two subagents with sessions_spawn:

Backend Engineer:

task: >
  Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.
  Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.
  Update {ABSOLUTE_BUILD_DIR}/integration.md with progress.
  IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.
  Use {backend framework} (FastAPI, Express, etc.).

Frontend Engineer:

task: >
  Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.
  Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.
  Use the API contract in SPEC.md for your fetch calls.
  Update {ABSOLUTE_BUILD_DIR}/integration.md with progress.
  IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.
  Use {frontend stack} (HTMX+Tailwind, React, etc.).

Set mode: "run" for one-shot completion.

Step 3: Both Build Simultaneously

Backend Engineer writes to {ABSOLUTE_BUILD_DIR}/backend/:

• Router/handler code
• Data models and schemas
• Config and infrastructure files
• Updates {ABSOLUTE_BUILD_DIR}/integration.md with progress and any blockers

Frontend Engineer writes to {ABSOLUTE_BUILD_DIR}/frontend/:

• UI components / templates
• Styles and layout
• API client code
• Updates {ABSOLUTE_BUILD_DIR}/integration.md with progress and any blockers

Step 4: Orchestrator Verifies and Merges

1. Check that artifacts actually landed — run ls on both {ABSOLUTE_BUILD_DIR}/backend/ and {ABSOLUTE_BUILD_DIR}/frontend/. Do not trust completion messages alone.
2. Read integration.md from both agents
3. Inspect files in backend/ and frontend/
4. Verify API responses match UI expectations
5. If mismatches found, follow the Recovery Protocol below
6. Move code to production paths
7. Archive the build directory (or delete it)

Recovery Protocol

When something goes wrong during a parallel build, follow these steps:

Agent Crash or Timeout

1. Verify artifacts first — ls {ABSOLUTE_BUILD_DIR}/backend/ or {ABSOLUTE_BUILD_DIR}/frontend/. A "completed successfully" status does not guarantee files were written to the expected path.
2. Check if the agent produced any files before crashing
3. Read integration.md — did it log progress before failing?
4. Re-spawn the agent with the same task + a note: "Previous run crashed. Continue from where you left off. Read integration.md for progress so far."
5. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces

Build Mismatch (API ≠ UI)

1. Identify the specific mismatch (field names, response shape, auth flow)
2. Determine which side is correct by re-reading SPEC.md
3. Send a targeted correction to the wrong agent — not a full re-spawn, just: "Fix {specific thing}. The spec says {X} but your code does {Y}."
4. If both sides deviated from spec, update SPEC.md with the correct contract, then correct both

Blocked Agent

1. Read the blocker in integration.md
2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):
   • Check if backend's route handler exists even partially
   • If yes, tell frontend to mock the expected response shape from the spec
   • If no, tell frontend to stub the API client and proceed with placeholder data
3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human

integration.md Conflict

If both agents edit integration.md simultaneously and create a conflict:

1. Read both versions
2. Merge manually — keep both progress sections
3. Write the merged version back
4. Consider switching to a per-agent log format (see references/integration-log.md)

Verification Guide

Before declaring the build complete, verify:

Backend Verification

# Test each endpoint from the spec
curl -s http://localhost:8000/api/v1/{resource} | jq .
curl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .

Frontend Verification

• Loading state renders (spinner/skeleton)
• Empty state renders (no data message)
• Error state renders (actionable error message)
• Populated state renders (data from API)
• All user interactions work (click, submit, navigate)

Integration Verification

• Frontend fetch calls match backend endpoint paths
• Request/response shapes match the spec
• Error responses display correctly in the UI
• Auth flow works end-to-end

Setup Script

Run once per project to initialize the collaboration structure:

scripts/init_collab.sh /path/to/project

Creates shared/ with template SPEC.md and .gitignore.

Reference Files

For deeper patterns and templates:

• references/spec-template.md — Full SPEC.md template with examples
• references/integration-log.md — integration.md status format
• references/handoff-format.md — Task handoff message template

When Not to Use

• Single-file changes (just do it directly)
• Solo tasks that don't cross backend/frontend boundaries
• Bug fixes that are purely backend or purely frontend
• Tasks where one agent can handle both sides (use a single subagent instead)

Limitations

• Requires the sessions_spawn tool (OpenClaw v1.0+)
• Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)
• Not a replacement for a design system — frontend engineer should have access to design tokens separately