reuse-surface/tools

Registry Tools

Reference tooling for the capability registry. The MVP is document-first; this directory documents validation and query workflows until executable tools land.

Current MVP workflows

Workflow	Location	Mode
Add capability	templates/capability-entry.template.md	manual
Discover capabilities	registry/indexes/capabilities.yaml	manual / agent
Validate entry shape	registry/README.md checklist	manual
Schema reference	schemas/capability.schema.yaml	manual
Maturity definitions	specs/CapabilityMaturityStandard.md	manual

Manual validation procedure

1. Open the capability entry Markdown file.
2. Compare YAML front matter against schemas/capability.schema.yaml.
3. Run the checklist in registry/README.md.
4. Confirm the index entry exists and the vector is current.
5. Confirm relation targets exist or are intentionally external.

Planned tools (out of MVP scope)

Future CLI commands may include:

# validate one entry or the whole registry
reuse-surface validate registry/capabilities/

# query by planning need, availability, or vector
reuse-surface query --discovery-min D4 --tag identity

# export machine-readable registry bundle
reuse-surface export --format yaml

These are documented here as targets only. Do not assume they exist yet.

Agent query pattern

Agents should start with the index, not individual entry files:

1. Read registry/indexes/capabilities.yaml.
2. Filter by vector, tags, consumption_modes, or summary.
3. Open only the candidate entry paths.
4. Before creating a new capability, search for overlap using the duplicate guidance in registry/README.md.

Related use cases

• UC-RS-013 — Use registry metadata in agentic coding
• UC-RS-019 — Publish a machine-readable registry export
• UC-RS-023 — Validate registry entries against schema