Skip to content

Capability Catalog

Capability register — instantiates Layer-Appropriate Capability Placement

A discoverable directory of what the host and shared layers already provide, who owns each capability, and how to consume it — so teams delegate to an existing facility instead of rebuilding it because they couldn't find it.

A Capability Catalog is the published, searchable directory of capabilities the host and shared layers already offer — each entry naming what it does, who owns it, what contract and service level it carries, and the sanctioned route to consume or extend it. Its distinctive premise is that a great deal of shadow-platform building is not defiance but ignorance: a team reconstructs auth, or queuing, or secrets storage locally because they never discovered the host already provides it. The catalog attacks that specific cause. It is not a decision tool and not an enforcement gate — it is the map of supply that makes "use the host" a discoverable default rather than a thing you'd have to already know existed.

Example

A company's internal developer platform provides managed secrets, a message queue, and single-sign-on — but three product teams have each quietly built their own secrets store, because finding the platform's version meant knowing which staff engineer to ask. The platform team stands up a Capability Catalog (say, on a service-catalog tool like the open-source Backstage). Each capability gets an entry: Managed Secrets — owner: Platform Security — contract: read/write via SDK, rotation every 90 days — SLA: 99.9% — extend via: request a new scope. Now when a fourth team starts a service, the secrets capability shows up in a search before they write a line of their own vault.

The catalog changes the default. Instead of "I couldn't find one, so I built one," the starting question becomes "what does the catalog already list?" The three duplicate stores don't vanish on their own — retiring those is another mechanism's job — but the catalog stops the fifth from being born, and it gives every existing duplicate a named host counterpart to migrate toward.

How it works

What makes a catalog this mechanism, rather than a wiki page, is that each entry is a structured, owned, consumable record:

  • Inventory, not documentation. Every host and shared-layer capability is an entry with a stable identity, so "does this exist already?" is a search, not a Slack question.
  • Ownership is explicit. Each capability names a responsible owner and its service level, so a consumer knows who stands behind it and what to expect — the difference between a supported facility and an abandoned one.
  • Consumption route attached. Each entry links the sanctioned way to use or extend it (the contract, the SDK, the request path), so discovery leads directly to delegation.
  • Curated, not crowd-dumped. Entries are maintained by owners against a real service level; a capability nobody will support does not get a listing that implies otherwise.

Tuning parameters

  • Coverage breadth — every internal capability versus only blessed, supported ones. Broad coverage aids discovery; narrow coverage keeps the catalog trustworthy. List an unsupported thing and you invite reliance the owner won't honor.
  • Entry richness — a name and owner versus full contract, SLA, versioning, and examples. Richer entries drive real adoption but cost upkeep and go stale faster.
  • Freshness enforcement — how aggressively stale entries are flagged or auto-expired. Strict freshness preserves trust; lax freshness lets the catalog quietly lie.
  • Ownership granularity — capability owned by a team, a person, or a rota. Finer ownership sharpens accountability; coarser ownership survives reorgs.

When it helps, and when it misleads

Its strength is removing the cheapest reason to build a shadow platform — not knowing the host already provides the thing. By making supply discoverable and owned, it turns delegation into the path of least resistance and gives every existing local duplicate a named target to migrate onto.

Its failure mode is the stale catalog that lies: entries that outlive their owners, SLAs that no longer hold, capabilities listed as supported that are quietly abandoned. A directory trusted after it has rotted is worse than none, because teams delegate to a facility no one is maintaining. Its classic misuse is treating the catalog as governance — assuming that listing a capability makes teams use it, when a catalog only informs and cannot compel. The discipline that keeps it honest is owner-bound freshness: every entry carries a live owner and a review date, and an entry that can't name a maintainer is removed rather than left to mislead.[1]

How it implements the components

A catalog realizes the supply-visibility slice of the archetype — it publishes what exists and who owns it, and nothing downstream of that:

  • host_capability_inventory — the catalog is this inventory made discoverable: the enumerated, searchable set of host and shared-layer capabilities a team can delegate to.
  • capability_ownership_matrix — each entry binds a capability to a named owner and service level, so the "who is responsible for this" mapping is published rather than tribal.

It does not decide where a capability belongs — the placement criterion lives in Architecture Decision Record and the promotion decision in Capability-Promotion Review. It publishes the contract's existence but does not define it (that is Service Layer or API Facade) or test it (that is Interface Contract Test).

Notes

The catalog is a system of record for supply; it is not the register of duplication. Which local facilities shadow a catalogued host capability is tracked by Shadow-Platform Audit, and the two are complementary: the catalog says what teams should be able to reach, the audit says where they built around it anyway.

References

[1] An owner-less catalog entry recreates the very failure the archetype warns about — two competing sources of truth — by presenting an unmaintained facility as though it were supported. The corrective is that authority to list is tied to accountability to maintain. ↩