Platform Capability Adoption¶
This playbook turns untool.ai platform capability announcements into work that coding-agent teams can actually pick up, implement, verify, and close.
The rule is simple: a capability announcement is not adopted until the relevant coding-agent team has a linked issue or PR proving the capability is used correctly in its owning repo.
Adoption Loop¶
flowchart LR
LOG["Capability log entry"] --> TRIAGE["Adoption triage"]
TRIAGE --> ISSUE["Capability adoption issue"]
ISSUE --> TEAM["Agent team implements usage"]
TEAM --> VERIFY["Validation evidence"]
VERIFY --> CLOSE["Issue or PR closes adoption"]
CLOSE --> FEEDBACK["Feedback to capability log"]
FEEDBACK --> LOG
When A Capability Is Announced¶
- Read the entry in
platform-capability-log.mdorplatform-capability-log.feed.json. The future live source is the Fuseki-backed system ontology projected to theplatform.capability.changed.v1NATS subject; seeplatform-capability-events.mdandplatform-capability-messaging.md. - Confirm the
statusis adoptable: availableandchangedentries can normally be adopted.plannedentries should become spikes or design issues.degradedandretiredentries should trigger migration or mitigation issues.- Identify the affected audiences and repos.
- Open one adoption issue per owning repo when real work is needed.
- Route the issue using the normal labels:
copilot-taskfor bounded, isolated, XS/S work.agent-army-taskfor multi-file, architecture, data, security, or unclear work.- Link the issue back to the capability log entry and the source artifacts.
- Close the issue only after validation evidence proves the capability is used.
Current View For Agent Threads¶
Point new coding-agent threads at this current-view packet before they start platform adoption work:
Current platform capability view:
- System capability model: docs/system-capability-model.md
- Bootstrap order: docs/untool-bootstrap-order.md
- Agent lexicon: ontology/platform-self-model/generated/lexicon.yaml
- Bootstrap order CLI: npm run -s bootstrap:order -- --json
- Bootstrap order MCP tool: platform_bootstrap_order
- Human log: docs/platform-capability-log.md
- Machine feed: docs/platform-capability-log.feed.json
- Status snapshot: docs/platform-capability-adoption.status.json
- Adoption board: docs/platform-capability-adoption-board.md
- Agent launch packets: docs/platform-capability-agent-launch-packets.json
- Dispatch state: docs/platform-capability-dispatch.json
- Repo launch bundles: docs/platform-capability-launch-bundles/index.json
- Agent work orders: docs/platform-capability-agent-workorders.json
- Agent work order prompts: docs/platform-capability-agent-workorders.md
- Adoption watchdog: docs/platform-capability-adoption-watchdog.json
- Adoption watchdog report: docs/platform-capability-adoption-watchdog.md
- Capability current view: docs/platform-capability-current-view.json
- Capability current view report: docs/platform-capability-current-view.md
- MCP tool: platform_capabilities_list
- Adoption audit tool: platform_capability_adoption_audit
- Status snapshot MCP tool: platform_capability_status
- MCP handoff tool: platform_capability_handoff
- Dispatch MCP tool: platform_capability_dispatch
- Repo bundle MCP tool: platform_capability_repo_bundle
- Work order MCP tool: platform_capability_workorders
- Current-view MCP tool: platform_capability_current_view
- Feed guard: npm run check:capability-feed
- Status guard: npm run check:capability-status
- Board guard: npm run check:capability-board
- Launch packet guard: npm run check:capability-packets
- Dispatch guard: npm run check:capability-dispatch
- Repo launch bundle guard: npm run check:capability-bundles
- Work order guard: npm run check:capability-workorders
- Watchdog guard: npm run check:capability-watchdog
- Current-view guard: npm run check:capability-current-view
- Template guard: npm run check:capability-template
- Bootstrap pickup audit: npm run audit:capability-adoption-bootstrap
- Launch packet pickup audit: npm run audit:capability-adoption-launch
- Work order pickup audit: npm run audit:capability-adoption-workorders
- Current-view pickup audit: npm run audit:capability-adoption-current-view
- Closure evidence audit: npm run audit:capability-adoption-closure
- Adoption readiness audit: npm run audit:capability-adoption-readiness
- Status refresh: npm run status:capabilities
- Board refresh: npm run board:capabilities
- Launch packet refresh: npm run packets:capabilities
- Dispatch refresh: npm run dispatch:capabilities
- Repo launch bundle refresh: npm run bundles:capabilities
- Work order refresh: npm run workorders:capabilities
- Watchdog refresh: npm run watchdog:capability-adoption
- Current-view refresh: npm run current-view:capabilities
- Repo handoff: npm run handoff:capabilities -- <repo-name>
- NATS subject: platform.capability.changed.v1
- Source of truth target: Fuseki graph https://agentarmy.dev/graphs/platform/capabilities
Agent behavior:
1. Read `docs/system-capability-model.md`.
2. Read or call the current capability view.
3. Filter entries by capabilityId, status, audience, and owning repo.
4. Pick up the linked repo adoption issue when adoption is open.
5. Check linked PRs in the status snapshot before starting duplicate work.
6. Preserve the MECE message family boundary named by the feed.
7. Attach validation evidence before closing the issue or PR.
Use the JSON feed or MCP tool for automation. Use the Markdown log when a human needs the announcement narrative. Treat NATS and webhook subscriptions as projection lanes; GitHub issues remain the durable work-evidence lane until HVFS-native evidence is live.
Use platform-capability-adoption.status.json
when a fresh agent thread needs the latest checked-in capability/adoption state without
making live GitHub calls. The snapshot includes per-track issue state, bootstrap pickup,
closure pickup, work-order pickup, and exact linked closing PR references from GitHub. Refresh it from live
issue state with:
npm run status:capabilities
Use platform-capability-adoption-board.md when a
human or coding-agent coordinator needs the current per-repo work queue in one page. The
board is generated from the status snapshot and includes the capability ID, bootstrap module,
issue state, linked PRs, pickup comments, agent lenses, CLI handoff command, and MCP handoff
call for each repo track. Refresh and guard it with:
npm run board:capabilities
npm run check:capability-board
Use platform-capability-agent-launch-packets.json
when an orchestration layer needs launch-ready owner/reviewer packets for coding agents. The
packet file is generated from the status snapshot, includes the Standard Subagent Handoff
fields, and verifies every advertised agentLenses name resolves to a synced Codex agent
definition under .codex/agents/. Refresh and guard it with:
npm run packets:capabilities
npm run check:capability-packets
Use platform-capability-dispatch.json when a coordinator
needs to separate enablement from implementation state. Dispatch state classifies each adoption
track as ready_to_launch, in_flight_pr_linked, adopted_verified,
adopted_pending_closure_evidence_audit, or blocked_missing_enablement, with the next action,
owner agent, reviewer agents, linked PRs, and handoff commands. When MCP is available, read the same state with
platform_capability_dispatch. Refresh and guard the checked-in file with:
npm run dispatch:capabilities
npm run check:capability-dispatch
Use platform-capability-launch-bundles/index.json
and the per-repo Markdown files under docs/platform-capability-launch-bundles/ when a
coordinator wants to hand one repo-specific launch packet to a fresh coding-agent thread. Each
bundle includes only that repo's tracks, owner/reviewer agents, issue links, CLI/MCP handoffs,
and Standard Subagent Handoff blocks. When MCP is available, request the same bundle with
platform_capability_repo_bundle({ "repo": "<repo-name>" }). Refresh and guard them with:
npm run bundles:capabilities
npm run check:capability-bundles
Use platform-capability-agent-workorders.json
or platform-capability-agent-workorders.md when a
coordinator is ready to start actual coding-agent threads. Work orders exclude
adopted_verified and blocked_missing_enablement tracks, and each work order contains a
copy/pasteable thread prompt with repo, capability ID, issue link, owner/reviewer lenses,
message families, bootstrap reading order, and closure-evidence requirements. When MCP is
available, request the same prompts with
platform_capability_workorders({ "dispatch_state": "ready_to_launch", "prompt_only": true }).
Refresh and guard them with:
npm run workorders:capabilities
npm run check:capability-workorders
Use platform-capability-adoption-watchdog.json
or platform-capability-adoption-watchdog.md when
a coordinator needs to see which enabled tracks still have no linked implementation PR. The
watchdog is generated from dispatch plus work orders, and lists the next launch queue with
repo, capability ID, issue URL, owner/reviewer lenses, MCP work-order call, and escalation
reason. Refresh and guard it with:
npm run watchdog:capability-adoption
npm run check:capability-watchdog
Use platform-capability-current-view.json or
platform-capability-current-view.md as the single
front-door packet for new coding-agent teams. It combines the naming rule, source files,
MCP endpoints, NATS/Fuseki pointers, refresh commands, guards, per-track dispatch state,
linked PRs, and work-order calls. When MCP is available, request the same packet with
platform_capability_current_view({}). Refresh and guard it with:
npm run current-view:capabilities
npm run check:capability-current-view
For a repo-filtered pickup packet, run:
npm run handoff:capabilities -- backend-core
When MCP is available, prefer:
platform_capability_handoff({ "repo": "backend-core" })
By default, both the MCP handoff and CLI handoff include live GitHub issue state
for the returned adoption tracks, so agents can distinguish work that is still
open from work that has already closed with evidence. Use --no-issue-state
with the CLI when a caller needs feed-only output without live GitHub lookup.
Use node tools/platform-capability-handoff.mjs --repo <repo> --capability <capabilityId>
to narrow the packet with explicit flags, and add --json when another tool will consume
the result.
Agent Team Handoff¶
Every capability adoption issue should tell the coding agent team:
| Field | What to include |
|---|---|
| Capability ID | The capabilityId from the feed. |
| Announcement | Link to the human log entry. |
| Owning repo | The repo where adoption work happens. |
| Target object/API/surface | The concrete code or docs path expected to use the capability. |
| Source artifacts | Contracts, schemas, ADRs, generated fixtures, or docs. |
| Required agent lenses | Specialist agents that should own or review the work. |
| Acceptance criteria | Observable behavior that proves adoption. |
| Validation | Commands, tests, screenshots, contract checks, or evidence files. |
| Feedback path | Where blockers, missing docs, or contract gaps get reported. |
The Capability adoption issue template should include the current-view packet:
bootstrap order, generated lexicon, status snapshot, status refresh command,
status guard, repo handoff command, and MCP equivalents. If an adoption issue is
missing those references, update the issue before assigning it to a coding-agent
team.
Check the template with:
npm run check:capability-template
Routing Patterns¶
| Adoption type | Default route |
|---|---|
| Docs-only usage update | technical-writer owner, documentation-engineer reviewer |
| Simple consumer wiring | copilot-task if isolated and acceptance criteria are explicit |
| Backend/object/API adoption | backend-developer + api-designer + contract-test-engineer |
| Data connector/source adoption | data-engineer + relevant database specialist |
| Frontend surface adoption | frontend-developer + ui-designer |
| Security, identity, secrets, or user data | security-auditor mandatory reviewer |
| Multi-repo rollout | agent-organizer + scrum-master + one owner per repo |
Done Criteria¶
A capability is adopted by a coding-agent team only when:
- A linked issue or PR names the capability ID.
- The owning repo uses the capability through the documented object/API/surface.
- Validation evidence is attached or linked.
- The closing issue or PR comment names
Validation evidence, the capability ID, evidence links or command output, and the adopted target/interface. - Any changed docs/contracts are updated.
- Feedback has been filed for missing capability docs, broken contracts, or adoption blockers.
- The capability feed is updated if adoption changes the status, audiences, or source artifacts.
Adoption Audit¶
Run the hub audit whenever capability adoption issues are created, closed, or linked:
node tools/capability-adoption-audit.mjs
Validate the capability feed's semantic guardrails whenever a feed entry, message family, or adoption track changes:
node tools/platform-capability-feed-check.mjs
The audit reads platform-capability-log.feed.json,
checks each capability tracking issue and adoption-track issue through the GitHub CLI, and
reports whether adoption is still open or fully closed.
Use JSON output when another tool needs to consume the result:
node tools/capability-adoption-audit.mjs --json
After posting bootstrap instructions to adoption issues, verify that every repo adoption track has the shared naming/order pickup packet:
npm run audit:capability-adoption-bootstrap
That guard checks each adoption-track issue for links to the bootstrap order, generated lexicon, machine-readable bootstrap CLI, MCP bootstrap tool, repo handoff CLI, and MCP handoff tool.
After posting launch-packet instructions to adoption issues, verify that every repo adoption track has the launch-ready owner/reviewer packet reference:
npm run audit:capability-adoption-launch
That guard checks each adoption-track issue for the launch packet file, repo and capability ID, packet generator, packet guard, repo handoff CLI, MCP handoff tool, synced Codex agent definition path, and Standard Subagent Handoff language.
After posting work-order instructions to adoption issues, verify that every repo adoption track has the copy/pasteable thread-prompt pickup packet:
npm run audit:capability-adoption-workorders
That guard checks each adoption-track issue for the work-order JSON and Markdown files,
work-order generator, work-order guard, platform_capability_workorders, repo/capability
filters, copy/pasteable thread-prompt language, and closure evidence reminder.
After posting the corrected safe self-building current-view packet to adoption issues, verify that every repo adoption track has the current-view pickup packet:
npm run audit:capability-adoption-current-view
That guard checks each adoption-track issue for the current-view JSON and Markdown files,
platform_capability_current_view, the safe bootstrap phrase
trust -> guardrailed LLM feed -> bootstrap ontology -> Fuseki truth, and the four first
bootstrap modules: Identity and Secret Kernel, Guardrailed LLM Feed, Bootstrap Ontology
Packet, and Fuseki Truth Store.
Before treating closed adoption tracks as real adoption, verify closure evidence:
npm run audit:capability-adoption-closure
That guard checks closed adoption-track issues for the capability ID, validation/evidence language, proof artifacts or commands, and a reference to the adoption target. Open tracks are not considered adopted.
After posting bootstrap, closure, launch, and work-order instructions to adoption issues, verify that every repo adoption track has all pickup packets and that any closed tracks have closure evidence:
npm run audit:capability-adoption-readiness
Refresh the checked-in status snapshot after materially changing capability/adoption issues:
npm run status:capabilities
npm run check:capability-status
The status guard compares the checked-in snapshot to the capability feed, including capability IDs, repo adoption tracks, issue URLs, agent lenses, bootstrap pickup presence, closure pickup presence, work-order pickup presence, linked PR arrays, summary counts, current-view pointers, NATS subject, and Fuseki source-of-truth graph.
The audit returning success means all linked issue URLs are reachable. A capability is fully adopted only when the audit shows every adoption issue for that capability is closed and the closing issues or PRs contain validation evidence.
First Adoption Candidate: UDA DataObject Runtime Receivers¶
Capability ID: uda.dataobject.runtime.receivers
Adoption rollup: #414
Recommended adoption tracks:
| Repo/team | Adoption target | Route |
|---|---|---|
backend-core |
Keep DataObjects talking to UDA sources through the standard receiver path. | #167 |
agentarmy-forge |
Generate receiver-ready fixture families and publish compatibility evidence. | #109 |
frontend-core |
Consume typed DataObjects instead of source-specific backend seams. | #130 |
| Hub docs | Keep log/feed/playbook current as capability shape changes. | technical-writer, documentation-engineer |
Minimum evidence:
- Contract or schema checks pass for the relevant UDA artifact.
- Receiver compatibility tests pass in the adopting repo.
- The adoption issue links back to #407 and #414.
Foundation Adoption Candidate: HVFS Source-Control Foundation¶
Capability ID: hvfs.source-control.foundation
Adoption rollup: #416
HVFS is the source-control substrate for the future untool.ai GitHub replacement. During the transition, GitHub Issues and PRs still carry durable work evidence, but repository state starts moving toward HVFS: virtual checkouts, branches, commits, merges, diffs, file reads and writes, and content-addressed blobs.
Recommended adoption tracks:
| Repo/team | Adoption target | Route |
|---|---|---|
backend-core |
Implement the lakeFS/HVFS UDA provider and CAS seam. | #169 |
commons-core |
Define the agent-facing virtual filesystem client contract. | #14 |
| Hub docs/feed | Keep platform.hvfs.*, capability feed, and adoption state discoverable. |
#416 |
Minimum evidence:
- HVFS contracts or docs distinguish provider responsibilities from agent-facing client responsibilities.
- backend-core validates branch, commit, merge, diff, and CAS semantics through the UDA seam.
- commons-core validates the VFS client shape without local clone assumptions.
- Platform messaging exposes HVFS events under
platform.hvfs.*, not under generic fleet or capability subjects.
Messaging Adoption Candidate: Platform Messaging Update System¶
Capability ID: platform.messaging.update-system
Adoption rollup: #417
The first-tier platform-building teams should be able to receive platform updates through NATS-native consumers, webhook projections, or MCP discovery while preserving MECE subject boundaries.
Minimum evidence:
- Subscription contracts validate against
contracts/platform-update-subscription.schema.json. - First-tier teams can identify their subject families and delivery lane.
- Webhook delivery is documented as a NATS projection, not an independent source of truth.
Recommended adoption tracks:
| Repo/team | Adoption target | Route |
|---|---|---|
AgentArmy |
Implement the NATS-to-webhook projector bridge for platform update subscriptions. | #418 |
backend-core |
Project Fuseki-backed capability facts onto NATS system messages. | #168 |
commons-core |
Represent and validate the shared subscription contract. | #15 |
agentarmy-forge |
Discover capability/adoption obligations through MCP, NATS, or webhook subscriptions. | #111 |
middle-core |
Implement or host the NATS-to-webhook projection bridge. | #132 |
frontend-core |
Surface platform updates in Fleet Console/frontend views. | #131 |