kanban-md

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

SKILL.md

GitHub
<!-- kanban-md-skill-version: 0.38.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, archived.
  • 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 --unblocked --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 --claim <agent>
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
Soft-delete with confirmation semantics kanban-md delete ID --yes
Archive a task explicitly kanban-md archive ID
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] [--unclaimed] [--claimed-by AGENT] \
  [--class C] [--archived] [--group-by FIELD]

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] [--class C] [--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 --archived  # include archived direct children
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] [--class C] \
  [--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] \
  [--parent ID] [--no-body]

Finds the highest-priority unclaimed, unblocked task and claims it in the same command. Use --status to restrict which column to pick from. Use --move to move the task in that operation. This replaces the slower list → claim → move sequence. Claims are cooperative leases rather than a distributed transaction. By default the result includes full task details; use --no-body when the one-line confirmation is enough.

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

Moves the task to archived; the task file remains on disk. Always pass --yes because non-interactive contexts cannot answer the confirmation prompt.

archive

kanban-md archive ID[,ID,...] [--claim AGENT]

Moves tasks to archived without a confirmation prompt. Pass the current claim name when archiving an actively claimed task.

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]

Common action types: create, edit, move, delete, block, unblock, claim, release, handoff, and priority.

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 — 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 archive ID

Sprint Planning

  1. kanban-md board --compact — current state
  2. kanban-md list --compact --status backlog,todo --sort priority — 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 tasks ready after dependencies resolve: kanban-md list --compact --unblocked

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 (single-step 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

Pick already prints full task details; add --no-body only when they are unnecessary.

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
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, a non-interactive command exits with a confirmation-required error.
  • DO use pick --claim <agent> --status todo --move in-progress rather than list → edit → move — one operation minimizes the coordination window and records ownership immediately.
  • 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.