kaizen-agentic/docs/adr/ADR-001-workplan-convention.md

id	title	status	date
ADR-001	Workplan Convention	accepted	2026-03-18

ADR-001 — Workplan Convention

Status

Accepted

Context

kaizen-agentic needs a way to track planned work that is version-controlled, visible to the state-hub, and authoritative when the two diverge.

Decision

Work items originate as Markdown files in workplans/ before being registered in the state-hub DB. The file is always authoritative; the DB is a read/query model derived from it.

File naming: workplans/KAIZEN-WP-NNNN-<slug>.md ID prefix: KAIZEN-WP

Required YAML frontmatter

---
id: KAIZEN-WP-NNNN
type: workplan
title: "..."
domain: custodian
repo: kaizen-agentic
status: active | completed | archived
owner: kaizen-agentic
topic_slug: custodian
state_hub_workstream_id: <uuid>
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
---

Task tracking

Tasks use - [ ] / - [x] checkboxes with a T## code prefix. A ## State Hub Task IDs table at the end of each workplan maps codes to DB UUIDs so status can be synced without a list_tasks lookup.

Consequences

• File is the source of truth; DB drift is auto-fixable via check_repo_consistency(fix=True).
• Tasks must be created in the file first, then registered in the hub.
• C-12 warnings are expected when the DB host has not yet seen local changes.