generated from coulomb/repo-seed
tegwick
f34b49ebde
S0 — Design boundary formalised across all integration surfaces:
- TOOLS.md restructured with Design Boundary section, Sanctioned Write Tools,
and Bootstrap-Only Tools (create_workstream, create_task) with explicit note
- project_claude_md.template and railiance CLAUDE.md updated with boundary note
and get_next_steps() in session start protocol
- Global ~/.claude/CLAUDE.md updated accordingly
S1 — Workstream dependency graph:
- WorkstreamDependency model (directed edge, CASCADE on delete, unique pair constraint)
- Alembic migration 0b547c153153; script.py.mako added (was missing)
- REST API: POST/GET /workstreams/{id}/dependencies/, DELETE …/{dep_id} (hard delete)
- StateSummary open_workstreams enriched with depends_on/blocks lists
- MCP tools: create_dependency(), list_dependencies()
- Dashboard workstreams page: Dependencies section with relationship cards
- Seeded: custodian-agent-runtime → llm-shared-library + phase-0-operational-baseline
S2 — Suggesting Next Steps (sanctioned write use case #2):
- GET /state/next_steps derives suggestions from recently resolved decisions
(→ first open task in same workstream) and cleared dependencies
(→ first todo task in now-unblocked workstream)
- StateSummary.next_steps included on every summary call
- MCP tool: get_next_steps()
- Dashboard: "What's next?" card grid above Registered Projects
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
88 lines
3.8 KiB
Plaintext
88 lines
3.8 KiB
Plaintext
# {PROJECT_NAME} — Claude Code Instructions
|
||
|
||
## Custodian State Hub Integration
|
||
|
||
This project is tracked as the **{DOMAIN}** domain in the Custodian State Hub.
|
||
Hub topic ID: `{TOPIC_ID}`
|
||
|
||
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 this domain 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** (v0.2).
|
||
> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`) are
|
||
> only for First Session Protocol. Formal work structure — requirements, workplans,
|
||
> milestones, tasks — belongs in the domain repo, not managed through the hub.
|
||
|
||
**At the end of every session:**
|
||
- Call `add_progress_event()` with a summary of what was accomplished or decided.
|
||
Include `topic_id: {TOPIC_ID}` and the relevant `workstream_id`.
|
||
|
||
### First Session Protocol
|
||
|
||
Triggered when `get_state_summary()` shows **no workstreams** for the `{DOMAIN}` 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/{DOMAIN}/project_charter_v0.1.md` — purpose, scope, success criteria
|
||
- `canon/projects/{DOMAIN}/roadmap_v0.1.md` — planned phases
|
||
- Scan the 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="{TOPIC_ID}", 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 {DOMAIN} work into N workstreams, M tasks",
|
||
event_type="milestone",
|
||
topic_id="{TOPIC_ID}",
|
||
detail={"workstreams": [...], "tasks_created": M}
|
||
)
|
||
```
|
||
|
||
### Quick Reference
|
||
|
||
See `~/the-custodian/state-hub/mcp_server/TOOLS.md` for a compact tool reference.
|