docs(decisions): ADR-018 propose central agent asset registry (#246)

[Kalindi-Dev]

Status

Draft — pending approved label on #246 per ADR-003. Opening as a concrete artifact for maintainer review while approval is being decided; not requesting merge until governance approval lands on the parent issue.

Summary

Proposes ADR-018, which fixes the contract for a central agent asset registry closing #246:

• URI grammar — registry://<kind>/<namespace>/<name>@<constraint> (already declared at agent/src/workflow/validator.py:50).
• MVP asset kinds — mcp_server, cedar_policy_module, skill. Others declared but not loaded.
• Semver — exact / ^ / ~ only. Rejects *, latest, >=.
• Immutability — (kind, namespace, name, version) immutable once published; republish returns 409.
• Lifecycle — draft → submitted → approved | rejected → deprecated → removed.
• Resolve at create-task boundary — same location workflow_ref resolves today; resolved_assets stamped on the task record.
• Fail-closed — unresolvable refs fail admission with a specific reason.
• Descriptor validation at publish — typed descriptor per kind (tool surface, egress domains, Cedar actions, min compute profile, permissions).
• Resolver interface as the seam — CDK/TS orchestrator and Python agent talk to a RegistryClient abstraction; substrate changes and any AgentCore Aug 6 2026 rename are confined to one implementation file per language.
• MVP E2E path is one asset kind: MCP server (per issue AC4).
• Governance workflow ships in MVP — publisher/approver roles, audit trail on every state transition, event-driven review integration.
• Workflows do not migrate to the registry in this ADR — ADR-014 workflows stay filesystem-backed.
• Clean split from docs(governance): refine ADR-012 to many-to-many ADR↔Persona↔Skill graph with bidirectional backlinks + parity linter #381 — registry stores skill runtime artifacts; docs(governance): refine ADR-012 to many-to-many ADR↔Persona↔Skill graph with bidirectional backlinks + parity linter #381's ADR↔Persona↔Skill documentation graph stays in docs/ + plugin markdown.

Substrate

The ADR does not pick the substrate. It ranks candidates by fit for ABCA and defers the pick to the design PR:

1. Preferred: AWS Agent Registry (Bedrock AgentCore).
2. Fallback: DynamoDB + S3.
3. Considered: mcp-gateway-registry (AWS OSS Blog June 2026), agentregistry.ai (Solo.io), Microsoft Entra Agent Registry + AGT.
4. Also considered, briefly: Google Cloud Agent Registry, Smithery, Glama, PulseMCP, ACI.dev, Composio, Toolhouse, Docker MCP Catalog, Jozu Hub, Stacklok/ToolHive — each with a one-line disqualifier.

Design PR decision framework names four concrete conditions under which the design PR flips from preferred to fallback (region GA, immutability guards, semver-on-top complexity, Aug 2026 rename cost).

Addressing #381 (per @scottschreckengaust's comment on #246)

Sub-decision 13 splits the two concerns cleanly:

• This registry stores skill runtime artifacts (prompt+tools bundles the agent loads at task start).
• docs(governance): refine ADR-012 to many-to-many ADR↔Persona↔Skill graph with bidirectional backlinks + parity linter #381 owns the ADR↔Persona↔Skill documentation graph in docs/ and plugin markdown with frontmatter edges + parity linter.

If a skill record's descriptor eventually cites an ADR, that's metadata on the record — not a graph edge #381 owns. Happy to iterate on the boundary if you see it differently.

Test plan

• ADR file present at docs/decisions/ADR-018-agent-asset-registry.md
• Starlight mirror regenerated at docs/src/content/docs/decisions/Adr-018-agent-asset-registry.md
• Sub-decisions referenced by number are internally consistent (1–13, no gaps)
• References section links resolve (spot-checked in commit)
• Maintainer review + approved label on feat(registry): central agent asset registry for capabilities, skills, plugins, and MCP servers #246
• After approval, undraft and merge as proposed status

Related

Progresses #246. See also #381 (documentation graph — split resolved in sub-decision 13), ADR-014 (workflow-driven tasks — resolver-interface precedent), and the ADR-003 contribution governance model.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@98736c1). Learn more about missing BASE report.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #548   +/-   ##
=======================================
  Coverage        ?   88.88%           
=======================================
  Files           ?      222           
  Lines           ?    52547           
  Branches        ?     4684           
=======================================
  Hits            ?    46705           
  Misses          ?     5842           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[scottschreckengaust]

How will the lookup "Registry of registries" be maintained?

For example:

• python: PyPi
• node: npm.js
• container: Docker Hub / ecr / ghr / gcr
• mcp: many - one example is the MCP registry https://registry.modelcontextprotocol.io/ from https://github.com/modelcontextprotocol/registry

Is there an abstraction from the Cloud Computing Native Foundation (CCNF) that can be utilized versus rolling a bespoke system?

[scottschreckengaust]

First off — this is genuinely one of the most thorough, well-reasoned ADRs I've read in this repo, and it was a pleasure to review. 🙌 You did the hard things right: it's template-compliant, it's honest about its own risks (the (!) section is excellent), and it correctly reaches for the repo's twice-learned parity lesson instead of re-discovering it. The contracts/registry-resolution/ proposal mirroring contracts/cedar-parity/ and contracts/workflow-validation/ is exactly the instinct we want to see — I verified both of those directories exist and this slots right in beside them. The four substrate flip-conditions turn "preferred with a fallback" into something falsifiable rather than hand-wavy, and resolving at the create-task boundary keeps you consistent with ADR-014's shipped workflow_ref model. Really strong work, and the effort clearly shows.

Everything below is in service of making an already-good document airtight before it graduates from proposed to accepted — I'm leaving this as a comment, not a change request, since it's a draft awaiting the approved label on #246. Please read the tone as "help me help this land," not "stop." 💛

Two things I'd fix before acceptance (both quick)

1. The "grammar already committed" claim doesn't hold against the shipped regex (inline on the sub-decision). I ran the ADR's own example refs against _REGISTRY_REF at validator.py:50, and the committed regex has no @ in its character class (so @<constraint> can't be parsed) and only allows hyphens in the kind segment (so mcp_server / cedar_policy_module / prompt_fragment don't match — only mcp-server does). This is totally fixable and doesn't weaken the design — it just means the framing "closing the loop rather than opening it" slightly overstates what's shipped. A one-line reframe ("this ADR extends the committed shape") plus a note on where the regex change lands fully resolves it. Details inline.

2. Small off-by-one in the References section (inline). It credits "sub-decision 12" for the #381 split, but 12 is the workflows-don't-migrate decision — the #381 split is 13 (your PR body has it right!). Tiny, but the test-plan box "sub-decisions referenced by number are internally consistent (1–13, no gaps)" is checked, so worth tidying so that claim stays true. Appears in both the source file and the generated mirror, so the fix lands in docs/decisions/ and re-syncs.

A few design-level thoughts (take or leave — you're the author)

These aren't blockers, just things I'd love your read on:

• Altitude. The doc is part ADR, part design spec, part market survey — and it's great diligence — but the ~15-vendor enumeration and the pinned implementation details (error-code strings, Cognito group names) are the most perishable content in an artifact whose whole job is to be durable. Totally your call, but you might keep the invariants + preferred/fallback ranking + flip-conditions here, and let the vendor deep-dive live in the design PR or a dated appendix. The decision survives; the survey ages.
• Governance-in-MVP sizing (inline). Sub-decision 10 is a strong principle ("governance is what separates a registry from a directory" — love it), but a full lifecycle + audit + event integration + auto-approve, on top of a two-language semver resolver and descriptor validation, is a big MVP for a reference project whose AC4 goal is one E2E kind. Might be worth an explicit sentence acknowledging governance may need staging if the estimate tightens.
• AgentCore timing. The ADR is dated 2026-07-08 and the preferred substrate hard-migrates namespaces on 2026-08-06 — likely mid-build. You flag it as a risk and lean on the RegistryClient seam, which is right for code, but the seam doesn't confine data migration / IAM action renames as cleanly as the prose implies. Maybe promote "don't take a production dependency until post-cutover GA" from a risk bullet into the decision framework.
• One status, two names (inline). approved "(also called active)" then both get used interchangeably — in a byte-for-byte two-language contract that's a latent divergence, and it's exactly the parity hazard your own (−) bullet warns about. Pick one canonical token.

Nits

• Two reference URLs look off by host convention (didn't fetch): www.docs.microsoft.com/... (usually learn.microsoft.com) and docs.cloud.google.com/... (usually cloud.google.com/...). Worth a spot-check since the test plan mentions link verification.
• Reserving a capability kind for workflows while sub-decision 12 says workflows won't migrate reads slightly oddly — fine as "declared but not loaded," just a one-clause note would smooth it.

Thank you for the care you put into this — the bones are excellent and none of the above is hard to address. Happy to pair on the grammar reconciliation (#1) if useful, since that's the one place code and contract need to meet. Excited to see this one land. 🚀

[scottschreckengaust]

Small but load-bearing accuracy fix 🙂 — this says the URI regex "matches the shape already committed at validator.py:50," but I tested the ADR's own example refs against the actual committed regex:

committed: ^registry://[a-z][a-z0-9-]*/[a-z0-9][a-z0-9./-]*$

MATCH   registry://mcp-server/acme/pdf-tools
NO      registry://mcp_server/acme/pdf-tools@^1.4.1   ← this ADR's grammar
NO      registry://mcp_server/acme/pdf-tools          ← underscore kind
NO      registry://skill/acme/refactor@~2.0.0

Two gaps:

1. No @<constraint> support — there's no @ in the character class, so the semver constraints from sub-decision 2 have nowhere to live in the shipped grammar.
2. No underscores in the kind segment — it's [a-z][a-z0-9-]* (hyphen only), but every MVP kind here is snake_case (mcp_server, cedar_policy_module, prompt_fragment). Only a hyphenated mcp-server matches today.

None of this hurts the design — it just means _REGISTRY_REF has to be extended to carry this contract. Suggested tweak: reframe as "extends the committed shape (adding @constraint and reconciling kind naming)" and note whether that regex change rides in this ADR's companion or the design PR. Same reasoning applies to the "the code already parses and validates registry:// refs" line down in Consequences. Happy to pair on this bit! 💪

[scottschreckengaust]

Tiny off-by-one: this credits sub-decision 12 for the #381 split, but 12 is "Workflows do not migrate to the registry" — the clean #381 split is sub-decision 13 (and your PR description has it right ✅). Worth fixing because the test-plan checkbox "sub-decisions referenced by number are internally consistent (1–13, no gaps)" is ticked, so this keeps that honest. It's in the generated mirror too, so the fix lands in this source file and re-syncs via mise //docs:sync.

[scottschreckengaust]

Really like the principle here — "governance is what separates a registry from a directory" is the right north star, and putting it up front is a good instinct. My only nudge: this is a lot of MVP (full lifecycle + audit trail + event-driven review integration + auto-approve mode) layered on top of a two-language semver resolver, descriptor validation, and a parity corpus — for a reference project whose stated E2E goal (AC4) is a single asset kind. Not asking you to cut it — just maybe one explicit sentence that governance can be staged if the estimate tightens, so a future implementer has permission to sequence it rather than treating all of (a)–(d) as an atomic MVP gate. Your call entirely. 🙏

[scottschreckengaust]

One canonical-name nudge: approved "(also called active)" introduces two tokens for one state, and sub-decisions 10 and 11 then use both interchangeably (e.g. "in submitted state (or active…)"). Since the resolver contract has to agree byte-for-byte across the TypeScript orchestrator and the Python agent — the exact parity hazard your own (−) bullet flags so well — I'd pick one canonical status string and mention the other only as "(formerly/aka)" prose. Cheap insurance against a sneaky divergence bug. 🙂