reuse-surface/registry/README.md

Capability Registry

Markdown-first registry for reusable capabilities in the helix_forge domain.

Layout

registry/
├── README.md
├── capabilities/
│   └── capability.<domain>.<name>.md
└── indexes/
    └── capabilities.yaml

• Entries live in capabilities/ as Markdown files with YAML front matter.
• Index at indexes/capabilities.yaml is the fast discovery surface for humans and agents.
• Schema at schemas/capability.schema.yaml defines required front matter.
• Template at templates/capability-entry.template.md is the authoring starting point.

Add a new capability (D0/A0/C0/R0)

1. Copy templates/capability-entry.template.md to registry/capabilities/capability.<domain>.<name>.md.
2. Set id, name, summary, owner, and status: draft.
3. Initialize all four dimensions explicitly:
   • maturity.discovery.current: D0
   • maturity.availability.current: A0
   • external_evidence.completeness.level: C0
   • external_evidence.reliability.level: R0
4. Add the entry to registry/indexes/capabilities.yaml.
5. Run reuse-surface validate --relations and reuse-surface federation compose.

Missing evidence is acceptable in the MVP when it is explicit rather than hidden.

Manual validation checklist

Use this checklist until an automated CLI validator exists.

Required fields

• id matches ^capability\.[a-z0-9]+(\.[a-z0-9-]+)+$
• name, summary, owner, and status are present
• maturity.discovery and maturity.availability include current and target
• external_evidence.completeness.level and external_evidence.reliability.level are present
• Completeness and reliability are not nested under maturity

Enum checks

Discovery levels: D0–D7
Availability levels: A0–A7
Completeness levels: C0–C6
Reliability levels: R0–R6
Entry status: draft, reviewed, approved, deprecated
Confidence: low, medium, high

Definitions live in specs/CapabilityMaturityStandard.md.

Relation checks

• Every relation target uses a valid capability ID format
• Referenced capabilities exist in the index or are explicitly marked as external/planned
• Cycles in depends_on are intentional and documented

Index checks

• New entry appears in indexes/capabilities.yaml
• path points to the correct Markdown file
• vector matches the entry's current maturity levels

Search and filter guidance

UC-RS-004 — Search by planning need

1. Run reuse-surface query --discovery-min D4 or read the index and scan summary, tags, and vector.
2. Open candidate entries and review discovery.intent, discovery.use_cases, and discovery.includes.
3. Prefer entries with discovery D3+ for roadmap work and D5+ for MVP selection.

Example filter:

discovery:
  minimum: D4
tags:
  - identity

UC-RS-005 — Search by consumption mode

1. Filter the index by consumption_modes or availability level.
2. Open entries and inspect availability.current_artifacts.
3. Treat A0 entries as planning-only; require A2+ for code reuse and A3+ for automation.

Example filter:

availability:
  minimum: A3
consumption_modes:
  - cli

UC-RS-006 — Compare capability candidates

Compare vectors side by side and read:

• discovery.includes / discovery.excludes for overlap
• external_evidence.completeness for expectation fit
• external_evidence.reliability for consumer risk
• relations for dependency and duplication signals

UC-RS-015 — Detect duplicate or overlapping capabilities

Run reuse-surface overlaps for automated candidate detection, then review:

Check for overlap in:

• similar name or summary
• shared discovery.includes
• relations.related_to without clear specialization
• duplicate tags and consumption modes with weak boundary differences

When overlap is real, link entries with relations.related_to, specializes, or generalizes rather than creating silent duplicates.

Relation graph

Regenerate the Mermaid graph after relation changes:

reuse-surface graph
reuse-surface graph --check

Outputs:

• docs/graph/capability-graph.mmd — Mermaid source
• docs/graph/index.html — in-browser explorer (also regenerated by catalog)

Promote a capability

1. Attach evidence appropriate to the target level in specs/CapabilityMaturityStandard.md.
2. Update maturity and/or external_evidence with rationale and confidence.
3. Append a promotion_history record with date, dimension, from, to, and rationale (optional author).
4. Update availability.current_artifacts when a new consumption mode appears.
5. Refresh the index vector and run reuse-surface validate --relations.
6. Run reuse-surface federation compose and reuse-surface graph.
7. Set status: reviewed or approved when an assessor validates the entry.