Kanban-md kanban-md

install

source · Clone the upstream repo

git clone https://github.com/antopolskiy/kanban-md

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

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

manifest: .claude/skills/kanban-md/SKILL.md

source content

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, 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 T1,T2] [--due YYYY-MM-DD] [--estimate E] [--body "TEXT"] \
  [--parent ID] [--depends-on ID1,ID2] [--claim AGENT]

Prints the created task ID and summary.

--claim

immediately claims the task for an agent, combining creation and claiming in one step.

show

kanban-md show ID
kanban-md show ID --json   # only when piping to another tool

Default format shows all fields including the body in a readable layout. Use

--json

only when you need to parse fields programmatically. For the JSON schema, see references/json-schemas.md.

agent-name

kanban-md agent-name

Generates a random two-word identifier (e.g.

frost-maple

) to use as a claim name. Run once per agent session and remember the result.

edit

kanban-md edit ID[,ID,...] [--title T] [--status S] [--priority P] [--assignee A] \
  [--add-tag T] [--remove-tag T] [--due YYYY-MM-DD] [--clear-due] \
  [--estimate E] [--body "TEXT"] [-a "TEXT"] [--started YYYY-MM-DD] [--clear-started] \
  [--completed YYYY-MM-DD] [--clear-completed] [--parent ID] \
  [--clear-parent] [--add-dep ID] [--remove-dep ID] \
  [--block "REASON"] [--unblock] \
  [--claim AGENT] [--release] [-t]

Only specified fields are changed. Prints a confirmation message.

-a

--append-body

appends text to the existing body without replacing it.

-t

--timestamp

prefixes a timestamp line when appending.

--claim

claims (or renews a claim on) the task for the agent.

--release

releases the claim on the task. Accepts comma-separated IDs for bulk edits.

move

kanban-md move ID[,ID,...] STATUS
kanban-md move ID --next
kanban-md move ID --prev
kanban-md move ID STATUS --claim AGENT

Auto-sets Started on first move from initial status. Auto-sets Completed on move to terminal status. Accepts comma-separated IDs for bulk moves.

--claim

claims the task during the move (useful when resuming a parked task).

pick

kanban-md pick --claim AGENT [--status S] [--move STATUS] [--tags T1,T2]

Atomically finds the highest-priority unclaimed, unblocked task and claims it. Use

--status

to restrict which column to pick from. Use

--move

to simultaneously move the task to a new status. Replaces the slower list → claim → move sequence.

handoff

kanban-md handoff ID --claim AGENT [--note "TEXT"] [--block "REASON"] [--release] [-t]

Moves the task to

review

, appends a handoff note, and optionally marks it blocked and/or releases the claim. Use when parking work for another agent or waiting on user input.

-t

adds a timestamp.

context

kanban-md context [--sections in-progress,blocked,overdue,recently-completed] \
  [--days N] [--write-to FILE]

Generates a markdown board summary suitable for embedding in

CLAUDE.md

AGENTS.md

--write-to

writes (or updates) the summary inside a delimited block in the target file.

delete

kanban-md delete ID --yes

Always pass

--yes

(non-interactive context requires it).

board

kanban-md board

Shows board overview: task counts per status, WIP utilization, blocked/overdue counts, priority distribution.

metrics

kanban-md metrics [--since YYYY-MM-DD]

Shows throughput (7d/30d), avg lead/cycle time, flow efficiency, aging items.

log

kanban-md log [--since YYYY-MM-DD] [--limit N] [--action TYPE] \
  [--task ID]

Action types: create, move, edit, delete, block, unblock.

Global Flags

All commands accept:

--json

--table

--compact

