generated from coulomb/repo-seed
Bootstrap and first implementation
This commit is contained in:
130
AGENTS.md
130
AGENTS.md
@@ -101,6 +101,136 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
|
||||
---
|
||||
|
||||
## Local Developer Workflow
|
||||
|
||||
This repository is currently documentation-only. There is no package manifest,
|
||||
runtime application, build system, executable test suite, or formatter/linter
|
||||
configuration checked in.
|
||||
|
||||
### Install
|
||||
|
||||
No install step is required for normal repository work.
|
||||
|
||||
### Build
|
||||
|
||||
No build step exists. Treat Markdown, YAML, and workplan edits as source
|
||||
artifacts.
|
||||
|
||||
### Test / lint
|
||||
|
||||
There is no project test runner or markdown linter configured yet. Use these
|
||||
checks before closing a change:
|
||||
|
||||
```bash
|
||||
# Confirm the repository file inventory still looks intentional
|
||||
rg --files
|
||||
|
||||
# Catch whitespace errors in tracked and staged diffs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
When workplan files change, sync ADR-001 file state into State Hub:
|
||||
|
||||
```bash
|
||||
curl -s -X POST "http://127.0.0.1:8000/repos/reuse-surface/sync?fix=true" \
|
||||
| python3 -m json.tool
|
||||
```
|
||||
|
||||
If the HTTP sync endpoint is unavailable, run the consistency script from the
|
||||
State Hub checkout:
|
||||
|
||||
```bash
|
||||
cd ~/state-hub
|
||||
.venv/bin/python scripts/consistency_check.py --repo reuse-surface --fix
|
||||
.venv/bin/python scripts/consistency_check.py --repo reuse-surface
|
||||
```
|
||||
|
||||
The generated instruction in older workplans says `make fix-consistency
|
||||
REPO=reuse-surface`; that is still valid when `uv` is installed and on PATH.
|
||||
On this workstation, the `.venv/bin/python` fallback has been verified.
|
||||
|
||||
### Run
|
||||
|
||||
There is no local service to run from this repository.
|
||||
|
||||
### Documentation Review Checklist
|
||||
|
||||
- Keep `INTENT.md`, `SCOPE.md`, and `specs/` aligned on the registry-first
|
||||
reuse boundary.
|
||||
- Keep maturity definitions in `specs/CapabilityMaturityStandard.md` consistent
|
||||
with `INTENT.md` and `specs/ProductRequirementsDocument.md`.
|
||||
- Keep registry entries, indexes, and schemas in `registry/`, `schemas/`, and
|
||||
`templates/` current when capabilities change.
|
||||
- Record implementation ideas in workplans, not as premature runtime code in
|
||||
this repository.
|
||||
|
||||
---
|
||||
|
||||
## Capability Registry
|
||||
|
||||
Before building or documenting a new reusable behavior, query the registry to
|
||||
avoid duplication and to select the best existing capability for planning or
|
||||
implementation reuse.
|
||||
|
||||
### Orient
|
||||
|
||||
```bash
|
||||
# Fast discovery surface — read this first
|
||||
cat registry/indexes/capabilities.yaml
|
||||
|
||||
# Authoring template and schema
|
||||
cat templates/capability-entry.template.md
|
||||
cat schemas/capability.schema.yaml
|
||||
|
||||
# Validation and search guidance
|
||||
cat registry/README.md
|
||||
cat tools/README.md
|
||||
```
|
||||
|
||||
### Query workflow
|
||||
|
||||
1. Read `registry/indexes/capabilities.yaml`.
|
||||
2. Filter by `vector`, `tags`, `consumption_modes`, `domain`, or `summary`.
|
||||
3. Open only matching files under `registry/capabilities/`.
|
||||
4. Compare candidates using `discovery`, `external_evidence`, `availability`,
|
||||
and `relations` from the entry front matter.
|
||||
5. Prefer planning reuse when discovery is strong (`D3+`, especially `D5+`).
|
||||
6. Prefer implementation reuse only when availability is consumable (`A2+` code,
|
||||
`A3+` CLI, `A4+` API/SDK).
|
||||
|
||||
### Add a new capability
|
||||
|
||||
1. Search the index for overlap (UC-RS-015) before creating a new entry.
|
||||
2. Copy `templates/capability-entry.template.md` to
|
||||
`registry/capabilities/capability.<domain>.<name>.md`.
|
||||
3. Start at `D0 / A0 / C0 / R0` when evidence is minimal; keep gaps explicit.
|
||||
4. Add the entry to `registry/indexes/capabilities.yaml`.
|
||||
5. Run the manual validation checklist in `registry/README.md`.
|
||||
|
||||
### Promote a capability
|
||||
|
||||
1. Attach evidence required by `specs/CapabilityMaturityStandard.md` for the
|
||||
target level.
|
||||
2. Update `maturity` for discovery/availability and `external_evidence` for
|
||||
completeness/reliability separately.
|
||||
3. Refresh the index `vector` and record rationale in the entry body.
|
||||
4. Do not treat higher availability as proof of reliability or completeness.
|
||||
|
||||
### MVP acceptance mapping
|
||||
|
||||
| Acceptance criterion | Registry surface |
|
||||
|---|---|
|
||||
| Add D0/A0/C0/R0 with minimal friction | template + index + registry README |
|
||||
| Promote through discovery levels | entry front matter + maturity standard |
|
||||
| Identify current consumption mode | `availability` + index `consumption_modes` |
|
||||
| Record expectations and broken expectations | `external_evidence.completeness` |
|
||||
| Record reliability evidence | `external_evidence.reliability` |
|
||||
| Search by maturity and availability | `indexes/capabilities.yaml` filters |
|
||||
| Compare candidates | entry vectors + relations + README guidance |
|
||||
| Avoid duplicate capabilities | index search before add |
|
||||
|
||||
---
|
||||
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
Work items originate as files in this repo — not in the hub. The hub is a
|
||||
|
||||
Reference in New Issue
Block a user