generated from coulomb/repo-seed
tegwick
0dbef6d1a3
Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide, extend schema with promotion_history, ship reuse-surface validate/query/export CLI, register three more helix_forge capabilities, and refresh SCOPE and gap analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.
129 lines
4.0 KiB
Markdown
129 lines
4.0 KiB
Markdown
# 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` |