reuse-surface/docs/CapabilityRegistryConcept.md

Capability Registry Concept

Repository: reuse-surface
Audience: Humans onboarding to the registry
Companion docs: INTENT.md, SCOPE.md, specs/CapabilityMaturityStandard.md

---

1. What problem this solves

Reusable capabilities are often scattered across repositories, documents, prototypes, and services. Without a registry, teams and agents rediscover, duplicate, and inconsistently assess the same behaviors.

reuse-surface makes capabilities visible, comparable, and reusable for planning and implementation through a registry-first reuse layer.

A capability that is not registered is invisible for registry-driven reuse.

---

2. Core principles

Registry first

The registry is the boundary of practical reuse awareness. Analysis starts with what is registered, not with everything that might exist informally.

Reuse over inventory

The goal is capability reuse, not a complete inventory of all work products.

Planning and implementation are different

• Planning reuse feeds primarily on Discovery maturity (D0–D7).
• Implementation reuse feeds primarily on Availability maturity (A0–A7).

A capability may be well researched (D5) but only informational (A0). Another may be deployable (A4) but weakly bounded (D2). Compare both dimensions.

Internal and external evidence stay separate

Type	Dimensions	Question
Internal registry assessment	Discovery, Availability	How reusable is it for planning? How consumable is it?
External consumer evidence	Completeness, Reliability	Does scope satisfy intent? Does it behave well in use?

Do not treat availability as reliability, or research depth as completeness.

---

3. Maturity vector

A compact summary:

D5 / A4 / C3 / R3

Vectors are descriptive, not grades. A research vocabulary capability may naturally target D5 / A0 / C4 / R3. A CLI tool may target D5 / A3 / C5 / R5.

Canonical level definitions: specs/CapabilityMaturityStandard.md.

---

4. How the artifacts fit together

templates/capability-entry.template.md   → authoring starting point
registry/capabilities/*.md               → canonical entries (YAML front matter)
registry/indexes/capabilities.yaml       → fast discovery index for agents
schemas/capability.schema.yaml           → machine-readable entry contract
registry/README.md                       → validation and search guidance
tools/                                   → CLI validate, query, export

Authoring flow

1. Search the index for overlap.
2. Copy the template to registry/capabilities/.
3. Fill maturity and evidence fields explicitly.
4. Add an index row.
5. Validate with reuse-surface validate.

Consumption flow

1. Read registry/indexes/capabilities.yaml.
2. Filter by vector, tags, or consumption mode.
3. Open candidate entry files for scope, relations, and guidance.
4. Prefer planning reuse at D3+ and implementation reuse at A2+.

---

5. What is manual vs automated today

See SCOPE.md for the live boundary. In summary:

Activity	Mode
Discover capabilities	Index + reuse-surface query
Add or promote entries	Markdown authoring + index update
Validate shape	reuse-surface validate
Export for agents	reuse-surface export
Promotion history	Optional promotion_history in entries
Graph visualization, federation, CI gates	Not yet available

---

6. When to register a capability

Register when a bounded reusable behavior should be:

• discoverable for roadmap or architecture planning
• comparable to adjacent capabilities
• consumable through known artifacts (now or later)
• assessed with explicit evidence over time

Do not register one-off features, tickets, or internal code modules unless they represent a reusable capability boundary.

---

7. Further reading

• Product requirements: specs/ProductRequirementsDocument.md
• Use cases: specs/UseCaseCatalog.md
• Intent vs delivered scope: docs/IntentScopeGapAnalysis.md
• Agent workflows: AGENTS.md