generated from coulomb/repo-seed
feat(registry): complete ATLAS-WP-0002 T02, T03, T06
Some checks failed
validate-registry / validate (push) Has been cancelled
Some checks failed
validate-registry / validate (push) Has been cancelled
T02: remove inherited capability.infotech.repo-template and template consumer docs (statehub-register, template-validation-checklist); add capability.infotech.config-surface-atlas and rewrite capabilities.yaml. T03: seed 4 configuration surfaces (state-hub api-config, ops-warden routing-catalog, reuse-surface federation-sources, ops-bridge tunnel-config) with registry/indexes/surfaces.yaml; source-linked, no values, secret deps by reference. T06: add tools/validate_registry.py (schema + index gate), Makefile (make validate), and .github/workflows/validate.yml (GitHub + Gitea Actions); document in stack-and-commands. Verified malformed entries are rejected. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -1,104 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,90 +0,0 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user