# Kanban Based Development

> >

- **Type:** Skill
- **Install:** `agentstack add skill-antopolskiy-kanban-md-kanban-based-development`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [antopolskiy](https://agentstack.voostack.com/s/antopolskiy)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [antopolskiy](https://github.com/antopolskiy)
- **Source:** https://github.com/antopolskiy/kanban-md/tree/main/internal/skill/skills/kanban-based-development

## Install

```sh
agentstack add skill-antopolskiy-kanban-md-kanban-based-development
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Kanban-Based Development

Autonomous, parallel-safe development using `kanban-md` to coordinate work on a shared board.
Claims prevent duplicate work; `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 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  --claim `.

## 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 ``:

```bash
cd 
pwd   # remember this path as 
```

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

- **Board shell** at `` 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:

```bash
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`:

```bash
cd 
git switch main
git status
```

### 1) Pick and claim (atomically)

From board home:

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

```bash
kanban-md pick --claim  --status todo --move in-progress
```

If `todo` is empty:

```bash
kanban-md pick --claim  --status backlog --move in-progress
```

This is atomic — if another agent claims the task between your list and claim, `pick` handles it safely. No need to list/choose/claim manually.

After picking, read the full task:

```bash
kanban-md show 
```

### 2) Create a worktree (default)

Create a worktree for the task branch from board home:

```bash
git worktree add ../kanban-md-task- -b task/-
cd ../kanban-md-task-
```

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:

```bash
git add 
git commit -m "feat: "
```

### Progress notes (recommended)

While a task is `in-progress`, leave short timestamped notes in the task body from **board home** (especially after major steps or before/after running tests). This makes handoffs and reviews much faster.

```bash
kanban-md edit  --append-body "Implemented X/Y/Z, now running tests." --timestamp --claim 
```

The `--append-body` (`-a`) flag appends text to the existing body without replacing it. The `--timestamp` (`-t`) flag prefixes a timestamp line like `[[2026-02-10]] Mon 15:04`.

### 4) Merge to main (from board home)

Switch back to board home and merge your task branch:

```bash
cd 
git switch main
git status
```

If `git status` shows unexpected changes outside the board directory (usually `kanban/`) or a git operation in progress, do not proceed. Park the task in `review` and move on.

Merge and re-run tests on main:

```bash
git merge task/-
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`, leave a note (branch name + what’s left), and pick the next task.

To park a “ready to merge” task:

From board home:

```bash
kanban-md handoff  --claim  --note "Ready to merge: task/-…; remaining: …" --timestamp --release
```

### 5) Mark done (only after merge)

Only after the merge is on main and checks pass:

From board home:

```bash
kanban-md edit  --release
kanban-md move  done
```

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

From board home:

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

### 7) Optional cleanup

```bash
git worktree remove --force ../kanban-md-task-
git branch -d task/-
```

## 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:

```bash
kanban-md handoff  --claim  \
  --block "Waiting on user: " \
  --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:

```bash
kanban-md edit  --claim 
kanban-md edit  --unblock --claim    # if it was blocked
kanban-md move  in-progress --claim 
```

## Status meanings (keep the board honest)

| Status | Meaning |
|---|---|
| `in-progress` | Actively being worked by an agent right now |
| `review` | Waiting state: ready to merge, or waiting on user/decision/unblock |
| `done` | Merged to main (and checks pass) |

## When there is nothing to pick

If `pick` returns "no unblocked, unclaimed tasks found":

- 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).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [antopolskiy](https://github.com/antopolskiy)
- **Source:** [antopolskiy/kanban-md](https://github.com/antopolskiy/kanban-md)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-antopolskiy-kanban-md-kanban-based-development
- Seller: https://agentstack.voostack.com/s/antopolskiy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.