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 task-owned 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

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] [--property KEY=LITERAL] \
  [--show-property KEY] [--group-by FIELD|property:KEY]

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] \
  [--set-property KEY=LITERAL]

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 task-owned fields and the body in a readable layout. Direct children use ID order unless children.detail_sort selects a numeric property. That setting affects detail order only, not list or pick. 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] \
  [--set-property KEY=LITERAL] [--clear-property KEY]

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.

Selected properties

Unknown task frontmatter survives ordinary edits but stays out of default output. Select a simple top-level value explicitly when it serves the board:

kanban-md create "Draft chapter" --parent 1 --set-property kind=chapter --set-property reading_order=20
kanban-md list --compact --property kind=chapter --show-property reading_order
kanban-md show 1 --json --show-property kind --show-property reading_order
kanban-md edit 2 --clear-parent --clear-property reading_order

The set/clear/filter/show flags are repeatable for distinct keys. Property keys are case-sensitive literal identifiers; dots do not traverse nested data. Task-owned names are reserved. CLI literals are bare or JSON-quoted strings, strict JSON numbers, lowercase booleans or null. For example, reading_order=20 is numeric; 'reading_order="20"' is a string. Null is not a missing key. Do not supply conflicting set/clear operations or duplicate keys.

Property filters are exact, typed and ANDed. list --group-by property:kind shows aggregate counts; it cannot combine with --show-property. A configured group order is not an enum: typos remain visible unknown groups.

Only ungrouped list and show accept --show-property. Requested JSON records add only selected supported scalars in properties; show projects the same keys on children. Missing values are omitted; null is retained; unsupported values are omitted with a warning. No wildcard or all-properties export exists. Nested objects, aliases and custom-tag values stay opaque. Configured badges and child order do not select JSON values.

Property values survive reparenting and detaching. Explicitly clear an ordering hint in the same edit when resetting placement. Selected mutations use normal claim/write checks and may refuse if retained YAML bindings would become unsafe; do not strip unrelated metadata to force success.

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.