generated from coulomb/repo-seed
104 lines
3.5 KiB
Markdown
104 lines
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. |