message-board-protocol

name	message-board-protocol
description	Use for any container agent that posts progress to the coordination server's message board. Defines the curl format, channels, message types, payload conventions, posting responsibilities, and verbosity levels.

Message Board Protocol

The coordination server at $SERVER_URL provides a message board for reporting progress. The human operator reads GET /messages/general to reconstruct a timeline of your work. Always post at the prescribed moments — but never let a failed post interrupt your work.

Identity Tag

Every message you post must be prefixed with your role tag in square brackets. Derive the tag from your agent definition name: strip the container- or scaffold- prefix, uppercase the remainder, and use that as your tag. Examples: container-implementer -> [IMPLEMENTER], scaffold-implementer -> [IMPLEMENTER], container-orchestrator -> [ORCHESTRATOR].

This tag goes at the start of every payload.message string in status_update messages, and in the notes field of phase events. It allows the operator to see at a glance which agent posted each message.

How to Post

Use curl via the Bash tool:

curl -s -X POST "${SERVER_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Name: ${AGENT_NAME}" \
  -H "X-Project-Id: ${PROJECT_ID}" \
  -d '{"channel":"general","type":"status_update","payload":{"message":"[YOUR-ROLE] Status message here."}}' \
  --max-time 5 >/dev/null 2>&1 || true

SERVER_URL, AGENT_NAME, and PROJECT_ID are environment variables already set in the container. The X-Project-Id header is REQUIRED — without it the server scopes the message to the default project and the operator will not see it on their dashboard. The || true makes the call non-fatal.

Smoke Test — First Message

Your very first action, before reading the plan or doing any work, is to post a hello message to the general channel:

curl -sf -X POST "${SERVER_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Name: ${AGENT_NAME}" \
  -H "X-Project-Id: ${PROJECT_ID}" \
  -d '{"channel":"general","type":"status_update","payload":{"message":"[YOUR-ROLE] Agent online. Beginning work."}}' \
  --max-time 5

Replace [YOUR-ROLE] with your actual role tag (e.g. [IMPLEMENTER]).

This confirms you can reach the message board and that you are visible to the operator. If this post fails, stop immediately and report the error as your final output — a broken message board means the operator has no visibility into your work.

Confirm Loaded Environment Skills

Some agent definitions instruct you to load one or more skills from your project checkout at runtime via the Skill tool — for example, the project's own ue-cpp-style. These environment skills are different from the skills already composed into this prompt: they are loaded from the working tree after you spin up, so they can silently fail to load when the checkout is wrong or the agent wiring is broken. That silent failure is invisible to the operator unless you surface it.

So: if your definition tells you to load any environment skill, load it as part of spin-up — before you post the hello above — and name each skill you loaded in that same hello message, so the operator has a standing confirmation the load actually happened:

curl -sf -X POST "${SERVER_URL}/messages" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Name: ${AGENT_NAME}" \
  -H "X-Project-Id: ${PROJECT_ID}" \
  -d '{"channel":"general","type":"status_update","payload":{"message":"[IMPLEMENTER] Agent online. Loaded environment skills: ue-cpp-style. Beginning work."}}' \
  --max-time 5

If a skill your definition told you to load is missing or fails to load, say so explicitly in the message (e.g. … environment skill ue-cpp-style UNAVAILABLE …) rather than staying silent — surfacing that gap is the entire purpose of this confirmation. If your definition does not require any environment skills, post the plain hello with no skills line.

Channels

• general — Phase transitions, failures, and final summaries. This is what the human reads.
• <role-name> (e.g. implementer, reviewer) — Sub-agent progress. Post build results, investigation notes, and detailed progress here.

Message Types

type	when to use
phase_start	Beginning a new phase
phase_complete	Phase passed build and review
phase_failed	Phase could not be completed after retries
build_result	After each build attempt
status_update	Progress narration, decisions, notable observations
summary	Final post when all work is done or the run has stopped

Payload Conventions

Keep payloads concise — they are persisted to the coordination server's database. Include at minimum:

• Phase events: { "phase": "<id>", "title": "<title>", "status": "...", "notes": "..." }
• Build results: { "phase": "<id>", "outcome": "pass" | "fail", "errors": ["..."] }
• Status updates: { "message": "<your message>" }
• Summary: { "summary": "<markdown block>" }

Who Posts

You are the primary message poster. Your sub-agents do not post to the message board — you read their output and relay the relevant parts. This avoids fragile multi-hop messaging chains.

Verbosity

Your delegation prompt may include a LOG_VERBOSITY level (quiet, normal, or verbose). If not specified, default to verbose.

quiet — Mandatory posts only.

normal — Mandatory posts, plus build outcomes with error summaries, and notable decisions or deviations from the plan.

verbose — Everything from normal, plus:

• Post a status_update when you start a significant block of work.
• Post after completing each significant chunk.
• Post when you encounter something unexpected or make a non-obvious decision.
• Post build results with enough detail to diagnose without reading the full log.
• Post when resolving sub-agent mappings (which agent type you selected and why).
• Post when locating (or failing to locate) the task document or plan file you need.
• Post when any tool call fails: web search errors, connection timeouts, permission denials, unexpected exit codes.
• Post when retrying something, and what you changed on the retry.

These message posts are your observability trail. If you log what you are doing, especially anything that fails, it gives the operator the opportunity to diagnose and fix these issues so you can complete your work. Silence during failures is the worst outcome: you struggle alone with no help, and the operator cannot tell whether you are stuck or making progress.

When in doubt about whether to post in verbose mode, post. The cost of a message is negligible; the cost of a silent 25-minute gap is far higher.