From 23f036869804c0c57d941af1cbe6cc6931c486e6 Mon Sep 17 00:00:00 2001 From: Coulomb Social Date: Fri, 26 Jun 2026 13:44:08 +0000 Subject: [PATCH] Initial commit --- .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 | 27 +++ .claude/rules/workplan-convention.md | 40 ++++ .custodian-brief.md | 18 ++ .gitignore | 176 ++++++++++++++ .repo-classification.yaml | 18 ++ AGENTS.md | 219 ++++++++++++++++++ CLAUDE.md | 12 + LICENSE | 16 ++ README.md | 16 ++ SCOPE.md | 31 +++ docs/statehub-register.md | 104 +++++++++ docs/template-validation-checklist.md | 90 +++++++ registry/README.md | 12 + registry/capabilities/.gitkeep | 0 .../capability.infotech.repo-template.md | 121 ++++++++++ registry/indexes/capabilities.yaml | 14 ++ workplans/REPO-WP-0001-statehub-bootstrap.md | 67 ++++++ ...O-WP-0002-template-validation-checklist.md | 34 +++ 25 files changed, 1229 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 .custodian-brief.md create mode 100644 .gitignore create mode 100644 .repo-classification.yaml create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 SCOPE.md create mode 100644 docs/statehub-register.md create mode 100644 docs/template-validation-checklist.md create mode 100644 registry/README.md create mode 100644 registry/capabilities/.gitkeep create mode 100644 registry/capabilities/capability.infotech.repo-template.md create mode 100644 registry/indexes/capabilities.yaml create mode 100644 workplans/REPO-WP-0001-statehub-bootstrap.md create mode 100644 workplans/REPO-WP-0002-template-validation-checklist.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..3ccf329 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,5 @@ +**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 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..ca469c0 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,27 @@ +## 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 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/.custodian-brief.md b/.custodian-brief.md new file mode 100644 index 0000000..899bb60 --- /dev/null +++ b/.custodian-brief.md @@ -0,0 +1,18 @@ + +# 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/.gitignore b/.gitignore new file mode 100644 index 0000000..36b13f1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,176 @@ +# ---> Python +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# UV +# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +#uv.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + +# Ruff stuff: +.ruff_cache/ + +# PyPI configuration file +.pypirc + 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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d61b5dd --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,219 @@ +# 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 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/LICENSE b/LICENSE new file mode 100644 index 0000000..a4e9dc9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,16 @@ +MIT No Attribution + +Copyright + +Permission is hereby granted, free of charge, to any person obtaining a copy of this +software and associated documentation files (the "Software"), to deal in the Software +without restriction, including without limitation the rights to use, copy, modify, +merge, publish, distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..2ea7af6 --- /dev/null +++ b/README.md @@ -0,0 +1,16 @@ +# 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 diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..802fd33 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,31 @@ +# 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 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/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/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 new file mode 100644 index 0000000..359c385 --- /dev/null +++ b/registry/indexes/capabilities.yaml @@ -0,0 +1,14 @@ +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 new file mode 100644 index 0000000..970d64d --- /dev/null +++ b/workplans/REPO-WP-0001-statehub-bootstrap.md @@ -0,0 +1,67 @@ +--- +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 new file mode 100644 index 0000000..db42096 --- /dev/null +++ b/workplans/REPO-WP-0002-template-validation-checklist.md @@ -0,0 +1,34 @@ +--- +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