Kanbanzai kanbanzai-documents

install

source · Clone the upstream repo

git clone https://github.com/sambeau/kanbanzai

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/sambeau/kanbanzai "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/kanbanzai-documents" ~/.claude/skills/sambeau-kanbanzai-kanbanzai-documents && rm -rf "$T"

manifest: .agents/skills/kanbanzai-documents/SKILL.md

source content

SKILL: Kanbanzai Documents

Purpose

Document types, where to place them, how to register them with the system, and the approval workflow that makes them authoritative.

When to Use

When creating any new document in a configured document root
When registering a document with
```
doc
```
action:
```
register
```
When approving a document or checking whether it is ready for approval
When editing a document that has already been registered
When unsure which document type or directory to use

Vocabulary

Term	Definition
document record	The YAML metadata file in `.kbz/state/documents/` that tracks a document's type, status, content hash, and ownership
content hash	A hash of the document's file contents, recorded at registration and checked at approval to ensure what was reviewed is what gets approved
document type	One of `design` , `specification` , `dev-plan` , `research` , `report` , or `policy` — determines how the system treats the document in lifecycle gates
document approval	Calling `doc(action: "approve")` to transition a document from `draft` to `approved` , binding the approval to the current content hash
document registration	Calling `doc(action: "register")` to create a document record, making the document visible to the workflow system
supersession	Replacing an approved document with a newer version via `doc(action: "supersede")` , marking the old document as `superseded`
document drift	The state where a registered document's file contents no longer match its stored content hash, typically after editing
hash refresh	Calling `doc(action: "refresh")` to update a document record's content hash to match current file contents
document owner	The parent Plan or Feature ID that a document is associated with, set via the `owner` field at registration
document chain	The succession history of a document — its predecessors and replacements, retrieved via `doc(action: "chain")`

Document Creation Checklist

Copy this checklist when creating any new document:

Determined the correct document type (design, specification, dev-plan, research, report, policy)
Placed the file in the correct directory for its type

Registered the document with

doc(action: register, path: "...", type: "...", title: "...", owner: "...")

Verified registration with
```
doc(action: get, path: "...")
```
Committed both the document file and the registration record together

Document Types and Locations

Documents live in configured roots under the project's document directory (typically

work/

). Each root has a default type:

Type	Typical directory	When to use
`design`	`work/design/`	Architecture, vision, approach decisions
`specification`	`work/spec/`	Acceptance criteria, binding contracts
`dev-plan`	`work/dev/` or `work/plan/`	Implementation plans, task breakdowns
`research`	`work/research/`	Analysis, exploration, background
`report`	`work/reports/`	Review reports, audits, post-mortems
`policy`	`work/design/`	Standing rules, process definitions

The actual roots and default types are defined in

.kbz/config.yaml

under

documents.roots

. Check the project configuration if the defaults above do not match.

Placement rule: design content goes in design documents, not in planning documents. A document in

work/plan/

that contains "Decision:", "Architecture:", or "Technology Choice:" is a sign that design work is being done in the wrong place.

Registration

Every document placed in a configured root must be registered with the system immediately after creation. Unregistered documents are invisible to document intelligence, entity extraction, approval workflow, and health checks.

Registering a single document

doc(
  action="register",
  path="work/design/my-document.md",
  type="design",
  title="Human-Readable Title"
)

The

type

