idea: board topic/subscription primitive for receiver-initiated announcements — inspired by MetaGPT's shared message pool

[github-actions]

Research brief

Landscape survey (2026-07-25), scoped to: "agent_mesh roadmap & comparable OSS
agent frameworks" (OpenHands, SWE-agent, Aider, MetaGPT/ChatDev, Renovate,
claude-code-action).

Landscape signal — MetaGPT's shared message pool. MetaGPT's agents don't
address each other directly for most coordination: each role "publishes
structured messages in a shared pool," and any other role can "subscribe to
relevant messages based on their own profiles" — an agent's next action fires
once its declared prerequisite messages have appeared in the pool, without
the publisher needing to know in advance who (or how many) will consume it.
Source (fetched, verified): https://arxiv.org/html/2308.00352v6 (MetaGPT
paper, full text — "shared message pool" / subscription mechanism sections).

Gap (confirmed against this repo, not just landscape-inspired)

agent_mesh has exactly two communication shapes today, and both require the
sender to already know every recipient:

1. delegate_to_peer (src/a2a/peer-bridge.js) — synchronous, ask-only,
   point-to-point: caller names one specific peer per call.
2. The task board create_task_for_peer (src/board/*) — durable and
   async, but still directed: from/to are a single named pair, framework
   stamped.
3. fanOutToPeers (the orchestrator's parallel-dispatch helper, closed
   idea: multi-peer fan-out / scatter-gather — concurrent delegate_to_peer to N peers + synthesis (v2 unlock) #185 "multi-peer fan-out / scatter-gather") is the closest existing
   analog to "one caller reaching several peers" — but it is still
   caller-directed: the orchestrator enumerates the N peers itself,
   synchronously, for one conductor workflow run. It is not a durable
   artifact a peer can publish once and have an a priori unknown set of
   interested peers discover later, asynchronously, on their own polling
   cadence.

There is no primitive for "peer A publishes that something happened (a PRD
landed, an MIR regenerated, a spec moved to approved) once, and any peer
that has separately declared interest in that topic picks it up on its own
next poll" — without A needing to enumerate or even know who those peers
are. Every existing coordination path in this repo is 1:1 or a
caller-enumerated fan-out, never receiver-initiated subscription.

Proposed direction

Extend the existing board store (<mesh-root>/mesh/board/) — already a
framework-owned, ask-safe write surface, per src/board/store.js — with a
second, parallel primitive rather than modifying task semantics:

• publish_board_topic({ topic, brief }) on the agentmesh_peerbridge
  bridge: framework-stamps from/id/timestamp exactly like
  create_task_for_peer does today (never trusts caller-supplied identity
  fields — same anti-spoof pattern), and appends a small durable record
  under a new <mesh-root>/mesh/board/topics/<topic>/ directory. No to
  field — publish is topic-addressed, not peer-addressed.
• Each peer self-declares subscriptions in its own mesh.json/
  agent.json (x-agentmesh.subscribedTopics: [...]) — operator-owned, so
  a publisher can never force delivery to a peer that hasn't opted in, and a
  compromised publisher can't expand its own read/write reach (matches the
  existing webTools/writeTools self-declared-manifest pattern from idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules #845
  and the webTools design).
• A new read verb list_topic_updates() lets a subscribed peer poll for
  topic records newer than its own last-seen cursor — same polling shape the
  board-notify hook already uses for list_my_tasks, so this fits the
  existing async, agent-driven pickup model rather than inventing a push
  mechanism.
• Purely additive: peers that declare no subscriptions see no behavior
  change; publishing writes only the framework-owned board store, never a
  peer's folder, so it stays ask-safe like task assignment.

Invariants preserved

• Task-board identity is framework-set: from/id/timestamps on a
  published topic record come from the authentic caller identity, never tool
  args — same rule already governing create_task_for_peer.
• Single writable root: publish only ever writes the shared board store,
  never a peer's own folder.
• Anti-spoof: subscription lists are declared once, out-of-band, in each
  peer's own manifest — never negotiated via tool-call args, so a topic
  publisher cannot expand who receives it.

Scope hint

src/board/store.js (new topics/ namespace alongside tasks/),
src/a2a/peer-bridge.js (publish_board_topic/list_topic_updates verbs),
manifest schema addition for subscribedTopics, pure unit tests for the new
store/read-cursor logic (no spawn/hook changes).

Sources

• https://arxiv.org/html/2308.00352v6 (MetaGPT paper, fetched and verified
  directly — shared message pool / subscription-by-profile mechanism)

[github-actions]

Spec ready — attempt 1 of 3.

Authored the full design at docs/superpowers/specs/2026-07-26-idea-board-topic-subscription-primitive-design.md on branch spec/issue-847, commit b38ea67.

git push origin spec/issue-847 → HTTP 403 (Permission to danabaxia/agent_mesh.git denied to github-actions[bot]) — reconfirmed this run via gh api repos/danabaxia/agent_mesh --jq '.permissions.push' → false. Same known root cause tracked centrally at #771 (DEV_MESH_PAT secret still not configured with contents:write), which remains open and unresolved as of this run.

Labels already correctly reflect this (spec:draft + blocked + needs-human). Local spec/issue-847 branch deleted after the failed push (nothing lost — it never reached origin; full spec content is reproduced below so a human can publish it manually). Two attempts remain before this issue's own circuit breaker trips.

To publish manually: create branch spec/issue-847, save the content below as docs/superpowers/specs/2026-07-26-idea-board-topic-subscription-primitive-design.md, commit, push, gh pr create --title "spec(#847): board topic/subscription primitive" --base main --head spec/issue-847. Then set label spec:in-review, remove spec:draft + blocked + needs-human.

---

Board Topic/Subscription Primitive — Design

Closes: #847.

1. Goal

Add a receiver-initiated, publisher-agnostic coordination primitive to the
mesh task board: a peer publishes that something happened (a PRD landed, an
MIR regenerated, a spec moved to approved) once, without needing to
enumerate or even know which other peers care — and any peer that has
separately, out-of-band declared interest in that topic discovers the record
later on its own polling cadence.

Landscape basis: MetaGPT's shared message pool — each role "publishes
structured messages in a shared pool," and any other role "subscribe[s] to
relevant messages based on their own profiles," so a role's next action fires
once its declared prerequisite messages appear, without the publisher naming
consumers in advance
(https://arxiv.org/html/2308.00352v6, "shared message pool" / subscription
sections).

2. Non-goals

• Not a replacement for existing coordination shapes. delegate_to_peer
  (synchronous point-to-point ask), create_task_for_peer (durable, directed
  1:1 handoff), and fanOutToPeers (caller-enumerated, synchronous scatter)
  are unaffected and keep their existing semantics. This spec adds a fourth,
  orthogonal shape: undirected, durable, receiver-declared — not a
  refactor of the other three.
• No push mechanism. Consistent with the board-notify hook's existing
  pattern (list_my_tasks is polled, never pushed to), subscribers poll
  list_topic_updates on their own cadence. No new transport, no webhook, no
  live channel.
• No cross-mesh / cross-process pub-sub. Topics live under one mesh's own
  <mesh-root>/mesh/board/ store, exactly like tasks do today — same
  single-mesh scope as the rest of the board.
• No unsubscribe/negotiation tool. Subscriptions are declared once,
  out-of-band, in a peer's own manifest (§4.3) — there is no
  subscribe_to_topic tool call, precisely so a publisher (or anything a
  publisher's prompt is tricked into doing) can never expand who receives a
  topic. Changing a subscription list is an operator (human/doctor) action,
  not a runtime one.
• No retention/GC policy in v1. Topic records accumulate under
  mesh/board/topics/<topic>/; pruning old records is deferred (same v1
  posture the task board itself started with before board-notify existed).

3. Background — current coordination shapes

All three existing paths require the sender to already know every
recipient:

1. delegate_to_peer (src/a2a/peer-bridge.js) — synchronous, point-to-point:
   caller names one specific peer per call.
2. create_task_for_peer (src/board/*) — durable and async, but still
   directed: from/to are a single named pair, framework-stamped.
3. fanOutToPeers — the closest existing analog to "one caller reaching
   several peers," but still caller-directed: the orchestrator enumerates
   the N peers itself, synchronously, for one conductor-workflow run. It is
   not a durable artifact a peer can publish once and have an a priori
   unknown set of interested peers discover later, asynchronously.

There is no "publish once, N peers discover later, publisher never enumerates
them" primitive today.

4. Design

4.1 Store: new topics/ namespace in src/board/store.js

Parallel to the existing tasks/ namespace (boardDir), add a sibling
directory layout:

<mesh-root>/mesh/board/topics/<topic>/<seq>.json

• topicDir(meshRoot, topic) → join(meshRoot, 'mesh', 'board', 'topics', slug(topic))
  (reuses the existing slug() sanitizer already used for task-id prefixes).
• publishTopic(meshRoot, { topic, from, brief, at }) — mirrors createTask's
  shape: assigns the next zero-padded sequence number within that topic
  (same existingIds-scan-and-increment approach nextTaskId already uses,
  scoped to the topic dir instead of a from-to- prefix), writes one
  atomic JSON record { id, topic, from, brief, at }. No to field — a
  published record is topic-addressed, not peer-addressed.
• listTopicUpdates(meshRoot, topic, sinceId) — reads all records in
  topicDir(meshRoot, topic), returns those with id > sinceId (numeric
  compare on the zero-padded sequence), sorted ascending. A missing/unknown
  topic directory returns [] (never throws) — same tolerant-read posture
  listTasks/readTask already have.
• Reuses atomicWriteFile for the same torn-file safety createTask/
  writeTask already rely on.

4.2 Bridge verbs on agentmesh_peerbridge

Two new verbs on the existing peer-bridge MCP server
(src/a2a/peer-bridge.js), alongside createTaskForPeer/listMyTasks/
updateMyTask — no new MCP server, same reserved bridge surface:

• publish_board_topic({ topic, brief }) — framework-stamps from (via the
  same resolveSelfName/boardContext() helper createTaskForPeer already
  calls) and at (server timestamp); the caller supplies only topic and
  brief as data. Validates topic/brief non-empty and
  brief.length <= MAX_TASK_CHARS, exactly like createTaskForPeer's field
  checks. Returns { ok: true, topic, id } or a boardRefusal(...).
• list_topic_updates({ topic, since_id }) — since_id optional, defaults to
  '0' (read everything). No registry/peer check needed (a topic isn't a
  peer name); only requires boardContext() to resolve the mesh root.
  Returns { ok: true, records: [{ id, from, brief, at }] } (topic name
  itself is not repeated per record — caller already knows which topic it
  asked for).
• Both verbs are ask-safe: like create_task_for_peer, they write only
  the framework-owned board store, never a peer's own folder, and never spawn
  claude -p — so they need no do-mode gate.

4.3 Self-declared subscriptions (manifest, not runtime)

A peer declares interest out-of-band, in its own agent.json (or
mesh.json entry):

{
  "x-agentmesh": {
    "subscribedTopics": ["mir-regenerated", "spec-approved"]
  }
}

• Purely advisory/self-documenting from the framework's point of view in v1 —
  list_topic_updates does not itself check the caller's declared
  subscriptions (any peer could technically poll any topic name it knows).
  The manifest field's job is to make the peer's own prompt aware of what
  it should be polling for (surfaced the same way list_peers' descriptions
  already surface data into the worker's context), and to make the mesh's
  subscription graph inspectable/auditable by a human or doctor, not to
  enforce access control — topics are not a security boundary, just a
  discovery convention. This mirrors the existing webTools/write-tool
  self-declared-manifest pattern (idea: per-peer write-tool allowlist narrowing for do-mode — inspired by Claude Code's parameterized subagent permission rules #845) for the "declared once, out-of-band"
  shape, though unlike those two it is advisory rather than gating.

4.4 Framework-stamped identity (anti-spoof, matches task-board rule)

Exactly like create_task_for_peer: the model-facing surface of
publish_board_topic is { topic, brief } only. from and at come from
the authentic caller identity (resolveSelfName) and the server clock —
never from tool args. A published record's id is framework-assigned
(sequence-scanned), never caller-supplied.

5. Invariants preserved

• Task-board identity is framework-set: extended verbatim to topics —
  from/id/timestamp on a published record come from the authentic caller
  identity and the framework, never tool args (same rule already governing
  create_task_for_peer/update_my_task).
• Single writable root: publish_board_topic writes only the shared
  <mesh-root>/mesh/board/topics/ store — never a peer's own folder — so it
  stays ask-safe exactly like task assignment.
• Anti-spoof: subscription lists are declared once, out-of-band, in each
  peer's own manifest — never negotiated via tool-call args, so a topic
  publisher cannot expand who "receives" it (and, since delivery is
  poll-based, a publisher has no mechanism to force delivery to anyone at
  all).
• AGENT.md/brief is untrusted data, never instructions: a published
  brief is surfaced to a polling subscriber as data through
  list_topic_updates, exactly like a task board objective/context field
  — never executed or obeyed by the framework.

6. Implementation surface

• src/board/store.js — new topicDir, publishTopic, listTopicUpdates
  (pure-ish fs shell, same style as the existing tasks/ functions; reuses
  slug() and atomicWriteFile).
• src/a2a/peer-bridge.js — two new bridge verbs
  (publish_board_topic/list_topic_updates) in createBridge()'s returned
  object, plus their tools/call dispatch cases and buildTools() entries,
  following the exact shape of createTaskForPeer/listMyTasks.
• Manifest schema — additive x-agentmesh.subscribedTopics: string[] field
  (no enforcement code path in v1; purely a documented/advisory convention,
  possibly validated for shape only by doctor's existing manifest checks).
• No changes to src/board/task-state.js (task lifecycle is untouched —
  topics are not tasks and have no state machine), src/context.js, or
  src/path-guard.js.

7. Testing (hermetic, npm test)

• board-store.test.js (extend existing task-board store tests):
  • publishTopic assigns sequential zero-padded ids scoped per-topic
    (publishing to two different topics does not share a counter).
  • listTopicUpdates returns [] for an unknown topic (never throws).
  • listTopicUpdates(meshRoot, topic, sinceId) correctly excludes records at
    or before sinceId and returns the rest in ascending order.
  • Concurrent publishTopic calls to the same topic never collide (same
    atomic-write + scan-and-increment guarantee nextTaskId already has,
    exercised the same way the existing task-id tests do).
• peer-bridge.test.js (extend existing bridge tests):
  • publish_board_topic framework-stamps from/id/at regardless of
    what the caller passes for those keys (anti-spoof — args ignored/absent
    from the tool's input schema entirely).
  • publish_board_topic with empty topic/brief, or brief over
    MAX_TASK_CHARS, returns the expected bad_input refusal.
  • list_topic_updates on a mesh root with no topics/ directory yet
    returns { ok: true, records: [] }, not an error.
  • No-mesh-root / unresolvable-caller-identity refusals mirror the existing
    boardContext() gate tests for createTaskForPeer.

8. Risks & mitigations

• Discovery-convention drift — since subscribedTopics isn't enforced,
  nothing stops a peer from polling a topic it never declared, or from
  forgetting to declare one it actually needs. Mitigation: this matches v1's
  intentionally advisory scope (§4.3); a future spec could add a doctor
  lint that warns when a peer's prompt references a topic name absent from
  its own manifest.
• Unbounded topic growth (no retention/GC, §2). Mitigation: deferred by
  design, consistent with how the task board itself shipped without
  retention initially; a follow-on can add a pruning sweep once real usage
  data exists.
• Topic name collisions across unrelated features (two peers independently
  inventing the same topic string for different meanings). Mitigation: topic
  names are plain strings under a human-curated manifest, same collision risk
  class as peer names in the registry today — no new namespace-collision
  surface beyond what already exists.

9. Open decisions

1. Whether list_topic_updates should also expose a list_topics() verb
   enumerating known topic directories (useful for a dashboard topics view)
   — proposed: defer to a follow-on once the dashboard wants to render it.
2. Whether doctor should validate subscribedTopics entries against a
   known-topics registry, or leave topic names entirely free-form (proposed:
   free-form in v1, matching how task board title/objective text is
   free-form today).
3. Sequence-id scheme: per-topic zero-padded counter (mirroring
   nextTaskId's per-from-to-pair counter) vs. an ISO-timestamp-based id.
   Proposed: the counter, for consistency with the existing task-id scheme
   and simpler since_id ordering semantics (numeric, not string, compare).

[github-actions]

Spec ready — attempt 2 of 3 (push blocked, HTTP 403 — same as #771)

Re-authored the spec (content unchanged from attempt 1 — no design changes)
at docs/superpowers/specs/2026-07-26-idea-board-topic-subscription-primitive-design.md
on branch spec/issue-847, commit c59f15b.

git push origin spec/issue-847 → HTTP 403 (Permission to danabaxia/agent_mesh.git denied to github-actions[bot]) — reconfirmed this run via gh api repos/danabaxia/agent_mesh --jq '.permissions.push' → false. Same known root cause tracked centrally at #771 (DEV_MESH_PAT secret still not configured with contents:write), which remains open and unresolved as of this run (2026-07-27).

Labels already correctly reflect this (spec:draft + blocked + needs-human). Local spec/issue-847 branch deleted after the failed push (nothing lost — it never reached origin). One attempt remains before this issue's own circuit breaker trips.

To publish manually: create branch spec/issue-847, save the content from the attempt-1 comment above (unchanged) as docs/superpowers/specs/2026-07-26-idea-board-topic-subscription-primitive-design.md, commit, push, gh pr create --title "spec(#847): board topic/subscription primitive" --base main --head spec/issue-847. Then set label spec:in-review, remove spec:draft + blocked + needs-human.

[github-actions]

Spec ready — attempt 3 of 3 (push blocked, HTTP 403 — same as #771)

Re-authored the spec (content unchanged from attempts 1–2 — no design changes)
at docs/superpowers/specs/2026-07-29-idea-board-topic-subscription-primitive-design.md
on branch spec/issue-847, commit 8b6dc72.

git push -u origin spec/issue-847 failed:

remote: Permission to danabaxia/agent_mesh.git denied to github-actions[bot].
fatal: unable to access 'https://github.com/danabaxia/agent_mesh.git/': The requested URL returned error: 403

Reconfirmed this run: gh api repos/danabaxia/agent_mesh --jq '.permissions' → push: false; active identity still github-actions[bot] (integration/15368 GitHub App install), not DEV_MESH_PAT. Same root cause tracked centrally at #771 (still open, unresolved as of 2026-07-29).

Labels already correctly reflect this (spec:draft + blocked + needs-human). Local spec/issue-847 branch deleted after the failed push (nothing lost — it never reached origin; full spec content is reproduced in the attempt-1 comment above). This is the 3rd consecutive failed attempt — per the circuit-breaker protocol, the next sweep trips the breaker rather than re-authoring again.

[github-actions]

CIRCUIT BREAKER: spec-push has failed 3+ consecutive times. DEV_MESH_PAT may lack write access or the spec directory is conflicted. Human intervention required. See .github/actions/mesh-retry-backoff for 529.