fix(cli): clarify experimental board coordination

[marius-kilocode]

What Problem This Solves

Experimental shared-board instructions leave room for unnecessary solo reporting, confusion between the board root and a task's parent, and treating a stored message as evidence that another worker read it. Unclear read checkpoints can also turn ordinary Task completion into an unnecessary board scan.

This addresses the communication-guidance portion of #13694, part of #13673.

Why This Change Was Made

Keep coordination advice behind experimental.shared_agent_board, where it belongs. Normal Task instructions govern sessions that do not use the board, so their definitions and scheduling guidance remain unchanged.

The revised wording follows dependencies rather than task categories: share material findings with affected participants, including background siblings, while preserving requested independence and communication limits. It clarifies incremental read cursors, the meaning of main, and when a Task continuation represents additional authorized work rather than notification delivery.

No runtime implementation, storage format, identity mechanism, permission boundary, or lifecycle control is changed. The guidance does not add an orchestration layer or change normal Task definitions.

User Impact

• Keep solo work free of irrelevant board bookkeeping.
• Share useful findings during work and read relevant pending updates before affected decisions or integration, without requiring a read merely because a Task finished.
• Route updates through known participant IDs; main means the board root, not necessarily the direct parent.
• Treat peer messages as evidence, not authority. A post or the sender's own read is not a recipient read receipt.
• Continue an existing child only for additional authorized work, not merely to deliver a note.

Evidence

Focused tests verify that the instructions, tools, and revised parameter descriptions reach model requests only when the experimental flag is enabled. Existing Task definitions and parameter shapes remain unchanged. After rebasing onto current main, 142 focused tests passed, along with CLI typecheck, targeted lint, formatting, and the annotation guard.

A frozen-guidance comparison used the same versioned timestamp-reporting fixture and task prompt across three model combinations. Each run had a parent, a read-only producer auditor, and a background consumer. All nine sessions in the valid comparison used medium reasoning, verified from stored requests.

Parent / background workers	Communication observed	Independent result
smart model / smart model	Auditor shared the contract while working. Consumer explicitly read it before changing timestamp interpretation. Parent completed integration without corrective continuation.	14 checks passed; 17 fixture tests passed.
cheap model / cheap model	The same handoff worked. Parent omitted one acceptance criterion from delegation, caught the resulting error, and continued the same child for required corrective work.	14 checks passed after correction; 8 fixture tests passed.
smart model / cheap model	Complete requirements reached both workers. Consumer read the auditor finding before editing; parent completed integration without corrective continuation.	14 checks passed; 16 fixture tests passed.

The producer contracts, exported interfaces, IDs, and protected files remained unchanged. The handoff was checked from message and edit timestamps, not inferred from final answers. An initial model-selection mismatch was stopped and excluded from the valid comparison; subsequent parents were verified with a no-tool control turn.

Limits: this is one directed fixture per combination, not proof of universal model cooperation. The cheap-model parent made repeated empty reads and required a correction, so functional success did not imply perfect communication discipline. Team-wide messages were sufficient for this fixture; it does not establish fine-grained nested recipient discovery. These live runs preceded the rebase onto main's merged notice/read changes, so their read counts are not a benchmark of the latest runtime. Raw model identifiers, session artifacts, and screenshots are not published.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (6 files)

• .changeset/swarm-collaboration-guidance.md
• packages/opencode/src/kilocode/board/context.ts
• packages/opencode/src/kilocode/tool/board.ts
• packages/opencode/test/kilocode/board-context.test.ts
• packages/opencode/test/kilocode/board-live.test.ts
• packages/opencode/test/kilocode/board-tools.test.ts

---

_{Reviewed by grok-4.6 · Input: 187.8K · Output: 16.3K · Cached: 714.5K}

_{Review guidance: REVIEW.md from base branch main}