From a59647cabcdae46ea3aaf5eb7b43826cb7b9e316 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 8 Jul 2026 14:50:07 +0200 Subject: [PATCH] Update project-rules templates for workplan-first terminology (CUST-WP-0055 T01) 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. --- scripts/project_rules/agents-codex.template | 6 +++++- scripts/project_rules/first-session.template | 10 +++++----- scripts/project_rules/session-protocol.template | 14 ++++++-------- .../project_rules/workplan-convention.template | 16 +++++++++++++--- 4 files changed, 29 insertions(+), 17 deletions(-) diff --git a/scripts/project_rules/agents-codex.template b/scripts/project_rules/agents-codex.template index 7e379dc..7576be9 100644 --- a/scripts/project_rules/agents-codex.template +++ b/scripts/project_rules/agents-codex.template @@ -145,7 +145,7 @@ owner: codex topic_slug: ... created: "YYYY-MM-DD" updated: "YYYY-MM-DD" -state_hub_workstream_id: "" # written by fix-consistency — do not edit (legacy name; holds the workplan id) +state_hub_workstream_id: "" # 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): ``` diff --git a/scripts/project_rules/first-session.template b/scripts/project_rules/first-session.template index 9aabb6d..195f8ca 100644 --- a/scripts/project_rules/first-session.template +++ b/scripts/project_rules/first-session.template @@ -20,14 +20,14 @@ roadmap phase. **Wait for approval before creating.** workplans/{WP_PREFIX}-NNNN-.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** ``` diff --git a/scripts/project_rules/session-protocol.template b/scripts/project_rules/session-protocol.template index bc5d40d..5c73ffa 100644 --- a/scripts/project_rules/session-protocol.template +++ b/scripts/project_rules/session-protocol.template @@ -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: diff --git a/scripts/project_rules/workplan-convention.template b/scripts/project_rules/workplan-convention.template index ff22391..ca9b4d9 100644 --- a/scripts/project_rules/workplan-convention.template +++ b/scripts/project_rules/workplan-convention.template @@ -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.