{"id":"00cfdc28-0ea7-4d4d-94ce-93ff4e17bb2c","entityType":"agent","slug":"clawhub-nightknight64-agent-collaboration-protocol","name":"Agent Collaboration Protocol","canonicalUrl":"https://www.xpersona.co/agent/clawhub-nightknight64-agent-collaboration-protocol","canonicalPath":"/agent/clawhub-nightknight64-agent-collaboration-protocol","generatedAt":"2026-10-11T10:50:18.938Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T07:51:48.168Z","emptyReason":null},"description":"Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on... Skill: Agent Collaboration Protocol Owner: nightknight64 Summary: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on... Tags: latest:1.5.3 Version history: v1.5.3 | 2026-05-09T16:25:35.138Z | user Security hardening: replaced all sudo systemctl commands with platform-agnostic service restart guidance. Fixed flawe","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1734cre4m4d0p2p7txrgyn9298636t0:agent-collaboration-protocol","sourceUrl":"https://clawhub.ai/nightknight64/agent-collaboration-protocol","homepage":"https://clawhub.ai/nightknight64/skills/agent-collaboration-protocol","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/nightknight64/agent-collaboration-protocol","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/nightknight64/skills/agent-collaboration-protocol","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on... "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:51:48.168Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:51:48.168Z","emptyReason":null},"stars":null,"forks":null,"downloads":1120,"packageName":null,"latestVersion":"1.5.3","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:51:48.108Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T07:51:48.168Z","lastCrawledAt":"2026-10-11T07:51:48.108Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T07:51:48.108Z","lastVerifiedAt":null,"highlights":[{"version":"1.5.3","createdAt":"2026-05-09T16:25:35.138Z","changelog":"Security hardening: replaced all sudo systemctl commands with platform-agnostic service restart guidance. Fixed flawed incremental build logic (rsync-into-symlink pattern removed). Deployment steps now describe patterns rather than copy-paste commands. Removed last rtsport reference.","fileCount":8,"zipByteSize":12226},{"version":"1.5.2","createdAt":"2026-05-09T16:14:31.871Z","changelog":"Security: removed hardcoded domain, user paths, and service names from SKILL.md and clawhub.json. All examples now use generic placeholders.","fileCount":7,"zipByteSize":10994},{"version":"1.5.1","createdAt":"2026-05-08T01:39:52.736Z","changelog":"v1.5.1: Fixed atomic current pivot — added full vs incremental build detection and rsync merge step. Documented the #1 symlink-swap failure mode (incremental build replacing entire tree).","fileCount":8,"zipByteSize":14135},{"version":"1.5.0","createdAt":"2026-05-08T01:12:05.885Z","changelog":"v1.5.0: Added Step 5 (Deploy & Activate) with atomic current symlink, Filesystem Conventions reference, and expanded scope guidance. Fixes 'edited wrong workspace copy' bugs.","fileCount":8,"zipByteSize":9424},{"version":"1.4.0","createdAt":"2026-05-06T14:21:58.883Z","changelog":"**Minor update adding identity clarification and log handling improvements.** - Clarifies that agent role identity comes from task context, not the label parameter in `sessions_spawn`. - Updates Recovery Protocol: orchestrator now reads from `integration.md` in failure scenarios; adds steps for resolving `integration.md` edit conflicts. - Adds a section outlining manual merge process for simultaneous edits to `integration.md`. - Reference and verification procedures updated to point to per-agent logs and `integration.md` as the shared integration log. - Introduces `_meta.json` and removes the old `README.md`; updates documentation structure.","fileCount":7,"zipByteSize":8924},{"version":"1.3.0","createdAt":"2026-05-06T13:58:11.317Z","changelog":"agent-collaboration-protocol v1.3.0 - Introduced per-agent log files (`backend-log.md`, `frontend-log.md`) to prevent simultaneous-write conflicts in integration logs. - Agents must now explicitly acknowledge (\"ACK\") the build directory path before beginning any work, improving handoff reliability. - Orchestrator now merges findings into a single `integration.md` after verifying agent logs and build artifacts. - Added clear abort/rescope triggers for orchestrators to recognize and halt unproductive multi-agent sessions. - Updated setup instructions and handoff protocols in documentation for greater clarity and robustness.","fileCount":8,"zipByteSize":13061},{"version":"1.2.0","createdAt":"2026-05-05T01:33:31.587Z","changelog":"v1.2.0: Absolute paths, artifact verification, {ABSOLUTE_BUILD_DIR} convention","fileCount":7,"zipByteSize":8583},{"version":"1.1.0","createdAt":"2026-05-04T19:56:11.701Z","changelog":"v1.1.0: Recovery protocol for crashes/mismatches/blocks, shared constants section, verification guide, per-agent log format, toned-down handoff monitoring, MIT-0 license","fileCount":7,"zipByteSize":8275}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1734cre4m4d0p2p7txrgyn9298636t0:agent-collaboration-protocol","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T10:50:18.936Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nightknight64-agent-collaboration-protocol/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T07:51:48.168Z","emptyReason":null},"readme":"Skill: Agent Collaboration Protocol\n\nOwner: nightknight64\n\nSummary: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on...\n\nTags: latest:1.5.3\n\nVersion history:\n\nv1.5.3 | 2026-05-09T16:25:35.138Z | user\n\nSecurity hardening: replaced all sudo systemctl commands with platform-agnostic service restart guidance. Fixed flawed incremental build logic (rsync-into-symlink pattern removed). Deployment steps now describe patterns rather than copy-paste commands. Removed last rtsport reference.\n\nv1.5.2 | 2026-05-09T16:14:31.871Z | user\n\nSecurity: removed hardcoded domain, user paths, and service names from SKILL.md and clawhub.json. All examples now use generic placeholders.\n\nv1.5.1 | 2026-05-08T01:39:52.736Z | user\n\nv1.5.1: Fixed atomic current pivot — added full vs incremental build detection and rsync merge step. Documented the #1 symlink-swap failure mode (incremental build replacing entire tree).\n\nv1.5.0 | 2026-05-08T01:12:05.885Z | user\n\nv1.5.0: Added Step 5 (Deploy & Activate) with atomic current symlink, Filesystem Conventions reference, and expanded scope guidance. Fixes 'edited wrong workspace copy' bugs.\n\nv1.4.0 | 2026-05-06T14:21:58.883Z | auto\n\n**Minor update adding identity clarification and log handling improvements.**\n\n- Clarifies that agent role identity comes from task context, not the label parameter in `sessions_spawn`.\n- Updates Recovery Protocol: orchestrator now reads from `integration.md` in failure scenarios; adds steps for resolving `integration.md` edit conflicts.\n- Adds a section outlining manual merge process for simultaneous edits to `integration.md`.\n- Reference and verification procedures updated to point to per-agent logs and `integration.md` as the shared integration log.\n- Introduces `_meta.json` and removes the old `README.md`; updates documentation structure.\n\nv1.3.0 | 2026-05-06T13:58:11.317Z | auto\n\nagent-collaboration-protocol v1.3.0\n\n- Introduced per-agent log files (`backend-log.md`, `frontend-log.md`) to prevent simultaneous-write conflicts in integration logs.\n- Agents must now explicitly acknowledge (\"ACK\") the build directory path before beginning any work, improving handoff reliability.\n- Orchestrator now merges findings into a single `integration.md` after verifying agent logs and build artifacts.\n- Added clear abort/rescope triggers for orchestrators to recognize and halt unproductive multi-agent sessions.\n- Updated setup instructions and handoff protocols in documentation for greater clarity and robustness.\n\nv1.2.0 | 2026-05-05T01:33:31.587Z | user\n\nv1.2.0: Absolute paths, artifact verification, {ABSOLUTE_BUILD_DIR} convention\n\nv1.1.0 | 2026-05-04T19:56:11.701Z | user\n\nv1.1.0: Recovery protocol for crashes/mismatches/blocks, shared constants section, verification guide, per-agent log format, toned-down handoff monitoring, MIT-0 license\n\nv1.0.0 | 2026-05-04T00:49:50.771Z | auto\n\nInitial release providing a structured protocol for coordinated multi-agent backend and frontend feature builds.\n\n- Defines three roles: Orchestrator, Backend Engineer, and Frontend Engineer, with clear responsibilities.\n- Introduces a shared build workspace and contract (SPEC.md) for collaboration and integration.\n- Details a step-by-step workflow for orchestrating, building, and merging full-stack features.\n- Includes setup instructions, integration logging, and reference templates.\n- Specifies scenarios where the protocol should or should not be used, and outlines current limitations.\n\nArchive index:\n\nArchive v1.5.3: 8 files, 12226 bytes\n\nFiles: _meta.json (147b), clawhub.json (876b), references/handoff-format.md (777b), references/integration-log.md (1708b), references/spec-template.md (3373b), scripts/init_collab.sh (1738b), skill-card.md (2465b), SKILL.md (14113b)\n\nFile v1.5.3:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Log your progress to {ABSOLUTE_BUILD_DIR}/frontend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n**Handoff acknowledgment is mandatory.** Each agent must confirm receipt and verify the build directory path exists before beginning work. If an agent does not ACK within a reasonable window (< 2 minutes), re-spawn it. See `references/handoff-format.md` for the full handoff template.\n\n> **Important: Identity comes from context, not the label.** The `label` parameter passed to `sessions_spawn` is a runtime tag for orchestrator tracking — it does NOT determine the agent's role. The subagent's role (Backend Engineer vs Frontend Engineer) is determined entirely by the orchestrator's context injection: the `task` message you provide tells the subagent what role to play, what files to write, and what contract to follow. Two subagents spawned with the same `label` can have completely different tasks and roles.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/backend-log.md`\n\n**Frontend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/frontend-log.md`\n\nEach agent has its own log file — **no simultaneous-write conflicts possible.**\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. Read both `backend-log.md` and `frontend-log.md` for progress\n2. Read `integration.md` for orchestrator notes\n3. Inspect files in `backend/` and `frontend/`\n4. Verify API responses match UI expectations\n5. If mismatches found, follow the Recovery Protocol below\n6. Verify against the [Verification Guide](#verification-guide)\n\n### Step 5: Deploy & Activate\n\nThe build is not done until the server reads from the new build. Follow these steps **in order**:\n\n**5a. Determine: full build or incremental?**\n\n| Build Type | What it means | Action |\n|------------|--------------|--------|\n| **Full build** | The build directory contains ALL project files (new + existing) | Point server at new build directly |\n| **Incremental build** | The build directory contains ONLY new/changed files | Integrate new files into the live tree first |\n\nMost collaborative builds are **incremental** — the backend and frontend agents only write the files they changed.\n\n**5b. Integrate incremental builds into the live tree**\n\nCopy new files from the build directory into the active deployment path. Use your platform's copy tool (cp, rsync, robocopy) with flags that preserve existing files. Only overwrite files that changed.\n\nAfter integration, verify the deployment is intact:\n```bash\n# Quick sanity: key endpoints still respond\ncurl -s -o /dev/null -w \"%{http_code}\" https://example.com/api/health\n```\n\n**5c. Point server at the new build (full builds)**\n\nUpdate your server's deployment target to the new build directory. On Unix systems this is typically a symlink swap (e.g. `ln -snf build-{YYYYMMDD}/ current`). On other platforms, update the server configuration directly.\n\n**5d. Configure server to use the deployment target**\n\nAny server config that references build paths should point to the deployment target (e.g. `current/`), never to a date-stamped directory. This is a **one-time config change** — set it once, then only the target changes on each deploy.\n\nExample pattern:\n```python\n# ✅ Correct — never needs updating after initial setup\nTEMPLATES = Path(\"/home/user/project/deploy/current/frontend\")\n\n# ❌ Wrong — bakes in a date, breaks after every deploy\nTEMPLATES = Path(\"/home/user/project/deploy/build-20260501/frontend\")\n```\n\n**5e. Restart the service**\n\nRestart your application server to pick up the new deployment. Use your platform's service manager (systemctl, supervisor, docker restart, etc.).\n\n**5f. Create workspace shortcuts (once per project)**\n\nSet up convenient access paths so the live deployment is easy to find and edit. On Unix: `ln -snf deploy/current/ ~/myproject`. On other platforms, create a shortcut or bookmark.\n\n**5g. Verify deploy**\n```bash\n# Confirm the deployment target points to the new build\nls -la /path/to/deploy/current\n# Check the server responds with the new code\ncurl -s https://example.com/health\n```\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. Check if the agent produced any files before crashing\n2. Read `integration.md` — did it log progress before failing?\n3. 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.\"\n4. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project\n```\n\nCreates `shared/` with template `SPEC.md` and `.gitignore`.\n\n## Filesystem Conventions\n\nEvery deployed project follows a three-tier filesystem pattern:\n\n| Path | Type | Purpose | Edit? |\n|------|------|---------|-------|\n| `shared/build-{YYYYMMDD}/` | Directory | Historical snapshot / rollback point | Read-only after deploy |\n| `shared/current/` | Symlink → active build | The server's source of truth | Set via `ln -snf` during deploy |\n| `~//` | Symlink → `shared/current/` | Your editing workspace | **This is where you edit** |\n\n**Rules:**\n\n1. **`shared/current/` is the heartbeat.** Every build deploy ends with an atomic symlink swap to `shared/current/`. The previous build is preserved as a dated snapshot.\n\n2. **Server config uses `current`, never a date.** Any import, mount, or path reference in server code (e.g., `RTS_BASE`, template directories, static file mounts) points to `shared/current/`. This is set once and never changes.\n\n3. **`~//` is the intuitive path.** All human-facing workspaces are symlinks to the deployment target. When you edit `~/myproject/frontend/...`, you are writing to the live build. No indirection.\n\n4. **This pattern applies ONLY to projects deployed via `shared/build-*/`.** Server code edited directly in agent workspaces (e.g., `myagent/workspace/`) does not use the `shared/current/` symlink — those directories ARE the live paths already.\n\n5. **⚠️ Symlink swap replaces the entire tree.** `ln -snf` does not merge — it atomically points `current` at a new destination. If the new build only contains the files that changed (incremental build), the server will lose access to all other files. Always integrate incremental builds into the live tree (Step 5b) before changing the deployment target.\n\n**Common pitfall:** You add a login page to `build-20260508/` and swap `current` to it. The login page works, but every other page returns 404 because the new build directory doesn't contain them. This is the #1 deploy-time failure mode.\n\n**Rollback procedure:**\n\nIf the new build is broken, point your deployment target back to the last known good build directory, then restart the service. On a Unix system using symlinks:\n\n```bash\nln -snf /path/to/deploy/build-{PREVIOUS_DATE}/ /path/to/deploy/current\n# Then restart your service via your platform's service manager\n```\n\nThe dated build directories are your safety net — each one is a complete, verifiable snapshot you can roll back to instantly.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — integration.md status format\n- `references/handoff-format.md` — Task handoff message template\n\n## When This Pattern Applies\n\nUse the full protocol (build dir → verify → symlink deploy) when:\n- A feature requires both backend and frontend code changes\n- The project is deployed from `shared/build-*/` directories\n- The server reads templates/static files from a separate frontend path\n\nDo NOT use when:\n- Single-file changes (just do it directly)\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n- Server-side code in `workspace-*/` directories (those are the live paths; no build/deploy step needed)\n- Config-only changes (feature flags, environment variables)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.5.3:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.5.3\",\n \"publishedAt\": 1778343935138\n}\n\nFile v1.5.3:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Files:**\n- `shared/build-{YYYYMMDD}/backend/router.py` — route handler\n- `shared/build-{YYYYMMDD}/SPEC.md` — API contract\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Monitoring\n\nAdapt monitoring to your setup. Suggested pattern:\n\n1. Check shortly after handoff: Did the agent start? Files modified?\n2. Check near ETA: Progress? Blockers?\n3. If no progress by ETA: re-spawn or escalate\n\nAdjust frequency and method based on your agent architecture and tooling.\n\nFile v1.5.3:references/integration-log.md\n\n# Integration Log — `shared/build-{YYYYMMDD}/integration.md`\n\n## Format\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting / 🔍 Reviewing / ✅ Complete\nBackend: 🔨 Building / ✅ Done / ❌ Blocked\nFrontend: 🔨 Building / ✅ Done / ❌ Blocked\n\n## Backend Progress\n- [ ] Router implemented at `backend/router.py`\n- [ ] Models defined at `backend/models.py`\n- [ ] Endpoints responding correctly\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Frontend Progress\n- [ ] Components built in `frontend/components/`\n- [ ] API client wired to endpoints\n- [ ] All states handled (loading, empty, error, populated)\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Integration Notes\n- Data format mismatch found: endpoint returns `items`, UI expects `data`\n- Auth tokens not flowing through — need session cookie handling\n```\n\n## Per-Agent Log Format (avoids conflicts)\n\nWhen both agents write to `integration.md` simultaneously, use separate log sections:\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting\nBackend: 🔨 Building\nFrontend: 🔨 Building\n\n## Backend Log\n\n- 2024-01-15 10:00: Started router implementation\n- 2024-01-15 10:30: GET /api/v1/items endpoint complete\n- 2024-01-15 11:00: BLOCKER: Need auth middleware from infra team\n\n## Frontend Log\n\n- 2024-01-15 10:15: Started ItemList component\n- 2024-01-15 10:45: Mock data wired, awaiting backend endpoint\n- 2024-01-15 11:10: Switched to using spec contract for API client\n\n## Integration Issues\n\n- (none yet)\n```\n\nFile v1.5.3:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.5.3:skill-card.md\n\n## Description:\n\nStructured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[nightknight64](https://clawhub.ai/user/nightknight64)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineering teams use this skill to coordinate backend and frontend agents around a shared contract, separate work areas, integration logs, verification steps, and deployment handoff guidance for full-stack feature work.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Deployment guidance may affect live services through copy, symlink, configuration, or restart actions.\n\nMitigation: Require explicit human approval, confirm the target environment, and prepare backups and rollback steps before executing deployment-related actions.\n\nRisk: Symlink-based deployment can point a service at an incomplete incremental build.\n\nMitigation: Confirm whether a build is full or incremental, integrate changed files into the live tree when needed, and verify the deployment target before restart.\n\nRisk: Backend and frontend agents may diverge from the shared API contract.\n\nMitigation: Use the SPEC.md contract as the source of truth and verify endpoint paths, request and response shapes, errors, auth flow, and UI states before release.\n\n## Reference(s):\n\n- [Skill release page](https://clawhub.ai/nightknight64/skills/agent-collaboration-protocol)\n- [Spec template](references/spec-template.md)\n- [Integration log format](references/integration-log.md)\n- [Handoff message format](references/handoff-format.md)\n\n## Skill Output:\n\n**Output Type(s):** [markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline code blocks and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces contract templates, handoff instructions, verification checklists, deployment guidance, and a setup script pattern for coordinated agent work.]\n\n## Skill Version(s):\n\n1.5.3 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.5.3:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.5.2\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with build directories, status tracking, recovery protocols, and integration verification.\",\n \"author\": \"Hoffmann Board\",\n \"license\": \"MIT-0\",\n \"tags\": [\n \"collaboration\",\n \"multi-agent\",\n \"workflow\",\n \"backend\",\n \"frontend\",\n \"integration\",\n \"contract-first\",\n \"orchestration\"\n ],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/clawhub/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.5.2: 7 files, 10994 bytes\n\nFiles: _meta.json (147b), clawhub.json (841b), references/handoff-format.md (777b), references/integration-log.md (1708b), references/spec-template.md (3373b), scripts/init_collab.sh (1738b), SKILL.md (14214b)\n\nFile v1.5.2:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Log your progress to {ABSOLUTE_BUILD_DIR}/frontend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n**Handoff acknowledgment is mandatory.** Each agent must confirm receipt and verify the build directory path exists before beginning work. If an agent does not ACK within a reasonable window (< 2 minutes), re-spawn it. See `references/handoff-format.md` for the full handoff template.\n\n> **Important: Identity comes from context, not the label.** The `label` parameter passed to `sessions_spawn` is a runtime tag for orchestrator tracking — it does NOT determine the agent's role. The subagent's role (Backend Engineer vs Frontend Engineer) is determined entirely by the orchestrator's context injection: the `task` message you provide tells the subagent what role to play, what files to write, and what contract to follow. Two subagents spawned with the same `label` can have completely different tasks and roles.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/backend-log.md`\n\n**Frontend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/frontend-log.md`\n\nEach agent has its own log file — **no simultaneous-write conflicts possible.**\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. Read both `backend-log.md` and `frontend-log.md` for progress\n2. Read `integration.md` for orchestrator notes\n3. Inspect files in `backend/` and `frontend/`\n4. Verify API responses match UI expectations\n5. If mismatches found, follow the Recovery Protocol below\n6. Verify against the [Verification Guide](#verification-guide)\n\n### Step 5: Deploy & Activate (Atomic Current Pivot)\n\nThe build is not done until the server reads from the new build. Follow these steps **in order**:\n\n**5a. Determine: full build or incremental?**\n\n| Build Type | What it means | Action |\n|------------|--------------|--------|\n| **Full build** | The build directory contains ALL project files (new + existing) | Symlink swap directly (5b) |\n| **Incremental build** | The build directory contains ONLY new/changed files | Merge first, then swap (5b) |\n\nMost collaborative builds are **incremental** — the backend and frontend agents only write the files they changed. An incremental build will break the site if you swap without merging, because `ln -snf` replaces the entire tree.\n\n**5b. Merge incremental builds (skip if full build)**\n\n```bash\n# Sync new files INTO the existing tree (preserves all existing files)\n# Replace {YYYYMMDD} with the new build date\nrsync -av ~/.openclaw/shared/build-{YYYYMMDD}/backend/ \\\n ~/.openclaw/shared/build-{YYYYMMDD}/frontend/ \\\n $(readlink ~/.openclaw/shared/current)/\n```\n\nThis copies new backend + frontend files into the current build tree. Existing files are only overwritten if they changed. **Verify nothing was lost:**\n```bash\n# Quick sanity: key endpoints still respond\ncurl -s -o /dev/null -w \"%{http_code}\" https://example.com/api/health\n```\n\n**5c. Atomic symlink swap (full builds, or post-merge)**\n```bash\nln -snf ~/.openclaw/shared/build-{YYYYMMDD}/ ~/.openclaw/shared/current\n```\n\n**5d. Update server config to use `current`**\n\nAny server config that uses absolute paths to the build directory **must** point to `shared/current/`, never to a date-stamped directory.\n\nExample — `rtsport_mock.py`:\n```python\n# ✅ Correct — never needs updating after initial setup\nTEMPLATES = Path(\"/home/user/project/shared/current/frontend\")\n\n# ❌ Wrong — bakes in a date, breaks after every deploy\nTEMPLATES = Path(\"/home/user/project/shared/build-20260501/frontend\")\n```\n\nThis is a **one-time config change**. Set it once, then the symlink swap handles every future deploy.\n\n**5e. Restart the service**\n```bash\nsudo systemctl restart myproject-api\n```\n\n**5f. Create intuitive workspace symlinks (once per project)**\n```bash\n# So that ~/{project}/ is always the live path\nln -snf ~/.openclaw/shared/current/ ~/rtsport\n```\n\nAfter this, any edit to `~/rtsport/frontend/templates/parent/dashboard.html` is a direct write to the live build. No indirection. No \"which copy am I editing\" questions.\n\n**5g. Verify deploy**\n```bash\n# Confirm `current` points to the new build\nls -la ~/.openclaw/shared/current\n# Check the server responds with the new code\ncurl -s https://example.com/health\n```\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. Check if the agent produced any files before crashing\n2. Read `integration.md` — did it log progress before failing?\n3. 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.\"\n4. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project\n```\n\nCreates `shared/` with template `SPEC.md` and `.gitignore`.\n\n## Filesystem Conventions\n\nEvery deployed project follows a three-tier filesystem pattern:\n\n| Path | Type | Purpose | Edit? |\n|------|------|---------|-------|\n| `shared/build-{YYYYMMDD}/` | Directory | Historical snapshot / rollback point | Read-only after deploy |\n| `shared/current/` | Symlink → active build | The server's source of truth | Set via `ln -snf` during deploy |\n| `~//` | Symlink → `shared/current/` | Your editing workspace | **This is where you edit** |\n\n**Rules:**\n\n1. **`shared/current/` is the heartbeat.** Every build deploy ends with an atomic symlink swap to `shared/current/`. The previous build is preserved as a dated snapshot.\n\n2. **Server config uses `current`, never a date.** Any import, mount, or path reference in server code (e.g., `RTS_BASE`, template directories, static file mounts) points to `shared/current/`. This is set once and never changes.\n\n3. **`~//` is the intuitive path.** All human-facing workspaces are symlinks to `shared/current/`. When you edit `~/rtsport/frontend/...`, you are writing to the live build. No indirection.\n\n4. **This pattern applies ONLY to projects deployed via `shared/build-*/`.** Server code edited directly in agent workspaces (e.g., `myagent/workspace/`) does not use the `shared/current/` symlink — those directories ARE the live paths already.\n\n5. **⚠️ Symlink swap replaces the entire tree.** `ln -snf` does not merge — it atomically points `current` at a new destination. If the new build only contains the files that changed (incremental build), the server will lose access to all other files. Always run the rsync merge step (Step 5b) for incremental builds before swapping the symlink.\n\n**Common pitfall:** You add a login page to `build-20260508/` and swap `current` to it. The login page works, but every other page (parent dashboard, coach dashboard, etc.) returns 404 because the new build directory doesn't contain them. This is the #1 deploy-time failure mode.\n\n**Rollback procedure:**\n\n```bash\n# If the new build is broken, point `current` back to the last known good build\nln -snf ~/.openclaw/shared/build-{PREVIOUS_DATE}/ ~/.openclaw/shared/current\nsudo systemctl restart myproject-api\n```\n\nThe dated build directories are your safety net — each one is a complete, verifiable snapshot you can roll back to instantly.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — integration.md status format\n- `references/handoff-format.md` — Task handoff message template\n\n## When This Pattern Applies\n\nUse the full protocol (build dir → verify → symlink deploy) when:\n- A feature requires both backend and frontend code changes\n- The project is deployed from `shared/build-*/` directories\n- The server reads templates/static files from a separate frontend path\n\nDo NOT use when:\n- Single-file changes (just do it directly)\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n- Server-side code in `workspace-*/` directories (those are the live paths; no build/deploy step needed)\n- Config-only changes (feature flags, environment variables)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.5.2:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.5.2\",\n \"publishedAt\": 1778343271871\n}\n\nFile v1.5.2:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Files:**\n- `shared/build-{YYYYMMDD}/backend/router.py` — route handler\n- `shared/build-{YYYYMMDD}/SPEC.md` — API contract\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Monitoring\n\nAdapt monitoring to your setup. Suggested pattern:\n\n1. Check shortly after handoff: Did the agent start? Files modified?\n2. Check near ETA: Progress? Blockers?\n3. If no progress by ETA: re-spawn or escalate\n\nAdjust frequency and method based on your agent architecture and tooling.\n\nFile v1.5.2:references/integration-log.md\n\n# Integration Log — `shared/build-{YYYYMMDD}/integration.md`\n\n## Format\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting / 🔍 Reviewing / ✅ Complete\nBackend: 🔨 Building / ✅ Done / ❌ Blocked\nFrontend: 🔨 Building / ✅ Done / ❌ Blocked\n\n## Backend Progress\n- [ ] Router implemented at `backend/router.py`\n- [ ] Models defined at `backend/models.py`\n- [ ] Endpoints responding correctly\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Frontend Progress\n- [ ] Components built in `frontend/components/`\n- [ ] API client wired to endpoints\n- [ ] All states handled (loading, empty, error, populated)\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Integration Notes\n- Data format mismatch found: endpoint returns `items`, UI expects `data`\n- Auth tokens not flowing through — need session cookie handling\n```\n\n## Per-Agent Log Format (avoids conflicts)\n\nWhen both agents write to `integration.md` simultaneously, use separate log sections:\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting\nBackend: 🔨 Building\nFrontend: 🔨 Building\n\n## Backend Log\n\n- 2024-01-15 10:00: Started router implementation\n- 2024-01-15 10:30: GET /api/v1/items endpoint complete\n- 2024-01-15 11:00: BLOCKER: Need auth middleware from infra team\n\n## Frontend Log\n\n- 2024-01-15 10:15: Started ItemList component\n- 2024-01-15 10:45: Mock data wired, awaiting backend endpoint\n- 2024-01-15 11:10: Switched to using spec contract for API client\n\n## Integration Issues\n\n- (none yet)\n```\n\nFile v1.5.2:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.5.2:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.5.1\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with build directories, status tracking, recovery protocols, and integration verification.\",\n \"author\": \"Hoffmann Board\",\n \"license\": \"MIT-0\",\n \"tags\": [\"collaboration\", \"multi-agent\", \"workflow\", \"backend\", \"frontend\", \"integration\", \"contract-first\", \"orchestration\"],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/clawhub/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.5.1: 8 files, 14135 bytes\n\nFiles: _meta.json (147b), clawhub.json (851b), README.md (2934b), references/handoff-format.md (1364b), references/integration-log.md (2596b), references/spec-template.md (3373b), scripts/init_collab.sh (6198b), SKILL.md (12566b)\n\nFile v1.5.1:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Log your progress to {ABSOLUTE_BUILD_DIR}/frontend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n**Handoff acknowledgment is mandatory.** Each agent must confirm receipt and verify the build directory path exists before beginning work. If an agent does not ACK within a reasonable window (< 2 minutes), re-spawn it. See `references/handoff-format.md` for the full handoff template.\n\n> **Important: Identity comes from context, not the label.** The `label` parameter passed to `sessions_spawn` is a runtime tag for orchestrator tracking — it does NOT determine the agent's role. The subagent's role (Backend Engineer vs Frontend Engineer) is determined entirely by the orchestrator's context injection: the `task` message you provide tells the subagent what role to play, what files to write, and what contract to follow. Two subagents spawned with the same `label` can have completely different tasks and roles.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/backend-log.md`\n\n**Frontend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/frontend-log.md`\n\nEach agent has its own log file — **no simultaneous-write conflicts possible.**\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. Read both `backend-log.md` and `frontend-log.md` for progress\n2. Read `integration.md` for orchestrator notes\n3. Inspect files in `backend/` and `frontend/`\n4. Verify API responses match UI expectations\n5. If mismatches found, follow the Recovery Protocol below\n6. Verify against the [Verification Guide](#verification-guide)\n\n### Step 5: Deploy & Activate (Atomic Current Pivot)\n\nThe build is not done until the server reads from the new build. Follow these steps **in order**:\n\n**5a. Atomic symlink swap**\n```bash\n# Atomically point `current` at the verified build\nln -snf ~/.openclaw/shared/build-{YYYYMMDD}/ ~/.openclaw/shared/current\n```\n\nThis is the heartbeat. `shared/current/` always points to the active build.\nThe old date-stamped directory is preserved as a rollback point.\n\n**5b. Update server config to use `current`**\n\nAny server config that uses absolute paths to the build directory **must** point to `shared/current/`, never to a date-stamped directory.\n\nExample — `rtsport_mock.py`:\n```python\n# ✅ Correct — never needs updating after initial setup\nRTS_BASE = Path(\"/home/hoffmann_admin/.openclaw/shared/current/frontend\")\n\n# ❌ Wrong — bakes in a date, breaks after every deploy\nRTS_BASE = Path(\"/home/hoffmann_admin/.openclaw/shared/build-20260501/frontend\")\n```\n\nThis is a **one-time config change**. Set it once, then the symlink swap handles every future deploy.\n\n**5c. Restart the service**\n```bash\nsudo systemctl restart hoffdesk-api\n```\n\n**5d. Create intuitive workspace symlinks (once per project)**\n```bash\n# So that ~/{project}/ is always the live path\nln -snf ~/.openclaw/shared/current/ ~/rtsport\n```\n\nAfter this, any edit to `~/rtsport/frontend/templates/parent/dashboard.html` is a direct write to the live build. No indirection. No \"which copy am I editing\" questions.\n\n**5e. Verify deploy**\n```bash\n# Confirm `current` points to the new build\nls -la ~/.openclaw/shared/current\n# Check the server responds with the new code\ncurl -s https://hoffdesk.com/health\n```\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. Check if the agent produced any files before crashing\n2. Read `integration.md` — did it log progress before failing?\n3. 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.\"\n4. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project\n```\n\nCreates `shared/` with template `SPEC.md` and `.gitignore`.\n\n## Filesystem Conventions\n\nEvery deployed project follows a three-tier filesystem pattern:\n\n| Path | Type | Purpose | Edit? |\n|------|------|---------|-------|\n| `shared/build-{YYYYMMDD}/` | Directory | Historical snapshot / rollback point | Read-only after deploy |\n| `shared/current/` | Symlink → active build | The server's source of truth | Set via `ln -snf` during deploy |\n| `~//` | Symlink → `shared/current/` | Your editing workspace | **This is where you edit** |\n\n**Rules:**\n\n1. **`shared/current/` is the heartbeat.** Every build deploy ends with an atomic symlink swap to `shared/current/`. The previous build is preserved as a dated snapshot.\n\n2. **Server config uses `current`, never a date.** Any import, mount, or path reference in server code (e.g., `RTS_BASE`, template directories, static file mounts) points to `shared/current/`. This is set once and never changes.\n\n3. **`~//` is the intuitive path.** All human-facing workspaces are symlinks to `shared/current/`. When you edit `~/rtsport/frontend/...`, you are writing to the live build. No indirection.\n\n4. **This pattern applies ONLY to projects deployed via `shared/build-*/`.** Server code edited directly in agent workspaces (e.g., `workspace-socrates/hoffdesk-api/`) does not use the `shared/current/` symlink — those directories ARE the live paths already.\n\n**Rollback procedure:**\n\n```bash\n# If the new build is broken, point `current` back to the last known good build\nln -snf ~/.openclaw/shared/build-{PREVIOUS_DATE}/ ~/.openclaw/shared/current\nsudo systemctl restart hoffdesk-api\n```\n\nThe dated build directories are your safety net — each one is a complete, verifiable snapshot you can roll back to instantly.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — integration.md status format\n- `references/handoff-format.md` — Task handoff message template\n\n## When This Pattern Applies\n\nUse the full protocol (build dir → verify → symlink deploy) when:\n- A feature requires both backend and frontend code changes\n- The project is deployed from `shared/build-*/` directories\n- The server reads templates/static files from a separate frontend path\n\nDo NOT use when:\n- Single-file changes (just do it directly)\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n- Server-side code in `workspace-*/` directories (those are the live paths; no build/deploy step needed)\n- Config-only changes (feature flags, environment variables)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.5.1:README.md\n\n# Agent Collaboration Protocol\n\nStructured multi-agent collaboration for backend + frontend builds.\n\n## Overview\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe contract lives in `shared/build-{YYYYMMDD}/`. Each builder writes to its own subdirectory with its own log file — **no conflicts, ever**. The orchestrator inspects and merges when both are done.\n\n## Quick Start\n\n1. Run `scripts/init_collab.sh /path/to/project` to create the shared workspace\n2. Edit `shared/SPEC.md` with your feature contract\n3. Spawn backend and frontend agents (see SKILL.md for task templates)\n4. Both agents build simultaneously, logging to their own files\n5. Orchestrator verifies and merges\n\n## What's New in v1.3.0\n\n- **Separate log files** — `backend-log.md` and `frontend-log.md` eliminate race conditions. No more simultaneous-write conflicts.\n- **Abort thresholds** — Clear triggers for when to stop debugging the collaboration and re-scope (3 crashes → split task, 2 no-file attempts → rewrite handoff, 15+ min no log → kill and restart).\n- **Handoff ACK requirement** — Receiving agents must confirm receipt and path before starting. No ACK in 2 min → re-spawn.\n- **Enhanced init script** — Framework stubs (`--framework fastapi|express`), dry-run mode (`--dry-run`), OpenClaw version detection, log file template creation.\n\n### v1.2.0\n\n- **Absolute path requirement** — Orchestrator must provide full absolute paths to subagents\n- **Artifact verification step** — \"Check that files actually landed\" as a required step\n- **{ABSOLUTE_BUILD_DIR} convention** — Consistent placeholder in all templates\n\n### v1.1.0\n\n- **Recovery Protocol** — Concrete steps for agent crashes, build mismatches, and blockers\n- **Shared Constants** — Status enums, error codes, and feature flags\n- **Verification Guide** — Backend curl tests, frontend state checklist, integration checks\n- **MIT-0 License** — Simplest possible open source license\n\n## Documentation\n\n- `SKILL.md` — Full workflow, abort thresholds, recovery protocol, verification guide\n- `references/spec-template.md` — Complete SPEC.md template with examples\n- `references/integration-log.md` — Per-agent log file format + orchestrator merge format\n- `references/handoff-format.md` — Task handoff template (includes ACK requirement)\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## License\n\nMIT-0 — do whatever you want, no attribution required.\n\nFile v1.5.1:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.5.1\",\n \"publishedAt\": 1778204392736\n}\n\nFile v1.5.1:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Build directory:** {Absolute path to shared/build-{YYYYMMDD}/}\n\n**Files:**\n- `{ABSOLUTE_BUILD_DIR}/SPEC.md` — API contract\n- `{ABSOLUTE_BUILD_DIR}/backend/` — write backend code here\n- `{ABSOLUTE_BUILD_DIR}/backend-log.md` — log progress here\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Handoff Acknowledgment (MANDATORY)\n\nThe receiving agent **must reply with ACK** before starting work:\n\n> \"ACK — confirmed build directory: /path/to/shared/build-{YYYYMMDD}/\"\n\nThis confirms:\n1. The agent received the handoff\n2. The agent can resolve the build directory path\n3. The agent understands the task context\n\n**If no ACK within 2 minutes: re-spawn the agent.** Do not wait indefinitely.\n\n## Monitoring\n\n1. **T+2 min:** Did the agent ACK? If not, re-spawn.\n2. **T+5 min:** Did the agent produce its first log entry? Files modified?\n3. **Near ETA:** Progress? Blockers?\n4. **At ETA:** If no progress and no communication, re-spawn or escalate.\n\n**Don't poll aggressively.** Subagents return results when they finish. Check only at these milestones.\n\nFile v1.5.1:references/integration-log.md\n\n# Integration Logs — `shared/build-{YYYYMMDD}/`\n\n## Per-Agent Log Files (default — avoids conflicts)\n\nEach agent writes to its own log file. **No simultaneous-write conflicts possible.**\n\n```\nshared/build-{YYYYMMDD}/\n backend-log.md ← Backend Engineer writes here\n frontend-log.md ← Frontend Engineer writes here\n integration.md ← Orchestrator merges findings here\n```\n\n### backend-log.md Format\n\n```markdown\n# Backend Build Log — {Feature Name}\n\nStarted: YYYY-MM-DD HH:MM UTC\n\n## Progress\n- HH:MM — Task started\n- HH:MM — Router scaffolded at `backend/router.py`\n- HH:MM — Models defined at `backend/models.py`\n- HH:MM — Endpoint `GET /api/v1/{resource}` responding with mock data\n- HH:MM — Shared constants file created\n- HH:MM — All endpoints complete, ready for integration testing\n\n## Blockers\n- HH:MM — BLOCKER: Need {dependency}. Resolution: {approach or \"waiting on orchestrator\"}\n\n## Notes\n- Any observations about the spec or approach\n```\n\n### frontend-log.md Format\n\n```markdown\n# Frontend Build Log — {Feature Name}\n\nStarted: YYYY-MM-DD HH:MM UTC\n\n## Progress\n- HH:MM — Task started\n- HH:MM — Component scaffolds created in `frontend/components/`\n- HH:MM — API client wired to endpoints from SPEC.md\n- HH:MM — Loading/empty/error states handled\n- HH:MM — All components complete, ready for integration testing\n\n## Blockers\n- HH:MM — BLOCKER: Waiting for backend endpoint `POST /api/v1/{resource}`. Using mock data in meantime.\n\n## Notes\n- Any observations about the spec or approach\n```\n\n### integration.md (Orchestrator's Merge)\n\n```markdown\n# Integration Report — {Feature Name}\n\n## Status\nBackend: ✅ Done / ❌ Blocked / ⚠️ Partial\nFrontend: ✅ Done / ❌ Blocked / ⚠️ Partial\n\n## Backend Summary\n(from backend-log.md)\n\n## Frontend Summary\n(from frontend-log.md)\n\n## Integration Issues Found\n- Issue: {description} — Resolution: {how fixed or \"pending\"}\n- Issue: {description} — Resolution: {how fixed or \"pending\"}\n\n## Verification\n- [ ] Backend endpoints respond per spec\n- [ ] Frontend renders all states correctly\n- [ ] API shapes match between frontend and backend\n- [ ] Auth flow works end-to-end\n- [ ] Shared constants are consistent\n\n## Decision\n✅ Merge to production / ❌ Re-spawn {which} agent / ⚠️ Manual intervention needed\n```\n\n## Deprecated: Single-File Format\n\nThe previous approach used a single `integration.md` for all agents. This caused race conditions when both agents wrote simultaneously. **Do not use.** Migrate existing builds by splitting into backend-log.md and frontend-log.md.\n\nFile v1.5.1:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.5.1:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.5.0\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with build directories, status tracking, recovery protocols, and integration verification.\",\n \"author\": \"the-hoffmann-board\",\n \"license\": \"MIT-0\",\n \"tags\": [\"collaboration\", \"multi-agent\", \"workflow\", \"backend\", \"frontend\", \"integration\", \"contract-first\", \"orchestration\"],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/hoffmann-matt/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.5.0: 8 files, 9424 bytes\n\nFiles: clawhub.json (850b), README.md (2034b), references/handoff-format.md (777b), references/integration-log.md (1708b), references/spec-template.md (3373b), scripts/init_collab.sh (1738b), SKILL.md (7025b), _meta.json (147b)\n\nFile v1.5.0:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe contract lives in `shared/build-{YYYYMMDD}/`. Both builders write to the same directory. The orchestrator inspects and merges when both are done.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n integration.md ← Both update as they work\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec in shared/build-{YYYYMMDD}/SPEC.md.\n Write all backend code to shared/build-{YYYYMMDD}/backend/.\n Update shared/build-{YYYYMMDD}/integration.md with progress.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec in shared/build-{YYYYMMDD}/SPEC.md.\n Write all frontend code to shared/build-{YYYYMMDD}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Update shared/build-{YYYYMMDD}/integration.md with progress.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `shared/build-{YYYYMMDD}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Updates `integration.md` with progress and any blockers\n\n**Frontend Engineer writes to** `shared/build-{YYYYMMDD}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Updates `integration.md` with progress and any blockers\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. Read `integration.md` from both agents\n2. Inspect files in `backend/` and `frontend/`\n3. Verify API responses match UI expectations\n4. If mismatches found, follow the Recovery Protocol below\n5. Move code to production paths\n6. Archive the build directory (or delete it)\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. Check if the agent produced any files before crashing\n2. Read `integration.md` — did it log progress before failing?\n3. 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.\"\n4. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project\n```\n\nCreates `shared/` with template `SPEC.md` and `.gitignore`.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — integration.md status format\n- `references/handoff-format.md` — Task handoff message template\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.5.0:README.md\n\n# Agent Collaboration Protocol\n\nStructured multi-agent collaboration for backend + frontend builds.\n\n## Overview\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe contract lives in `shared/build-{YYYYMMDD}/`. Both builders write to the same directory. The orchestrator inspects and merges when both are done.\n\n## Quick Start\n\n1. Run `scripts/init_collab.sh /path/to/project` to create the shared workspace\n2. Edit `shared/SPEC.md` with your feature contract\n3. Spawn backend and frontend agents (see SKILL.md for task templates)\n4. Both agents build simultaneously, updating `integration.md`\n5. Orchestrator verifies and merges\n\n## What's New in v1.1.0\n\n- **Recovery Protocol** — Concrete steps for agent crashes, build mismatches, and blockers\n- **Shared Constants** — Status enums, error codes, and feature flags that both sides must agree on\n- **Verification Guide** — Backend curl commands, frontend state checklist, integration checks\n- **Per-Agent Log Format** — Solves simultaneous-write conflicts in integration.md\n- **MIT-0 License** — Simplest possible open source license\n\n## Documentation\n\n- `SKILL.md` — Full workflow, recovery protocol, and verification guide\n- `references/spec-template.md` — Complete SPEC.md template with examples\n- `references/integration-log.md` — Integration log format (standard + per-agent)\n- `references/handoff-format.md` — Task handoff message template\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## License\n\nMIT-0 — do whatever you want, no attribution required.\n\nFile v1.5.0:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.5.0\",\n \"publishedAt\": 1778202725885\n}\n\nFile v1.5.0:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Files:**\n- `shared/build-{YYYYMMDD}/backend/router.py` — route handler\n- `shared/build-{YYYYMMDD}/SPEC.md` — API contract\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Monitoring\n\nAdapt monitoring to your setup. Suggested pattern:\n\n1. Check shortly after handoff: Did the agent start? Files modified?\n2. Check near ETA: Progress? Blockers?\n3. If no progress by ETA: re-spawn or escalate\n\nAdjust frequency and method based on your agent architecture and tooling.\n\nFile v1.5.0:references/integration-log.md\n\n# Integration Log — `shared/build-{YYYYMMDD}/integration.md`\n\n## Format\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting / 🔍 Reviewing / ✅ Complete\nBackend: 🔨 Building / ✅ Done / ❌ Blocked\nFrontend: 🔨 Building / ✅ Done / ❌ Blocked\n\n## Backend Progress\n- [ ] Router implemented at `backend/router.py`\n- [ ] Models defined at `backend/models.py`\n- [ ] Endpoints responding correctly\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Frontend Progress\n- [ ] Components built in `frontend/components/`\n- [ ] API client wired to endpoints\n- [ ] All states handled (loading, empty, error, populated)\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Integration Notes\n- Data format mismatch found: endpoint returns `items`, UI expects `data`\n- Auth tokens not flowing through — need session cookie handling\n```\n\n## Per-Agent Log Format (avoids conflicts)\n\nWhen both agents write to `integration.md` simultaneously, use separate log sections:\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting\nBackend: 🔨 Building\nFrontend: 🔨 Building\n\n## Backend Log\n\n- 2024-01-15 10:00: Started router implementation\n- 2024-01-15 10:30: GET /api/v1/items endpoint complete\n- 2024-01-15 11:00: BLOCKER: Need auth middleware from infra team\n\n## Frontend Log\n\n- 2024-01-15 10:15: Started ItemList component\n- 2024-01-15 10:45: Mock data wired, awaiting backend endpoint\n- 2024-01-15 11:10: Switched to using spec contract for API client\n\n## Integration Issues\n\n- (none yet)\n```\n\nFile v1.5.0:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.5.0:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.1.0\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with build directories, status tracking, recovery protocols, and integration verification.\",\n \"author\": \"the-hoffmann-board\",\n \"license\": \"MIT-0\",\n \"tags\": [\"collaboration\", \"multi-agent\", \"workflow\", \"backend\", \"frontend\", \"integration\", \"contract-first\", \"orchestration\"],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/hoffmann-matt/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.4.0: 7 files, 8924 bytes\n\nFiles: _meta.json (147b), clawhub.json (851b), references/handoff-format.md (777b), references/integration-log.md (1708b), references/spec-template.md (3373b), scripts/init_collab.sh (1738b), SKILL.md (8780b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Log your progress to {ABSOLUTE_BUILD_DIR}/frontend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n**Handoff acknowledgment is mandatory.** Each agent must confirm receipt and verify the build directory path exists before beginning work. If an agent does not ACK within a reasonable window (< 2 minutes), re-spawn it. See `references/handoff-format.md` for the full handoff template.\n\n> **Important: Identity comes from context, not the label.** The `label` parameter passed to `sessions_spawn` is a runtime tag for orchestrator tracking — it does NOT determine the agent's role. The subagent's role (Backend Engineer vs Frontend Engineer) is determined entirely by the orchestrator's context injection: the `task` message you provide tells the subagent what role to play, what files to write, and what contract to follow. Two subagents spawned with the same `label` can have completely different tasks and roles.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/backend-log.md`\n\n**Frontend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/frontend-log.md`\n\nEach agent has its own log file — **no simultaneous-write conflicts possible.**\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. Read both `backend-log.md` and `frontend-log.md` for progress\n2. Read `integration.md` for orchestrator notes\n3. Inspect files in `backend/` and `frontend/`\n3. Verify API responses match UI expectations\n4. If mismatches found, follow the Recovery Protocol below\n5. Move code to production paths\n6. Archive the build directory (or delete it)\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. Check if the agent produced any files before crashing\n2. Read `integration.md` — did it log progress before failing?\n3. 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.\"\n4. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project\n```\n\nCreates `shared/` with template `SPEC.md` and `.gitignore`.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — integration.md status format\n- `references/handoff-format.md` — Task handoff message template\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.4.0:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.4.0\",\n \"publishedAt\": 1778077318883\n}\n\nFile v1.4.0:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Files:**\n- `shared/build-{YYYYMMDD}/backend/router.py` — route handler\n- `shared/build-{YYYYMMDD}/SPEC.md` — API contract\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Monitoring\n\nAdapt monitoring to your setup. Suggested pattern:\n\n1. Check shortly after handoff: Did the agent start? Files modified?\n2. Check near ETA: Progress? Blockers?\n3. If no progress by ETA: re-spawn or escalate\n\nAdjust frequency and method based on your agent architecture and tooling.\n\nFile v1.4.0:references/integration-log.md\n\n# Integration Log — `shared/build-{YYYYMMDD}/integration.md`\n\n## Format\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting / 🔍 Reviewing / ✅ Complete\nBackend: 🔨 Building / ✅ Done / ❌ Blocked\nFrontend: 🔨 Building / ✅ Done / ❌ Blocked\n\n## Backend Progress\n- [ ] Router implemented at `backend/router.py`\n- [ ] Models defined at `backend/models.py`\n- [ ] Endpoints responding correctly\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Frontend Progress\n- [ ] Components built in `frontend/components/`\n- [ ] API client wired to endpoints\n- [ ] All states handled (loading, empty, error, populated)\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Integration Notes\n- Data format mismatch found: endpoint returns `items`, UI expects `data`\n- Auth tokens not flowing through — need session cookie handling\n```\n\n## Per-Agent Log Format (avoids conflicts)\n\nWhen both agents write to `integration.md` simultaneously, use separate log sections:\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting\nBackend: 🔨 Building\nFrontend: 🔨 Building\n\n## Backend Log\n\n- 2024-01-15 10:00: Started router implementation\n- 2024-01-15 10:30: GET /api/v1/items endpoint complete\n- 2024-01-15 11:00: BLOCKER: Need auth middleware from infra team\n\n## Frontend Log\n\n- 2024-01-15 10:15: Started ItemList component\n- 2024-01-15 10:45: Mock data wired, awaiting backend endpoint\n- 2024-01-15 11:10: Switched to using spec contract for API client\n\n## Integration Issues\n\n- (none yet)\n```\n\nFile v1.4.0:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.4.0:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.4.0\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with build directories, status tracking, recovery protocols, and integration verification.\",\n \"author\": \"the-hoffmann-board\",\n \"license\": \"MIT-0\",\n \"tags\": [\"collaboration\", \"multi-agent\", \"workflow\", \"backend\", \"frontend\", \"integration\", \"contract-first\", \"orchestration\"],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/hoffmann-matt/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.3.0: 8 files, 13061 bytes\n\nFiles: clawhub.json (894b), README.md (2934b), references/handoff-format.md (1364b), references/integration-log.md (2596b), references/spec-template.md (3373b), scripts/init_collab.sh (6136b), SKILL.md (9552b), _meta.json (147b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Log your progress to {ABSOLUTE_BUILD_DIR}/frontend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n**Handoff acknowledgment is mandatory.** Each agent must confirm receipt and verify the build directory path exists before beginning work. If an agent does not ACK within a reasonable window (< 2 minutes), re-spawn it. See `references/handoff-format.md` for the full handoff template.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/backend-log.md`\n\n**Frontend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Logs progress to `{ABSOLUTE_BUILD_DIR}/frontend-log.md`\n\nEach agent has its own log file — **no simultaneous-write conflicts possible.**\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. **Check that artifacts actually landed** — run `ls` on both `{ABSOLUTE_BUILD_DIR}/backend/` and `{ABSOLUTE_BUILD_DIR}/frontend/`. Do not trust completion messages alone.\n2. Read `backend-log.md` and `frontend-log.md`\n3. Inspect files in `backend/` and `frontend/`\n4. Verify API responses match UI expectations\n5. If mismatches found, follow the Recovery Protocol below\n6. Merge findings into `integration.md`\n7. Move code to production paths\n8. Archive the build directory (or delete it)\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. **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.\n2. Check if the agent produced any files before crashing\n3. Read the agent's log file — did it log progress before failing?\n4. Re-spawn the agent with the *same* task + a note: \"Previous run crashed. Continue from where you left off. Read your log file for progress so far.\"\n5. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in the agent's log file\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### When to Abort\n\nRecognize the sunk-cost trap. Stop and re-scope when:\n\n| Trigger | Action |\n|---------|--------|\n| Same agent crashes **3 times** on the same task | Re-scope: split task into smaller sub-tasks and run sequentially |\n| No files produced after **2 attempts** | The task is too ambiguous. Rewrite the handoff with more concrete deliverables |\n| Either agent has been running **>15 minutes** without producing a log entry | The agent is likely stuck. Kill the session, check its outputs, re-scope |\n| Integration mismatch requires **>2 rounds** of corrections | The spec is wrong. Stop both agents, update `SPEC.md`, restart |\n| Agent produces code that doesn't match the spec **after explicit correction** | Model capability gap. Switch to a stronger model for that role or simplify the task |\n\n**The override rule:** If you've spent more time debugging the collaboration than it would take to do the work yourself, abort and do it sequentially.\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project [--framework fastapi|express|django] [--dry-run]\n```\n\nOptions:\n- `--framework` — pre-populate backend skeleton with framework-specific stubs\n- `--dry-run` — show what will be created without writing files\n\nCreates `shared/` with template `SPEC.md`, log file structure, and `.gitignore`.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — Log file format for backend-log.md and frontend-log.md\n- `references/handoff-format.md` — Task handoff message template (includes ACK requirement)\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.3.0:README.md\n\n# Agent Collaboration Protocol\n\nStructured multi-agent collaboration for backend + frontend builds.\n\n## Overview\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe contract lives in `shared/build-{YYYYMMDD}/`. Each builder writes to its own subdirectory with its own log file — **no conflicts, ever**. The orchestrator inspects and merges when both are done.\n\n## Quick Start\n\n1. Run `scripts/init_collab.sh /path/to/project` to create the shared workspace\n2. Edit `shared/SPEC.md` with your feature contract\n3. Spawn backend and frontend agents (see SKILL.md for task templates)\n4. Both agents build simultaneously, logging to their own files\n5. Orchestrator verifies and merges\n\n## What's New in v1.3.0\n\n- **Separate log files** — `backend-log.md` and `frontend-log.md` eliminate race conditions. No more simultaneous-write conflicts.\n- **Abort thresholds** — Clear triggers for when to stop debugging the collaboration and re-scope (3 crashes → split task, 2 no-file attempts → rewrite handoff, 15+ min no log → kill and restart).\n- **Handoff ACK requirement** — Receiving agents must confirm receipt and path before starting. No ACK in 2 min → re-spawn.\n- **Enhanced init script** — Framework stubs (`--framework fastapi|express`), dry-run mode (`--dry-run`), OpenClaw version detection, log file template creation.\n\n### v1.2.0\n\n- **Absolute path requirement** — Orchestrator must provide full absolute paths to subagents\n- **Artifact verification step** — \"Check that files actually landed\" as a required step\n- **{ABSOLUTE_BUILD_DIR} convention** — Consistent placeholder in all templates\n\n### v1.1.0\n\n- **Recovery Protocol** — Concrete steps for agent crashes, build mismatches, and blockers\n- **Shared Constants** — Status enums, error codes, and feature flags\n- **Verification Guide** — Backend curl tests, frontend state checklist, integration checks\n- **MIT-0 License** — Simplest possible open source license\n\n## Documentation\n\n- `SKILL.md` — Full workflow, abort thresholds, recovery protocol, verification guide\n- `references/spec-template.md` — Complete SPEC.md template with examples\n- `references/integration-log.md` — Per-agent log file format + orchestrator merge format\n- `references/handoff-format.md` — Task handoff template (includes ACK requirement)\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## License\n\nMIT-0 — do whatever you want, no attribution required.\n\nFile v1.3.0:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.3.0\",\n \"publishedAt\": 1778075891317\n}\n\nFile v1.3.0:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Build directory:** {Absolute path to shared/build-{YYYYMMDD}/}\n\n**Files:**\n- `{ABSOLUTE_BUILD_DIR}/SPEC.md` — API contract\n- `{ABSOLUTE_BUILD_DIR}/backend/` — write backend code here\n- `{ABSOLUTE_BUILD_DIR}/backend-log.md` — log progress here\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Handoff Acknowledgment (MANDATORY)\n\nThe receiving agent **must reply with ACK** before starting work:\n\n> \"ACK — confirmed build directory: /path/to/shared/build-{YYYYMMDD}/\"\n\nThis confirms:\n1. The agent received the handoff\n2. The agent can resolve the build directory path\n3. The agent understands the task context\n\n**If no ACK within 2 minutes: re-spawn the agent.** Do not wait indefinitely.\n\n## Monitoring\n\n1. **T+2 min:** Did the agent ACK? If not, re-spawn.\n2. **T+5 min:** Did the agent produce its first log entry? Files modified?\n3. **Near ETA:** Progress? Blockers?\n4. **At ETA:** If no progress and no communication, re-spawn or escalate.\n\n**Don't poll aggressively.** Subagents return results when they finish. Check only at these milestones.\n\nFile v1.3.0:references/integration-log.md\n\n# Integration Logs — `shared/build-{YYYYMMDD}/`\n\n## Per-Agent Log Files (default — avoids conflicts)\n\nEach agent writes to its own log file. **No simultaneous-write conflicts possible.**\n\n```\nshared/build-{YYYYMMDD}/\n backend-log.md ← Backend Engineer writes here\n frontend-log.md ← Frontend Engineer writes here\n integration.md ← Orchestrator merges findings here\n```\n\n### backend-log.md Format\n\n```markdown\n# Backend Build Log — {Feature Name}\n\nStarted: YYYY-MM-DD HH:MM UTC\n\n## Progress\n- HH:MM — Task started\n- HH:MM — Router scaffolded at `backend/router.py`\n- HH:MM — Models defined at `backend/models.py`\n- HH:MM — Endpoint `GET /api/v1/{resource}` responding with mock data\n- HH:MM — Shared constants file created\n- HH:MM — All endpoints complete, ready for integration testing\n\n## Blockers\n- HH:MM — BLOCKER: Need {dependency}. Resolution: {approach or \"waiting on orchestrator\"}\n\n## Notes\n- Any observations about the spec or approach\n```\n\n### frontend-log.md Format\n\n```markdown\n# Frontend Build Log — {Feature Name}\n\nStarted: YYYY-MM-DD HH:MM UTC\n\n## Progress\n- HH:MM — Task started\n- HH:MM — Component scaffolds created in `frontend/components/`\n- HH:MM — API client wired to endpoints from SPEC.md\n- HH:MM — Loading/empty/error states handled\n- HH:MM — All components complete, ready for integration testing\n\n## Blockers\n- HH:MM — BLOCKER: Waiting for backend endpoint `POST /api/v1/{resource}`. Using mock data in meantime.\n\n## Notes\n- Any observations about the spec or approach\n```\n\n### integration.md (Orchestrator's Merge)\n\n```markdown\n# Integration Report — {Feature Name}\n\n## Status\nBackend: ✅ Done / ❌ Blocked / ⚠️ Partial\nFrontend: ✅ Done / ❌ Blocked / ⚠️ Partial\n\n## Backend Summary\n(from backend-log.md)\n\n## Frontend Summary\n(from frontend-log.md)\n\n## Integration Issues Found\n- Issue: {description} — Resolution: {how fixed or \"pending\"}\n- Issue: {description} — Resolution: {how fixed or \"pending\"}\n\n## Verification\n- [ ] Backend endpoints respond per spec\n- [ ] Frontend renders all states correctly\n- [ ] API shapes match between frontend and backend\n- [ ] Auth flow works end-to-end\n- [ ] Shared constants are consistent\n\n## Decision\n✅ Merge to production / ❌ Re-spawn {which} agent / ⚠️ Manual intervention needed\n```\n\n## Deprecated: Single-File Format\n\nThe previous approach used a single `integration.md` for all agents. This caused race conditions when both agents wrote simultaneously. **Do not use.** Migrate existing builds by splitting into backend-log.md and frontend-log.md.\n\nFile v1.3.0:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.3.0:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.3.0\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with per-agent log files (no conflicts), abort thresholds, handoff ACK requirements, recovery protocols, and integration verification.\",\n \"author\": \"the-hoffmann-board\",\n \"license\": \"MIT-0\",\n \"tags\": [\"collaboration\", \"multi-agent\", \"workflow\", \"backend\", \"frontend\", \"integration\", \"contract-first\", \"orchestration\"],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/NightKnight64/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.2.0: 7 files, 8583 bytes\n\nFiles: clawhub.json (850b), references/handoff-format.md (777b), references/integration-log.md (1708b), references/spec-template.md (3373b), scripts/init_collab.sh (1738b), SKILL.md (7843b), _meta.json (147b)\n\nFile v1.2.0:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n integration.md ← Both update as they work\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Update {ABSOLUTE_BUILD_DIR}/integration.md with progress.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Update {ABSOLUTE_BUILD_DIR}/integration.md with progress.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Updates `{ABSOLUTE_BUILD_DIR}/integration.md` with progress and any blockers\n\n**Frontend Engineer writes to** `{ABSOLUTE_BUILD_DIR}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Updates `{ABSOLUTE_BUILD_DIR}/integration.md` with progress and any blockers\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. **Check that artifacts actually landed** — run `ls` on both `{ABSOLUTE_BUILD_DIR}/backend/` and `{ABSOLUTE_BUILD_DIR}/frontend/`. Do not trust completion messages alone.\n2. Read `integration.md` from both agents\n3. Inspect files in `backend/` and `frontend/`\n4. Verify API responses match UI expectations\n5. If mismatches found, follow the Recovery Protocol below\n6. Move code to production paths\n7. Archive the build directory (or delete it)\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. **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.\n2. Check if the agent produced any files before crashing\n3. Read `integration.md` — did it log progress before failing?\n4. 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.\"\n5. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d '{...}' | jq .\n```\n\n### Frontend Verification\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders (data from API)\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration Verification\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Error responses display correctly in the UI\n- [ ] Auth flow works end-to-end\n\n## Setup Script\n\nRun once per project to initialize the collaboration structure:\n\n```\nscripts/init_collab.sh /path/to/project\n```\n\nCreates `shared/` with template `SPEC.md` and `.gitignore`.\n\n## Reference Files\n\nFor deeper patterns and templates:\n- `references/spec-template.md` — Full SPEC.md template with examples\n- `references/integration-log.md` — integration.md status format\n- `references/handoff-format.md` — Task handoff message template\n\n## When Not to Use\n\n- Single-file changes (just do it directly)\n- Solo tasks that don't cross backend/frontend boundaries\n- Bug fixes that are purely backend or purely frontend\n- Tasks where one agent can handle both sides (use a single subagent instead)\n\n## Limitations\n\n- Requires the `sessions_spawn` tool (OpenClaw v1.0+)\n- Works best with model pairs that have complementary strengths (e.g., backend-specialized + frontend-specialized)\n- Not a replacement for a design system — frontend engineer should have access to design tokens separately\n\nFile v1.2.0:_meta.json\n\n{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.2.0\",\n \"publishedAt\": 1777944811587\n}\n\nFile v1.2.0:references/handoff-format.md\n\n# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Files:**\n- `shared/build-{YYYYMMDD}/backend/router.py` — route handler\n- `shared/build-{YYYYMMDD}/SPEC.md` — API contract\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Monitoring\n\nAdapt monitoring to your setup. Suggested pattern:\n\n1. Check shortly after handoff: Did the agent start? Files modified?\n2. Check near ETA: Progress? Blockers?\n3. If no progress by ETA: re-spawn or escalate\n\nAdjust frequency and method based on your agent architecture and tooling.\n\nFile v1.2.0:references/integration-log.md\n\n# Integration Log — `shared/build-{YYYYMMDD}/integration.md`\n\n## Format\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting / 🔍 Reviewing / ✅ Complete\nBackend: 🔨 Building / ✅ Done / ❌ Blocked\nFrontend: 🔨 Building / ✅ Done / ❌ Blocked\n\n## Backend Progress\n- [ ] Router implemented at `backend/router.py`\n- [ ] Models defined at `backend/models.py`\n- [ ] Endpoints responding correctly\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Frontend Progress\n- [ ] Components built in `frontend/components/`\n- [ ] API client wired to endpoints\n- [ ] All states handled (loading, empty, error, populated)\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Integration Notes\n- Data format mismatch found: endpoint returns `items`, UI expects `data`\n- Auth tokens not flowing through — need session cookie handling\n```\n\n## Per-Agent Log Format (avoids conflicts)\n\nWhen both agents write to `integration.md` simultaneously, use separate log sections:\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting\nBackend: 🔨 Building\nFrontend: 🔨 Building\n\n## Backend Log\n\n- 2024-01-15 10:00: Started router implementation\n- 2024-01-15 10:30: GET /api/v1/items endpoint complete\n- 2024-01-15 11:00: BLOCKER: Need auth middleware from infra team\n\n## Frontend Log\n\n- 2024-01-15 10:15: Started ItemList component\n- 2024-01-15 10:45: Mock data wired, awaiting backend endpoint\n- 2024-01-15 11:10: Switched to using spec contract for API client\n\n## Integration Issues\n\n- (none yet)\n```\n\nFile v1.2.0:references/spec-template.md\n\n# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between frontend and backend\n- [ ] Auth flow works end-to-end\n\n## Success Criteria\n\n- [ ] Observable behavior that proves it works (not \"tests pass\")\n- [ ] User can complete the full happy path end-to-end\n- [ ] API errors display actionable messages in the UI\n\n## Out of Scope\n\n- What we are NOT building right now\n- Authentication improvements\n- Performance optimization\n\nFile v1.2.0:clawhub.json\n\n{\n \"name\": \"agent-collaboration-protocol\",\n \"displayName\": \"Agent Collaboration Protocol\",\n \"version\": \"1.2.0\",\n \"description\": \"Structured multi-agent collaboration for backend + frontend builds. Orchestrator, Backend Engineer, and Frontend Engineer roles work from a shared contract-first workspace with build directories, status tracking, recovery protocols, and integration verification.\",\n \"author\": \"the-hoffmann-board\",\n \"license\": \"MIT-0\",\n \"tags\": [\"collaboration\", \"multi-agent\", \"workflow\", \"backend\", \"frontend\", \"integration\", \"contract-first\", \"orchestration\"],\n \"minOpenClawVersion\": \"1.0.0\",\n \"repository\": \"https://github.com/NightKnight64/agent-collaboration-protocol\",\n \"requirements\": [\n \"OpenClaw v1.0.0+ with sessions_spawn support\",\n \"Access to at least one backend-capable and one frontend-capable model\"\n ]\n}\n\nArchive v1.1.0: 7 files, 8275 bytes\n\nFiles: _meta.json (147b), clawhub.json (850b), references/handoff-format.md (777b), references/integration-log.md (1708b), references/spec-template.md (3373b), scripts/init_collab.sh (1738b), SKILL.md (7025b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe contract lives in `shared/build-{YYYYMMDD}/`. Both builders write to the same directory. The orchestrator inspects and merges when both are done.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n integration.md ← Both update as they work\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec in shared/build-{YYYYMMDD}/SPEC.md.\n Write all backend code to shared/build-{YYYYMMDD}/backend/.\n Update shared/build-{YYYYMMDD}/integration.md with progress.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**Frontend Engineer:**\n```\ntask: >\n Implement the UI for the spec in shared/build-{YYYYMMDD}/SPEC.md.\n Write all frontend code to shared/build-{YYYYMMDD}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Update shared/build-{YYYYMMDD}/integration.md with progress.\n Use {frontend stack} (HTMX+Tailwind, React, etc.).\n```\n\nSet `mode: \"run\"` for one-shot completion.\n\n### Step 3: Both Build Simultaneously\n\n**Backend Engineer writes to** `shared/build-{YYYYMMDD}/backend/`:\n- Router/handler code\n- Data models and schemas\n- Config and infrastructure files\n- Updates `integration.md` with progress and any blockers\n\n**Frontend Engineer writes to** `shared/build-{YYYYMMDD}/frontend/`:\n- UI components / templates\n- Styles and layout\n- API client code\n- Updates `integration.md` with progress and any blockers\n\n### Step 4: Orchestrator Verifies and Merges\n\n1. Read `integration.md` from both agents\n2. Inspect files in `backend/` and `frontend/`\n3. Verify API responses match UI expectations\n4. If mismatches found, follow the Recovery Protocol below\n5. Move code to production paths\n6. Archive the build directory (or delete it)\n\n## Recovery Protocol\n\nWhen something goes wrong during a parallel build, follow these steps:\n\n### Agent Crash or Timeout\n1. Check if the agent produced any files before crashing\n2. Read `integration.md` — did it log progress before failing?\n3. 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.\"\n4. If the agent crashes again on the same task, reduce scope — split the work into smaller pieces\n\n### Build Mismatch (API ≠ UI)\n1. Identify the specific mismatch (field names, response shape, auth flow)\n2. Determine which side is correct by re-reading `SPEC.md`\n3. 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}.\"\n4. If both sides deviated from spec, update `SPEC.md` with the correct contract, then correct both\n\n### Blocked Agent\n1. Read the blocker in `integration.md`\n2. If it's a dependency on the other agent's work (e.g., frontend needs an endpoint that backend hasn't built yet):\n - Check if backend's route handler exists even partially\n - If yes, tell frontend to mock the expected response shape from the spec\n - If no, tell frontend to stub the API client and proceed with placeholder data\n3. If it's an external blocker (missing credentials, environment issue), alert the orchestrator's human\n\n### integration.md Conflict\nIf both agents edit `integration.md` simultaneously and create a conflict:\n1. Read both versions\n2. Merge manually — keep both progress sections\n3. Write the merged version back\n4. Consider switching to a per-agent log format (see `references/integration-log.md`)\n\n## Verification Guide\n\nBefore declaring the build complete, verify:\n\n### Backend Verification\n```bash\n# Test each endpoint from the spec\ncurl -s http://localhost:8000/api/v1/{resource} | jq .\ncurl -X POST http://localhost:8000/api/v1/{resource} -d\n\nArchive v1.0.0: 7 files, 6141 bytes\n\nFiles: clawhub.json (875b), references/handoff-format.md (688b), references/integration-log.md (858b), references/spec-template.md (1950b), scripts/init_collab.sh (1548b), SKILL.md (4343b), _meta.json (147b)","readmeExcerpt":"Skill: Agent Collaboration Protocol Owner: nightknight64 Summary: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on... Tags: latest:1.5.3 Version history: v1.5.3 | 2026-05-09T16:25:35.138Z | user Security hardening: replaced all sudo systemctl commands with platform-agnostic service restart guidance. Fixed flawe","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"shared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here"},{"language":"markdown","snippet":"# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\""},{"language":"text","snippet":"task: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.)."},{"language":"text","snippet":"task: >\n Implement the UI for the spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all frontend code to {ABSOLUTE_BUILD_DIR}/frontend/.\n Use the API contract in SPEC.md for your fetch calls.\n Log your progress to {ABSOLUTE_BUILD_DIR}/frontend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {frontend stack} (HTMX+Tailwind, React, etc.)."},{"language":"bash","snippet":"curl -s -o /dev/null -w \"%{http_code}\" https://example.com/api/health"},{"language":"bash","snippet":"# Quick sanity: key endpoints still respond\ncurl -s -o /dev/null -w \"%{http_code}\" https://example.com/api/health"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: agent-collaboration-protocol\ndescription: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on the same feature. Triggered by multi-role build requests like \"build a dashboard with an API and UI\" or \"create a full-stack feature\" or any task requiring both backend (API, data, infra) and frontend (UI, templates, design) work.\n---\n\n# Agent Collaboration Protocol\n\n## How It Works\n\nThree roles collaborate through a shared workspace:\n\n| Role | Responsibility |\n|------|---------------|\n| **Orchestrator** | Defines the contract, spawns both builders, verifies integration, merges |\n| **Backend Engineer** | Writes API code, data models, infrastructure |\n| **Frontend Engineer** | Writes UI components, templates, styles |\n\nThe 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.\n\n## Workflow\n\n### Step 1: Orchestrator Creates the Build Directory and Contract\n\n```\nshared/build-{YYYYMMDD}/\n SPEC.md ← Integration contract (orchestrator writes)\n backend/ ← Backend Engineer writes here\n frontend/ ← Frontend Engineer writes here\n backend-log.md ← Backend Engineer updates (own file, no conflicts)\n frontend-log.md ← Frontend Engineer updates (own file, no conflicts)\n integration.md ← Orchestrator merges findings here\n```\n\nWrite `SPEC.md` with these sections:\n\n```markdown\n# SPEC: {Feature Name}\n\n## Contract\n- API base path, auth scheme, content type\n- Data models (all entities, fields, types, relationships)\n- Endpoints (method, path, request/response shapes)\n- Shared constants (status enums, error codes, feature flags)\n- Error format\n\n## Routes\nBackend Engineer implements these. Frontend Engineer consumes them.\n\n## UI Components\nFrontend Engineer builds these. Backend Engineer doesn't touch them.\n\n## Shared Constants\nBoth agents use these. Status enums, error codes, UI state labels.\n\n## Success Criteria\nObservable behavior. Not \"tests pass\" — \"user can log in and see calendar.\"\n```\n\nFor the full spec template with examples, see `references/spec-template.md`.\n\n### Step 2: Orchestrator Spawns Agents\n\nSpawn two subagents with `sessions_spawn`:\n\n**Backend Engineer:**\n```\ntask: >\n Implement the API spec at {ABSOLUTE_BUILD_DIR}/SPEC.md.\n Write all backend code to {ABSOLUTE_BUILD_DIR}/backend/.\n Log your progress to {ABSOLUTE_BUILD_DIR}/backend-log.md.\n FIRST: Reply \"ACK — confirmed build directory: {ABSOLUTE_BUILD_DIR}\" before starting any work.\n IMPORTANT: Use the full absolute path for ALL file writes. Verify files exist after writing.\n Use {backend framework} (FastAPI, Express, etc.).\n```\n\n**F"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7b9ca8tx0e2ktzzdd8c94cfh863xmn\",\n \"slug\": \"agent-collaboration-protocol\",\n \"version\": \"1.5.3\",\n \"publishedAt\": 1778343935138\n}"},{"path":"references/handoff-format.md","content":"# Handoff Message Format\n\nUse this template when spawning or messaging agents. Include ALL fields.\n\n```\n## Handoff: {Title}\n\n**What:** {Specific task or deliverable — one sentence}\n\n**Why:** {Context and priority — why this is needed now}\n\n**Files:**\n- `shared/build-{YYYYMMDD}/backend/router.py` — route handler\n- `shared/build-{YYYYMMDD}/SPEC.md` — API contract\n\n**Success criteria:** {Observable behavior — how we know it's done}\n\n**ETA:** {YYYY-MM-DD HH:MM UTC}\n```\n\n## Monitoring\n\nAdapt monitoring to your setup. Suggested pattern:\n\n1. Check shortly after handoff: Did the agent start? Files modified?\n2. Check near ETA: Progress? Blockers?\n3. If no progress by ETA: re-spawn or escalate\n\nAdjust frequency and method based on your agent architecture and tooling."},{"path":"references/integration-log.md","content":"# Integration Log — `shared/build-{YYYYMMDD}/integration.md`\n\n## Format\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting / 🔍 Reviewing / ✅ Complete\nBackend: 🔨 Building / ✅ Done / ❌ Blocked\nFrontend: 🔨 Building / ✅ Done / ❌ Blocked\n\n## Backend Progress\n- [ ] Router implemented at `backend/router.py`\n- [ ] Models defined at `backend/models.py`\n- [ ] Endpoints responding correctly\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Frontend Progress\n- [ ] Components built in `frontend/components/`\n- [ ] API client wired to endpoints\n- [ ] All states handled (loading, empty, error, populated)\n- [ ] Shared constants match spec\n\n### Blockers\n- ...\n\n## Integration Notes\n- Data format mismatch found: endpoint returns `items`, UI expects `data`\n- Auth tokens not flowing through — need session cookie handling\n```\n\n## Per-Agent Log Format (avoids conflicts)\n\nWhen both agents write to `integration.md` simultaneously, use separate log sections:\n\n```markdown\n# Build: {Feature Name} — {Date}\n\n## Status\nOrchestrator: ⏳ Waiting\nBackend: 🔨 Building\nFrontend: 🔨 Building\n\n## Backend Log\n\n- 2024-01-15 10:00: Started router implementation\n- 2024-01-15 10:30: GET /api/v1/items endpoint complete\n- 2024-01-15 11:00: BLOCKER: Need auth middleware from infra team\n\n## Frontend Log\n\n- 2024-01-15 10:15: Started ItemList component\n- 2024-01-15 10:45: Mock data wired, awaiting backend endpoint\n- 2024-01-15 11:10: Switched to using spec contract for API client\n\n## Integration Issues\n\n- (none yet)\n```"},{"path":"references/spec-template.md","content":"# SPEC: {Feature Name}\n\n> Generated by Agent Collaboration Protocol\n\n## Overview\n\nOne sentence. What this feature does and why it matters.\n\n## Contract\n\n| Field | Value |\n|-------|-------|\n| API Base Path | `http://localhost:8000/api/v1` |\n| Auth Scheme | Bearer JWT / Session cookie / None |\n| Content Type | `application/json` |\n| Error Format | `{ \"error\": \"...\", \"detail\": { ... } }` |\n\n## Data Models\n\n### {Entity Name}\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| id | string | yes | UUID |\n| name | string | yes | Display name |\n| status | string | yes | See Shared Constants |\n\n### {Entity Name 2}\n...\n\n## Shared Constants\n\nBoth backend and frontend must use the same values for these:\n\n### Status Enums\n| Constant | Values | Used By |\n|----------|--------|---------|\n| `{Entity}Status` | `active`, `inactive`, `pending` | Backend enum + frontend labels |\n| `ErrorCode` | `NOT_FOUND`, `UNAUTHORIZED`, `VALIDATION_ERROR` | Backend error responses + frontend error messages |\n\n### Feature Flags\n| Flag | Default | Description |\n|------|---------|-------------|\n| `ENABLE_{FEATURE}` | `false` | Controls {feature} visibility |\n\n## Endpoints\n\n### `GET /api/v1/{resource}`\n**Response:**\n```json\n{\n \"data\": [ ... ],\n \"total\": 42,\n \"page\": 1\n}\n```\n\n### `POST /api/v1/{resource}`\n**Request:**\n```json\n{\n \"field\": \"value\"\n}\n```\n**Response:** `201 Created` with body containing the created entity\n\n### Error Response (all endpoints)\n```json\n{\n \"error\": \"VALIDATION_ERROR\",\n \"detail\": {\n \"field\": \"email\",\n \"message\": \"Invalid email format\"\n }\n}\n```\n\n## UI Components\n\n### {Component Name}\n- Purpose: One sentence\n- Data source: `GET /api/v1/{resource}`\n- States: loading, empty, error, populated\n- Interactions: click to select, pull to refresh\n\n## File Structure\n\n### Backend\n```\nbackend/\n router.py ← Route handlers\n models.py ← Data models/schemas\n service.py ← Business logic\n```\n\n### Frontend\n```\nfrontend/\n components/ ← UI components\n templates/ ← Page templates\n styles/ ← Styles\n api.js ← API client\n```\n\n## Edge Cases\n\n- Empty state: What shows when no data exists?\n- Error state: What shows on API failure?\n- Loading state: What shows while data fetches?\n- Offline: Does it degrade gracefully?\n\n## Verification Checklist\n\n### Backend\n- [ ] Each endpoint returns correct status codes (200, 201, 400, 404, 500)\n- [ ] Error responses match the shared error format\n- [ ] Status enums match the Shared Constants section\n- [ ] Auth scheme matches the Contract section\n\n### Frontend\n- [ ] Loading state renders (spinner/skeleton)\n- [ ] Empty state renders (no data message)\n- [ ] Error state renders (actionable error message)\n- [ ] Populated state renders with real data\n- [ ] All user interactions work (click, submit, navigate)\n\n### Integration\n- [ ] Frontend fetch calls match backend endpoint paths\n- [ ] Request/response shapes match the spec\n- [ ] Shared constants are consistent between fron"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on... Skill: Agent Collaboration Protocol Owner: nightknight64 Summary: Structured multi-agent collaboration for backend + frontend builds. Use when an orchestrator needs to coordinate a backend engineer and frontend engineer on... Tags: latest:1.5.3 Version history: v1.5.3 | 2026-05-09T16:25:35.138Z | user Security hardening: replaced all sudo systemctl commands with platform-agnostic service restart guidance. Fixed flawe","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1282,"uniquenessScore":52,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T07:51:48.168Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T07:51:48.168Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:50:18.938Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}