Normalize agent instructions and workplan frontmatter (STATE-WP-0067)
Some checks are pending
ci / validate-registry (push) Waiting to run

- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
This commit is contained in:
2026-06-22 23:16:28 +02:00
parent fe05d60a66
commit 368fb156d4
13 changed files with 29 additions and 182 deletions

162
AGENTS.md
View File

@@ -4,7 +4,7 @@
**Purpose:** Capability registry for planning and implementation reuse based on discovery and delivery maturity.
**Domain:** helix_forge
**Domain:** infotech
**Repo slug:** reuse-surface
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
**Workplan prefix:** `REUSE-WP-`
@@ -101,159 +101,6 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
---
## Local Developer Workflow
The repository is primarily documentation-first with a small Python CLI for
registry validate, query, and export. There is no long-running service.
### Install
```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```
### Build
No separate build step. Treat Markdown, YAML, and workplan edits as source
artifacts.
### Test / lint
```bash
# Registry validation (schema + index drift)
.venv/bin/reuse-surface validate
# Overlap, catalog, federation, and graph
.venv/bin/reuse-surface overlaps
.venv/bin/reuse-surface catalog
.venv/bin/reuse-surface federation compose
.venv/bin/reuse-surface graph --check
# Federation service (local)
# REUSE_SURFACE_TOKEN=dev-token reuse-surface serve
# Hub CLI (against deployed or local service)
# REUSE_SURFACE_URL=http://127.0.0.1:8000 reuse-surface hub status
# Automated tests
.venv/bin/pytest -q
# Repository hygiene
rg --files
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.
CI runs `reuse-surface validate` on push and pull requests via
`.gitea/workflows/ci.yml`.
### 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 federated index when multi-repo
cat registry/indexes/federated.yaml
cat registry/indexes/capabilities.yaml
# CLI discovery and export
.venv/bin/reuse-surface query --discovery-min D4
.venv/bin/reuse-surface export --format 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. Run `.venv/bin/reuse-surface query` with filters, or read the index directly.
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 `.venv/bin/reuse-surface validate`.
### 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 | `reuse-surface query` or index filters |
| Compare candidates | entry vectors + relations + README guidance |
| Avoid duplicate capabilities | index search before add |
---
## Credential and access routing
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
@@ -304,6 +151,11 @@ every repo's agent instructions because it is high-frequency, high-risk, and eas
get wrong.
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention (ADR-001)
@@ -329,7 +181,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
id: REUSE-WP-NNNN
type: workplan
title: "..."
domain: helix_forge
domain: infotech
repo: reuse-surface
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex

View File

@@ -1,17 +1,12 @@
{
"agents": {
"coach": {
"path": "agents/agent-coach.md",
"enabled": true
},
"optimization": {
"path": "agents/agent-optimization.md",
"enabled": true
},
"scope-analyst": {
"path": "agents/agent-scope-analyst.md",
"enabled": true
}
}
}
# reuse-surface — Claude Code Instructions
@SCOPE.md
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/credential-routing.md
@.claude/rules/agents.md

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0002
type: workplan
title: "MVP registry foundation"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0003
type: workplan
title: "Close intent-scope gaps: docs, tooling, and registry growth"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0004
type: workplan
title: "Registry hardening: CI, overlap detection, and catalog"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0005
type: workplan
title: "Registry federation and relation graphs"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0006
type: workplan
title: "Registry hygiene and coverage expansion"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0007
type: workplan
title: "Interactive capability catalog"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0008
type: workplan
title: "Interactive relation graph explorer"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0009
type: workplan
title: "CLI hardening and test suite"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0010
type: workplan
title: "Network federation for remote indexes"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0016
type: workplan
title: "Interactive registry maintain with llm-connect automation"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex