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. 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 create_task() / update_task_status() to track concrete deliverables.
• Use record_decision() for any decision that affects direction or dependencies.
• Use add_progress_event() for notable events (milestones, blockers, insights).

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.