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:

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):

T01 — Review and refine generated integration files
T02 — Document install/test/lint/build/run commands in agent instructions
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:

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 to verify a bootstrapped repo against expected statehub register output.

3.5 KiB Raw Blame History Unescape Escape