tegwick
e766f38e6f
Register six new capabilities (12 total), add searchable catalog UI and graph explorer, introduce pytest suite with CI fail-on-warnings, and close gap analysis priorities 13 and 16. WP-0010 remains backlog for network federation.
4.2 KiB
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
- Search the index for overlap.
- Copy the template to
registry/capabilities/. - Fill maturity and evidence fields explicitly.
- Add an index row.
- Validate with
reuse-surface validate.
Consumption flow
- Read
registry/indexes/capabilities.yamlor opendocs/catalog/search.htmlfor client-side filter by name, tags, vector, and consumption mode. - Filter by vector, tags, or consumption mode (
reuse-surface query). - Open candidate entry files for scope, relations, and guidance.
- Prefer planning reuse at D3+ and implementation reuse at A2+.
- Browse relation structure in
docs/graph/index.htmlafter runningreuse-surface graph.
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