3.8 KiB
Workplan Convention (ADR-001)
File location: workplans/CUST-WP-NNNN-<slug>.md
ID prefix: CUST-WP-
Work items originate as files in this repo before being registered in the hub.
Canonical workplan frontmatter statuses are:
proposed, ready, active, blocked, backlog, finished, archived.
Use proposed for a newly drafted plan, ready after review against current
repo state, and finished when implementation is complete. stalled and
needs_review are derived health labels, not stored statuses.
Optional frontmatter (STATE-WP-0092):
flavor: planning | implementation | refactoring | extension | residual
depends_on:
- STATE-WP-0092
Unset flavor is not residual. Do not implement flavor: residual unless
demand or risk has promoted it to another flavor. Frontmatter depends_on
lists blocker workplan ids (C-20). Task-block depends_on (below) lists
what one task waits for and is indexed the same way.
Closed workplans may be moved to workplans/archived/ with a completion-date
prefix: YYMMDD-CUST-WP-NNNN-<slug>.md. The frontmatter id remains
unchanged; the prefix is only for quick visual reference.
Small opportunistic tasks discovered during another session use Ad Hoc Tasks:
workplans/ADHOC-YYYY-MM-DD.md, workplan slug adhoc-YYYY-MM-DD, and task ids
ADHOC-YYYY-MM-DD-T01, T02, etc. Use adhocs only for low-risk work completed
directly. Promote anything requiring analysis, design, approval, dependencies, or
multiple planned phases into a normal workplan.
Ecosystem todos from other agents arrive as [repo:the-custodian] 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 (legacy MCP alias: create_workstream).
Task blocks use this shape:
id: CUST-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
depends_on: [OTHER-WP-0001, OTHER-WP-0002-T03] # wait: external commitment
needs_human: true # wait: human gate
blocked_on: message-from:<agent> # wait: owner reply, no workplan id yet
blocking_reason: "<why, one line>" # required whenever status is wait
decision_id: CCR-2026-0004 # optional, tracked decision behind a human gate
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
Status progression is todo → progress → done; use wait for waiting or
blocked work and cancel for stopped work.
A wait task must be qualified: depends_on (clears by itself when every
target is terminal — derived state waiting-external), needs_human: true
(a person clears it — derived state needs-human), or both. Neither is a
fix-consistency WARN. The kind is derived, not a stored status; see
canon/standards/task-wait-qualifiers_v0.1.md. A blocked workplan is
derived as blocked-human when any wait task is a human gate, else
blocked-external.
Workplan frontmatter carries state_hub_workstream_id — a legacy field name
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.
Workplan 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.