kanban

Files (1)

• SKILL.md

SKILL.md (first lines)

## NO REVIEW COLUMN (Tom 2026-07-16 — won't-undo)

There is **no `review` column**. Board columns are only:
`backlog → todo → doing → done`.

- Incomplete work that is still agent-actionable: stay in `todo` or `doing`
- Complete work: `done` only with merge/END-STATE proof
- Intentional holds: set `block_status=needs_human|deferred|design_first` + reason
  and park in **`backlog`** (not the default pickup `todo` lane — see below)

Never `kanban move <slug> review`. The live board rejects it. Do not invent
a review lane on custom boards either.

## Default `todo` is the pickup claim lane (won't-undo — 2026-08-15)

On the **default** board, `todo` is the autonomous pickup lane. The CLI/MCP
enforces pickup-readiness on writes into that lane. Agents that ignore these
rules burn a retry (and often a whole routine turn) on hard rejections:

| Rejection (real CLI/MCP error) | Correct action |
|---|---|
| `cannot be placed in default/todo with block_status=deferred` (same family for human-gated holds) | Put holds in **`backlog`** with `block_status` + reason. Do **not** park deferred/human-gated work in default `todo`. |
| `Kind:pr card … cannot enter todo without a milestone` | File Kind:pr via `$LAST_STACK_ROOT/bin/last-stack-kanban-file-pr` with **live** `--north-star` **and** `--milestone` (or `--ensure-milestone`). Raw `kanban add --column todo` without both is refused or becomes `unattached-outcome`. |
| `cannot carry --pr-url / --branch in default/todo` | Leave `todo` cards claim-ready without in-flight PR fields. Stamp `--pr-url` / `--branch` only after the card is in **`doing`** (or when re-adding mid-claim). |
| `Milestone "…" not found` | Use the full milestone slug (`kanban milestone list` / `milestone show`). Never truncate slugs. |

Quick rules of thumb:

1. **Pickup-ready Kind:pr** → always `last-stack-kanban-file-pr` (not raw `kanban add`).
2. **Human/deferred hold** → `backlog` + `block_status` + reason.
3. **In-flight PR linkage** → `doing` + `--pr-url`/`--branch`.
4. **Non-PR trackers** → `Kind: tracker|validation|meta` + `DONE-WHEN:`; still need clean `Repo:`/`Base:` headers; do not force them into the Kind:pr helper path.

## Settled decisions before file (won't-undo — 2026-08-20)

A new Kind:pr card must not contradict a settled brain record.

- **Producer:** `last-stack-kanban-file-pr` runs `last-stack-kanban-decision-check` and stamps `## DECISION-CHECK`. A mechanical conflict exits 2 and does not write the card.
- **Scope:** brain `type: decision`, `type: design`, and `type: preference`. Search is candidate slugs only. Each slug is point-got.
- **Honor:** if the stamp lists slugs, read those records with the stamp's `read:` lines (for example `read: gbrain get decision/<slug>` while gbrain is primary; `brain get` reads LastDB, which does not hold most settled records). Rewrite the brief so it follows them, or do not file.
- **Unavailable:** `verdict: unavailable` means the check could not run. Only repair/incident/proof/closeout cards are filed that way; re-run `last-stack-kanban-decision-check --title ... --inject < body` before you act on the card.
- **Do not** pass `--skip-decision-check` from a generator or routine. That flag is operator only.
- Raw `kanban add` / MCP `fkanban_add` for Kind:pr skips this gate. Use `last-stack-kanban-file-pr`.
- Metadata-only upserts (`--pr-url`, `--branch` on a live card) are not a create. Do not re-run the helper for those.

`--force` waives the gate for operator override only — unattended routines and
generator agents must not use it to hide unattached or deferred work.


# kanban — board management

kanban is a kanban task board stored in **LastDB**: a thin CLI/MCP client of a
LastDB node. Cards move through columns; every change persists in the node.

- **Location / how to run:** clone `kanban` and run its `src/cli.ts` under
  **bun**. A global shim (`kanban`) can be symlinked onto your PATH so a bare
  `kanban <command>` resolves from anywhere; without it, run
  `bun run src/cli.ts <command>` from the repo directory. See the
  **kanban-setup** skill for install.
- **⚠️ PATH gotcha (sandboxed shells):** some agent harnesses run shell commands
  **sandboxed** with a stripped `$PATH`, so a bare `kanban …` fails with
  `command not found: kanban`, and even after you add the shim's directory the
  shim's internal `exec bun` can then fail with `command not found: bun`. Both
  the shim dir and the bun dir must be on PATH. The robust fix is to prepend a
  complete PATH that includes both at the start of every kanban Bash call (PATH
  does not persist between calls), or invoke the CLI directly:
  `cd <kanban-repo> && PATH="$HOME/.bun/bin:$PATH" bun run src/cli.ts <command>`.
  Confirm the shim with `command -v kanban` and a narrow read.
- **Where the data lives:** the board records live on **your LastDB node**. The
  CLI talks to the node over its configured transport. Local daily-driver nodes
  may be **Unix-socket only** with HTTP intentionally shut down; use a
  socket-backed narrow read as the routine health check. The node URL is
  **configurable** — `init` defaults to a node running locally on your machine;
  point it elsewhere with `--node-url` / the config file (`~/.kanban/config.json`).
- **Columns:** `backlog → todo → doing → done`.

Before doing anything non-trivial, sanity-check the setup with a socket-backed
narrow read:

```bash
kanban list --column todo --json
```

## Commands

(With the shim on PATH these run from anywhere; otherwise replace `kanban`
with `bun run src/cli.ts` and run from the kanban repo directory.)

```bash
kanban list --column todo --json   # narrow column preview
kanban list --board <b> --column todo --json  # board-scoped column preview
# Avoid kanban list --full-body in routines; use show for selected cards.
kanban search "<text>" --json      # text search; no --full-body flag
kanban show <slug> --json          # one card in detail
kanban add <slug> [flags]          # create OR update a card
kanban mark <slug> "<line>"        # append one PROGRESS/HANDOFF line
kanban move <slug> <column> [--position N]
kanban set <slug> --block-status <s> [--block-reason "..."]
kanban rank                        # rewrite the column order (no slug)
kanban rm <slug>                   # delete (hard erase; no trash)
kanban board create <slug> --title ... --columns a,b,c
kanban board list
```

`mark` takes the slug and the line as positional arguments. There is no
`--note` and no `--line`. Those flags exit 2 with `Unknown option`. MCP
`fkanban_mark` is the structured equivalent.

`rank` rewrites every work card's `position` in one column (default `todo`).
It takes no card slug and no `--top`. `kanban rank <slug> --top` exits 2 with
`Unknown option '--top'`. To place one card, use
`kanban move <slug> <column> --position N` (lowest N is first for pickup).

`move` changes column (and optional `--position`). It has no `--block-status`.
Stamp a hold with `kanban set <slug> --block-status needs_human|deferred|design_first --block-reason "..."`,
then `kanban move <slug> backlog` if it must leave the pickup lane. `add` can
set `--block-status` on create; `set` is the metadata-only path for an existing
card.

From EdgeVector/last-stack, MIT.

More from EdgeVector/last-stack