Normalize agent instructions and workplan frontmatter (STATE-WP-0067)

- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
This commit is contained in:
2026-06-22 23:16:24 +02:00
parent 35052500b1
commit 2f94943d97
16 changed files with 344 additions and 89 deletions

View File

@@ -1,25 +1,8 @@
## Architecture
`coulomb-loop` is a **markdown-first engagement layer** — no application runtime.
<!-- TODO: Describe the key design decisions and component structure.
Key modules, data flows, external integrations, state machines, etc. -->
```
activity-core (cron/event)
→ state-hub roster + coulomb-loop rosters
→ tasks on target repos
→ kaizen-agentic schedule prepare / metrics CLI
→ coding-agent sessions (supplier agents)
```
## Quick Reference
### Layers
| Layer | Repo | Role |
|-------|------|------|
| Customer contracts | coulomb-loop | Workplans, ADRs, ActivityDefinition copies, `loops/` |
| Supplier IP | kaizen-agentic | Agents, CLI, ADR-002006 |
| Scheduler | activity-core | Temporal schedules, resolvers |
| Roster | state-hub | Repo list, workstreams, events |
| Execution state | target repos | `.kaizen/schedule.yml`, memory, metrics |
### Four loops
See `INTENT.md` and LOOP-WP-00010004. LOOP-WP-0004 regulates cadence (ADR-003).
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

View File

@@ -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 "<describe your need>" --json
warden route show <catalog-id> --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=coulomb-loop` 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`

View File

@@ -1,11 +1,11 @@
## First Session Protocol
Triggered when `get_domain_summary("coulomb_social")` shows **no workstreams**.
Triggered when `get_domain_summary("communication")` shows **no workstreams**.
The project is registered but work has not yet been structured.
**Step 1 — Read, don't write**
- `~/the-custodian/canon/projects/coulomb_social/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/coulomb_social/roadmap_v0.1.md` — planned phases
- `~/the-custodian/canon/projects/communication/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/communication/roadmap_v0.1.md` — planned phases
- Scan repo root: README, directory structure, existing code or docs
**Step 2 — Survey in-progress work**
@@ -17,7 +17,7 @@ roadmap phase. **Wait for approval before creating.**
**Step 4 — Create workplan file first, then DB record (ADR-001)**
```
workplans/COULOMB-WP-NNNN-<slug>.md ← write this first
workplans/LOOP-WP-NNNN-<slug>.md ← write this first
```
Then register in the hub:
```
@@ -28,7 +28,7 @@ create_task(workstream_id="<id>", title="...", priority="high|medium|low")
**Step 5 — Record the setup**
```
add_progress_event(
summary="First session: structured coulomb_social into N workstreams, M tasks",
summary="First session: structured communication into N workstreams, M tasks",
event_type="milestone",
topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc",
detail={"workstreams": [...], "tasks_created": M}

View File

@@ -1,11 +1,8 @@
## Repo boundary
This repo owns **coulomb-loop engagement operations** only. It does not own:
This repo owns **coulomb-loop** only. It does not own:
- Kaizen agent definitions `kaizen-agentic`
- activity-core resolvers and Temporal workers → `activity-core`
- State-hub API/MCP`state-hub` / `the-custodian`
- reuse-surface CLI and federation hub → `reuse-surface`
- Target repo `.kaizen/` state → each fleet repo checkout
Cross-repo handoffs are documented in loop workplans and `docs/adr/ADR-002-customer-supplier-boundary.md`.
<!-- TODO: List what belongs in adjacent repos, e.g.:
- SSH key management → railiance-infra/
- State hub code → state-hub/
-->

View File

@@ -1,15 +1,5 @@
## Repo Identity
**Purpose:** Coulomb fleet self-improvement loop engagement — customer repo for scheduled kaizen-agentic supplier operations.
**Purpose:** coulomb-loop — Coulomb customer engagement repo for fleet self-improvement loops operated with kaizen-agentic as supplier.
**Domain:** coulomb_social
**Domain:** communication
**Repo slug:** coulomb-loop
**Topic ID:** 36c7421b-c537-4723-bf75-42a3ebc6a1dc
**Supplier:** `kaizen-agentic` (agents, CLI, playbook — not merged into this repo)
**Custodian integration:** Registered in state-hub. Workplans use `LOOP-WP` prefix (ADR-001). Sync after workplan edits:
```bash
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
```

View File

@@ -1,6 +1,7 @@
## Session Protocol
State Hub: http://127.0.0.1:8000
Dev Hub (State Hub API): http://127.0.0.1:8000
MCP server name in `~/.claude.json`: `dev-hub`
**Step 1 — Orient**
@@ -10,7 +11,7 @@ cat .custodian-brief.md
```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
```
get_domain_summary("coulomb_social")
get_domain_summary("communication")
```
If MCP tools are unavailable in the current agent session, use the REST API:
```bash
@@ -43,7 +44,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
**Step 4 — Present brief**
1. **Active workstreams** for `coulomb_social` — title, task counts, blocking decisions
1. **Active workstreams** for `communication` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:coulomb-loop]` hub tasks
3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*

View File

@@ -1,28 +1,19 @@
## Stack and Commands
## Stack
**Language:** Markdown / YAML coordination artefacts
**Package manager:** none
**Test runner:** none
<!-- TODO: Fill in language, frameworks, and key dependencies -->
- **Language:**
- **Key deps:**
### Essential commands
## Dev Commands
```bash
# Sync workplans to state-hub after edits
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
# TODO: Fill in the standard commands for this repo
# Validate reuse-surface registry (when entries exist)
reuse-surface validate
# Install dependencies
# Supplier CLI on target repos (not this repo)
kaizen-agentic schedule validate --target /path/to/target-repo
kaizen-agentic schedule prepare coach --target /path/to/target-repo
# Run tests
# Lint / type check
# Build / package (if applicable)
```
### Session orientation
```bash
# MCP when available
get_domain_summary("coulomb_social")
```
Fallback: `.custodian-brief.md`

View File

@@ -1,17 +1,40 @@
## Workplan Convention (ADR-001)
File location: `workplans/LOOP-WP-NNNN-<slug>.md`
ID prefix: `LOOP-WP` (see `docs/adr/ADR-001-workplan-prefix.md`)
ID prefix: `LOOP-WP-`
Work items originate as files in this repo **before** being registered in the hub.
Ecosystem todos from supplier or other agents arrive as `[repo:coulomb-loop]` hub tasks.
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.
After workplan file updates:
Closed workplans may be moved to `workplans/archived/` with a completion-date
prefix: `YYMMDD-LOOP-WP-NNNN-<slug>.md`. The frontmatter id remains
unchanged; the prefix is only for quick visual reference.
```bash
cd ~/state-hub && make fix-consistency REPO=coulomb-loop
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:coulomb-loop]` 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: LOOP-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
```
Customer loop workplans: LOOP-WP-0000 (bootstrap), LOOP-WP-00010004 (loops).
Supplier mirror: `kaizen-agentic` KAIZEN-WP-0008.
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 -->

