reuse-surface/workplans/REUSE-WP-0002-mvp-registry-foundation.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
REUSE-WP-0002	workplan	MVP registry foundation	helix_forge	reuse-surface	finished	codex	helix-forge	2026-06-15	2026-06-15	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

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

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

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

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

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

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.