From cfa0ff6fc14dd1e217914ae4417d9137d4212b85 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 24 Jun 2026 18:16:07 +0200 Subject: [PATCH] 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. --- .claude/rules/repo-identity.md | 2 +- .claude/rules/stack-and-commands.md | 9 +- AGENTS.md | 2 +- README.md | 15 ++- docs/statehub-register.md | 104 +++++++++++++++ docs/template-validation-checklist.md | 90 +++++++++++++ .../capability.infotech.repo-template.md | 121 ++++++++++++++++++ registry/indexes/capabilities.yaml | 16 ++- ...O-WP-0002-template-validation-checklist.md | 14 +- 9 files changed, 362 insertions(+), 11 deletions(-) create mode 100644 docs/statehub-register.md create mode 100644 docs/template-validation-checklist.md create mode 100644 registry/capabilities/capability.infotech.repo-template.md diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 4b02439..3ccf329 100644 --- 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 diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index 987fe75..ca469c0 100644 --- 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 ``` diff --git a/AGENTS.md b/AGENTS.md index ba8fbb3..d61b5dd 100644 --- 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 diff --git a/README.md b/README.md index fcd7b8f..2ea7af6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ # repo-seed -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +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=`. +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`. \ No newline at end of file diff --git a/docs/statehub-register.md b/docs/statehub-register.md new file mode 100644 index 0000000..895fae3 --- /dev/null +++ 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 \ + --repo-slug \ + --wp-prefix \ + --description "One-sentence repo purpose." \ + --no-llm + +# Operator follow-up (from state-hub checkout) +cd ~/state-hub +make fix-consistency REPO= +``` + +`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/-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= +``` + +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. \ No newline at end of file diff --git a/docs/template-validation-checklist.md b/docs/template-validation-checklist.md new file mode 100644 index 0000000..785cefe --- /dev/null +++ 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: `) + +## 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=` documented for workplan edits + +## 3. First workplan + +- [ ] `workplans/-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=` + +## 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=` 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`. \ No newline at end of file diff --git a/registry/capabilities/capability.infotech.repo-template.md b/registry/capabilities/capability.infotech.repo-template.md new file mode 100644 index 0000000..5ee0399 --- /dev/null +++ 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. \ No newline at end of file diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml index f944e47..359c385 100644 --- 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] \ No newline at end of file diff --git a/workplans/REPO-WP-0002-template-validation-checklist.md b/workplans/REPO-WP-0002-template-validation-checklist.md index 36c03e3..db42096 100644 --- 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. \ No newline at end of file