feat(bootstrap): complete ATLAS-WP-0001 State Hub integration

Customize config-atlas identity (INTENT, SCOPE, AGENTS, rules), document
dev workflow commands, remove inherited repo-seed workplans, and add
ATLAS-WP-0002 registry foundation workplan.
This commit is contained in:
2026-06-26 17:52:30 +02:00
parent 3918ef8a0d
commit 7078eaf596
14 changed files with 335 additions and 160 deletions

View File

@@ -1,8 +1,11 @@
## Repo boundary
This repo owns **Repo Seed** only. It does not own:
This repo owns **config-atlas** only — the federated configuration surface
registry and its documentation. It does not own:
<!-- TODO: List what belongs in adjacent repos, e.g.:
- SSH key management → railiance-infra/
- State hub code → state-hub/
-->
- Repo template bootstrap (`repo-seed`)
- Capability reuse registry (`reuse-surface`)
- Secret storage or live config values (`railiance-platform` / OpenBao)
- Feature flag control plane (`feature-control`)
- State Hub implementation (`state-hub`)
- Deployment and infrastructure execution (`railiance-infra`, `ops-bridge`)

View File

@@ -1,5 +1,6 @@
**Purpose:** Git repository template to bootstrap coulomb projects.
**Purpose:** Federated configuration atlas for the Coulomb ecosystem.
**Domain:** infotech
**Repo slug:** repo-seed
**Repo slug:** config-atlas
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
**Workplan prefix:** ATLAS-WP-

View File

