railiance-cluster/CLAUDE.md

railiance-bootstrap — Claude Code Instructions

Custodian State Hub Integration

This project is tracked as the railiance domain in the Custodian State Hub. 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.

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.

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.

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.

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.

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.

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 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 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

Present the proposals and wait for approval before creating anything.

Step 4 — Create and populate (after approval)

create_workstream(topic_id="ca369340-a64e-442e-98f1-a4fa7dc74a38", title="...", owner="...", description="...")
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
# 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

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}
)

Quick Reference

See ~/the-custodian/state-hub/mcp_server/TOOLS.md for a compact tool reference.