/kanban-md

name: kanban-md
description: >
  Manage project tasks using kanban-md, a file-based kanban board CLI.
  Use when the user mentions tasks, kanban, board, backlog, sprint,
  project management, work items, priorities, blockers, or wants to
  track, create, list, move, edit, or delete tasks. Also use for
  standup, status update, sprint planning, triage, or project metrics.
allowed-tools:
  - Bash(kanban-md *)
  - Bash(kbmd *)

<!-- kanban-md-skill-version: 0.31.0 -->

kanban-md

Manage kanban boards stored as Markdown files with YAML frontmatter. Each task is a `.md` file in `kanban/tasks/`. The CLI is `kanban-md` (alias `kbmd` if installed via Homebrew).

Current Board State

!`kanban-md board 2>/dev/null || echo 'No board found — run: kanban-md init --name PROJECT_NAME'`

Rules

• Use `--compact` for listing commands (`list`, `board`, `metrics`, `log`) to get

token-efficient one-line output.

• Use `kanban-md show ID` (default table format) to read task details — it includes

the full body and all fields in a human-readable layout. Only add `--json` when you need to pipe the output to another tool or parse fields programmatically.

• Always pass `--yes` when deleting (`kanban-md delete ID --yes`).
• Dates use `YYYY-MM-DD` format.
• Statuses and priorities are board-specific. Check the board state above or run

`kanban-md board` to discover valid values before using them.

• Default statuses: backlog, todo, in-progress, review, done.
• Default priorities: low, medium, high, critical.

Decision Tree

| User wants to... | Command | |-----------------------------------------|------------------------------------------------------------------| | See board overview / standup | `kanban-md board --compact` | | Get a unique agent name (for claims) | `kanban-md agent-name` | | List all tasks | `kanban-md list --compact` | | List tasks by status | `kanban-md list --compact --status todo,in-progress` | | List tasks by priority | `kanban-md list --compact --priority high,critical` | | List tasks by assignee | `kanban-md list --compact --assignee alice` | | List tasks by tag | `kanban-md list --compact --tag bug` | | List blocked tasks | `kanban-md list --compact --blocked` | | List ready-to-start tasks | `kanban-md list --compact --not-blocked --status todo` | | List tasks with resolved deps | `kanban-md list --compact --unblocked` | | Find a specific task | `kanban-md show ID` | | Claim next available task | `kanban-md pick --claim <agent> --status todo --move in-progress`| | Create a task | `kanban-md create "TITLE" --priority P --tags T` | | Create a task with body | `kanban-md create "TITLE" --body "DESC"` | | Create and immediately claim a task | `kanban-md create "TITLE" --priority P --claim <agent>` | | Start working on a task | `kanban-md move ID in-progress` | | Advance to next status | `kanban-md move ID --next` | | Move a task back | `kanban-md move ID --prev` | | Complete a task | `kanban-md move ID done` | | Edit task fields | `kanban-md edit ID --title "NEW" --priority P` | | Add/remove tags | `kanban-md edit ID --add-tag T --remove-tag T` | | Set a due date | `kanban-md edit ID --due 2026-03-01` | | Block a task | `kanban-md edit ID --block "REASON"` | | Unblock a task | `kanban-md edit ID --unblock` | | Add a dependency | `kanban-md edit ID --add-dep DEP_ID` | | Set a parent task | `kanban-md edit ID --parent PARENT_ID` | | Append a note to task body | `kanban-md edit ID --append-body "note" --timestamp` | | Hand off a task to review | `kanban-md handoff ID --claim <agent> --note "…" --release` | | Delete a task | `kanban-md delete ID --yes` | | See flow metrics | `kanban-md metrics --compact` | | See activity log | `kanban-md log --compact --limit 20` | | See recent activity for a task | `kanban-md log --compact --task ID` | | Get a board context summary | `kanban-md context` | | Initialize a new board | `kanban-md init --name "NAME"` |

Core Commands

list

kanban-md list [--status S] [--priority P] [--assignee A] [--tag T] \
  [--sort FIELD] [-r] [-n LIMIT] [--blocked] [--not-blocked] \
  [--parent ID] [--unblocked]

Sort fields: id, title, status, priority, created, updated, due. `-r` reverses. `--unblocked` shows tasks whose dependencies are all at terminal status.

create

kanban-md create "TITLE" [--status S] [--priority P] [--assignee A] \
  [--tags