# 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**

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`