AkurAI-Build

public

Latest change 30e6b8c347048d64c2c048dfd05a8ded219d37f6 - Host authenticated Git repositories over Smart HTTP with repo host/sync CLI by Ólafur Búi Ólafsson

# 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

```sh
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:

```sh
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:

```sh
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

| Order | Status | Purpose | WIP |
| ---: | --- | --- | ---: |
| 1 | Inbox | Capture demand without commitment | — |
| 2 | Triage | Decide value, urgency, duplicates, and routing | 10 |
| 3 | Discovery | Resolve scope, risks, dependencies, and acceptance | 5 |
| 4 | Ready | Keep a small ordered pull queue | 10 |
| 5 | In Progress | Owned implementation; commitment point | 3 |
| 6 | Review | Independent engineering and security review | 3 |
| 7 | Verification | Deterministic tests and acceptance evidence | 3 |
| 8 | Release Ready | Current evidence plus human release/merge gate | 5 |
| 9 | Done | Delivered or explicitly resolved; finish point | — |

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

## Commands

```text
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

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