docs: add ThreePhoenix architecture concept and workplan

RailianceThreePhoenix: 3-node HA Kubernetes cluster with embedded etcd,
Longhorn distributed storage, PostgreSQL HA (repmgr + Pgpool-II), and
Phoenix CronJob for weekly node rotation to prevent configuration drift.

ThreePhoenixWorkplan: 7-phase implementation plan from blank Ubuntu nodes
to self-healing Gitea cluster with monitoring and alert silencing.

Also adds CLAUDE.md with Custodian State Hub session protocol.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-02-25 01:13:05 +01:00
parent b7696e657f
commit eb8a6902b6
3 changed files with 477 additions and 0 deletions

78
CLAUDE.md Normal file
View File

@@ -0,0 +1,78 @@
# 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 13 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 37 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.