From 64bc9c3f161455c39774f473ecf2e2ae8044b5b4 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 8 Jul 2026 14:50:33 +0200 Subject: [PATCH] Regenerate agent instructions from state-hub templates (CUST-WP-0055 T01) Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules templates: workplan-first session protocol, legacy terminology footnote, and GET /workplans/ examples. --- .claude/rules/credential-routing.md | 2 +- .claude/rules/first-session.md | 12 ++++++------ .claude/rules/repo-identity.md | 4 ++-- .claude/rules/session-protocol.md | 22 ++++++++++------------ .claude/rules/workplan-convention.md | 18 ++++++++++++++---- AGENTS.md | 12 ++++++------ CLAUDE.md | 2 +- 7 files changed, 40 insertions(+), 32 deletions(-) diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md index 64b8403..7c1b89a 100644 --- a/.claude/rules/credential-routing.md +++ b/.claude/rules/credential-routing.md @@ -19,7 +19,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=railiance-cluster` is for coordination, not secret vending | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=railiance-bootstrap` is for coordination, not secret vending | | **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **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` | diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index a7ac6ec..15e4e05 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -20,14 +20,14 @@ roadmap phase. **Wait for approval before creating.** workplans/RAIL-BS-WP-NNNN-.md ← write this, commit it ``` Then register by running the consistency check — do **not** call -`create_workplan`/`create_task` (or legacy `create_workstream`) yourself; -manual registration duplicates what C-06 creates from the file: +`create_workplan`/`create_task` yourself; manual registration duplicates what +C-06 creates from the file: ```bash -statehub fix-consistency --repo railiance-cluster +statehub fix-consistency --repo railiance-bootstrap ``` -C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` / -`state_hub_task_id` back into the file (legacy field names, kept for -compatibility — they hold workplan/task IDs). +C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` +(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id` +back into the file. **Step 5 — Record the setup** ``` diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 60c065f..60ea14b 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -1,5 +1,5 @@ -**Purpose:** OAS S2 Cluster Runtime — k3s, Helm, ingress, CNI, operators +**Purpose:** Infrastructure bootstrap and configuration management for the railiance domain. Contains Ansible playbooks, cluster provisioning scripts, and environment safety nets. **Domain:** financials -**Repo slug:** railiance-cluster +**Repo slug:** railiance-bootstrap **Topic ID:** ca369340-a64e-442e-98f1-a4fa7dc74a38 diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 729db36..510de60 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -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="railiance-cluster", unread_only=True) +get_messages(to_agent="railiance-bootstrap", 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=railiance-cluster&unread_only=true" \ +curl -s "http://127.0.0.1:8000/messages/?to_agent=railiance-bootstrap&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 '{}' @@ -45,7 +45,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending **Step 4 — Present brief** 1. **Active workplans** for `financials` — title, task counts, blocking decisions -2. **Pending tasks** from `workplans/` + any `[repo:railiance-cluster]` hub tasks +2. **Pending tasks** from `workplans/` + any `[repo:railiance-bootstrap]` 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 @@ -57,15 +57,13 @@ If no workplans: follow First Session Protocol (`first-session.md`). **During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` > State Hub is a *read model*. **Never register workplans or tasks by hand** -> (`create_workplan`, `create_task`, or the legacy `create_workstream`) — write -> the workplan file in `workplans/` and run `fix-consistency`; its C-06 check -> registers the workplan and its tasks in the hub and writes the IDs back into -> the file. Manual registration creates duplicates the moment fix-consistency -> runs. Work structure belongs in repo files (ADR-001). +> (`create_workplan`, `create_task`) — write the workplan file in `workplans/` +> and run `fix-consistency`; C-06 registers the workplan and tasks and writes +> IDs back into the file. Manual registration creates duplicates when +> fix-consistency runs. Work structure belongs in repo files (ADR-001). > -> Terminology: "workstream" is the legacy name for workplan. Some API/frontmatter -> field names keep it for compatibility (`state_hub_workstream_id`, -> `workstream_id` params) — treat them as workplan IDs. +> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases — +> see `workplan-convention.md` (compatibility footnote). **Session close:** With MCP tools: @@ -87,7 +85,7 @@ statehub fix-consistency For repos where implementation runs on a remote machine (e.g. CoulombCore), use the pull-before-fix mode from any shell with the State Hub CLI: ```bash -statehub fix-consistency --repo railiance-cluster --remote +statehub fix-consistency --repo railiance-bootstrap --remote ``` **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 diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index f01c779..d4fbc2b 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -21,10 +21,10 @@ 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:railiance-cluster]` hub tasks — +Ecosystem todos from other agents arrive as `[repo:railiance-bootstrap]` hub tasks — visible at session start. Pick one up by creating the workplan file, committing, and running `statehub fix-consistency` — C-06 registers the workplan in the hub. -Never register by hand with `create_workplan`/`create_workstream`. +Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`). Task blocks use this shape: @@ -39,7 +39,17 @@ Status progression is `todo` → `progress` → `done`; use `wait` for waiting o blocked work and `cancel` for stopped work. Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name -kept for compatibility ("workstream" is the old term for workplan); it holds -the hub workplan id and is written by fix-consistency. Do not edit or rename it. +kept for compatibility; it holds the hub workplan UUID and is written by +fix-consistency. Do not edit or rename it. + +### Legacy terminology (compatibility footnote) + +**Workplan** is the fleet term — see +`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`. +**Workstream** is legacy only: some API routes (`/workstreams/`), params +(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field +above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those +identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new +examples and scripts. diff --git a/AGENTS.md b/AGENTS.md index 07b9576..882576c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,11 +1,11 @@ -# railiance-cluster — Agent Instructions +# railiance-bootstrap — Agent Instructions ## Repo Identity -**Purpose:** OAS S2 Cluster Runtime — k3s, Helm, ingress, CNI, operators +**Purpose:** Infrastructure bootstrap and configuration management for the railiance domain. Contains Ansible playbooks, cluster provisioning scripts, and environment safety nets. **Domain:** financials -**Repo slug:** railiance-cluster +**Repo slug:** railiance-bootstrap **Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38` **Workplan prefix:** `RAIL-BS-WP-` @@ -38,7 +38,7 @@ curl -s "http://127.0.0.1:8000/workplans/?topic_id=ca369340-a64e-442e-98f1-a4fa7 | python3 -m json.tool # Check inbox -curl -s "http://127.0.0.1:8000/messages/?to_agent=railiance-cluster&unread_only=true" \ +curl -s "http://127.0.0.1:8000/messages/?to_agent=railiance-bootstrap&unread_only=true" \ | python3 -m json.tool ``` @@ -87,7 +87,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ **Start:** 1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) -2. Check inbox: `GET /messages/?to_agent=railiance-cluster&unread_only=true`; mark read +2. Check inbox: `GET /messages/?to_agent=railiance-bootstrap&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` @@ -128,7 +128,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=railiance-cluster` is for coordination, not secret vending | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=railiance-bootstrap` is for coordination, not secret vending | | **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **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` | diff --git a/CLAUDE.md b/CLAUDE.md index 84f1c45..0d355f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# railiance-cluster — Claude Code Instructions +# railiance-bootstrap — Claude Code Instructions @SCOPE.md @.claude/rules/repo-identity.md