Skip to content

Platform Capability Messaging

Capability adoption uses two messaging lanes that serve different speeds.

Two Lanes

Lane System Purpose Source of truth
Durable repo messaging GitHub Issues, PRs, comments Auditable work ownership, acceptance criteria, validation evidence, closure. GitHub issue/PR state.
High-speed orchestration untool.ai MCP tools + NATS system messages Fast discovery, routing, subscription, agent handoff, and live adoption status. System ontology in Fuseki, projected through NATS and MCP.
Webhook projection HTTPS delivery from NATS JetStream to subscribers that cannot hold a NATS consumer. The NATS CloudEvent plus the subscription contract.

GitHub remains the durable record because every coding-agent team can see it inside its repo sandbox. untool.ai provides the fast control surface because agents should not have to scrape docs and issue pages to know which platform capabilities exist or what they should do next. Webhook subscriptions are projections from NATS, not a competing source of truth; see Platform Messaging Update System.

GitHub Repo Messaging

Use GitHub when the message is part of the record:

  • capability adoption issues;
  • PRs that close adoption work;
  • acceptance criteria and validation evidence;
  • blockers that need human or cross-repo follow-up;
  • durable comments linking spoke work back to hub rollups.

For capability adoption, every repo-owned issue should name the capabilityId and link the hub rollup. The hub rollup remains the cross-repo audit point.

untool.ai Orchestration

Use untool.ai when the message is operational:

  • "what capabilities are available right now?";
  • "which adoption tracks are still open?";
  • "which NATS subject should I subscribe to?";
  • "which specialist agent lenses should review this?";
  • "which repo issue should I pick up next?";

The capability source-of-truth path is:

system ontology -> Fuseki graph -> NATS system message -> MCP tool surface -> coding agents

The current capability subject is platform.capability.changed.v1. Its payload is governed by contracts/platform-capability-event.schema.json.

The broader MECE subject families are:

Family Boundary
platform.capability.* Capability lifecycle facts.
platform.adoption.* Repo/team adoption state and validation evidence pointers.
platform.hvfs.* Source-control substrate workspace, branch, commit, merge, diff, and file events.
fleet.agent.* Agent handoff, heartbeat, claim, control, and coordination.
platform.security.* Security evidence, waivers, incidents, and control state.

MCP Tools

The local-fleet MCP server exposes the first read-only tools for coding-agent adoption:

Tool Purpose
platform_capabilities_list List platform capabilities, ontology pointers, NATS subscription metadata, and adoption tracks.
platform_capability_adoption_audit Check live GitHub issue state for the adoption issues named by the capability feed.

These tools are read-only and safe for coding agents to call frequently. Mutating orchestration tools can be added later, but should be gated by capability grants, HITL policy, audit logging, and per-tool approval.

Agent Behavior

When a coding agent starts work:

  1. Call platform_capabilities_list.
  2. Filter to capabilities relevant to the repo or task.
  3. Call platform_capability_adoption_audit for the capability.
  4. Pick up the repo-owned GitHub issue if adoption is open.
  5. Use the issue/PR for durable evidence.
  6. Use NATS/MCP for fast status and handoff messages.

When a capability changes:

  1. The system ontology fact changes.
  2. Fuseki stores the updated fact.
  3. The projector emits platform.capability.changed.v1.
  4. Subscribed agents or Fleet Console refresh their local view.
  5. GitHub issues remain the durable closure and evidence surface.