tegwick
cfa0ff6fc1
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.
104 lines
No EOL
3.5 KiB
Markdown
104 lines
No EOL
3.5 KiB
Markdown
# 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. |