(alias

--oneline

--dir PATH

--no-color

Workflows

Daily Standup

```
kanban-md board --compact
```
— board overview

kanban-md list --compact --status in-progress

— in-flight work

```
kanban-md list --compact --blocked
```
— stuck items
```
kanban-md metrics --compact
```
— throughput and aging
Summarize: completed, active, blocked, aging items

Triage New Work

kanban-md list --compact --status backlog --sort priority -r

— review backlog

For items to promote:
```
kanban-md move ID todo
```

For new items:

kanban-md create "TITLE" --priority P --tags T

For stale items:
```
kanban-md delete ID --yes
```

Sprint Planning

```
kanban-md board --compact
```
— current state

kanban-md list --compact --status backlog,todo --sort priority -r

— candidates

Promote selected:
```
kanban-md move ID todo
```
Assign:
```
kanban-md edit ID --assignee NAME
```
Set deadlines:
```
kanban-md edit ID --due YYYY-MM-DD
```

Complete a Task

```
kanban-md move ID done
```
— marks complete, sets Completed timestamp
```
kanban-md show ID --json
```
— verify status and timestamps

Track a Bug

kanban-md create "Fix: DESCRIPTION" --priority high --tags bug

kanban-md edit ID --body "Steps to reproduce: ..."

Track a Dependency Chain

Create parent:
```
kanban-md create "Epic title"
```

Create subtask:

kanban-md create "Subtask" --parent PARENT_ID

Or add dependency:

kanban-md create "Task B" --depends-on TASK_A_ID

List unresolved:
```
kanban-md list --compact --blocked
```

Agent Cheatsheet

Quick-reference for the agent task lifecycle. These are combination commands — multiple flags in one call to minimize round-trips. Replace

<agent>

with your session's

agent-name

output.

Session start

kanban-md agent-name                             # generate a unique claim name; remember it
kanban-md board --compact                        # orient: what's active, blocked, overdue

Claim next task (atomic pick + move)

# Pick highest-priority unclaimed task from todo and move it to in-progress in one step
kanban-md pick --claim <agent> --status todo --move in-progress

# If todo is empty, pick from backlog
kanban-md pick --claim <agent> --status backlog --move in-progress

# Read the full task after picking
kanban-md show <ID>

Create and claim in one shot

# Create a task and immediately claim it
kanban-md create "TITLE" --priority high --tags bug --claim <agent>

# Add a body separately (or use --body inline if short)
kanban-md edit <ID> --body "Steps to reproduce: ..."

Progress note (renews claim, appends without overwriting)

# Leave a timestamped note while keeping your claim active
kanban-md edit <ID> -a "Implemented X, running tests." -t --claim <agent>

Finish task (release claim + mark done)

# Run from board home, after merging
kanban-md edit <ID> --release
kanban-md move <ID> done

Park / handoff (moves to review, appends note, releases claim)

# Waiting on user decision or external action
kanban-md handoff <ID> --claim <agent> \
  --note "Ready to merge: branch task/<ID>-…; waiting for: ..." \
  -t --release

# Blocked on something specific
kanban-md handoff <ID> --claim <agent> \
  --block "Reason for block" \
  --note "What's needed to unblock and next step." \
  -t --release

Resume a parked task

kanban-md edit <ID> --claim <agent>                  # re-claim
kanban-md edit <ID> --unblock --claim <agent>        # unblock (if it was blocked)
kanban-md move <ID> in-progress --claim <agent>      # move back to in-progress

Bulk operations (comma-separated IDs)

# Tag multiple tasks at once
kanban-md edit <ID1>,<ID2>,<ID3> --add-tag layer-3

# Move multiple tasks
kanban-md move <ID1>,<ID2> todo

# List with combined filters
kanban-md list --compact --status backlog --priority high,critical --sort priority -r
kanban-md list --compact --not-blocked --status todo   # tasks ready to start
kanban-md list --compact --status in-progress,review   # all active/parked work

Pitfalls

DO use
```
--compact
```
for listing, board, metrics, and log commands — it is the most token-efficient format.
DO use
```
kanban-md show ID
```
(default format) to read task details — it is readable and includes the full body.
DO pass
```
--yes
```
on delete. Without it, the command hangs waiting for stdin.
DO use
```
pick --claim <agent> --status todo --move in-progress
```
rather than list → edit → move — it's atomic and prevents claim races.
DO use
```
-a
```
/
```
--append-body
```
with
```
--claim <agent>
```
when adding progress notes — this renews the claim and appends without overwriting the body.
DO NOT use
```
--json
```
unless you are piping output to another tool or parsing fields programmatically. Default and
```
--compact
```
formats are sufficient for reading.
DO NOT hardcode status or priority values. Read them from
```
kanban-md board --compact
```
.
DO NOT use
```
--next
```
or
```
--prev
```
without checking current status. They fail at boundary statuses.
DO NOT pass both
```
--status
```
and
```
--next
```
/
```
--prev
```
to move. Use one or the other.
DO quote task titles with special characters:
```
kanban-md create "Fix: the 'login' bug"
```
.