generated from coulomb/repo-seed
tegwick
80bccc4bbb
Document gaps between INTENT.md and SCOPE.md, refresh SCOPE with current MVP capabilities, and seed the follow-up workplan for documentation alignment, registry CLI tooling, and coverage growth.
120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
# SCOPE
|
|
|
|
## One-liner
|
|
|
|
Capability registry for planning and implementation reuse based on discovery and delivery maturity.
|
|
|
|
## Core Idea
|
|
|
|
`reuse-surface` provides a registry-centric reuse layer for capabilities. It
|
|
makes capabilities visible, comparable, assessable, and reusable for planning,
|
|
implementation, and operation. A capability that is not registered is invisible
|
|
for reuse within this product boundary.
|
|
|
|
## In Scope
|
|
|
|
- Maintain the capability maturity model, standards, schemas, registry formats,
|
|
sample entries, indexes, validation guidance, and agent instructions.
|
|
- Keep `INTENT.md`, `specs/`, registry artifacts, and State Hub workplans
|
|
aligned on the registry-first reuse boundary.
|
|
- Support humans and agents as registry consumers through Markdown-first
|
|
authoring and machine-readable metadata.
|
|
- Record decisions, progress, and workplan status through State Hub.
|
|
- Verify changes with documentation review, `git diff --check`, and ADR-001
|
|
consistency checks.
|
|
|
|
## Out of Scope
|
|
|
|
- Host or operate the registered capabilities themselves.
|
|
- Replace package registries, service catalogs, issue trackers, or project
|
|
management systems.
|
|
- Judge internal code quality as capability maturity.
|
|
- Own unrelated adjacent systems or make irreversible operational decisions
|
|
without human approval.
|
|
|
|
## What Is Possible Now
|
|
|
|
The MVP registry foundation is in place. Humans and agents can:
|
|
|
|
- **Discover capabilities** via `registry/indexes/capabilities.yaml`
|
|
- **Add a new capability** at D0/A0/C0/R0 using
|
|
`templates/capability-entry.template.md`
|
|
- **Promote capabilities** by updating front matter with evidence-backed
|
|
discovery, availability, completeness, and reliability levels
|
|
- **Compare candidates** using maturity vectors, scope, relations, and consumer
|
|
guidance in entry files
|
|
- **Record expectations** through `external_evidence.completeness` and
|
|
`external_evidence.reliability` fields
|
|
- **Validate entries manually** using the checklist in `registry/README.md`
|
|
against `schemas/capability.schema.yaml`
|
|
- **Avoid duplicates** by searching the index before creating new entries
|
|
|
|
These workflows satisfy the MVP acceptance criteria in
|
|
`specs/ProductRequirementsDocument.md` section 16 through manual, Git-friendly
|
|
authoring. There is no CLI, API, or automated validator yet.
|
|
|
|
## What Is Not Possible Yet
|
|
|
|
- Automated schema validation or registry export
|
|
- CLI query/filter commands
|
|
- Generated human-readable catalog site
|
|
- Capability graph visualization
|
|
- Promotion history tracking or review workflows in tooling
|
|
- Federation across repositories or organizations
|
|
|
|
See `tools/README.md` for planned tooling that remains out of scope for the
|
|
current MVP.
|
|
|
|
## Current State
|
|
|
|
- Status: active MVP registry (documentation-only, A0 availability).
|
|
- The repository has no package manifest, build system, runtime app, or
|
|
executable test suite. Registry consumption is informational: read, author,
|
|
compare, and plan.
|
|
- Three sample capabilities are registered in `registry/capabilities/`:
|
|
- `capability.registry.register` — D3 / A0 / C1 / R0
|
|
- `capability.feature-control.evaluate` — D5 / A4 / C3 / R3
|
|
- `capability.identity.vocabulary-canonicalize` — D4 / A0 / C2 / R0
|
|
- `specs/` holds the product requirements, use case catalog, and maturity
|
|
standard. `schemas/`, `templates/`, `registry/`, and `tools/` hold the
|
|
registry authoring and validation surfaces.
|
|
- Bootstrap work (`REUSE-WP-0001`) and MVP registry foundation
|
|
(`REUSE-WP-0002`) are finished. The next work should expand registry coverage,
|
|
tighten validation, or add CLI tooling through new workplans.
|
|
|
|
## Repository Layout
|
|
|
|
```text
|
|
reuse-surface/
|
|
├── INTENT.md
|
|
├── SCOPE.md
|
|
├── AGENTS.md
|
|
├── specs/
|
|
│ ├── ProductRequirementsDocument.md
|
|
│ ├── UseCaseCatalog.md
|
|
│ └── CapabilityMaturityStandard.md
|
|
├── schemas/
|
|
│ └── capability.schema.yaml
|
|
├── templates/
|
|
│ └── capability-entry.template.md
|
|
├── registry/
|
|
│ ├── README.md
|
|
│ ├── capabilities/
|
|
│ └── indexes/
|
|
│ └── capabilities.yaml
|
|
├── tools/
|
|
│ └── README.md
|
|
└── workplans/
|
|
```
|
|
|
|
## Getting Oriented
|
|
|
|
- Start with: INTENT.md
|
|
- Intent vs scope gaps: docs/IntentScopeGapAnalysis.md
|
|
- Product requirements: specs/ProductRequirementsDocument.md
|
|
- Use cases: specs/UseCaseCatalog.md
|
|
- Maturity standard: specs/CapabilityMaturityStandard.md
|
|
- Registry index: registry/indexes/capabilities.yaml
|
|
- Registry guidance: registry/README.md
|
|
- Agent instructions: AGENTS.md
|
|
- Workplans: workplans/ |