Kanban Md

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.