state-hub/scripts/project_claude_md.template

# {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}
)
```

### Contribution Tracking

This project tracks upstream contributions in `contrib/` — bug reports, feature
requests, extension-point proposals, and upstream PRs — as canonical Markdown files.

**Directory layout:**
```
contrib/
  bug-reports/       # br-YYYY-MM-DD--org--repo--slug.md
  feature-requests/  # fr-YYYY-MM-DD--org--repo--slug.md
  extension-points/  # EP-{DOMAIN}-NNN--org--repo--slug.md
  upstream-prs/      # upr-YYYY-MM-DD--org--repo--slug.md
```

Templates: `~/the-custodian/canon/standards/contrib-templates/`
Convention: `~/the-custodian/canon/standards/contribution-convention_v0.1.md`

**Register a contribution in the State Hub:**
```
register_contribution(
    type="upr",             # br | fr | ep | upr
    title="Add injectTocTop to Observable Framework",
    target_org="observablehq",
    target_repo="framework",
    body_path="contrib/upstream-prs/2026-02-26--observablehq--framework--inject.md",
    related_workstream_id="<uuid>",
)
```

**Update status when upstream responds:**
```
update_contribution_status(contribution_id="<uuid>", status="submitted")
# then: acknowledged → accepted → merged
```

**List all contributions for this domain:**
```
get_contributions(target_repo="framework")
```

### SBOM

Software Bill of Materials for this repo is tracked in the State Hub.

**Ingest the current lockfile:**
```bash
cd ~/the-custodian/state-hub
make ingest-sbom REPO={REPO_SLUG}
```

**Check licence risk:**
```
get_licence_report()
```

**View SBOM dashboard:** `http://localhost:3000/sbom`

### Quick Reference

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