Complete REPO-WP-0002 template validation and bootstrap docs

Add statehub register consumer guide and validation checklist, register capability.infotech.repo-template in the registry index, and close the workplan after filling repo identity placeholders and README bootstrap steps.
2026-06-24 18:16:07 +02:00
parent af52150f49
commit cfa0ff6fc1
9 changed files with 362 additions and 11 deletions
--- a/.claude/rules/repo-identity.md
+++ b/.claude/rules/repo-identity.md
@@ -1,4 +1,4 @@
-**Purpose:** Repo Seed - (fill in purpose)
+**Purpose:** Git repository template to bootstrap coulomb projects.

 **Domain:** infotech
 **Repo slug:** repo-seed
--- a/.claude/rules/stack-and-commands.md
+++ b/.claude/rules/stack-and-commands.md
@@ -8,13 +8,20 @@
 ```bash
 # Orient (offline-safe)
 cat .custodian-brief.md
-cat INTENT.md
+cat README.md
 cat SCOPE.md
 ls workplans/

+# Consumer bootstrap docs
+cat docs/statehub-register.md
+cat docs/template-validation-checklist.md
+
 # After workplan or registry edits — from ~/state-hub
 make fix-consistency REPO=repo-seed

+# Validate registry entries (from reuse-surface checkout)
+reuse-surface validate --root .
+
 # Sanity-check markdown / registry edits
 git diff --check
 ```
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@

 ## Repo Identity

-**Purpose:** Repo Seed - (fill in purpose)
+**Purpose:** Git repository template to bootstrap coulomb projects.

 **Domain:** infotech
 **Repo slug:** repo-seed
--- a/README.md
+++ b/README.md
@@ -1,3 +1,16 @@
 # repo-seed

