antopolskiy/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

1. kanban-md board --compact — board overview
2. kanban-md list --compact --status in-progress — in-flight work
3. kanban-md list --compact --blocked — stuck items
4. kanban-md metrics --compact — throughput and aging
5. Summarize: completed, active, blocked, aging items

Triage New Work

1. kanban-md list --compact --status backlog --sort priority -r — review backlog
2. For items to promote: kanban-md move ID todo
3. For new items: kanban-md create "TITLE" --priority P --tags T
4. For stale items: kanban-md delete ID --yes

Sprint Planning

1. kanban-md board --compact — current state
2. kanban-md list --compact --status backlog,todo --sort priority -r — candidates
3. Promote selected: kanban-md move ID todo
4. Assign: kanban-md edit ID --assignee NAME
5. Set deadlines: kanban-md edit ID --due YYYY-MM-DD

Complete a Task

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

Track a Bug

1. kanban-md create "Fix: DESCRIPTION" --priority high --tags bug
2. kanban-md edit ID --body "Steps to reproduce: ..."

Track a Dependency Chain

1. Create parent: kanban-md create "Epic title"
2. Create subtask: kanban-md create "Subtask" --parent PARENT_ID
3. Or add dependency: kanban-md create "Task B" --depends-on TASK_A_ID
4. 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".