Kanban Md

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 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 or 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".
• DO escape backticks in --body and --append-body values. Shell interprets backticks ( ) and $(...) inside double quotes as command substitution, which will execute the text as commands. Escape every backtick with a backslash: \ or use single quotes for the outer string if possible.