generated from coulomb/repo-seed
Normalize agent instructions and workplan frontmatter (STATE-WP-0067)
Some checks failed
ci / validate-registry (push) Has been cancelled
Some checks failed
ci / validate-registry (push) Has been cancelled
- 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.
|
**Purpose:** Capability registry for planning and implementation reuse based on discovery and delivery maturity.
|
||||||
|
|
||||||
**Domain:** helix_forge
|
**Domain:** infotech
|
||||||
**Repo slug:** reuse-surface
|
**Repo slug:** reuse-surface
|
||||||
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
|
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
|
||||||
**Workplan prefix:** `REUSE-WP-`
|
**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
|
## Credential and access routing
|
||||||
|
|
||||||
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
**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.
|
get wrong.
|
||||||
|
|
||||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
**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)
|
## Workplan Convention (ADR-001)
|
||||||
@@ -329,7 +181,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
|
|||||||
id: REUSE-WP-NNNN
|
id: REUSE-WP-NNNN
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "..."
|
title: "..."
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: proposed | ready | active | blocked | backlog | finished | archived
|
status: proposed | ready | active | blocked | backlog | finished | archived
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
27
CLAUDE.md
27
CLAUDE.md
@@ -1,17 +1,12 @@
|
|||||||
{
|
# reuse-surface — Claude Code Instructions
|
||||||
"agents": {
|
|
||||||
"coach": {
|
@SCOPE.md
|
||||||
"path": "agents/agent-coach.md",
|
@.claude/rules/repo-identity.md
|
||||||
"enabled": true
|
@.claude/rules/session-protocol.md
|
||||||
},
|
@.claude/rules/first-session.md
|
||||||
"optimization": {
|
@.claude/rules/workplan-convention.md
|
||||||
"path": "agents/agent-optimization.md",
|
@.claude/rules/stack-and-commands.md
|
||||||
"enabled": true
|
@.claude/rules/architecture.md
|
||||||
},
|
@.claude/rules/repo-boundary.md
|
||||||
"scope-analyst": {
|
|
||||||
"path": "agents/agent-scope-analyst.md",
|
|
||||||
"enabled": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@.claude/rules/credential-routing.md
|
@.claude/rules/credential-routing.md
|
||||||
|
@.claude/rules/agents.md
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0001
|
id: REUSE-WP-0001
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Bootstrap State Hub integration"
|
title: "Bootstrap State Hub integration"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0002
|
id: REUSE-WP-0002
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "MVP registry foundation"
|
title: "MVP registry foundation"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0003
|
id: REUSE-WP-0003
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Close intent-scope gaps: docs, tooling, and registry growth"
|
title: "Close intent-scope gaps: docs, tooling, and registry growth"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0004
|
id: REUSE-WP-0004
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Registry hardening: CI, overlap detection, and catalog"
|
title: "Registry hardening: CI, overlap detection, and catalog"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0005
|
id: REUSE-WP-0005
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Registry federation and relation graphs"
|
title: "Registry federation and relation graphs"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0006
|
id: REUSE-WP-0006
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Registry hygiene and coverage expansion"
|
title: "Registry hygiene and coverage expansion"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0007
|
id: REUSE-WP-0007
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Interactive capability catalog"
|
title: "Interactive capability catalog"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0008
|
id: REUSE-WP-0008
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Interactive relation graph explorer"
|
title: "Interactive relation graph explorer"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0009
|
id: REUSE-WP-0009
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "CLI hardening and test suite"
|
title: "CLI hardening and test suite"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0010
|
id: REUSE-WP-0010
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Network federation for remote indexes"
|
title: "Network federation for remote indexes"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
id: REUSE-WP-0016
|
id: REUSE-WP-0016
|
||||||
type: workplan
|
type: workplan
|
||||||
title: "Interactive registry maintain with llm-connect automation"
|
title: "Interactive registry maintain with llm-connect automation"
|
||||||
domain: helix_forge
|
domain: infotech
|
||||||
repo: reuse-surface
|
repo: reuse-surface
|
||||||
status: finished
|
status: finished
|
||||||
owner: codex
|
owner: codex
|
||||||
|
|||||||
Reference in New Issue
Block a user