57 lines
1.3 KiB
Markdown
57 lines
1.3 KiB
Markdown
---
|
|
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-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.
|