generated from coulomb/repo-seed
Normalize agent instructions and workplan frontmatter (STATE-WP-0067)
Some checks are pending
ci / validate-registry (push) Waiting to run
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:
162
AGENTS.md
162
AGENTS.md
@@ -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
|
||||
|
||||
27
CLAUDE.md
27
CLAUDE.md
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user