must match the document root. The system generates a document ID from the path (e.g.,

PROJECT/design-my-document

Batch import

To catch unregistered documents or register many at once:

doc(action="import", path="work")

This is idempotent — already-registered documents are skipped. Safe to run at any time as a consistency check.

Verify registration

doc(action="get", id="PROJECT/design-my-document")

A document is properly registered when a YAML record exists in

.kbz/state/documents/

and

doc

action:

get

returns its metadata.

Approval Workflow

Documents follow a three-status lifecycle: draft → approved → superseded.

Agent or human creates the document file.
Agent registers it with
```
doc
```
action:
```
register
```
— status becomes
```
draft
```
.
Human reviews the document and signals approval (verbally: "Approved", "LGTM", or equivalent).
Agent calls
```
doc
```
action:
```
approve
```
— status becomes
```
approved
```
.
Approved documents are the authoritative basis for downstream work:
- Approved design → features can be created
- Approved specification → tasks can be decomposed

A draft document is a working document. An approved document is a contract.

Auto-Approve for Agent-Authored Documents

For agent-authored documents of types

dev-plan

research

, and

report

, registration and approval can be combined in a single call:

doc(action: "register", type: "dev-plan", auto_approve: true, path: "...", title: "...", owner: "...")

This registers the document and immediately approves it. The

auto_approve

flag is only honoured for types in the whitelist (

dev-plan

research

report

). Design documents and specifications always require explicit human approval.

Drift and Refresh

When a document is registered, the system records a content hash. If the file is edited after registration, the hash becomes stale — this is called drift.

doc approve
auto-refreshes on hash mismatch. If the file has drifted since registration,
```
doc
```
action:
```
approve
```
automatically updates the hash before approving — it no longer fails on mismatch.
doc refresh
is still available for checking or correcting drift outside the approval path (e.g. to detect whether a document has changed since it was last registered).
If an approved document is edited, the approval is effectively void. The content no longer matches what was approved. Notify the human and re-approve after review.

Supersession

When a document is replaced by a newer version:

Create and register the new document.
Call
```
doc
```
action:
```
supersede
```
on the old document, linking it to the new one.
The old document's status becomes
```
superseded
```
.

Superseded documents remain in the repository as historical records. They are no longer authoritative.

Moving Documents

To move a document file to a new path:

Call

doc(action: "move", id: "DOC-xxx", new_path: "work/new-location/file.md")

The system moves the file, updates the record's path, recomputes the content hash, and commits atomically.
If the new path implies a different document type, the type is updated automatically.

Note: Approval status, owner, and cross-references are preserved across moves.

Deleting Documents

To delete a document:

Call
```
doc(action: "delete", id: "DOC-xxx")
```
for draft documents.

For approved documents, add

force: true

doc(action: "delete", id: "DOC-xxx", force: true)

The system removes the file, clears the entity's document reference, and commits atomically.

Note: This operation is irreversible. Consider supersession instead if historical preservation matters.

Anti-Patterns

Unregistered Document

Detect: A design, spec, or plan document exists on disk but has no document record in
```
.kbz/state/documents/
```
.
BECAUSE: Unregistered documents are invisible to the workflow system — stage gates can't check prerequisites, and other agents can't discover the document through MCP tools.
Resolve: Call
```
doc(action: "register")
```
immediately after creating any document.

Stale Content Hash

Detect: A registered document's file contents no longer match its stored content hash (visible via
```
doc(action: "refresh")
```
).
BECAUSE: The file was edited after registration, so the stored hash no longer matches disk.
Note:
```
doc(action: "approve")
```
now auto-refreshes the hash before approving, so this no longer blocks approval. Use
```
doc(action: "refresh")
```
explicitly if you need to check or update drift outside the approval path.

Silent Supersession

Detect: An approved document is edited directly instead of creating a replacement and superseding.
BECAUSE: The approval is tied to the content hash. Editing voids the approval silently — downstream consumers see "approved" but the content has drifted.
Resolve: Create a new document, register it, and call
```
doc(action: "supersede")
```
on the old one.

Gotchas

Forgot to register. If you create a file in
```
work/
```
and forget to call
```
doc
```
action:
```
register
```
, the document is invisible to the system. Run
```
doc(action="import", path="work")
```
as a safety net if unsure.
Design in the wrong place. Design decisions belong in
```
work/design/
```
, not
```
work/plan/
```
. If a planning document contains architecture decisions, move that content to a design document.
Registering with the wrong type. A specification registered as
```
design
```
won't be found when the system checks for specification prerequisites. Check the Document Types table — the type determines how the system treats the document in lifecycle gates.
Tool call fails. If
```
doc
```
action:
```
register
```
or
```
doc
```
action:
```
approve
```
returns an error, read the message — it explains the problem. Do not retry with the same arguments. Fix the underlying issue first.

Commit Discipline

Document registration and approval are automatically committed by the MCP tools. Manual commits for document files are no longer required.

If you create or edit a document file outside of an MCP tool (e.g. writing content directly to disk), commit the file itself using the standard commit format — the registration record will be handled by the tool when you call

doc(action: "register")

Output Templates

When producing specific document types, use these templates as structural guides:

Specifications:

work/templates/specification-prompt-template.md

Implementation plans:

work/templates/implementation-plan-prompt-template.md

Reviews:

work/templates/review-prompt-template.md

Evaluation Criteria

#	Question	Weight
1	Was every new document registered via `doc(action: "register")` immediately after creation?	required
2	Was `doc(action: "approve")` called immediately when approval was signalled?	required
3	Were edited approved documents handled via supersession rather than direct edit?	high
4	Was `doc(action: "refresh")` used to resolve content hash mismatches before re-approval?	high

Questions This Skill Answers

How do I register a new document?
How do I approve a document?
What do I do when approval fails with a hash mismatch?
How do I supersede an old document?
What document types does the system support?
When should I call
```
doc(action: "refresh")
```
?
How do I check if all specs for a plan are approved?

```
kanbanzai-getting-started
```
— session orientation
```
kanbanzai-workflow
```
— stage gates that depend on document approval
```
write-design
```
— the design process that produces design documents