From 5c9902afbc08d0dc60efb258c238ef6ff72df5d1 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 16 Jun 2026 01:58:54 +0200 Subject: [PATCH 01/10] Add capability registry scaffold (REUSE-WP-0014-T07 B05) --- registry/README.md | 12 ++++++++++++ registry/capabilities/.gitkeep | 0 registry/indexes/capabilities.yaml | 4 ++++ 3 files changed, 16 insertions(+) create mode 100644 registry/README.md create mode 100644 registry/capabilities/.gitkeep create mode 100644 registry/indexes/capabilities.yaml diff --git a/registry/README.md b/registry/README.md new file mode 100644 index 0000000..569abe9 --- /dev/null +++ b/registry/README.md @@ -0,0 +1,12 @@ +# 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 new file mode 100644 index 0000000..e69de29 diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml new file mode 100644 index 0000000..f944e47 --- /dev/null +++ b/registry/indexes/capabilities.yaml @@ -0,0 +1,4 @@ +version: 1 +updated: '2026-06-16' +domain: helix_forge +capabilities: [] From d8833cf6b13f5b1f48ea1dfb323e56f6264f2ad1 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 17:47:42 +0200 Subject: [PATCH 02/10] Add .repo-classification.yaml (CUST-WP-0050 T11 agent first-pass) --- .repo-classification.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .repo-classification.yaml diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..ea7b5f4 --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,18 @@ +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. From 9c7c3388a337117331072139168274cf50eaa751 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 18:03:30 +0200 Subject: [PATCH 03/10] chore(consistency): sync task status from DB [auto] Updated by fix-consistency on 2026-06-22: - update .custodian-brief.md for repo-seed --- .custodian-brief.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .custodian-brief.md diff --git a/.custodian-brief.md b/.custodian-brief.md new file mode 100644 index 0000000..6d73c4f --- /dev/null +++ b/.custodian-brief.md @@ -0,0 +1,18 @@ + +# Custodian Brief — repo-seed + +**Domain:** (unknown) +**Last synced:** 2026-06-22 16:03 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("")` +This provides richer cross-domain context. +If the MCP call fails, use this file as your orientation source. From 0a594b9b2c8d6d74c92472cce74613e23e6fbf2e Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 21:40:49 +0200 Subject: [PATCH 04/10] chore(consistency): sync task status from DB [auto] Updated by fix-consistency on 2026-06-22: - update .custodian-brief.md for repo-seed --- .custodian-brief.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.custodian-brief.md b/.custodian-brief.md index 6d73c4f..feeabf4 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -1,18 +1,24 @@ # Custodian Brief — repo-seed -**Domain:** (unknown) -**Last synced:** 2026-06-22 16:03 UTC +**Domain:** infotech +**Last synced:** 2026-06-22 19:40 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)* +### Bootstrap State Hub integration +Progress: 0/3 done | workstream_id: `b809c762-8675-470c-be3e-0e5552f7d79d` + +**Open tasks:** +- · Review Generated Integration Files `65734e48` +- · Verify Local Developer Workflow `76f1c245` +- · Seed First Real Workplan `9670ff11` --- ## MCP Orientation (when available) If the state-hub MCP server is reachable, call: -`get_domain_summary("")` +`get_domain_summary("infotech")` This provides richer cross-domain context. If the MCP call fails, use this file as your orientation source. From 54e44a70a3c0cd7686633ed59dc6f84977c28c86 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 21:44:40 +0200 Subject: [PATCH 05/10] Add State Hub bootstrap workplan and agent integration files Seed workplans/ with bootstrap workplan to satisfy ADR-001 C-01. Includes regenerated dev-hub session-protocol and agent instruction files. --- .claude/rules/agents.md | 20 ++ .claude/rules/architecture.md | 8 + .claude/rules/credential-routing.md | 50 +++++ .claude/rules/first-session.md | 38 ++++ .claude/rules/repo-boundary.md | 8 + .claude/rules/repo-identity.md | 5 + .claude/rules/session-protocol.md | 85 +++++++ .claude/rules/stack-and-commands.md | 19 ++ .claude/rules/workplan-convention.md | 40 ++++ AGENTS.md | 219 +++++++++++++++++++ CLAUDE.md | 12 + SCOPE.md | 137 ++++++++++++ workplans/REPO-WP-0001-statehub-bootstrap.md | 58 +++++ 13 files changed, 699 insertions(+) create mode 100644 .claude/rules/agents.md create mode 100644 .claude/rules/architecture.md create mode 100644 .claude/rules/credential-routing.md create mode 100644 .claude/rules/first-session.md create mode 100644 .claude/rules/repo-boundary.md create mode 100644 .claude/rules/repo-identity.md create mode 100644 .claude/rules/session-protocol.md create mode 100644 .claude/rules/stack-and-commands.md create mode 100644 .claude/rules/workplan-convention.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 SCOPE.md create mode 100644 workplans/REPO-WP-0001-statehub-bootstrap.md diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..0e8a5d9 --- /dev/null +++ b/.claude/rules/agents.md @@ -0,0 +1,20 @@ +## 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 new file mode 100644 index 0000000..7c2a645 --- /dev/null +++ b/.claude/rules/architecture.md @@ -0,0 +1,8 @@ +## 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 new file mode 100644 index 0000000..e50f4c8 --- /dev/null +++ b/.claude/rules/credential-routing.md @@ -0,0 +1,50 @@ +# 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 new file mode 100644 index 0000000..368ae12 --- /dev/null +++ b/.claude/rules/first-session.md @@ -0,0 +1,38 @@ +## 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 new file mode 100644 index 0000000..eef78f4 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,8 @@ +## 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 new file mode 100644 index 0000000..4b02439 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,5 @@ +**Purpose:** Repo Seed - (fill in purpose) + +**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 new file mode 100644 index 0000000..800d2b2 --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,85 @@ +## 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 new file mode 100644 index 0000000..dc53ac6 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,19 @@ +## Stack + + +- **Language:** +- **Key deps:** + +## Dev Commands + +```bash +# TODO: Fill in the standard commands for this repo + +# Install dependencies + +# Run tests + +# Lint / type check + +# Build / package (if applicable) +``` diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..1c2895d --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,40 @@ +## 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/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ba8fbb3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,219 @@ +# Repo Seed — Agent Instructions + +## Repo Identity + +**Purpose:** Repo Seed - (fill in purpose) + +**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 new file mode 100644 index 0000000..a01c656 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,12 @@ +# 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/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..d48e39a --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,137 @@ +# SCOPE + +> This file helps you quickly understand what this repository is about, +> when it is relevant, and when it is not. +> It is intentionally lightweight and may be incomplete. + +--- + +## One-liner + + + + +--- + +## Core Idea + + + + +--- + +## In Scope + + + + +- +- +- + +--- + +## Out of Scope + + + + +- +- +- + +--- + +## Relevant When + + + +- +- +- + +--- + +## Not Relevant When + + + +- +- +- + +--- + +## Current State + + + +- Status: +- Implementation: +- Stability: +- Usage: + + + +--- + +## How It Fits + + + +- Upstream dependencies: +- Downstream consumers: +- Often used with: + +--- + +## Terminology + + + + +- Preferred terms: +- Also known as: +- Potentially confusing terms: + +--- + +## Related / Overlapping Repositories + + + + +- — + +--- + +## Getting Oriented + + + +- Start with: +- Key files / directories: +- Entry points: + +--- + +## Provided Capabilities + + + + + + + +--- + +## Notes + + diff --git a/workplans/REPO-WP-0001-statehub-bootstrap.md b/workplans/REPO-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..6f5cef8 --- /dev/null +++ b/workplans/REPO-WP-0001-statehub-bootstrap.md @@ -0,0 +1,58 @@ +--- +id: REPO-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: infotech +repo: repo-seed +status: ready +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: todo +priority: high +state_hub_task_id: "65734e48-ec48-47f2-bd5c-5673e94343cc" +``` + +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: todo +priority: high +state_hub_task_id: "76f1c245-3f06-4ef7-943f-bf2e9722c71b" +``` + +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: todo +priority: medium +state_hub_task_id: "9670ff11-ed7a-49e6-8a1f-944af9794f6a" +``` + +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 +``` From 39ca07b4432e92bb1884cabe8c4dece3e625114f Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 23:33:57 +0200 Subject: [PATCH 06/10] chore(consistency): sync task status from DB [auto] Updated by fix-consistency on 2026-06-22: - update .custodian-brief.md for repo-seed --- .custodian-brief.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/.custodian-brief.md b/.custodian-brief.md index feeabf4..833cb43 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -2,18 +2,16 @@ # Custodian Brief — repo-seed **Domain:** infotech -**Last synced:** 2026-06-22 19:40 UTC +**Last synced:** 2026-06-22 21:33 UTC **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* ## Active Workstreams -### Bootstrap State Hub integration -Progress: 0/3 done | workstream_id: `b809c762-8675-470c-be3e-0e5552f7d79d` +### Template consumer validation checklist +Progress: 0/1 done | workstream_id: `8aaf98a0-7045-4d5b-915f-bc9ecc5aa319` **Open tasks:** -- · Review Generated Integration Files `65734e48` -- · Verify Local Developer Workflow `76f1c245` -- · Seed First Real Workplan `9670ff11` +- · Template validation checklist `a1b0aaab` --- ## MCP Orientation (when available) From 615d0f309aeba8edafde3dbfbeb850ce0c996a3e Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 23:35:18 +0200 Subject: [PATCH 07/10] Complete State Hub bootstrap workplans (WP-0001) - Review integration files; fill SCOPE where templated - Document dev workflow in stack-and-commands.md - Seed WP-0002 implementation workplan; mark bootstrap finished - Hub sync via fix-consistency --- .claude/rules/stack-and-commands.md | 21 +-- SCOPE.md | 122 ++---------------- workplans/REPO-WP-0001-statehub-bootstrap.md | 17 ++- ...O-WP-0002-template-validation-checklist.md | 28 ++++ 4 files changed, 60 insertions(+), 128 deletions(-) create mode 100644 workplans/REPO-WP-0002-template-validation-checklist.md diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index dc53ac6..987fe75 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,19 +1,20 @@ ## Stack - -- **Language:** -- **Key deps:** +- **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 -# TODO: Fill in the standard commands for this repo +# Orient (offline-safe) +cat .custodian-brief.md +cat INTENT.md +cat SCOPE.md +ls workplans/ -# Install dependencies +# After workplan or registry edits — from ~/state-hub +make fix-consistency REPO=repo-seed -# Run tests - -# Lint / type check - -# Build / package (if applicable) +# Sanity-check markdown / registry edits +git diff --check ``` diff --git a/SCOPE.md b/SCOPE.md index d48e39a..802fd33 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,137 +1,31 @@ # SCOPE -> This file helps you quickly understand what this repository is about, -> when it is relevant, and when it is not. -> It is intentionally lightweight and may be incomplete. +> 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 -- -- -- - ---- - -## Relevant When - - - -- -- -- - ---- - -## Not Relevant When - - - -- -- -- - ---- - -## Current State - - - -- Status: -- Implementation: -- Stability: -- Usage: - - - ---- - -## How It Fits - - - -- Upstream dependencies: -- Downstream consumers: -- Often used with: - ---- - -## Terminology - - - - -- Preferred terms: -- Also known as: -- Potentially confusing terms: - ---- - -## Related / Overlapping Repositories - - - - -- — - ---- - -## Getting Oriented - - - -- Start with: -- Key files / directories: -- Entry points: - ---- - -## Provided Capabilities - - - - - - - ---- - -## Notes - - diff --git a/workplans/REPO-WP-0001-statehub-bootstrap.md b/workplans/REPO-WP-0001-statehub-bootstrap.md index 6f5cef8..970d64d 100644 --- a/workplans/REPO-WP-0001-statehub-bootstrap.md +++ b/workplans/REPO-WP-0001-statehub-bootstrap.md @@ -4,7 +4,7 @@ type: workplan title: "Bootstrap State Hub integration" domain: infotech repo: repo-seed -status: ready +status: finished owner: codex topic_slug: infotech created: "2026-06-22" @@ -20,11 +20,14 @@ Git repository template to bootstrap coulomb projects. ```task id: REPO-WP-0001-T01 -status: todo +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. @@ -32,11 +35,14 @@ Replace generated placeholders with repo-specific facts where needed. ```task id: REPO-WP-0001-T02 -status: todo +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. @@ -45,11 +51,14 @@ changes confidently. ```task id: REPO-WP-0001-T03 -status: todo +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`: diff --git a/workplans/REPO-WP-0002-template-validation-checklist.md b/workplans/REPO-WP-0002-template-validation-checklist.md new file mode 100644 index 0000000..36c03e3 --- /dev/null +++ b/workplans/REPO-WP-0002-template-validation-checklist.md @@ -0,0 +1,28 @@ +--- +id: REPO-WP-0002 +type: workplan +title: "Template consumer validation checklist" +domain: infotech +repo: repo-seed +status: ready +owner: codex +topic_slug: infotech +created: "2026-06-22" +updated: "2026-06-22" +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: todo +priority: high +state_hub_task_id: "a1b0aaab-f0dc-4bd0-bde3-89635ac0ca3b" +``` + +Author checklist for new repo bootstrap: register, agent files, first workplan, fix-consistency. From af52150f49f2db9788b2c0e2c745801d2e9a39d7 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 24 Jun 2026 15:36:16 +0200 Subject: [PATCH 08/10] chore(consistency): sync task status from DB [auto] Updated by fix-consistency on 2026-06-24: - update .custodian-brief.md for repo-seed --- .custodian-brief.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/.custodian-brief.md b/.custodian-brief.md index 833cb43..899bb60 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -2,16 +2,12 @@ # Custodian Brief — repo-seed **Domain:** infotech -**Last synced:** 2026-06-22 21:33 UTC +**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 -### Template consumer validation checklist -Progress: 0/1 done | workstream_id: `8aaf98a0-7045-4d5b-915f-bc9ecc5aa319` - -**Open tasks:** -- · Template validation checklist `a1b0aaab` +*(none — repo may need first-session setup)* --- ## MCP Orientation (when available) From cfa0ff6fc14dd1e217914ae4417d9137d4212b85 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 24 Jun 2026 18:16:07 +0200 Subject: [PATCH 09/10] Complete REPO-WP-0002 template validation and bootstrap docs 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. --- .claude/rules/repo-identity.md | 2 +- .claude/rules/stack-and-commands.md | 9 +- AGENTS.md | 2 +- README.md | 15 ++- docs/statehub-register.md | 104 +++++++++++++++ docs/template-validation-checklist.md | 90 +++++++++++++ .../capability.infotech.repo-template.md | 121 ++++++++++++++++++ registry/indexes/capabilities.yaml | 16 ++- ...O-WP-0002-template-validation-checklist.md | 14 +- 9 files changed, 362 insertions(+), 11 deletions(-) create mode 100644 docs/statehub-register.md create mode 100644 docs/template-validation-checklist.md create mode 100644 registry/capabilities/capability.infotech.repo-template.md diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 4b02439..3ccf329 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -1,4 +1,4 @@ -**Purpose:** Repo Seed - (fill in purpose) +**Purpose:** Git repository template to bootstrap coulomb projects. **Domain:** infotech **Repo slug:** repo-seed diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index 987fe75..ca469c0 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -8,13 +8,20 @@ ```bash # Orient (offline-safe) cat .custodian-brief.md -cat INTENT.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/AGENTS.md b/AGENTS.md index ba8fbb3..d61b5dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ ## Repo Identity -**Purpose:** Repo Seed - (fill in purpose) +**Purpose:** Git repository template to bootstrap coulomb projects. **Domain:** infotech **Repo slug:** repo-seed diff --git a/README.md b/README.md index fcd7b8f..2ea7af6 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ # repo-seed -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +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 diff --git a/docs/statehub-register.md b/docs/statehub-register.md new file mode 100644 index 0000000..895fae3 --- /dev/null +++ b/docs/statehub-register.md @@ -0,0 +1,104 @@ +# 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 new file mode 100644 index 0000000..785cefe --- /dev/null +++ b/docs/template-validation-checklist.md @@ -0,0 +1,90 @@ +# 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/capabilities/capability.infotech.repo-template.md b/registry/capabilities/capability.infotech.repo-template.md new file mode 100644 index 0000000..5ee0399 --- /dev/null +++ b/registry/capabilities/capability.infotech.repo-template.md @@ -0,0 +1,121 @@ +--- +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 index f944e47..359c385 100644 --- a/registry/indexes/capabilities.yaml +++ b/registry/indexes/capabilities.yaml @@ -1,4 +1,14 @@ version: 1 -updated: '2026-06-16' -domain: helix_forge -capabilities: [] +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-0002-template-validation-checklist.md b/workplans/REPO-WP-0002-template-validation-checklist.md index 36c03e3..db42096 100644 --- a/workplans/REPO-WP-0002-template-validation-checklist.md +++ b/workplans/REPO-WP-0002-template-validation-checklist.md @@ -4,11 +4,11 @@ type: workplan title: "Template consumer validation checklist" domain: infotech repo: repo-seed -status: ready +status: finished owner: codex topic_slug: infotech created: "2026-06-22" -updated: "2026-06-22" +updated: "2026-06-24" state_hub_workstream_id: "8aaf98a0-7045-4d5b-915f-bc9ecc5aa319" --- @@ -20,9 +20,15 @@ Validate repo-seed against statehub_register output and document consumer steps. ```task id: REPO-WP-0002-T01 -status: todo +status: done priority: high state_hub_task_id: "a1b0aaab-f0dc-4bd0-bde3-89635ac0ca3b" ``` -Author checklist for new repo bootstrap: register, agent files, first workplan, fix-consistency. +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 From 51fd7a7a0fdba09cd2cabad075c8c0a4b49e1d74 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 8 Jul 2026 12:37:45 +0200 Subject: [PATCH 10/10] Add Forgejo CI smoke workflow (enablement template) --- .forgejo/workflows/ci-smoke.yaml | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 .forgejo/workflows/ci-smoke.yaml diff --git a/.forgejo/workflows/ci-smoke.yaml b/.forgejo/workflows/ci-smoke.yaml new file mode 100644 index 0000000..bd44c56 --- /dev/null +++ b/.forgejo/workflows/ci-smoke.yaml @@ -0,0 +1,29 @@ +# 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