coulomb/state-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update project-rules templates for workplan-first terminology (CUST-WP-0055 T01)

Browse source 
Add legacy terminology compatibility footnote to workplan-convention, align
session-protocol and first-session with workplan-first registration, and point
agents-codex at GET /workplans/ plus the fleet canon addendum.
This commit is contained in:
tegwick 2026-07-08 14:50:07 +02:00
parent 74be4f2b65
commit a59647cabc
4 changed files with 29 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

6
scripts/project_rules/agents-codex.template
View file

@ -145,7 +145,7 @@ owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit (legacy name; holds the workplan id)
state_hub_workstream_id: "<uuid>" # fix-consistency — do not edit (legacy field name; workplan UUID)
---
```
@ -153,6 +153,10 @@ Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Task block format** (one per `##` section):
```

10
scripts/project_rules/first-session.template
View file

@ -20,14 +20,14 @@ roadmap phase. **Wait for approval before creating.**
workplans/{WP_PREFIX}-NNNN-<slug>.md ← write this, commit it
```
Then register by running the consistency check — do **not** call
`create_workplan`/`create_task` (or legacy `create_workstream`) yourself;
manual registration duplicates what C-06 creates from the file:
`create_workplan`/`create_task` yourself; manual registration duplicates what
C-06 creates from the file:
```bash
statehub fix-consistency --repo {REPO_SLUG}
```
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` /
`state_hub_task_id` back into the file (legacy field names, kept for
compatibility — they hold workplan/task IDs).
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
back into the file.
**Step 5 — Record the setup**
```

14
scripts/project_rules/session-protocol.template
View file

@ -57,15 +57,13 @@ If no workplans: follow First Session Protocol (`first-session.md`).
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
> State Hub is a *read model*. **Never register workplans or tasks by hand**
> (`create_workplan`, `create_task`, or the legacy `create_workstream`) — write
> the workplan file in `workplans/` and run `fix-consistency`; its C-06 check
> registers the workplan and its tasks in the hub and writes the IDs back into
> the file. Manual registration creates duplicates the moment fix-consistency
> runs. Work structure belongs in repo files (ADR-001).
> (`create_workplan`, `create_task`) — write the workplan file in `workplans/`
> and run `fix-consistency`; C-06 registers the workplan and tasks and writes
> IDs back into the file. Manual registration creates duplicates when
> fix-consistency runs. Work structure belongs in repo files (ADR-001).
>
> Terminology: "workstream" is the legacy name for workplan. Some API/frontmatter
> field names keep it for compatibility (`state_hub_workstream_id`,
> `workstream_id` params) — treat them as workplan IDs.
> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
> see `workplan-convention.md` (compatibility footnote).
**Session close:**
With MCP tools:

16
scripts/project_rules/workplan-convention.template
View file

@ -24,7 +24,7 @@ multiple planned phases into a normal workplan.
Ecosystem todos from other agents arrive as `[repo:{REPO_SLUG}]` hub tasks —
visible at session start. Pick one up by creating the workplan file, committing,
and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
Never register by hand with `create_workplan`/`create_workstream`.
Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).
Task blocks use this shape:
@ -39,7 +39,17 @@ Status progression is `todo` → `progress` → `done`; use `wait` for waiting o
blocked work and `cancel` for stopped work.
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
kept for compatibility ("workstream" is the old term for workplan); it holds
the hub workplan id and is written by fix-consistency. Do not edit or rename it.
kept for compatibility; it holds the hub workplan UUID and is written by
fix-consistency. Do not edit or rename it.
### Legacy terminology (compatibility footnote)
**Workplan** is the fleet term — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Workstream** is legacy only: some API routes (`/workstreams/`), params
(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
examples and scripts.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->