---
id: REUSE-WP-0002
type: workplan
title: "MVP registry foundation"
domain: helix_forge
repo: reuse-surface
status: finished
owner: codex
topic_slug: helix-forge
created: "2026-06-15"
updated: "2026-06-15"
state_hub_workstream_id: "32e0f249-65dd-4401-831c-736b229c5865"
---

# MVP registry foundation

This workplan implements the first registry artifacts required by
`specs/ProductRequirementsDocument.md` section 15 (MVP Requirements) and section
16 (MVP Acceptance Criteria). The repository already has `INTENT.md`, the
product requirements, use case catalog, and capability maturity standard under
`specs/`. The remaining MVP work is to make the registry usable by humans and
agents.

## Design decisions

- **Canonical format:** Markdown capability entries with YAML front matter under
  `registry/capabilities/`. The index at `registry/indexes/capabilities.yaml`
  is the machine-readable discovery surface for agents.
- **Schema alignment:** Follow `INTENT.md` and `specs/CapabilityMaturityStandard.md`
  section 10. Internal maturity uses `maturity.discovery` and
  `maturity.availability`. Consumer evidence uses `external_evidence.completeness`
  and `external_evidence.reliability` — not nested under `maturity`.
- **Sample capabilities:** Seed three helix_forge entries illustrating different
  vectors: registry meta (`capability.registry.register`), implementation-ready
  feature control (`capability.feature-control.evaluate`), and research-heavy
  identity canon (`capability.identity.vocabulary-canonicalize`).
- **Validation:** Document manual validation rules in `registry/README.md` and
  `tools/README.md` for MVP. Automated CLI validation is out of scope here.

## Define Capability Schema

```task
id: REUSE-WP-0002-T01
status: done
priority: high
state_hub_task_id: "431edb19-2166-4715-bb3d-4428149aa2bc"
```

Create `schemas/capability.schema.yaml` as a JSON Schema draft (YAML syntax)
for registry entry front matter. Cover stable IDs, `maturity` (discovery and
availability only), `external_evidence`, discovery scope fields, availability
artifacts, relations, evidence references, and consumer guidance. Enum values
must match `specs/CapabilityMaturityStandard.md`.

## Create Capability Entry Template

```task
id: REUSE-WP-0002-T02
status: done
priority: high
state_hub_task_id: "a4763385-954f-4141-9f16-a85e96704f46"
```

Create `templates/capability-entry.template.md` as the Markdown-first authoring
template. Include YAML front matter with required fields, commented guidance
for assessors, and placeholders for evidence, relations, and consumer guidance.
The template must be consistent with the schema from T01.

## Seed Sample Registry Entries

```task
id: REUSE-WP-0002-T03
status: done
priority: high
state_hub_task_id: "96078fbb-f2cc-4d4f-ac7c-6a1744c33e0b"
```

Create three sample entries under `registry/capabilities/`:

- `capability.registry.register.md` — D3/A0, meta registry capability
- `capability.feature-control.evaluate.md` — D5/A4, implementation-ready example
- `capability.identity.vocabulary-canonicalize.md` — D4/A0, research/planning example

Each entry must conform to the schema and illustrate distinct maturity vectors.
Include relations between entries where appropriate.

## Build Capability Index

```task
id: REUSE-WP-0002-T04
status: done
priority: medium
state_hub_task_id: "19e0d200-fe1f-4273-9f47-abdf4a67b517"
```

Create `registry/indexes/capabilities.yaml` as a manually maintained index.
Include IDs, names, summaries, compact maturity vectors, domain, and paths to
entry files. The index must list all three sample capabilities from T03.

## Add Validation And Search Guidance

```task
id: REUSE-WP-0002-T05
status: done
priority: medium
state_hub_task_id: "bf0dd838-9c13-480e-93b9-47d4ae5edc82"
```

Create `registry/README.md` and `tools/README.md` documenting:

- Required and recommended fields
- Manual validation checklist (schema enums, relation ID format, broken references)
- Search/filter guidance for UC-RS-004, UC-RS-005, UC-RS-006, and UC-RS-015
- How to add a D0/A0/C0/R0 entry with minimal friction (MVP acceptance criteria)

## Extend Agent Registry Instructions

```task
id: REUSE-WP-0002-T06
status: done
priority: medium
state_hub_task_id: "a78fc037-b432-4af3-a068-132690344bb2"
```

Add a **Capability Registry** section to `AGENTS.md` explaining how coding
agents should orient to the registry, query the index, add or promote entries
using the template, validate manually, and avoid duplicating existing
capabilities. Reference paths created in earlier tasks and map guidance to MVP
acceptance criteria in `specs/ProductRequirementsDocument.md` section 16.