coulomb/reuse-surface
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage

Browse Source 
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.
This commit is contained in:
Bernd Worsch
2026-06-15 01:12:09 +02:00
parent 80bccc4bbb
commit 0dbef6d1a3
20 changed files with 1051 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
tools/README.md
View File

@@ -1,52 +1,64 @@
# Registry Tools
Reference tooling for the capability registry. The MVP is document-first; this
directory documents validation and query workflows until executable tools land.
CLI tooling for the capability registry, implemented in `reuse_surface/`.
## 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:
## Install
```bash
# 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
python3 -m venv .venv
.venv/bin/pip install -e .
```
These are documented here as targets only. Do not assume they exist yet.
## Commands
## Agent query pattern
### validate
Agents should start with the index, not individual entry files:
Validate one entry or the full registry against `schemas/capability.schema.yaml`
and warn on index drift.
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`.
```bash
reuse-surface validate
reuse-surface validate registry/capabilities/capability.registry.register.md
```
### query
Filter the capability index by maturity, tags, domain, consumption mode, or keyword.
```bash
reuse-surface query --discovery-min D4
reuse-surface query --availability-min A3
reuse-surface query --tag identity
reuse-surface query --consumption-mode cli
reuse-surface query --keyword rollout
```
### export
Export a machine-readable bundle combining index rows and parsed entry front matter.
```bash
reuse-surface export
reuse-surface export --format json
```
## Export format
The export bundle includes:
- `version`, `domain`, `updated` from the index
- `capabilities[]` with `{ index, entry }` pairs
Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
## Workflows
| Workflow | Command |
|---|---|
| Add capability | template + index update + `reuse-surface validate` |
| Discover capabilities | `reuse-surface query` or read the index |
| Validate entry shape | `reuse-surface validate` |
| Export for agents | `reuse-surface export --format json` |
## Related use cases