219
AGENTS.md Normal file
View File

@@ -0,0 +1,219 @@
# coulomb-loop — Agent Instructions
## Repo Identity
**Purpose:** Coulomb fleet self-improvement loop engagement — customer repo for scheduled kaizen-agentic supplier operations.
**Domain:** communication
**Repo slug:** coulomb-loop
**Topic ID:** `36c7421b-c537-4723-bf75-42a3ebc6a1dc`
**Workplan prefix:** `LOOP-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=36c7421b-c537-4723-bf75-42a3ebc6a1dc&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=coulomb-loop&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/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": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workstream_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-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/<task_id>" \
-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=coulomb-loop&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=coulomb-loop
```
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 "<describe your need>" --json
warden route show <catalog-id> --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=coulomb-loop` 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`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## 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/COULOMB-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-COULOMB-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
`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: COULOMB-WP-NNNN
type: workplan
title: "..."
domain: communication
repo: coulomb-loop
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # 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: COULOMB-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
` ` `
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=coulomb-loop`
(or send a message to the hub agent via `POST /messages/`)

View File

@@ -8,4 +8,5 @@
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/credential-routing.md
@.claude/rules/agents.md

View File

@@ -2,11 +2,11 @@
id: LOOP-WP-0000
type: workplan
title: "Engagement bootstrap (registration, assessment, governance)"
domain: coulomb_social
domain: communication
repo: coulomb-loop
status: done
owner: coulomb-loop
topic_slug: coulomb_social
topic_slug: coulomb-social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-18"

View File

@@ -2,11 +2,11 @@
id: LOOP-WP-0001
type: workplan
title: "Kaizen Improvement Stack (coach + metrics + optimization)"
domain: coulomb_social
domain: communication
repo: coulomb-loop
status: done
owner: coulomb-loop
topic_slug: coulomb_social
topic_slug: coulomb-social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-18"

View File

@@ -2,11 +2,11 @@
id: LOOP-WP-0002
type: workplan
title: "Reactive Quality Escalation (signal-driven improvement)"
domain: coulomb_social
domain: communication
repo: coulomb-loop
status: finished
owner: coulomb-loop
topic_slug: coulomb_social
topic_slug: coulomb-social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-18"

View File

@@ -2,11 +2,11 @@
id: LOOP-WP-0003
type: workplan
title: "Registry & Orientation Hygiene (fleet legibility)"
domain: coulomb_social
domain: communication
repo: coulomb-loop
status: done
owner: coulomb-loop
topic_slug: coulomb_social
topic_slug: coulomb-social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-18"

View File

@@ -2,11 +2,11 @@
id: LOOP-WP-0004
type: workplan
title: "Loop Regulator (second-order improvement)"
domain: coulomb_social
domain: communication
repo: coulomb-loop
status: done
owner: coulomb-loop
topic_slug: coulomb_social
topic_slug: coulomb-social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-18"

View File

@@ -2,11 +2,11 @@
id: LOOP-WP-0005
type: workplan
title: "Operate phase observation and fleet expansion prep"
domain: coulomb_social
domain: communication
repo: coulomb-loop
status: done
owner: coulomb-loop
topic_slug: coulomb_social
topic_slug: coulomb-social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-19"