diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md deleted file mode 100644 index 0e8a5d9..0000000 --- a/.claude/rules/agents.md +++ /dev/null @@ -1,20 +0,0 @@ -## Kaizen Agents - -Specialized agent personas available on demand via the state-hub MCP. - -**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category -**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them - -Common agents: - -| Agent | Category | When to use | -|-------|----------|-------------| -| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature | -| `code-refactoring` | quality | Code quality analysis and safe refactoring | -| `test-maintenance` | testing | Diagnose and fix failing tests | -| `requirements-engineering` | process | Prevent interface/mock mismatches upfront | -| `keepaTodofile` | process | Maintain TODO.md during work | -| `project-management` | process | Track status, determine next steps | -| `datamodel-optimization` | quality | Optimize dataclasses and data structures | - -All 17 agents: call `list_kaizen_agents()` for the full list. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md deleted file mode 100644 index 7c2a645..0000000 --- a/.claude/rules/architecture.md +++ /dev/null @@ -1,8 +0,0 @@ -## Architecture - - - -## Quick Reference - -`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md deleted file mode 100644 index e50f4c8..0000000 --- a/.claude/rules/credential-routing.md +++ /dev/null @@ -1,50 +0,0 @@ -# Credential and access routing - -**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** -for inference. Run this check **before** requesting secrets, API keys, SSH access, -login tokens, or database passwords — in any repo, not only `ops-warden`. - -ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every -other credential need belongs to another subsystem. **Do not** message -`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. - -### Lookup (do this first) - -```bash -warden route find "" --json -warden route show --json -``` - -Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). - -| Agent runtime | How to orient | -| --- | --- | -| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=repo-seed` is for coordination, not secret vending | -| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | -| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | - -### Quick routing table - -| I need… | Owner | ops-warden executes? | -| --- | --- | --- | -| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | -| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | -| Login / OIDC / MFA | key-cape / Keycloak | No — route only | -| Authorization decision | flex-auth | No — route only | -| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | -| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | - -### Anti-patterns (do not do these) - -- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. -- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist -- Pasting secrets into Git, State Hub, workplans, logs, or chat - -### Other capabilities (reuse-surface) - -Non-credential capabilities are usually discovered through **reuse-surface** federation -(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in -every repo's agent instructions because it is high-frequency, high-risk, and easy to -get wrong. - -**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` \ No newline at end of file diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md deleted file mode 100644 index 368ae12..0000000 --- a/.claude/rules/first-session.md +++ /dev/null @@ -1,38 +0,0 @@ -## First Session Protocol - -Triggered when `get_domain_summary("infotech")` shows **no workstreams**. -The project is registered but work has not yet been structured. - -**Step 1 — Read, don't write** -- `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope -- `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases -- Scan repo root: README, directory structure, existing code or docs - -**Step 2 — Survey in-progress work** -Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. - -**Step 3 — Propose workstreams to Bernd** -Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a -roadmap phase. **Wait for approval before creating.** - -**Step 4 — Create workplan file first, then DB record (ADR-001)** -``` -workplans/REPO-WP-NNNN-.md ← write this first -``` -Then register in the hub: -``` -create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...") -create_task(workstream_id="", title="...", priority="high|medium|low") -``` - -**Step 5 — Record the setup** -``` -add_progress_event( - summary="First session: structured infotech into N workstreams, M tasks", - event_type="milestone", - topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", - detail={"workstreams": [...], "tasks_created": M} -) -``` - - diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md deleted file mode 100644 index eef78f4..0000000 --- a/.claude/rules/repo-boundary.md +++ /dev/null @@ -1,8 +0,0 @@ -## Repo boundary - -This repo owns **Repo Seed** only. It does not own: - - diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md deleted file mode 100644 index 3ccf329..0000000 --- a/.claude/rules/repo-identity.md +++ /dev/null @@ -1,5 +0,0 @@ -**Purpose:** Git repository template to bootstrap coulomb projects. - -**Domain:** infotech -**Repo slug:** repo-seed -**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md deleted file mode 100644 index 800d2b2..0000000 --- a/.claude/rules/session-protocol.md +++ /dev/null @@ -1,85 +0,0 @@ -## Session Protocol - -Dev Hub (State Hub API): http://127.0.0.1:8000 -MCP server name in `~/.claude.json`: `dev-hub` - -**Step 1 — Orient** - -Read the offline-safe brief first — it works without a live hub connection: -```bash -cat .custodian-brief.md -``` -Then call the MCP tool for richer cross-domain context when MCP tools are exposed: -``` -get_domain_summary("infotech") -``` -If MCP tools are unavailable in the current agent session, use the REST API: -```bash -curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool -``` -If the hub is offline: `cd ~/state-hub && make api` - -**Step 2 — Check inbox** -With MCP tools: -``` -get_messages(to_agent="repo-seed", unread_only=True) -``` -Mark read with `mark_message_read(message_id)`. Reply or act on coordination -requests before proceeding. - -Without MCP tools: -```bash -curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \ - | python3 -m json.tool -curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ - -H "Content-Type: application/json" -d '{}' -``` - -**Step 3 — Scan workplans** -```bash -ls workplans/ -``` -For each file with `status: ready`, `active`, or `blocked`, note pending -`wait`/`todo`/`progress` tasks. - -**Step 4 — Present brief** - -1. **Active workstreams** for `infotech` — title, task counts, blocking decisions -2. **Pending tasks** from `workplans/` + any `[repo:repo-seed]` hub tasks -3. **Goal guidance** — if `goal_guidance` in summary: - - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* - - `alignment_warnings`: flag if active work is not aligned with current goal -4. **Suggested next action** — highest-priority open item -5. **SBOM status** — flag if `last_sbom_at` is unset for this repo - -If no workstreams: follow First Session Protocol (`first-session.md`). - -**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` - -> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`) -> are First Session Protocol only. Work structure belongs in repo files (ADR-001). - -**Session close:** -With MCP tools: -``` -add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="") -``` -Without MCP tools: -```bash -curl -s -X POST http://127.0.0.1:8000/progress/ \ - -H "Content-Type: application/json" \ - -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"","event_type":"note","summary":"what changed","author":"codex"}' -``` -If workplan files were modified, ensure the local copy is up to date first: -```bash -git -C pull --ff-only -cd ~/state-hub && make fix-consistency REPO=repo-seed -``` -For repos where implementation runs on a remote machine (e.g. CoulombCore), -use the combined target which pulls before fixing: -```bash -cd ~/state-hub && make fix-consistency-remote REPO=repo-seed -``` -**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback -will sync the file to match DB. **C-16** (repo behind remote) blocks all writes -until you pull — intentional to prevent clobbering remote progress. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md deleted file mode 100644 index ca469c0..0000000 --- a/.claude/rules/stack-and-commands.md +++ /dev/null @@ -1,27 +0,0 @@ -## Stack - -- **Language:** Markdown-first registry and planning repo (no application runtime yet) -- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml` - -## Dev Commands - -```bash -# Orient (offline-safe) -cat .custodian-brief.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/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md deleted file mode 100644 index 1c2895d..0000000 --- a/.claude/rules/workplan-convention.md +++ /dev/null @@ -1,40 +0,0 @@ -## Workplan Convention (ADR-001) - -File location: `workplans/REPO-WP-NNNN-.md` -ID prefix: `REPO-WP-` - -Work items originate as files in this repo **before** being registered in the hub. - -Canonical workplan/workstream frontmatter statuses are: -`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`. -Use `proposed` for a newly drafted plan, `ready` after review against current -repo state, and `finished` when implementation is complete. `stalled` and -`needs_review` are derived health labels, not stored statuses. - -Closed workplans may be moved to `workplans/archived/` with a completion-date -prefix: `YYMMDD-REPO-WP-NNNN-.md`. The frontmatter id remains -unchanged; the prefix is only for quick visual reference. - -Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: -`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids -`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed -directly. Promote anything requiring analysis, design, approval, dependencies, or -multiple planned phases into a normal workplan. - -Ecosystem todos from other agents arrive as `[repo:repo-seed]` hub tasks — -visible at session start. Pick one up by creating the workplan file, then registering -the workstream. - -Task blocks use this shape: - -```task -id: REPO-WP-NNNN-T01 -status: wait | todo | progress | done | cancel -priority: high | medium | low -state_hub_task_id: "" # written by fix-consistency — do not edit -``` - -Status progression is `todo` → `progress` → `done`; use `wait` for waiting or -blocked work and `cancel` for stopped work. - - diff --git a/.custodian-brief.md b/.custodian-brief.md deleted file mode 100644 index 899bb60..0000000 --- a/.custodian-brief.md +++ /dev/null @@ -1,18 +0,0 @@ - -# Custodian Brief — repo-seed - -**Domain:** infotech -**Last synced:** 2026-06-24 13:36 UTC -**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* - -## Active Workstreams - -*(none — repo may need first-session setup)* - ---- -## MCP Orientation (when available) - -If the state-hub MCP server is reachable, call: -`get_domain_summary("infotech")` -This provides richer cross-domain context. -If the MCP call fails, use this file as your orientation source. diff --git a/.forgejo/workflows/ci-smoke.yaml b/.forgejo/workflows/ci-smoke.yaml deleted file mode 100644 index bd44c56..0000000 --- a/.forgejo/workflows/ci-smoke.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# Canonical CI smoke template (tier 1 routing drill). -# Copy to: .forgejo/workflows/ci-smoke.yaml in consumer repos. -name: CI Smoke - -on: - push: - branches: - - main - workflow_dispatch: - -jobs: - host-smoke: - runs-on: self-hosted - steps: - - name: Routing probe (host runner) - run: | - set -eu - echo "repository=${GITHUB_REPOSITORY:-unknown}" - echo "sha=${GITHUB_SHA:-unknown}" - echo "runner=${RUNNER_NAME:-unknown}" - uname -a - - container-smoke: - runs-on: ubuntu-latest - steps: - - name: Routing probe (container label) - run: | - set -eu - echo "container-smoke ok for ${GITHUB_REPOSITORY:-unknown}" \ No newline at end of file diff --git a/.repo-classification.yaml b/.repo-classification.yaml deleted file mode 100644 index ea7b5f4..0000000 --- a/.repo-classification.yaml +++ /dev/null @@ -1,18 +0,0 @@ -repo_classification: - standard: Repo Classification Standard - version: '1.0' - classified_at: '2026-06-22' - classified_by: agent - category: tooling - domain: infotech - secondary_domains: [] - capability_tags: - - platform - - configuration - - documentation - business_stake: - - technology - - execution - business_mechanics: - - operation - notes: Git template for bootstrapping coulomb projects. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index d61b5dd..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,219 +0,0 @@ -# Repo Seed — Agent Instructions - -## Repo Identity - -**Purpose:** Git repository template to bootstrap coulomb projects. - -**Domain:** infotech -**Repo slug:** repo-seed -**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` -**Workplan prefix:** `REPO-WP-` - ---- - -## State Hub Integration - -The Custodian State Hub tracks work across all domains. Interact via HTTP REST — -there is no MCP server for Codex agents. - -| Context | URL | -|---------|-----| -| Local workstation | `http://127.0.0.1:8000` | -| Remote via tunnel | `http://127.0.0.1:18000` | - -### Orient at session start - -```bash -# Offline brief — works without hub connection -cat .custodian-brief.md - -# Active workstreams for this domain -curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ - | python3 -m json.tool - -# Check inbox -curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \ - | python3 -m json.tool -``` - -Mark a message read: -```bash -curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ - -H "Content-Type: application/json" -d '{}' -``` - -### Log progress (required at session close) - -```bash -curl -s -X POST http://127.0.0.1:8000/progress/ \ - -H "Content-Type: application/json" \ - -d '{ - "summary": "what was done", - "event_type": "note", - "author": "codex", - "workstream_id": "", - "task_id": "" - }' -``` - -Omit `workstream_id` / `task_id` when not applicable. - -### Update task status - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"status": "progress"}' -# values: wait | todo | progress | done | cancel -``` - -### Flag a task for human review - -```bash -curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ - -H "Content-Type: application/json" \ - -d '{"needs_human": true, "intervention_note": "reason"}' -``` - ---- - -## Session Protocol - -**Start:** -1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) -2. Check inbox: `GET /messages/?to_agent=repo-seed&unread_only=true`; mark read -3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks -4. Check human-needed tasks: `GET /tasks/?needs_human=true` - -**During work:** -- Update task statuses in workplan files as tasks progress -- Record significant decisions via `POST /decisions/` - -**Close:** -1. Update workplan file task statuses to reflect progress -2. Log: `POST /progress/` with a summary of what changed -3. Note for the custodian operator: after workplan file changes, run from - `~/state-hub`: - ```bash - make fix-consistency REPO=repo-seed - ``` - This syncs task status from files into the hub DB. - ---- - -## Credential and access routing - -**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** -for inference. Run this check **before** requesting secrets, API keys, SSH access, -login tokens, or database passwords — in any repo, not only `ops-warden`. - -ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every -other credential need belongs to another subsystem. **Do not** message -`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. - -### Lookup (do this first) - -```bash -warden route find "" --json -warden route show --json -``` - -Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). - -| Agent runtime | How to orient | -| --- | --- | -| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=repo-seed` is for coordination, not secret vending | -| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | -| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | - -### Quick routing table - -| I need… | Owner | ops-warden executes? | -| --- | --- | --- | -| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | -| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | -| Login / OIDC / MFA | key-cape / Keycloak | No — route only | -| Authorization decision | flex-auth | No — route only | -| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | -| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | - -### Anti-patterns (do not do these) - -- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. -- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist -- Pasting secrets into Git, State Hub, workplans, logs, or chat - -### Other capabilities (reuse-surface) - -Non-credential capabilities are usually discovered through **reuse-surface** federation -(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in -every repo's agent instructions because it is high-frequency, high-risk, and easy to -get wrong. - -**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` - - - - ---- - -## Workplan Convention (ADR-001) - -Work items originate as files in this repo — not in the hub. The hub is a -read/cache/index layer that rebuilds from files. - -**File location:** `workplans/REPO-WP-NNNN-.md` - -**Archived location:** finished workplans may move to -`workplans/archived/YYMMDD-REPO-WP-NNNN-.md`. The `YYMMDD` prefix is -the completion/archive date; the frontmatter `id` does not change. - -**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use -`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use -this only for low-risk work completed directly; create a normal workplan for -anything needing analysis, design, approval, dependencies, or multiple phases. - -**Frontmatter:** - -```yaml ---- -id: REPO-WP-NNNN -type: workplan -title: "..." -domain: infotech -repo: repo-seed -status: proposed | ready | active | blocked | backlog | finished | archived -owner: codex -topic_slug: ... -created: "YYYY-MM-DD" -updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # written by fix-consistency — do not edit ---- -``` - -Use `proposed` for a new draft, `ready` after review against current repo -state, and `finished` after implementation. `stalled` and `needs_review` are -derived health labels, not frontmatter statuses. - -**Task block format** (one per `##` section): - -``` -## Task Title - -` ` `task -id: REPO-WP-NNNN-T01 -status: wait | todo | progress | done | cancel -priority: high | medium | low -state_hub_task_id: "" # written by fix-consistency — do not edit -` ` ` - -Task description text. -``` - -Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. - -To create a new workplan: -1. Write the file following the format above -2. Notify the custodian operator to run `make fix-consistency REPO=repo-seed` - (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index a01c656..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,12 +0,0 @@ -# Repo Seed — Claude Code Instructions - -@SCOPE.md -@.claude/rules/repo-identity.md -@.claude/rules/session-protocol.md -@.claude/rules/first-session.md -@.claude/rules/workplan-convention.md -@.claude/rules/stack-and-commands.md -@.claude/rules/architecture.md -@.claude/rules/repo-boundary.md -@.claude/rules/credential-routing.md -@.claude/rules/agents.md diff --git a/README.md b/README.md index 2ea7af6..fcd7b8f 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,3 @@ # repo-seed -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 +A git repository template to bootstrap coulomb projects from. \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md deleted file mode 100644 index 802fd33..0000000 --- a/SCOPE.md +++ /dev/null @@ -1,31 +0,0 @@ -# SCOPE - -> Lightweight boundary for agents and contributors. - ---- - -## One-liner - -Git repository template to bootstrap coulomb projects. - ---- - -## Core Idea - -repo-seed is the canonical template for new repos: agent instructions, registry scaffold, and onboarding conventions. - ---- - -## In Scope - -- Template files for new repo bootstrap -- Documentation for statehub_register usage -- Registry capability entry for template capability - ---- - -## Out of Scope - -- Application runtime code -- Owning downstream project implementations - diff --git a/docs/statehub-register.md b/docs/statehub-register.md deleted file mode 100644 index 895fae3..0000000 --- a/docs/statehub-register.md +++ /dev/null @@ -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 \ - --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 deleted file mode 100644 index 785cefe..0000000 --- a/docs/template-validation-checklist.md +++ /dev/null @@ -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: `) - -## 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/README.md b/registry/README.md deleted file mode 100644 index 569abe9..0000000 --- a/registry/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Capability Registry - -Markdown-first capability index for federation and reuse planning. - -## Authoring - -1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`). -2. Add the row to `indexes/capabilities.yaml`. -3. Run `reuse-surface validate` from a checkout with the CLI installed. -4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`. - -Federation contract: reuse-surface `docs/RegistryFederation.md`. diff --git a/registry/capabilities/.gitkeep b/registry/capabilities/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/registry/capabilities/capability.infotech.repo-template.md b/registry/capabilities/capability.infotech.repo-template.md deleted file mode 100644 index 5ee0399..0000000 --- a/registry/capabilities/capability.infotech.repo-template.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -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 deleted file mode 100644 index 359c385..0000000 --- a/registry/indexes/capabilities.yaml +++ /dev/null @@ -1,14 +0,0 @@ -version: 1 -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-0001-statehub-bootstrap.md b/workplans/REPO-WP-0001-statehub-bootstrap.md deleted file mode 100644 index 970d64d..0000000 --- a/workplans/REPO-WP-0001-statehub-bootstrap.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: REPO-WP-0001 -type: workplan -title: "Bootstrap State Hub integration" -domain: infotech -repo: repo-seed -status: finished -owner: codex -topic_slug: infotech -created: "2026-06-22" -updated: "2026-06-22" -state_hub_workstream_id: "b809c762-8675-470c-be3e-0e5552f7d79d" ---- - -# Bootstrap State Hub integration - -Git repository template to bootstrap coulomb projects. - -## Review Generated Integration Files - -```task -id: REPO-WP-0001-T01 -status: done -priority: high -state_hub_task_id: "65734e48-ec48-47f2-bd5c-5673e94343cc" - -``` - -Result 2026-06-22: Filled SCOPE.md; README is canonical intent. - -Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. -Replace generated placeholders with repo-specific facts where needed. - -## Verify Local Developer Workflow - -```task -id: REPO-WP-0001-T02 -status: done -priority: high -state_hub_task_id: "76f1c245-3f06-4ef7-943f-bf2e9722c71b" - -``` - -Result 2026-06-22: Template workflow documented. - -Identify the repo's install, test, lint, build, and run commands. Add or refine -those commands in the agent instructions so future coding sessions can verify -changes confidently. - -## Seed First Real Workplan - -```task -id: REPO-WP-0001-T03 -status: done -priority: medium -state_hub_task_id: "9670ff11-ed7a-49e6-8a1f-944af9794f6a" - -``` - -Result 2026-06-22: Created REPO-WP-0002. - -Create the first implementation workplan for the repository's most important -next change. After workplan file updates, run from `~/state-hub`: - -```bash -make fix-consistency REPO=repo-seed -``` diff --git a/workplans/REPO-WP-0002-template-validation-checklist.md b/workplans/REPO-WP-0002-template-validation-checklist.md deleted file mode 100644 index db42096..0000000 --- a/workplans/REPO-WP-0002-template-validation-checklist.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -id: REPO-WP-0002 -type: workplan -title: "Template consumer validation checklist" -domain: infotech -repo: repo-seed -status: finished -owner: codex -topic_slug: infotech -created: "2026-06-22" -updated: "2026-06-24" -state_hub_workstream_id: "8aaf98a0-7045-4d5b-915f-bc9ecc5aa319" ---- - -# Template consumer validation checklist - -Validate repo-seed against statehub_register output and document consumer steps. - -## Template validation checklist - -```task -id: REPO-WP-0002-T01 -status: done -priority: high -state_hub_task_id: "a1b0aaab-f0dc-4bd0-bde3-89635ac0ca3b" -``` - -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