From 1aa5e436ae354b87d0b52df55e14201445e485c3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 1 Mar 2026 20:05:22 +0100 Subject: [PATCH] fix(CLAUDE.md): rewrite session protocol to surface custodian tasks on open MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CLAUDE.md | 147 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 98 insertions(+), 49 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4c37b78..38bb248 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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`) exposes tools for reading and writing state without touching the API directly. +--- + ### Session Protocol -**On receiving your first message — before writing any response text — call -`get_state_summary()` immediately.** Do not greet, do not ask what to do. -Call the tool first, then respond based on what you find. +**On receiving your first message — before writing any response text — execute +this orientation sequence. Do not greet, do not ask what to do first.** -**At the start of every session:** -1. Call `get_state_summary()` — orients you to active workstreams, blocking decisions, - and recent progress. If it fails, the API is likely 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. -3. Check whether the `railiance` topic has any open workstreams in the summary. - - **If workstreams exist:** review blocking decisions before starting work. - - **If no workstreams exist:** follow the First Session Protocol below. +**Step 1 — Call the State Hub** +``` +get_state_summary() # orientation: workstreams, decisions, recent progress +get_next_steps() # contextual suggestions from resolved decisions +``` +If the call fails, the API is offline: `cd ~/the-custodian/state-hub && make api` + +**Step 2 — Scan local workplans** + +Read every file matching `workplans/*.md` in this repo. For each one with +`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:** - Use `record_decision()` for any decision that affects direction or dependencies. - 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 - of the two sanctioned write operations in the hub. +- Use `resolve_decision()` to close a decision once the choice is made. > **Design boundary:** The State Hub is a *read model*. Two write operations are > permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**. -> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`) are -> only for First Session Protocol. Formal work structure belongs in the domain repo. +> Bootstrap tools are only for First Session Protocol. Work structure belongs +> in the domain repo as files (ADR-001). **At the end of every session:** -- Call `add_progress_event()` with a summary of what was accomplished or decided. - Include `topic_id: ca369340-a64e-442e-98f1-a4fa7dc74a38` and the relevant `workstream_id`. +- Call `add_progress_event()` with a summary of what was accomplished. + 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 -Triggered when `get_state_summary()` shows **no workstreams** for the `railiance` topic. -This means the project is registered but work has not yet been structured. +Triggered when `get_state_summary()` shows **no workstreams** for `railiance`. -**Step 1 — Understand the project (read, don't write)** -- `canon/projects/railiance/project_charter_v0.1.md` in `~/the-custodian/` — purpose, scope, success criteria -- `canon/projects/railiance/roadmap_v0.1.md` — planned phases -- Scan this repo root: README, directory structure, any existing code or docs +**Step 1** — Read `~/the-custodian/canon/projects/railiance/project_charter_v0.1.md` +and `roadmap_v0.1.md`, then scan this repo root. -**Step 2 — Survey in-progress work** -- Look for TODOs, open branches, half-finished files, or notes -- Note what is already done vs. what is clearly started but incomplete +**Step 2** — Survey in-progress work (TODOs, open branches, half-finished files). -**Step 3 — Propose workstreams to Bernd** -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 +**Step 3** — Propose 1–3 workstreams. Wait for approval before creating anything. -Present the proposals and **wait for approval before creating anything**. - -**Step 4 — Create and populate (after approval)** +**Step 4** — Create workplan file first (`workplans/RAIL-WP-NNNN-.md`), +then register in hub: ``` -create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", title="...", owner="...", description="...") -create_task(workstream_id="", title="...", priority="high|medium|low") -# repeat for each task in the workstream +create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", ...) +create_task(workstream_id="", ...) ``` -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( - summary="First session: structured railiance work into N workstreams, M tasks", - event_type="milestone", - topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", - detail={"workstreams": [...], "tasks_created": M} -) +contrib/ + bug-reports/ # br-YYYY-MM-DD--org--repo--slug.md + feature-requests/ # fr-YYYY-MM-DD--org--repo--slug.md + extension-points/ # EP-RAIL-NNN--org--repo--slug.md + 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 -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