@@ -22,14 +22,14 @@ 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)
get_messages(to_agent="config-atlas", 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" \
curl -s "http://127.0.0.1:8000/messages/?to_agent=config-atlas&unread_only=true" \
| python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
@@ -45,7 +45,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
**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
2. **Pending tasks** from `workplans/` + any `[repo:config-atlas]` 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
@@ -73,7 +73,7 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
If workplan files were modified, ensure the local copy is up to date first:
```bash
git -C <repo_path> pull --ff-only
cd ~/state-hub && make fix-consistency REPO=repo-seed
cd ~/state-hub && make fix-consistency REPO=config-atlas
```
For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the combined target which pulls before fixing:

View File

@@ -1,6 +1,6 @@
## Stack
- **Language:** Markdown-first registry and planning repo (no application runtime yet)
- **Language:** Markdown-first registry and planning repo (no application runtime)
- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml`
## Dev Commands
@@ -8,20 +8,21 @@
```bash
# Orient (offline-safe)
cat .custodian-brief.md
cat README.md
cat INTENT.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
ls registry/
# Validate registry entries (from reuse-surface checkout)
reuse-surface validate --root .
# Sanity-check markdown / registry edits
git diff --check
# After workplan or registry edits — from ~/state-hub
make fix-consistency REPO=config-atlas
```
**Install / test / lint / build / run:** not applicable — this repo has no
application runtime. Verify changes with `git diff --check` and
`reuse-surface validate` when registry files change.

View File

@@ -1,7 +1,7 @@
## Workplan Convention (ADR-001)
File location: `workplans/REPO-WP-NNNN-<slug>.md`
ID prefix: `REPO-WP-`
File location: `workplans/ATLAS-WP-NNNN-<slug>.md`
ID prefix: `ATLAS-WP-`
Work items originate as files in this repo **before** being registered in the hub.
@@ -12,7 +12,7 @@ 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-<slug>.md`. The frontmatter id remains
prefix: `YYMMDD-ATLAS-WP-NNNN-<slug>.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**:
@@ -21,14 +21,14 @@ Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**
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 —
Ecosystem todos from other agents arrive as `[repo:config-atlas]` 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
id: ATLAS-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
@@ -37,4 +37,4 @@ state_hub_task_id: "<uuid>" # 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.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

View File

@@ -1,7 +1,7 @@
repo_classification:
standard: Repo Classification Standard
version: '1.0'
classified_at: '2026-06-22'
classified_at: '2026-06-26'
classified_by: agent
category: tooling
domain: infotech
@@ -15,4 +15,4 @@ repo_classification:
- execution
business_mechanics:
- operation
notes: Git template for bootstrapping coulomb projects.
notes: Federated configuration atlas cataloging configuration surfaces across the Coulomb ecosystem.

View File

@@ -1,13 +1,13 @@
# Repo Seed — Agent Instructions
# config-atlas — Agent Instructions
## Repo Identity
**Purpose:** Git repository template to bootstrap coulomb projects.
**Purpose:** Federated configuration atlas for the Coulomb ecosystem.
**Domain:** infotech
**Repo slug:** repo-seed
**Repo slug:** config-atlas
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `REPO-WP-`
**Workplan prefix:** `ATLAS-WP-`
---
@@ -32,7 +32,7 @@ curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=repo-seed&unread_only=true" \
curl -s "http://127.0.0.1:8000/messages/?to_agent=config-atlas&unread_only=true" \
| python3 -m json.tool
```
@@ -81,7 +81,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
**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
2. Check inbox: `GET /messages/?to_agent=config-atlas&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`
@@ -95,7 +95,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`:
```bash
make fix-consistency REPO=repo-seed
make fix-consistency REPO=config-atlas
```
This syncs task status from files into the hub DB.
@@ -122,7 +122,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
| 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 |
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=config-atlas` 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` |
@@ -156,6 +156,33 @@ get wrong.
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
## Dev Workflow
Markdown-first registry repo — no application install, test, build, or run step.
```bash
# Orient (offline-safe)
cat .custodian-brief.md
cat INTENT.md
cat SCOPE.md
ls workplans/
ls registry/
# Validate registry structure (from reuse-surface checkout)
reuse-surface validate --root .
# Sanity-check markdown edits
git diff --check
# After workplan or registry edits — from ~/state-hub
make fix-consistency REPO=config-atlas
```
**Install:** none (no runtime dependencies in this repo).
**Test / lint / build / run:** not applicable — verify changes with `git diff --check`
and `reuse-surface validate` when registry files change.
---
## Workplan Convention (ADR-001)
@@ -163,10 +190,10 @@ get wrong.
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-<slug>.md`
**File location:** `workplans/ATLAS-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-REPO-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
`workplans/archived/YYMMDD-ATLAS-WP-NNNN-<slug>.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
@@ -178,11 +205,11 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
```yaml
---
id: REPO-WP-NNNN
id: ATLAS-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: repo-seed
repo: config-atlas
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
@@ -202,7 +229,7 @@ derived health labels, not frontmatter statuses.
## Task Title
` ` `task
id: REPO-WP-NNNN-T01
id: ATLAS-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
@@ -215,5 +242,5 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo
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`
2. Notify the custodian operator to run `make fix-consistency REPO=config-atlas`
(or send a message to the hub agent via `POST /messages/`)

58
INTENT.md Normal file
View File

@@ -0,0 +1,58 @@
# INTENT — config-atlas
> Repository purpose and boundary. Governance file for agents and contributors.
## One-liner
Federated configuration atlas for the Coulomb ecosystem — cataloging configuration
surfaces, schemas, defaults, ownership, and cross-repo relationships.
## Purpose
`config-atlas` exists because configuration knowledge is scattered across repos,
deployment manifests, environment variables, feature flags, policy files, and
operator runbooks. Without a shared atlas, agents and humans rediscover the same
configuration surfaces repeatedly and cannot reason confidently about defaults,
precedence, or ownership.
The atlas treats each **configuration surface** as a first-class, registry-backed
entry: what it configures, where it lives, who owns it, how it is validated, and
which capabilities or repos consume it.
## Core stance
- **Discoverable over tribal knowledge** — if a configuration surface matters to
reuse or operations, it should be indexed here or linked from here.
- **Source-linked** — atlas entries point at canonical files or APIs; the atlas
does not become a second source of truth for live config values.
- **Agent-friendly** — markdown and YAML registry formats that coding agents can
orient from without bespoke tooling.
- **Federated** — downstream repos remain authoritative for their own config; this
repo aggregates indexes, relationships, and documentation.
## In Scope
- Configuration surface registry (schemas, indexes, capability entries)
- Cross-repo configuration relationship maps
- Documentation of discovery, contribution, and validation workflows
- State Hub workplans and agent instructions for atlas maintenance
## Out of Scope
- Storing secret values or live environment-specific configuration
- Owning application runtime or deployment execution
- Replacing repo-local configuration files or secret stores (OpenBao, etc.)
- Acting as the canonical repo template (`repo-seed` owns that)
## Current State
- Bootstrapped from `repo-seed` on 2026-06-26; State Hub registration complete.
- Identity files customized; bootstrap workplan ATLAS-WP-0001 in progress.
- Registry still carries inherited template artifacts — see ATLAS-WP-0002.
## Getting Oriented
- Boundary: `SCOPE.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`
- Registry: `registry/`

View File

@@ -1,16 +1,35 @@
# repo-seed
# config-atlas
A git repository template to bootstrap coulomb projects from.
Federated configuration atlas for the Coulomb ecosystem — cataloging configuration
surfaces, schemas, defaults, ownership, and cross-repo relationships.
## Bootstrap a new repo
## Orient
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=<slug>`.
5. Validate with [docs/template-validation-checklist.md](docs/template-validation-checklist.md).
```bash
cat INTENT.md
cat SCOPE.md
cat .custodian-brief.md
ls workplans/
```
## Registry
This repo publishes `capability.infotech.repo-template` — see
`registry/capabilities/capability.infotech.repo-template.md`.
Configuration surface entries live under `registry/`. After registry or workplan
edits, sync with State Hub:
```bash
cd ~/state-hub && make fix-consistency REPO=config-atlas
```
Validate registry structure (from a `reuse-surface` checkout):
```bash
reuse-surface validate --root /home/worsch/config-atlas
```
## Governance
- **INTENT.md** — why the atlas exists and core principles
- **SCOPE.md** — in/out scope and current state
- **AGENTS.md** — agent session protocol and workplan conventions
- **workplans/** — canonical work items (ADR-001)

View File

@@ -6,26 +6,59 @@
## One-liner
Git repository template to bootstrap coulomb projects.
Federated configuration atlas — cataloging configuration surfaces, schemas,
defaults, ownership, and cross-repo relationships across the Coulomb ecosystem.
---
## Core Idea
repo-seed is the canonical template for new repos: agent instructions, registry scaffold, and onboarding conventions.
`config-atlas` indexes **configuration surfaces**: bounded, named places where
configuration is defined, read, or overridden (files, env vars, APIs, feature
flags, policy bundles, deployment parameters). Each surface gets a registry entry
with ownership, scope, validation hooks, and links to canonical sources.
The atlas helps agents and operators answer:
1. What configuration exists for a repo, capability, or deployment context?
2. Who owns it and where is the source of truth?
3. What are the safe defaults and precedence rules?
4. Which other surfaces depend on or override it?
---
## In Scope
- Template files for new repo bootstrap
- Documentation for statehub_register usage
- Registry capability entry for template capability
- Configuration surface registry (`registry/`) with indexes and capability entries
- Schema and naming conventions for atlas entries
- Cross-repo relationship documentation (consumes, overrides, extends)
- Contribution and validation workflow docs
- State Hub workplans and agent orientation files
---
## Out of Scope
- Application runtime code
- Owning downstream project implementations
- Secret values, credentials, or environment-specific live config
- Application runtime, deployment automation, or config push/pull engines
- Owning downstream repo implementations or their local config files
- Template bootstrap mechanics (`repo-seed` and `statehub register`)
---
## Current State
- State Hub integration bootstrapped (ATLAS-WP-0001).
- Inherited `repo-seed` registry and template docs pending replacement
(ATLAS-WP-0002).
- No application runtime; markdown-first registry and planning repo.
---
## Getting Oriented
- Start with: `INTENT.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`
- Verify: `cat .custodian-brief.md` ; `ls workplans/` ; from `~/state-hub`:
`make fix-consistency REPO=config-atlas`

View File

@@ -0,0 +1,68 @@
---
id: ATLAS-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: infotech
repo: config-atlas
status: finished
owner: codex
topic_slug: custodian
created: "2026-06-26"
updated: "2026-06-26"
state_hub_workstream_id: "74c1f6bb-9b4d-4640-aa1f-1c7e2116883a"
---
# Bootstrap State Hub integration
Federated configuration atlas for the Coulomb ecosystem.
## Review Generated Integration Files
```task
id: ATLAS-WP-0001-T01
status: done
priority: high
state_hub_task_id: "bb307d50-d3bc-4487-9170-cd54221fee8d"
```
Result 2026-06-26: Customized INTENT.md, SCOPE.md, AGENTS.md, README.md,
`.claude/rules/*`, and `.repo-classification.yaml` for config-atlas. Removed
inherited REPO-WP template workplans.
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: ATLAS-WP-0001-T02
status: done
priority: high
state_hub_task_id: "f4d28bd5-2577-44f2-b7b8-df3adaa1effb"
```
Result 2026-06-26: Documented orient, validate, and fix-consistency commands in
AGENTS.md and `.claude/rules/stack-and-commands.md`. No install/test/build/run
(no application runtime).
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: ATLAS-WP-0001-T03
status: done
priority: medium
state_hub_task_id: "8f641e16-ab62-427d-af6b-04f3e5778239"
```
Result 2026-06-26: Created ATLAS-WP-0002 (configuration atlas registry foundation).
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=config-atlas
```

View File

@@ -0,0 +1,66 @@
---
id: ATLAS-WP-0002
type: workplan
title: "Configuration atlas registry foundation"
domain: infotech
repo: config-atlas
status: ready
owner: codex
topic_slug: custodian
created: "2026-06-26"
updated: "2026-06-26"
state_hub_workstream_id: "27b42720-1bd7-4755-ab2f-59a6d095a2c3"
---
# Configuration atlas registry foundation
Replace inherited `repo-seed` template artifacts with config-atlas-specific
registry scaffold and establish the configuration surface model.
## Define configuration surface schema
```task
id: ATLAS-WP-0002-T01
status: todo
priority: high
state_hub_task_id: "125a4ad3-ddd4-4aee-bb94-9433a5fa4651"
```
Document the configuration surface model: required fields (id, name, owner,
source path, scope, validation), naming conventions, and index file layout.
Add schema docs under `registry/` (e.g. `registry/README.md` expansion and a
`docs/configuration-surface-schema.md` reference).
## Replace inherited template registry
```task
id: ATLAS-WP-0002-T02
status: todo
priority: high
state_hub_task_id: "2d8e41e9-ba93-4a1a-862b-993da03df1f9"
```
Remove `capability.infotech.repo-template` and other repo-seed artifacts from
`registry/`. Add the config-atlas capability entry and update
`registry/indexes/capabilities.yaml`. Remove or relocate inherited template
consumer docs (`docs/template-validation-checklist.md`,
`docs/statehub-register.md`) — those belong in `repo-seed`.
## Seed initial configuration surfaces
```task
id: ATLAS-WP-0002-T03
status: todo
priority: medium
state_hub_task_id: "9b8bb1c2-a6ee-4b6e-91a4-2cd902fb52ff"
```
Index 35 high-value configuration surfaces already present in the ecosystem
(e.g. State Hub API config, warden routing catalog, reuse-surface registry
layout). Each entry must link to canonical source files, not duplicate values.
After workplan file updates, run from `~/state-hub`:
```bash
make fix-consistency REPO=config-atlas
```

View File

@@ -1,67 +0,0 @@
---
id: REPO-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: infotech
repo: repo-seed
status: finished
owner: codex
topic_slug: infotech
created: "2026-06-22"
updated: "2026-06-22"
state_hub_workstream_id: "b809c762-8675-470c-be3e-0e5552f7d79d"
---
# Bootstrap State Hub integration
Git repository template to bootstrap coulomb projects.
## Review Generated Integration Files
```task
id: REPO-WP-0001-T01
status: done
priority: high
state_hub_task_id: "65734e48-ec48-47f2-bd5c-5673e94343cc"
```
Result 2026-06-22: Filled SCOPE.md; README is canonical intent.
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed.
## Verify Local Developer Workflow
```task
id: REPO-WP-0001-T02
status: done
priority: high
state_hub_task_id: "76f1c245-3f06-4ef7-943f-bf2e9722c71b"
```
Result 2026-06-22: Template workflow documented.
Identify the repo's install, test, lint, build, and run commands. Add or refine
those commands in the agent instructions so future coding sessions can verify
changes confidently.
## Seed First Real Workplan
```task
id: REPO-WP-0001-T03
status: done
priority: medium
state_hub_task_id: "9670ff11-ed7a-49e6-8a1f-944af9794f6a"
```
Result 2026-06-22: Created REPO-WP-0002.
Create the first implementation workplan for the repository's most important
next change. After workplan file updates, run from `~/state-hub`:
```bash
make fix-consistency REPO=repo-seed
```

View File

@@ -1,34 +0,0 @@
---
id: REPO-WP-0002
type: workplan
title: "Template consumer validation checklist"
domain: infotech
repo: repo-seed
status: finished
owner: codex
topic_slug: infotech
created: "2026-06-22"
updated: "2026-06-24"
state_hub_workstream_id: "8aaf98a0-7045-4d5b-915f-bc9ecc5aa319"
---
# Template consumer validation checklist
Validate repo-seed against statehub_register output and document consumer steps.
## Template validation checklist
```task
id: REPO-WP-0002-T01
status: done
priority: high
state_hub_task_id: "a1b0aaab-f0dc-4bd0-bde3-89635ac0ca3b"
```
Result 2026-06-24: Added `docs/statehub-register.md` (consumer guide),
`docs/template-validation-checklist.md` (bootstrap verification checklist),
`registry/capabilities/capability.infotech.repo-template.md` with index entry,
and README bootstrap pointers. Validated register output structure against
`statehub_register.write_registration_files`.
Author checklist for new repo bootstrap: register, agent files, first workplan, fix-consistency.