agent-collaboration-protocol

Files (8)

• origin.json · .clawhub/
• SKILL.md
• _meta.json
• clawhub.json
• handoff-format.md · references/
• integration-log.md · references/
• spec-template.md · references/
• init_collab.sh · scripts/

SKILL.md (first lines)

# Agent Collaboration Protocol

## How It Works

Three roles collaborate through a shared workspace:

| Role | Responsibility |
|------|---------------|
| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |
| **Backend Engineer** | Writes API code, data models, infrastructure |
| **Frontend Engineer** | Writes UI components, templates, styles |

The contract lives in `shared/build-{YYYYMMDD}/`. 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:

```markdown
# SPEC: {Feature Name}

## Contract
- API base path, auth scheme, content type
- Data models (all entities, fields, types, relationships)
- Endpoints (method, path, request/response shapes)
- Error format

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

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

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

### Step 2: Orchestrator Spawns Agents

Spawn two subagents with `sessions_spawn`:

**Backend Engineer:**
```
task: >
  Implement the API spec in shared/build-{YYYYMMDD}/SPEC.md.
  Write all backend code to shared/build-{YYYYMMDD}/backend/.
  Update shared/build-{YYYYMMDD}/integration.md with progress.
  Use {backend framework} (FastAPI, Express, etc.).
```

**Frontend Engineer:**
```
task: >
  Implement the UI for the spec in shared/build-{YYYYMMDD}/SPEC.md.
  Write all frontend code to shared/build-{YYYYMMDD}/frontend/.
  Use the API contract in SPEC.md for your fetch calls.
  Update shared/build-{YYYYMMDD}/integration.md with progress.
  Use {frontend stack} (HTMX+Tailwind, React, etc.).
```

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

### Step 3: Both Build Simultaneously

**Backend Engineer writes to** `shared/build-{YYYYMMDD}/backend/`:
- Router/handler code
- Data models and schemas
- Config and infrastructure files
- Updates `integration.md` with progress and any blockers

**Frontend Engineer writes to** `shared/build-{YYYYMMDD}/frontend/`:
- UI components / templates
- Styles and layout
- API client code
- Updates `integration.md` with progress and any blockers

### Step 4: Orchestrator Verifies and Merges

1. Read `integration.md` from both agents
2. Inspect files in `backend/` and `frontend/`
3. Verify API responses match UI expectations
4. If mismatches found, send corrections to the responsible agent
5. Move code to production paths
6. Archive the build directory (or delete it)

## 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)

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills