| name | kanbanzai-documents |
| description | Use this skill whenever you create, edit, register, or approve any document in a Kanbanzai-managed project, including files in work/design/, work/spec/, work/plan/, work/dev/, work/research/, work/report/, work/review/, work/retro/, or any configured document root. Activate even when document registration is not the primary goal of the task — any file creation in a document root requires registration.
|
Purpose
This skill covers document types, where to place them, how to register them, and the
approval workflow. Every document placed in a configured root must be registered.
Document Types and Locations
| Type | Directory | When to use |
|---|
design | work/design/ | Architecture, vision, approach decisions |
specification | work/spec/ | Acceptance criteria, binding contracts |
plan | work/plan/ | Project planning: roadmaps, scope, decision logs |
dev-plan | work/dev/ | Feature implementation plans, task breakdowns |
research | work/research/ | Analysis, exploration, background reading |
report | work/report/ | Audit reports, post-mortems, general reports |
report | work/review/ | Feature and plan review reports |
retrospective | work/retro/ | Retrospective synthesis documents |
Design decisions belong in work/design/, not work/plan/. If a document contains
architecture, API shapes, data models, or technology choices, it is a design document.
Registration Procedure
Every document placed in a configured root must be registered immediately after creation:
doc(action="register", path="work/design/my-doc.md", type="design", title="Human-readable title")
To batch-import an entire directory (idempotent, safe to repeat):
doc(action="import", path="work")
Approval Workflow
Documents follow a three-status lifecycle: draft → approved → superseded.
- Draft: created, not yet approved. Cannot be used as a stage gate basis.
- Approved: approved by a human. An approved design document allows Feature entity
creation. An approved specification allows task decomposition.
- Superseded: replaced by a newer document. The superseding document becomes the
authoritative basis.
Approval can be verbal; record it immediately:
doc(action="approve", id="DOC-...")
Drift and Refresh
If a document is edited after registration, its content hash becomes stale. Attempting
to approve a drifted document will fail.
Check drift status:
doc(action="get", id="DOC-...")
Refresh before approving:
doc(action="refresh", id="DOC-...")
Supersession
When a document is replaced by a newer version:
- Create and register the new document.
- Call
doc(action="supersede", id="old-DOC-...", superseded_by="new-DOC-...").
Do not silently amend an approved document. Any edit to an approved document requires
creating a new document and superseding the old one.
Gotchas
Forgot to register: The document is invisible to document intelligence, entity
extraction, approval workflow, and health checks. Use doc(action="import", path="work")
as a safety net to catch any unregistered files.
Editing after registration: The content hash becomes stale and approval will fail.
Always call doc with action: refresh after editing, before approving.
Design content in the wrong place: Design decisions placed in work/plan/ instead
of work/design/ bypass the approval gate. The system cannot enforce what it cannot find.
Blind retries: If a tool call fails, read the error message before retrying. Most
failures are caused by drift, missing records, or invalid state — not transient errors.
Dates and Timestamps
Always call now() to get the current UTC datetime before writing any date field in
document content. Never guess or invent a date.
now(timezone="utc")
# returns e.g. "2026-03-26T15:44:49Z"
Use full UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) in document metadata headers:
| Created | 2026-03-26T15:44:49Z |
| Updated | 2026-03-26T15:44:49Z |
Or for design-doc frontmatter style:
- Date: 2026-03-26T15:44:49Z
This format is unambiguous and lets any viewer convert to local time. The same UTC ISO
8601 format is used by entity records in .kbz/state/ — keeping document content
consistent with entity metadata makes the project's timeline easy to reason about.
Related
kanbanzai-workflow — how document approval gates interact with stage progressionkanbanzai-agents — task dispatch and knowledge contribution
