---
id: ADR-001
title: Workplan Convention
status: accepted
date: "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-agentic-WP-NNNN-<slug>.md`
**ID prefix:** `KAIZEN-WP`

### Required YAML frontmatter

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