AkurAI-Build Kanban

A repository-local, dependency-free Kanban system for humans and Pi agents. Task cards are Markdown with machine-readable JSON front matter. The board has exactly nine flow states; blocked work remains in its current state and is marked blocked so WIP and ageing stay honest.

Quick start

node .kanban/bin/kanban.mjs validate
node .kanban/bin/kanban.mjs new --title "Describe the outcome" --type feature --priority P2
node .kanban/bin/kanban.mjs list
node .kanban/bin/kanban.mjs next

Move an item through intake and refinement:

node .kanban/bin/kanban.mjs move KB-ID triage --agent planner
node .kanban/bin/kanban.mjs move KB-ID discovery --agent planner
# Edit the card's objective, context, acceptance criteria, and verification.
node .kanban/bin/kanban.mjs move KB-ID ready --agent planner

Claim and deliver:

node .kanban/bin/kanban.mjs claim KB-ID --agent developer
node .kanban/bin/kanban.mjs evidence KB-ID --stage implementation --result "focused tests: pass" --agent developer
node .kanban/bin/kanban.mjs handoff KB-ID --from developer --to reviewer --summary "review current implementation"
node .kanban/bin/kanban.mjs accept KB-ID --agent reviewer
node .kanban/bin/kanban.mjs move KB-ID review --agent reviewer
node .kanban/bin/kanban.mjs evidence KB-ID --stage review --result "independent review: clean" --agent reviewer
node .kanban/bin/kanban.mjs move KB-ID verification --agent reviewer
node .kanban/bin/kanban.mjs evidence KB-ID --stage verification --result "acceptance checks: pass" --agent reviewer
node .kanban/bin/kanban.mjs move KB-ID release-ready --agent reviewer
node .kanban/bin/kanban.mjs set KB-ID --field resolution --value delivered --agent reviewer
node .kanban/bin/kanban.mjs move KB-ID done --agent reviewer --approval human-owner

Nine columns

The authoritative configuration and transition graph are in board.json. Column README.md files define entry, work, and exit policies.

Commands

new       Create a task in Inbox.
list      List tasks; filter by status, owner, or blocked state.
next      Return the highest-priority dependency-free Ready task.
show      Print a task card or its JSON metadata.
set       Update an approved metadata field as the owner.
evidence  Append status-bound evidence:
          implementation/review/verification/release/resolution.
move      Enforce ownership, transition, WIP, and entry gates.
claim     Atomically assign a Ready task and move it to In Progress.
block     Mark work blocked without hiding its current flow state.
unblock   Clear a blocker.
handoff   Create a durable agent-to-agent handoff artifact.
accept    Accept a pending handoff and transfer ownership.
validate  Check structure, cards, WIP limits, dependencies, and handoffs.
metrics   Report WIP, throughput, cycle time, work age, and the SLE.

Run node .kanban/bin/kanban.mjs help for exact arguments. Structured set values (labels, dependencies) are JSON arrays.

Operating model

• Pull work; do not push past a full WIP limit.
• One task has one owner. One shared worktree has one writer.
• In Progress is the commitment point; Done is the finish point.
• Blocked is a flag and reason, not a tenth column.
• Every non-trivial transition carries durable evidence in the card or handoff.
• Release Ready -> Done requires explicit human approval when project policy requires merge, deployment, publication, or external side effects.
• Forced transitions/claims require a reason and should be exceptional.
• The CLI serializes all board commands with .kanban/state/write.lock and atomically replaces individual files. Card moves plus event appends are not a filesystem transaction; run validate after interruption. It fails fast instead of polling when another command owns the lock.

Read:

• policies/definition-of-workflow.md for the complete flow contract.
• policies/agent-handoff.md for Pi-agent ownership and handoffs.
• policies/automation.md for local, Pi-loop, CI, and GitHub integration.
• policies/metrics.md for measurement and SLE review.
• sources.md for researched practices and design decisions.

Folder contract

.kanban/
├── board.json                 # nine columns, transitions, WIP, SLE
├── bin/kanban.mjs             # dependency-free automation CLI
├── columns/<status>/          # authoritative task location
├── handoffs/                  # immutable handoff records after acceptance
├── decisions/                 # lightweight architecture/product decisions
├── archive/                   # optional year-based Done archival
├── templates/                 # task, handoff, decision, retrospective
├── prompts/                   # bounded worker/reviewer agent prompts
├── policies/                  # workflow, agent, automation, metrics contracts
├── automation/                # optional integration templates
├── state/events.jsonl         # append-only local transition audit log
└── tests/kanban.test.mjs      # CLI workflow regression test

Do not edit state/events.jsonl to move work. Move cards only through the CLI. Card body edits are allowed while the task is owned; keep JSON front matter valid. Never put credentials, tokens, private keys, or secret values in cards, events, handoffs, prompts, or command arguments.