diff --git a/AGENTS.md b/AGENTS.md index 2f76b1b..eb78be0 100644 --- a/AGENTS.md +++ b/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/" \ --- -## 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...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` + + + + --- ## 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 diff --git a/CLAUDE.md b/CLAUDE.md index f035ef5..01f3319 100644 --- a/CLAUDE.md +++ b/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 diff --git a/workplans/REUSE-WP-0001-statehub-bootstrap.md b/workplans/REUSE-WP-0001-statehub-bootstrap.md index e0e249b..71bcf60 100644 --- a/workplans/REUSE-WP-0001-statehub-bootstrap.md +++ b/workplans/REUSE-WP-0001-statehub-bootstrap.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 diff --git a/workplans/REUSE-WP-0002-mvp-registry-foundation.md b/workplans/REUSE-WP-0002-mvp-registry-foundation.md index 19a61fd..cad5cd4 100644 --- a/workplans/REUSE-WP-0002-mvp-registry-foundation.md +++ b/workplans/REUSE-WP-0002-mvp-registry-foundation.md @@ -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 diff --git a/workplans/REUSE-WP-0003-intent-scope-gap-closure.md b/workplans/REUSE-WP-0003-intent-scope-gap-closure.md index 3692856..3f1edf6 100644 --- a/workplans/REUSE-WP-0003-intent-scope-gap-closure.md +++ b/workplans/REUSE-WP-0003-intent-scope-gap-closure.md @@ -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 diff --git a/workplans/REUSE-WP-0004-registry-hardening.md b/workplans/REUSE-WP-0004-registry-hardening.md index c004a5d..ed0f62f 100644 --- a/workplans/REUSE-WP-0004-registry-hardening.md +++ b/workplans/REUSE-WP-0004-registry-hardening.md @@ -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 diff --git a/workplans/REUSE-WP-0005-registry-federation.md b/workplans/REUSE-WP-0005-registry-federation.md index a44d3d8..3e73a9d 100644 --- a/workplans/REUSE-WP-0005-registry-federation.md +++ b/workplans/REUSE-WP-0005-registry-federation.md @@ -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 diff --git a/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md b/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md index 346424b..752e7c8 100644 --- a/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md +++ b/workplans/REUSE-WP-0006-registry-hygiene-and-coverage.md @@ -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 diff --git a/workplans/REUSE-WP-0007-interactive-catalog.md b/workplans/REUSE-WP-0007-interactive-catalog.md index 02daebd..6252385 100644 --- a/workplans/REUSE-WP-0007-interactive-catalog.md +++ b/workplans/REUSE-WP-0007-interactive-catalog.md @@ -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 diff --git a/workplans/REUSE-WP-0008-graph-explorer.md b/workplans/REUSE-WP-0008-graph-explorer.md index 0b83307..57eb61b 100644 --- a/workplans/REUSE-WP-0008-graph-explorer.md +++ b/workplans/REUSE-WP-0008-graph-explorer.md @@ -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 diff --git a/workplans/REUSE-WP-0009-cli-hardening.md b/workplans/REUSE-WP-0009-cli-hardening.md index 8d4379b..86c4938 100644 --- a/workplans/REUSE-WP-0009-cli-hardening.md +++ b/workplans/REUSE-WP-0009-cli-hardening.md @@ -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 diff --git a/workplans/REUSE-WP-0010-network-federation.md b/workplans/REUSE-WP-0010-network-federation.md index 5f24c15..a79604a 100644 --- a/workplans/REUSE-WP-0010-network-federation.md +++ b/workplans/REUSE-WP-0010-network-federation.md @@ -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 diff --git a/workplans/REUSE-WP-0016-interactive-registry-maintain.md b/workplans/REUSE-WP-0016-interactive-registry-maintain.md index 1a36d32..7f13840 100644 --- a/workplans/REUSE-WP-0016-interactive-registry-maintain.md +++ b/workplans/REUSE-WP-0016-interactive-registry-maintain.md @@ -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