diff --git a/state-hub/scripts/project_claude_md.template b/state-hub/scripts/project_claude_md.template index a028081..5ff042c 100644 --- a/state-hub/scripts/project_claude_md.template +++ b/state-hub/scripts/project_claude_md.template @@ -8,69 +8,84 @@ 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. +**On receiving your first message — before writing any response text — execute +this orientation sequence. Do not greet, do not ask what to do first.** -**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. +**Step 1 — Call the State Hub** +``` +get_state_summary() # orientation: workstreams, decisions, recent progress +get_next_steps() # contextual suggestions from resolved decisions +``` +If the call fails, the API is offline: `cd ~/the-custodian/state-hub && make api` + +**Step 2 — Scan local workplans** + +Read every file matching `workplans/*.md` in this repo. For each one with +`status: active`, extract and note: +- The workplan title and ID +- All tasks whose `status` is `todo` or `in_progress` + +**Step 3 — Present orientation to the user** + +Output a concise brief covering: +1. **Active workstreams** (from state hub) for the `{DOMAIN}` domain — title, + task counts, any blocking decisions +2. **Pending tasks for this repo** — from local `workplans/` files (Step 2) + plus any state hub tasks with `[repo:{REPO_SLUG}]` in their title +3. **Suggested next action** — the highest-priority open item across both sources +4. **SBOM status** — is `last_sbom_at` set for this repo? If not, note it as a gap + +If there are no workstreams at all: 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. +- Use `resolve_decision()` to close a decision once the choice is made. > **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. +> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**. +> The bootstrap tools (`create_workstream`, `create_task`, `update_task_status`) +> are only for First Session Protocol. Formal work structure — workplans, tasks — +> belongs in the domain repo as files (ADR-001), not managed through the hub alone. **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. +Triggered when `get_state_summary()` shows **no workstreams** for the `{DOMAIN}` +topic. 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 +- `~/the-custodian/canon/projects/{DOMAIN}/project_charter_v0.1.md` — purpose, scope +- `~/the-custodian/canon/projects/{DOMAIN}/roadmap_v0.1.md` — planned phases +- Scan the repo root: README, directory structure, existing code or docs **Step 2 — Survey in-progress work** -- Look for TODOs, open branches, half-finished files, or notes +- Look for TODOs, open branches, half-finished files, 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 +Propose 1–3 workstreams — each a coherent strand of work lasting weeks to months, +named clearly, anchored to a roadmap phase. **Wait for approval before creating.** -Present the proposals and **wait for approval before creating anything**. - -**Step 4 — Create and populate (after approval)** +**Step 4 — Create workplan file first, then DB record** +Per ADR-001, work items originate as files in the repo: +``` +workplans/-WP-NNNN-.md ← write this first +``` +Then register in the hub: ``` create_workstream(topic_id="{TOPIC_ID}", title="...", owner="...", description="...") create_task(workstream_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** ``` @@ -82,12 +97,28 @@ add_progress_event( ) ``` +--- + +### Workplan Convention (ADR-001) + +Work items MUST originate as files in this repo before being registered in the hub. + +**File location:** `workplans/-.md` +**Frontmatter required:** `id`, `type: workplan`, `domain`, `repo`, `status`, +`state_hub_workstream_id`, `state_hub_task_id` (per task) + +When the custodian creates a task targeting this repo from another session, it: +1. Creates a state hub task with `[repo:{REPO_SLUG}]` in the title +2. Creates a workplan file in this repo's `workplans/` +3. You will see both at session start via the orientation sequence above + +--- + ### Contribution Tracking -This project tracks upstream contributions in `contrib/` — bug reports, feature -requests, extension-point proposals, and upstream PRs — as canonical Markdown files. +Track upstream contributions in `contrib/` — bug reports (BR), feature requests +(FR), extension-point proposals (EP), upstream PRs (UPR). -**Directory layout:** ``` contrib/ bug-reports/ # br-YYYY-MM-DD--org--repo--slug.md @@ -99,46 +130,27 @@ contrib/ 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="", -) -``` - -**Update status when upstream responds:** ``` +register_contribution(type="br|fr|ep|upr", title="...", target_org="...", + target_repo="...", body_path="contrib/...", related_workstream_id="") update_contribution_status(contribution_id="", 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:** +After updating dependencies, re-ingest the SBOM: ```bash cd ~/the-custodian/state-hub -make ingest-sbom REPO={REPO_SLUG} +make ingest-sbom REPO={REPO_SLUG} SCAN=1 REPO_PATH=$(pwd) ``` -**Check licence risk:** -``` -get_licence_report() -``` +Check compliance: `http://localhost:3000/repos` +Standard: `~/the-custodian/canon/standards/sbom-convention_v0.1.md` -**View SBOM dashboard:** `http://localhost:3000/sbom` +--- ### Quick Reference -See `~/the-custodian/state-hub/mcp_server/TOOLS.md` for a compact tool reference. +`~/the-custodian/state-hub/mcp_server/TOOLS.md` — compact MCP tool reference