Kanban-Based Development

Autonomous, parallel-safe development using

kanban-md

review

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 prevents two agents from working on the same task. You MUST claim a task before starting any work on it, and you MUST only pick unclaimed tasks. Violating this causes duplicate work, merge conflicts, and wasted effort.

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

If you are unsure you’re using the shared board, run

kanban-md board --compact

Defer-to-User Boundary (exceptions)

By default, agents should take tasks all the way to

done

Defer to the user (leave the task in

review

• 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

frost-maple

Example: if the generated name is

frost-maple

--claim frost-maple

Default Loop (worktree → merge → done)

Use

--compact

Before picking work, ensure board home is on

main

cd <board-home>
git switch main
git status

1) Pick and claim (atomically)

From board home:

Pick only from startable columns to avoid accidentally re-picking

review

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

If

todo

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

This is atomic — if another agent claims the task between your list and claim,

pick

After picking, read the full task:

kanban-md show <ID>

2) Create a worktree (default)

Create a worktree for the task branch from board home:

git worktree add ../kanban-md-task-<ID> -b task/<ID>-<kebab-description>
cd ../kanban-md-task-<ID>

Skip a worktree only for truly non-conflicting work (e.g., board-only changes or writing an untracked research report). If you touch tracked code/config, use a worktree.

3) Implement, test, commit (in the worktree)

Implement the smallest change that satisfies the task.

• Bugs: write a failing test first (TDD), then fix.
• Run the appropriate checks for the change (common defaults):

  • go test ./...

  • golangci-lint run ./...

Commit in the worktree when green:

git add <files>
git commit -m "feat: <description>"

Progress notes (recommended)

While a task is

in-progress

kanban-md edit <ID> --append-body "Implemented X/Y/Z, now running tests." --timestamp --claim <agent>

The

--append-body

-a

--timestamp

-t

[[2026-02-10]] Mon 15:04

4) Merge to main (from board home)

Switch back to board home and merge your task branch:

cd <board-home>
git switch main
git status

If

git status

kanban/

review

Merge and re-run tests on main:

git merge task/<ID>-<kebab-description>
go test ./...
golangci-lint run ./...

If you cannot merge right now (e.g., another merge/rebase is in progress), do not force. Park the task in

review

To park a “ready to merge” task:

From board home:

kanban-md handoff <ID> --claim <agent> --note "Ready to merge: task/<ID>-…; remaining: …" --timestamp --release

5) Mark done (only after merge)

Only after the merge is on main and checks pass:

From board home:

kanban-md edit <ID> --release
kanban-md move <ID> done

6) Commit board changes (only if board is git-tracked)

From board home:

git add kanban/config.yml kanban/tasks/
git commit -m "chore(board): update task #<ID>"

7) Optional cleanup

git worktree remove --force ../kanban-md-task-<ID>
git branch -d task/<ID>-<kebab-description>

Blocked / Needs User Input (the “review and move on” rule)

If you cannot continue without the user (decision, access, environment, or anything outside your control):

From board home:

kanban-md handoff <ID> --claim <agent> \
  --block "Waiting on user: <what you need>" \
  --note "## Handoff
- Current state:
- Branch (if any):
- Open questions (A/B):
- Next step:" \
  --timestamp --release

In your handoff note, include:

• The exact question(s) for the user (prefer A/B options)
• What you already tried and what happened
• The minimal next step after the user responds

Then pick the next task. Do not idle.

Resuming a parked task

When the user answers and you need to continue, re-claim and move back to

in-progress

From board home:

kanban-md edit <ID> --claim <agent>
kanban-md edit <ID> --unblock --claim <agent>   # if it was blocked
kanban-md move <ID> in-progress --claim <agent>

Status meanings (keep the board honest)

in-progress

review

done

When there is nothing to pick

If

pick

• Check blocked work:

  kanban-md list --compact --blocked

• Check waiting work:

  kanban-md list --compact --status review

• If everything is waiting on the user, ask targeted questions and stop (don't thrash the board).