Kanban Based Development

<!-- kanban-md-skill-version: 0.38.0 -->

Kanban-Based Development

Autonomous, parallel-safe development using kanban-md to coordinate work on a shared board. Claims expose task ownership and reduce duplicate work when participants follow the protocol; review is the waiting room (handoff, user action, merge, decisions).

Multi-Agent Environment

This board is shared. Multiple agents and humans may be working on it simultaneously. You are NOT the only one reading or modifying tasks. This means:

• Another agent may claim a task between the time you list it and try to pick it.
• Tasks you saw as available a moment ago may no longer be available.

The claim mechanic is the coordination primitive. It lets cooperating agents exclude work already owned by someone else. You MUST claim a task before starting any work on it, and you MUST only pick unclaimed tasks. Claims are leases rather than a security or distributed-transaction boundary; ignoring the protocol can still cause duplicate work and merge conflicts.

Non-Negotiables

• Claim before you change anything. No task edits, no code changes.
• One active task per agent. Keep at most one task in in-progress for your agent session.
• Never steal a live claim. If it's claimed, pick something else.
• Never release someone else’s claim. Only use edit --release for your own work (or when the user explicitly asks).
• Always leave a handoff. Before you park a task, write a short update in the body so someone else can continue.
• Refresh claims to avoid timeout. If the task might take longer than claim_timeout, periodically renew your claim: kanban-md edit <ID> --claim <agent>.

Board Home vs Worktrees (simple rule)

• Always run kanban-md from board home (the canonical repo directory that owns the shared board).
• Always do code changes in a task worktree. Never edit code in board home.
• If the board is git-tracked, commit board changes on main as a separate commit after the task is merged and moved to done.

At the start of the session, determine and remember <board-home>:

cd <the canonical repo directory that owns the shared board>
pwd   # remember this path as <board-home>

Recommended: keep two shells (or split panes) open:

• Board shell at <board-home> for kanban-md commands
• Worktree shell at the task worktree for code changes

Do not run multiple mutating kanban-md commands in parallel against the same board directory.

If you are unsure you’re using the shared board, run kanban-md board --compact and confirm the board name/shape is what you expect.

Defer-to-User Boundary (exceptions)

By default, agents should take tasks all the way to done (worktree → commit → merge → done).

Defer to the user (leave the task in review with a handoff) only when you need:

• an important product/spec decision with multiple valid options and no clear winner
• credentials/access or external actions (push to remote, releases, deployments, ENV variables, etc.)
• a merge conflict that requires judgment (not just mechanical resolution)
• repeated test/lint failures you can’t resolve

Agent Identity (for claims)

Each agent session must generate a unique name to identify itself for claims. At the very start of a session, run:

kanban-md agent-name

This produces a name like quiet-storm or frost-maple. Remember this name in your context and use it as a literal string in all claim/release commands for the rest of the session. Do not store it in a file or environment variable — those are not persistent or isolated between agents.

Example: if the generated name is frost-maple, use --claim frost-maple in every claim command.

Default Loop (worktree → merge → done)

Use --compact for board/list/log output whenever available to keep output short.

Before picking work, ensure board home is on main:

cd <board-home>
git switch main
git status

1) Pick and claim in one command

From board home:

Pick only from startable columns to avoid accidentally re-picking review work:

kanban-md pick --claim <agent> --status todo --move in-progress

If todo is empty:

kanban-md pick --claim <agent> --status backlog --move in-progress

This replaces a separate list → choose → claim sequence and records ownership immediately. By default, pick also prints the full task details, including the body, so a follow-up show is unnecessary.