2026-06-15 01:12:09 +02:00
|
|
|
|
# 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:
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
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**
|
|
|
|
|
|
|
2026-06-15 02:24:20 +02:00
|
|
|
|
1. Read `registry/indexes/capabilities.yaml` or open `docs/catalog/search.html`
|
|
|
|
|
|
for client-side filter by name, tags, vector, and consumption mode.
|
|
|
|
|
|
2. Filter by vector, tags, or consumption mode (`reuse-surface query`).
|
2026-06-15 01:12:09 +02:00
|
|
|
|
3. Open candidate entry files for scope, relations, and guidance.
|
|
|
|
|
|
4. Prefer planning reuse at D3+ and implementation reuse at A2+.
|
2026-06-15 02:24:20 +02:00
|
|
|
|
5. Browse relation structure in `docs/graph/index.html` after running
|
|
|
|
|
|
`reuse-surface graph`.
|
2026-06-15 01:12:09 +02:00
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 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`
|
