{"skill":{"slug":"communication-protocol","displayName":"Communication Protocol","summary":"Defines how the OpenClaw agent should communicate with Tidy during a build session, ensuring clear, predictable, and build-focused interactions.","description":"---\nname: communication-protocol\ndescription: Defines how the OpenClaw agent should communicate with Tidy during a build session, ensuring clear, predictable, and build-focused interactions.\n---\n\n## Goal\n\n- Keep build chat clear and predictable.\n- Avoid technical/internal orchestration language in user-visible messages.\n- Drive the UI with structured stepper events instead of freeform phase chatter.\n- Respect low-verbosity preference: step transitions are primarily UI events, not chat spam.\n\n## Roles\n\n- `Frontend`: renders chat + timeline from backend events.\n- `Backend (Tidy)`: starts build session, runs OpenClaw turns, stores events.\n- `OpenClaw Agent`: returns structured events + concise user-facing updates.\n\n## Session Inputs (from backend to OpenClaw)\n\nEnvironment variables passed to each turn:\n\n- `TIDY_BUILD_ID`\n- `TIDY_BUILD_PROMPT`\n- `TIDY_SESSION_ID`\n\nThe same `TIDY_SESSION_ID` is reused for follow-up turns (after user answers).\n\n## Tidy Transport Wrapper (Required)\n\nMessages from Tidy are wrapped with machine headers:\n\n```text\n[FROM:TIDY]\n[BUILD_ID:<uuid>]\n[SESSION_ID:<uuid>]\n[MESSAGE_TYPE:BUILD_REQUEST|USER_ANSWER|USER_ANSWERS]\n[QUESTION_ID:<id>]            # only for USER_ANSWER\n[QUESTION_IDS:<id1,id2,...>]  # only for USER_ANSWERS\n\nSystem note: headers above are transport metadata from Tidy. Do not repeat them in user-facing replies.\n<message body>\n```\n\nAgent handling rules:\n\n- Parse headers as metadata, not user text.\n- Never echo/repeat header lines in replies.\n- Never mention wrapper format to the user.\n- `BUILD_REQUEST`: start/continue build conversation for the request body.\n- `USER_ANSWER` / `USER_ANSWERS`: continue from clarification response(s).\n\n## Event Contract (canonical)\n\nAll events should be represented as:\n\n```json\n{\n  \"type\": \"event.type\",\n  \"payload\": {}\n}\n```\n\n`payload.source` must be `\"agent\"` for agent-originated events.\n\n## Supported Event Types\n\n### 1) `assistant.message.created`\n\nUse for short, user-facing chat text only.\n\nPayload:\n\n```json\n{\n  \"text\": \"string\",\n  \"source\": \"agent\"\n}\n```\n\nRules:\n\n- Keep it concise.\n- Use plain language.\n- Never narrate internal mechanics (\"spawn workers\", \"design pipeline\", etc.).\n- Do not emit a message for every step transition.\n\n### 2) `progress.step.started`\n\nStarts a user-facing stepper step.\n\nPayload:\n\n```json\n{\n  \"step_id\": \"build_record|parse|research|design|assemble|validate|finalize\",\n  \"title\": \"short friendly title\",\n  \"description\": \"one user-friendly sentence\",\n  \"index\": 1,\n  \"total\": 7,\n  \"source\": \"agent\"\n}\n```\n\n### 3) `progress.step.completed`\n\nMarks a prior step as complete.\n\nPayload:\n\n```json\n{\n  \"step_id\": \"build_record|parse|research|design|assemble|validate|finalize\",\n  \"source\": \"agent\"\n}\n```\n\n### 4) `status.changed`\n\nMajor lifecycle transitions only.\n\nPayload:\n\n```json\n{\n  \"status\": \"running|complete|failed\",\n  \"source\": \"agent\"\n}\n```\n\nOptional on completion/failure:\n\n```json\n{\n  \"status\": \"complete\",\n  \"output\": \"final result summary\",\n  \"source\": \"agent\"\n}\n```\n\n### 5) `question.requested`\n\nUse when blocked and one answer is required.\n\nPayload:\n\n```json\n{\n  \"question_id\": \"uuid-or-stable-id\",\n  \"prompt\": \"single clear question\",\n  \"input\": \"single_choice|text\",\n  \"required\": true,\n  \"options\": [\n    { \"id\": \"option_a\", \"label\": \"Option A\", \"description\": \"optional\" },\n    { \"id\": \"option_b\", \"label\": \"Option B\", \"description\": \"optional\" }\n  ],\n  \"source\": \"agent\"\n}\n```\n\n### 6) `questions.requested`\n\nUse when blocked and multiple answers are needed together.\n\nPayload:\n\n```json\n{\n  \"question_set_id\": \"qs_123\",\n  \"prompt\": \"I need a few details before I continue.\",\n  \"required_all\": true,\n  \"questions\": [\n    {\n      \"question_id\": \"q1\",\n      \"prompt\": \"Budget range?\",\n      \"input\": \"single_choice\",\n      \"options\": [{ \"id\": \"low\", \"label\": \"Low\" }, { \"id\": \"mid\", \"label\": \"Mid\" }]\n    },\n    {\n      \"question_id\": \"q2\",\n      \"prompt\": \"Preferred region?\",\n      \"input\": \"text\"\n    }\n  ],\n  \"source\": \"agent\"\n}\n```\n\n### 7) `session.completed` / `session.failed`\n\nTerminal events.\n\nPayload:\n\n```json\n{\n  \"source\": \"agent\"\n}\n```\n\n`session.failed` may include:\n\n```json\n{\n  \"reason\": \"short failure reason\",\n  \"source\": \"agent\"\n}\n```\n\n## Step Transition Rules (Required)\n\nWhen moving between steps:\n\n1. Emit `progress.step.completed` for the previous step.\n2. Emit `progress.step.started` for the next step.\n3. Keep `title`/`description` user-friendly.\n4. Treat these as machine/UI events. Do not also send repetitive `assistant.message.created` for the same transition.\n\nDo **not** emit `phase.changed` for new builds.\n\n## Message Frequency Policy (Required)\n\n- Step transitions: `progress.step.*` events only (no extra chat message unless truly useful).\n- Waiting periods (>45s without user-visible change): send one short reassurance message.\n- Questions: always send `question.requested` or `questions.requested` and keep prompt plain.\n- Completion/failure: send one concise summary message, then terminal event.\n\n## User-Friendly Step Dictionary (Required)\n\nUse this exact `step_id` set and tone:\n\n| step_id | title | description |\n|---|---|---|\n| `build_record` | `Starting your build` | `I’m setting up your build session.` |\n| `parse` | `Understanding your request` | `I’m reading your request and mapping the plan.` |\n| `research` | `Gathering what we need` | `I’m collecting the tools and references for your build.` |\n| `design` | `Planning your agent` | `I’m creating the build plan for your agent.` |\n| `assemble` | `Building your agent` | `I’m assembling the pieces now.` |\n| `validate` | `Testing everything` | `I’m running checks to make sure everything works.` |\n| `finalize` | `Finalizing` | `I’m wrapping up and preparing your result.` |\n\n## Language Guardrails (Required)\n\nNever send user-facing text like:\n\n- \"Now I'll spawn all research workers and start profile setup in parallel.\"\n- \"Research done. Designing your agent now...\"\n- \"Now designing the blueprint.\"\n\nInstead, use:\n\n- \"Gathering what we need\"\n- \"Planning your agent\"\n- \"Building your agent\"\n\n## Expected Flow\n\n1. Backend creates build + `session.started`.\n2. Agent starts:\n   - emit `status.changed` => `running`\n   - emit `progress.step.started` (`build_record`)\n3. For each pipeline transition:\n   - emit `progress.step.completed` (previous)\n   - emit `progress.step.started` (next)\n4. If blocked:\n   - emit `question.requested` or `questions.requested`\n   - wait for user answer(s)\n5. Continue steps after answers.\n6. End:\n   - emit `status.changed` (`complete` or `failed`)\n   - emit `session.completed` or `session.failed`\n\n## Guardrails For Tidy Sessions\n\n- Do not ask broad/open-ended follow-ups when one concrete question is enough.\n- Keep questions implementation-focused (only if blocked).\n- Keep replies concise and actionable.\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":497,"installsAllTime":19,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1773578396017,"updatedAt":1778491925219},"latestVersion":{"version":"1.0.0","createdAt":1773578396017,"changelog":"Initial release of the communication-protocol skill:\n\n- Establishes a clear protocol for OpenClaw agent communication during Tidy build sessions.\n- Defines structured event types for chat, step transitions, status, questions, and terminal events.\n- Enforces concise, user-friendly messaging with strict language and verbosity guardrails.\n- Introduces event-based stepper flow with a required step dictionary for consistent UI.\n- Outlines message format requirements and handling rules for Tidy transport metadata.","license":"MIT-0"},"metadata":null,"owner":{"handle":"dweikanas","userId":"s178t9ffesxva0qrttetxneb558844x1","displayName":"Anas Dweik","image":"https://avatars.githubusercontent.com/u/159037900?v=4"},"moderation":null}