From fda64c8eba8d2035dac9019fdc5770de18584167 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Tue, 24 Feb 2026 23:43:39 +0100
Subject: [PATCH] Add First Session Protocol to project CLAUDE.md template

When get_state_summary() shows no workstreams for the domain, Claude
now has explicit instructions: read the canon charter + roadmap, survey
the repo for in-progress work, propose 1-3 workstreams to Bernd, wait
for approval, then create workstreams + tasks and record a milestone.

The "wait for approval before creating anything" gate keeps the human
in control while making the expected first-session behaviour unambiguous.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 scripts/project_claude_md.template | 44 +++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/scripts/project_claude_md.template b/scripts/project_claude_md.template
index 2ad0da2..88171b6 100644
--- a/scripts/project_claude_md.template
+++ b/scripts/project_claude_md.template
@@ -16,7 +16,9 @@ exposes tools for reading and writing state without touching the API directly.
    ```
    cd ~/the-custodian/state-hub && make api
    ```
-2. Review any `blocking_decisions` entries for this project before starting work.
+2. 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 `create_task()` / `update_task_status()` to track concrete deliverables.
@@ -27,6 +29,46 @@ exposes tools for reading and writing state without touching the API directly.
 - 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.