tmux-amq/.claude/rules/workplan-convention.md

Workplan Convention (ADR-001)

File location: workplans/TAMQ-WP-NNNN-<slug>.md ID prefix: TAMQ-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.

Closed workplans may be moved to workplans/archived/ with a completion-date prefix: YYMMDD-TAMQ-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 id TAMQ-WP-ADHOC-YYYY-MM-DD, and task ids TAMQ-WP-ADHOC-YYYY-MM-DD-T01, T02, etc. TAMQ-WP includes its final -WP token. Unqualified historic ADHOC-* ids are grandfathered and must not be copied into new records. 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:tmux-amq] 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).

If fix-consistency reports C-06/C-11 skipped because this host is not the identifier registrar, further retries cannot help. Do not set STATEHUB_REGISTRAR and do not create hub rows manually. Commit and push the file-backed work, then run the scoped repo-manager fallback once:

uv run --project ~/repo-manager rmgr registrar-reconcile \
  --path . --confirm-primary --push

If it is unavailable, send one request to repo-manager naming the repository and missing canonical ids. Continue local work from files; hub UUID absence is an indexing delay, not a reason to repeat the same checks.

Task blocks use this shape:

id: TAMQ-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
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.

Residuals (role, not kind)

When finishing a workplan, actionable leftovers must become live work records before status: finished. Residual is not a registered kind and must not be parked only in SCOPE.md or finished-file prose.

Shape	Capture as	Links
Small Green/Blue parkable	intake (queue YAML / *-IN-*)	origin: residual, origin_ref: TAMQ-WP-NNNN
Multi-step	next workplan	name parent WP; optional promote from residual intake
Founder gate / time	decision / engagement	same origin fields when from residual intake

Fleet listing of residuals is a State Hub concern (list_intakes + origin filters; planned statehub residuals). Canon: the-custodian/canon/standards/work-record-types_v0.1.md § Residuals.

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. 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.