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.
This commit is contained in:
parent
c65e56acf1
commit
64bc9c3f16
7 changed files with 40 additions and 32 deletions
|
|
@ -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` |
|
||||
|
||||
|
|
|
|||
|
|
@ -20,14 +20,14 @@ roadmap phase. **Wait for approval before creating.**
|
|||
workplans/RAIL-BS-WP-NNNN-<slug>.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**
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/<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 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||
|
|
|
|||
12
AGENTS.md
12
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/<task_id>" \
|
|||
|
||||
**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` |
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# railiance-cluster — Claude Code Instructions
|
||||
# railiance-bootstrap — Claude Code Instructions
|
||||
|
||||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue