coulomb/railiance-cluster
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix(CLAUDE.md): rewrite session protocol to surface custodian tasks on open

Browse source 
Previous CLAUDE.md only had a First Session Protocol. When workstreams already
existed, the session would call get_state_summary() and produce no useful output.

New 3-step protocol:
- Step 1: get_state_summary() + get_next_steps() via state-hub MCP tools
- Step 2: scan workplans/*.md for active tasks
- Step 3: output orientation brief: active workstreams, pending repo tasks
  (from workplans/ + [repo:railiance-bootstrap] state hub tasks), suggested
  next action, SBOM status (currently null — gap noted)

Also adds Known Pending Tasks table for RAIL-BS-WP-0001 (dep management)
and strengthens ADR-001 workplan convention and contribution tracking sections.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
tegwick 2026-03-01 20:05:22 +01:00
parent 44428655d2
commit 1aa5e436ae
1 changed files with 98 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

147
CLAUDE.md
View file

@ -8,79 +8,128 @@ Hub topic ID: `ca369340-a64e-442e-98f1-a4fa7dc74a38`
The State Hub runs locally at http://127.0.0.1:8000. The MCP server (`state-hub`) The State Hub runs locally at http://127.0.0.1:8000. The MCP server (`state-hub`)
exposes tools for reading and writing state without touching the API directly. exposes tools for reading and writing state without touching the API directly.
---
### Session Protocol ### Session Protocol
**On receiving your first message — before writing any response text — call **On receiving your first message — before writing any response text — execute
`get_state_summary()` immediately.** Do not greet, do not ask what to do. this orientation sequence. Do not greet, do not ask what to do first.**
Call the tool first, then respond based on what you find.
**At the start of every session:** **Step 1 — Call the State Hub**
1. Call `get_state_summary()` — orients you to active workstreams, blocking decisions, ```
and recent progress. If it fails, the API is likely offline: get_state_summary() # orientation: workstreams, decisions, recent progress
``` get_next_steps() # contextual suggestions from resolved decisions
cd ~/the-custodian/state-hub && make api ```
``` If the call fails, the API is offline: `cd ~/the-custodian/state-hub && make api`
2. Call `get_next_steps()` — surfaces contextual suggestions from recently resolved
decisions and cleared workstream dependencies. Act on these before starting new work. **Step 2 — Scan local workplans**
3. Check whether the `railiance` topic has any open workstreams in the summary.
- **If workstreams exist:** review blocking decisions before starting work. Read every file matching `workplans/*.md` in this repo. For each one with
- **If no workstreams exist:** follow the First Session Protocol below. `status: active`, extract and note:
- The workplan title and ID
- All tasks whose `status` is `todo` or `in_progress`
**Step 3 — Present orientation to the user**
Output a concise brief covering:
1. **Active workstreams** for the `railiance` domain — title, task counts,
any blocking decisions
2. **Pending tasks for this repo** — from local `workplans/` files (Step 2)
plus any state hub tasks with `[repo:railiance-bootstrap]` in their title
3. **Suggested next action** — the highest-priority open item across both sources
4. **SBOM status** — `last_sbom_at` for `railiance-bootstrap` is currently null
(gap: no lockfile yet — see `workplans/RAIL-BS-WP-0001-dependency-management.md`)
**During work:** **During work:**
- Use `record_decision()` for any decision that affects direction or dependencies. - Use `record_decision()` for any decision that affects direction or dependencies.
- Use `add_progress_event()` for notable events (milestones, blockers, insights). - Use `add_progress_event()` for notable events (milestones, blockers, insights).
- Use `resolve_decision()` to close a decision once the choice is made — this is one - Use `resolve_decision()` to close a decision once the choice is made.
of the two sanctioned write operations in the hub.
> **Design boundary:** The State Hub is a *read model*. Two write operations are > **Design boundary:** The State Hub is a *read model*. Two write operations are
> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**. > permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**.
> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`) are > Bootstrap tools are only for First Session Protocol. Work structure belongs
> only for First Session Protocol. Formal work structure belongs in the domain repo. > in the domain repo as files (ADR-001).
**At the end of every session:** **At the end of every session:**
- Call `add_progress_event()` with a summary of what was accomplished or decided. - Call `add_progress_event()` with a summary of what was accomplished.
Include `topic_id: ca369340-a64e-442e-98f1-a4fa7dc74a38` and the relevant `workstream_id`. Include `topic_id: ca369340-a64e-442e-98f1-a4fa7dc74a38` and `workstream_id`.
---
### Known Pending Tasks (as of 2026-03-01)
**RAIL-BS-WP-0001 — Dependency Management** (`workplans/RAIL-BS-WP-0001-dependency-management.md`)
The SBOM scanner finds nothing to ingest because Ansible and control-node pip
dependencies are not declared in any lockfile. This is the top-priority open
task for this repo.
| Task | Priority | Status |
|------|----------|--------|
| T01: Audit control-node pip deps | medium | todo |
| T02: Create pyproject.toml + uv.lock | medium | todo |
| T03: Ingest SBOM into State Hub | medium | todo |
| T04: Create ansible/requirements.yml | low | todo |
State Hub task ID: `5f8cade5-119c-42e8-ba93-e9d0478650e4`
---
### First Session Protocol ### First Session Protocol
Triggered when `get_state_summary()` shows **no workstreams** for the `railiance` topic. Triggered when `get_state_summary()` shows **no workstreams** for `railiance`.
This means the project is registered but work has not yet been structured.
**Step 1 — Understand the project (read, don't write)** **Step 1** — Read `~/the-custodian/canon/projects/railiance/project_charter_v0.1.md`
- `canon/projects/railiance/project_charter_v0.1.md` in `~/the-custodian/` — purpose, scope, success criteria and `roadmap_v0.1.md`, then scan this repo root.
- `canon/projects/railiance/roadmap_v0.1.md` — planned phases
- Scan this repo root: README, directory structure, any existing code or docs
**Step 2 — Survey in-progress work** **Step 2** — Survey in-progress work (TODOs, open branches, half-finished files).
- Look for TODOs, open branches, half-finished files, or notes
- Note what is already done vs. what is clearly started but incomplete
**Step 3 — Propose workstreams to Bernd** **Step 3** — Propose 1–3 workstreams. Wait for approval before creating anything.
Based on what you found, propose 1–3 workstreams. Each workstream should be:
- A coherent strand of work lasting weeks to months (not a single task)
- Named clearly enough that its scope is obvious
- Anchored to a phase in the roadmap if possible
Present the proposals and **wait for approval before creating anything**. **Step 4** — Create workplan file first (`workplans/RAIL-WP-NNNN-<slug>.md`),
then register in hub:
**Step 4 — Create and populate (after approval)**
``` ```
create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", title="...", owner="...", description="...") create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", ...)
create_task(workstream_id="<id>", title="...", priority="high|medium|low") create_task(workstream_id="<id>", ...)
# repeat for each task in the workstream
``` ```
Aim for 3–7 tasks per workstream at this stage. Tasks should be concrete and actionable.
**Step 5 — Record the setup** **Step 5** — Record setup with `add_progress_event()`.
---
### Workplan Convention (ADR-001)
Work items originate as files in `workplans/` before being registered in the hub.
When the custodian creates a task for this repo, it places a workplan file here
AND creates a state hub task with `[repo:railiance-bootstrap]` in the title.
Both appear at session start via the orientation above.
---
### Contribution Tracking
``` ```
add_progress_event( contrib/
summary="First session: structured railiance work into N workstreams, M tasks", bug-reports/ # br-YYYY-MM-DD--org--repo--slug.md
event_type="milestone", feature-requests/ # fr-YYYY-MM-DD--org--repo--slug.md
topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", extension-points/ # EP-RAIL-NNN--org--repo--slug.md
detail={"workstreams": [...], "tasks_created": M} upstream-prs/ # upr-YYYY-MM-DD--org--repo--slug.md
)
``` ```
Templates: `~/the-custodian/canon/standards/contrib-templates/`
---
### SBOM
After creating and committing the lockfile (see RAIL-BS-WP-0001), ingest:
```bash
cd ~/the-custodian/state-hub
make ingest-sbom REPO=railiance-bootstrap SCAN=1 REPO_PATH=/home/worsch/railiance-bootstrap
```
---
### Quick Reference ### Quick Reference
See `~/the-custodian/state-hub/mcp_server/TOOLS.md` for a compact tool reference. `~/the-custodian/state-hub/mcp_server/TOOLS.md` — compact MCP tool reference