-A git repository template to bootstrap coulomb projects from.
+A git repository template to bootstrap coulomb projects from.
+
+## Bootstrap a new repo
+
+1. Clone or copy this template into a new repository.
+2. Run `statehub register` from the new repo root (see [docs/statehub-register.md](docs/statehub-register.md)).
+3. Complete the generated bootstrap workplan (`*-0001-statehub-bootstrap.md`).
+4. Sync workplans: `cd ~/state-hub && make fix-consistency REPO=<slug>`.
+5. Validate with [docs/template-validation-checklist.md](docs/template-validation-checklist.md).
+
+## Registry
+
+This repo publishes `capability.infotech.repo-template` — see
+`registry/capabilities/capability.infotech.repo-template.md`.
--- a/docs/statehub-register.md
+++ b/docs/statehub-register.md
@@ -0,0 +1,104 @@
+# statehub register — Consumer Guide
+
+Use this guide when bootstrapping a new Coulomb repository from the `repo-seed`
+template and registering it with Custodian State Hub.
+
+## Prerequisites
+
+- State Hub API running locally (`cd ~/state-hub && make api`) or reachable via tunnel
+- `statehub` CLI installed from `~/state-hub` (`uv tool install .` or `uv run statehub`)
+- A git repository cloned or copied from `repo-seed` (or an equivalent scaffold)
+
+## Quick start
+
+From the new repository root:
+
+```bash
+cd /path/to/new-repo
+
+# Optional: skip LLM inference and supply facts manually
+statehub register \
+  --domain <domain-slug> \
+  --repo-slug <repo-slug> \
+  --wp-prefix <PREFIX-WP> \
+  --description "One-sentence repo purpose." \
+  --no-llm
+
+# Operator follow-up (from state-hub checkout)
+cd ~/state-hub
+make fix-consistency REPO=<repo-slug>
+```
+
+`statehub register` is idempotent: existing files are not overwritten unless you
+pass `--force`.
+
+## What register writes
+
+`statehub register` inspects the repository, infers identity (optionally via
+`llm-connect`), and writes these files when absent:
+
+| File | Purpose |
+|------|---------|
+| `INTENT.md` | Why the repository exists |
+| `SCOPE.md` | In/out scope and current state |
+| `AGENTS.md` | Codex/Grok agent instructions with repo identity placeholders filled |
+| `.custodian-brief.md` | Offline-safe session orientation |
+| `workplans/<PREFIX>-0001-statehub-bootstrap.md` | First workplan with T01–T03 bootstrap tasks |
+
+It also registers the repo and host path through the State Hub API and records a
+progress milestone.
+
+## Template extras (from repo-seed)
+
+Cloning `repo-seed` provides additional scaffold not written by `register`:
+
+| Path | Purpose |
+|------|---------|
+| `CLAUDE.md` + `.claude/rules/` | Claude Code agent instructions |
+| `registry/` | Capability registry scaffold |
+| `README.md`, `LICENSE`, `.gitignore` | Project metadata |
+| `.repo-classification.yaml` | Repo classification metadata |
+
+After `register`, complete the bootstrap workplan (`*-0001-statehub-bootstrap.md`):
+
+1. **T01** — Review and refine generated integration files
+2. **T02** — Document install/test/lint/build/run commands in agent instructions
+3. **T03** — Create the first real implementation workplan
+
+## CLI reference
+
+```
+statehub register [options]
+
+  --path PATH           Repo directory (default: cwd)
+  --domain SLUG         State Hub domain slug
+  --repo-slug SLUG      Repo slug (auto-detected from directory name)
+  --wp-prefix PREFIX    Workplan prefix, e.g. DEMO-WP
+  --description TEXT    One-sentence repo description
+  --intent TEXT         Intent text when INTENT.md is absent
+  --api-base URL        State Hub API base (default: http://127.0.0.1:8000)
+  --no-llm              Skip LLM inference; use files and flags
+  --force               Overwrite generated files
+```
+
+Environment overrides: `API_BASE`, `STATEHUB_REGISTER_LLM_PROVIDER`,
+`STATEHUB_REGISTER_LLM_MODEL`, `STATEHUB_REGISTER_LLM_API_KEY`,
+`STATEHUB_REGISTER_LLM_TIMEOUT`.
+
+## fix-consistency
+
+Workplans are canonical in repo files (ADR-001). After creating or updating
+workplan files, sync them into State Hub:
+
+```bash
+cd ~/state-hub
+make fix-consistency REPO=<repo-slug>
+```
+
+This rebuilds hub workstreams/tasks from files, updates `.custodian-brief.md`,
+and reports consistency findings (C-15 file/DB drift, C-16 remote behind, etc.).
+
+## Validation
+
+Use [template-validation-checklist.md](template-validation-checklist.md) to
+verify a bootstrapped repo against expected `statehub register` output.
--- a/docs/template-validation-checklist.md
+++ b/docs/template-validation-checklist.md
@@ -0,0 +1,90 @@
+# Template Validation Checklist
+
+Validate a repository bootstrapped from `repo-seed` against `statehub register`
+output and Coulomb onboarding conventions.
+
+**Validated:** 2026-06-24 against `statehub register` in `~/state-hub`.
+
+---
+
+## 1. Register with State Hub
+
+- [ ] State Hub API is reachable (`curl -s http://127.0.0.1:8000/state/health`)
+- [ ] `statehub register` completes without error
+- [ ] Registration prints repo slug, domain, topic ID, and `make fix-consistency` hint
+- [ ] Progress milestone recorded (`Repo registered with State Hub: <slug>`)
+
+## 2. Agent files (register output)
+
+Confirm these files exist and contain repo-specific values (not `{PLACEHOLDER}` tokens):
+
+- [ ] `INTENT.md` — governing purpose; derived from README or `--intent`
+- [ ] `SCOPE.md` — one-liner, in/out scope, current state
+- [ ] `AGENTS.md` — **Purpose**, **Domain**, **Repo slug**, **Topic ID**, **Workplan prefix**
+- [ ] `.custodian-brief.md` — domain, topic ID, bootstrap workplan reference
+
+### AGENTS.md spot checks
+
+- [ ] `**Repo slug:**` matches directory slug and State Hub registration
+- [ ] `**Workplan prefix:**` matches workplan file prefix (e.g. `DEMO-WP-`)
+- [ ] Session protocol references `cat .custodian-brief.md` and inbox curl examples
+- [ ] `make fix-consistency REPO=<slug>` documented for workplan edits
+
+## 3. First workplan
+
+- [ ] `workplans/<PREFIX>-0001-statehub-bootstrap.md` exists
+- [ ] Frontmatter: `id`, `type: workplan`, `status: ready`, `repo`, `domain`
+- [ ] Tasks T01 (review files), T02 (dev workflow), T03 (seed real workplan) present
+- [ ] T03 references `make fix-consistency REPO=<slug>`
+
+## 4. Template extras (repo-seed scaffold)
+
+Beyond register output, confirm template scaffold is present:
+
+- [ ] `CLAUDE.md` includes `@.claude/rules/*` references
+- [ ] `.claude/rules/` contains session-protocol, workplan-convention, stack-and-commands
+- [ ] `registry/README.md` and `registry/indexes/capabilities.yaml` exist
+- [ ] `README.md` describes the repository purpose
+- [ ] `.gitignore` and `LICENSE` present
+
+## 5. Bootstrap workplan completion
+
+After register, complete `*-0001-statehub-bootstrap.md`:
+
+- [ ] **T01** — Placeholders replaced; SCOPE refined for repo-specific boundaries
+- [ ] **T02** — `.claude/rules/stack-and-commands.md` lists real dev commands
+- [ ] **T03** — First implementation workplan created (`*-0002-*.md` or equivalent)
+- [ ] Workplan status set to `finished` when all tasks done
+
+## 6. fix-consistency sync
+
+- [ ] `make fix-consistency REPO=<slug>` run from `~/state-hub`
+- [ ] `.custodian-brief.md` updated with active workstreams (replaces register stub)
+- [ ] Hub workstreams/tasks match workplan file statuses
+- [ ] No blocking C-16 (repo behind remote) findings
+
+## 7. Registry (optional)
+
+When the repo exposes reusable behavior:
+
+- [ ] Capability entry in `registry/capabilities/`
+- [ ] Row added to `registry/indexes/capabilities.yaml`
+- [ ] `reuse-surface validate --root .` passes
+
+---
+
+## repo-seed self-validation notes
+
+`repo-seed` is the meta-template and intentionally differs in a few places:
+
+| Item | repo-seed state | Consumer expectation |
+|------|-----------------|----------------------|
+| `INTENT.md` | Absent — `README.md` is canonical intent | Present after `register` |
+| `SCOPE.md` | Refined (no "generated by statehub register" banner) | Generated, then refined in T01 |
+| `.custodian-brief.md` | Maintained by `fix-consistency` | Register stub, then fix-consistency |
+| `REPO-WP-0001` | `finished` | `ready` until bootstrap complete |
+| `REPO-WP-0002` | Template validation (this checklist) | First domain-specific workplan |
+
+All register-output structures were verified by running `write_registration_files`
+from `statehub_register.py` with `repo_slug=repo-seed`, `wp_prefix=REPO-WP`,
+`domain=infotech`.
--- a/registry/capabilities/capability.infotech.repo-template.md
+++ b/registry/capabilities/capability.infotech.repo-template.md
@@ -0,0 +1,121 @@
+---
+id: capability.infotech.repo-template
+name: Coulomb Repository Template
+summary: Bootstrap new git repositories with agent instructions, registry scaffold, and State Hub onboarding conventions.
+owner: repo-seed
+status: draft
+domain: infotech
+tags:
+  - template
+  - bootstrap
+  - state-hub
+  - onboarding
+
+maturity:
+  discovery:
+    current: D3
+    target: D5
+    confidence: medium
+    rationale: >
+      Template purpose, consumer guide, and validation checklist are documented.
+      Scope boundaries are explicit in SCOPE.md.
+  availability:
+    current: A3
+    target: A4
+    confidence: medium
+    rationale: >
+      Consumers clone or copy repo-seed and run statehub register. Template
+      files are markdown/git artifacts without a hosted provisioning API.
+
+external_evidence:
+  completeness:
+    level: C2
+    confidence: medium
+    basis: scope_vs_intent_and_consumer_expectations
+    satisfied_expectations:
+      - agent instruction scaffold (AGENTS.md, CLAUDE.md, .claude/rules/)
+      - registry directory scaffold
+      - statehub register consumer documentation
+      - template validation checklist for bootstrap verification
+      - bootstrap workplan pattern (WP-0001)
+    broken_expectations: []
+    out_of_scope_expectations:
+      - automated repo creation on Gitea
+      - runtime application code generation
+  reliability:
+    level: R2
+    confidence: medium
+    basis: consumer_quality_signals
+    known_reliability_risks:
+      - register output evolves with state-hub releases; checklist must be revalidated
+      - LLM inference path depends on llm-connect availability
+
+discovery:
+  intent: >
+    Give new Coulomb repositories a consistent starting point for agent
+    coordination, capability registry growth, and State Hub workplan tracking.
+  includes:
+    - git template files for agent instructions and registry scaffold
+    - documentation for statehub register usage
+    - consumer validation checklist
+    - bootstrap workplan convention
+  excludes:
+    - application runtime implementation
+    - owning downstream project code
+  assumptions:
+    - consumers have access to state-hub CLI and API
+    - workplans remain canonical in repo files (ADR-001)
+  use_cases: []
+  research_memos:
+    - docs/statehub-register.md
+    - docs/template-validation-checklist.md
+
+availability:
+  current_level: A3
+  target_level: A4
+  current_artifacts:
+    - README.md
+    - AGENTS.md
+    - CLAUDE.md
+    - .claude/rules/
+    - registry/
+    - docs/statehub-register.md
+    - docs/template-validation-checklist.md
+  consumption_modes:
+    - git clone
+    - informational
+
+relations:
+  depends_on:
+    - capability.statehub.workstream-coordinate
+  supports: []
+  related_to:
+    - capability.registry.register
+
+evidence:
+  documentation:
+    - docs/statehub-register.md
+    - docs/template-validation-checklist.md
+    - SCOPE.md
+  tests: []
+
+consumer_guidance:
+  recommended_for:
+    - bootstrapping new Coulomb domain repositories
+    - standardizing agent onboarding and workplan conventions
+  not_recommended_for:
+    - repos that already have mature agent instructions and hub registration
+    - application templates with heavy code generation requirements
+  known_limitations:
+    - register must be run separately after cloning
+    - fix-consistency requires operator access to state-hub checkout
+---
+
+# Coulomb Repository Template
+
+`repo-seed` is the canonical git template for new Coulomb repositories. Clone it,
+run `statehub register`, complete the bootstrap workplan, and sync with
+`make fix-consistency`.
+
+See `docs/statehub-register.md` for the consumer workflow and
+`docs/template-validation-checklist.md` for verification steps.
--- a/registry/indexes/capabilities.yaml
+++ b/registry/indexes/capabilities.yaml
@@ -1,4 +1,14 @@
 version: 1
-updated: '2026-06-16'
-domain: helix_forge
-capabilities: []
+updated: '2026-06-24'
+domain: infotech
+capabilities:
+  - id: capability.infotech.repo-template
+    name: Coulomb Repository Template
+    summary: Bootstrap new git repositories with agent instructions, registry scaffold, and State Hub onboarding conventions.
+    vector: D3 / A3 / C2 / R2
+    domain: infotech
+    status: draft
+    owner: repo-seed
+    path: registry/capabilities/capability.infotech.repo-template.md
+    tags: [template, bootstrap, state-hub, onboarding]
+    consumption_modes: [git clone, informational]
--- a/workplans/REPO-WP-0002-template-validation-checklist.md
+++ b/workplans/REPO-WP-0002-template-validation-checklist.md
@@ -4,11 +4,11 @@ type: workplan
 title: "Template consumer validation checklist"
 domain: infotech
 repo: repo-seed
-status: ready
+status: finished
 owner: codex
 topic_slug: infotech
 created: "2026-06-22"
-updated: "2026-06-22"
+updated: "2026-06-24"
 state_hub_workstream_id: "8aaf98a0-7045-4d5b-915f-bc9ecc5aa319"
 ---

@@ -20,9 +20,15 @@ Validate repo-seed against statehub_register output and document consumer steps.

 ```task
 id: REPO-WP-0002-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "a1b0aaab-f0dc-4bd0-bde3-89635ac0ca3b"
 ```

-Author checklist for new repo bootstrap: register, agent files, first workplan, fix-consistency.
+Result 2026-06-24: Added `docs/statehub-register.md` (consumer guide),
+`docs/template-validation-checklist.md` (bootstrap verification checklist),
+`registry/capabilities/capability.infotech.repo-template.md` with index entry,
+and README bootstrap pointers. Validated register output structure against
+`statehub_register.write_registration_files`.
+
+Author checklist for new repo bootstrap: register, agent files, first workplan, fix-consistency.