What you're building
A task management system that lives inside your repo as markdown files. Three folders (inbox, in-progress, done) hold individual task files. Gates at each transition enforce dependency order, acceptance criteria, and WIP limits. Multiple Claude Code agents can work the board at the same time, each claiming and finishing tasks without stepping on each other.
The board lives at .kanban/ in your project root. An index.md file tracks the full inventory, changelog, and configuration. Each task is its own file with YAML frontmatter: priority, complexity, dependencies, acceptance criteria, ownership.
No external tools or SaaS. Just files that travel with the repo.
Prerequisites
- Claude Code (CLI, desktop, or IDE extension)
- A git repo (the board lives alongside your code)
Install the skill
Clone the skill repo into your Claude Code skills directory:
bashgit clone https://github.com/solutionscay/agent-kanban.git \
~/.claude/skills/agent-kanban
Claude Code picks up skills from ~/.claude/skills/ automatically. Once cloned, the skill activates when you mention task management, ask "what should I work on next," or reference a PRD.
Initialize a board
Tell Claude Code to set up a board. It can work from a PRD, a plain list of tasks, or build one interactively:
> Set up a kanban board from this PRD: [paste or reference file]
> Create a kanban board with these tasks: > 1. Set up the database schema > 2. Build the API endpoints > 3. Wire up the frontend forms
The skill creates this structure:
.kanban/
index.md # board controller
inbox/
001-database-schema.md
002-api-endpoints.md
003-frontend-forms.md
in-progress/ # empty at start
done/ # empty at start
Tasks are numbered sequentially. The skill derives dependencies automatically. If task 3 references tables from task 1, it adds that dependency.
Task file format
Each task file uses YAML frontmatter with a body for notes:
yaml---
id: "001"
title: "Set up the database schema"
priority: p0
complexity: M
depends_on: []
created: "2026-05-26T10:00:00Z"
last_touched: "2026-05-26T10:00:00Z"
claimed_by: ""
stale: false
acceptance:
- "Migration runs without errors"
- "All tables have proper indexes"
- "Seed data loads successfully"
---
p0 is must-have, p1 is should-have, p2 is nice-to-have. Complexity goes from S (under 30 minutes) through M (1-2 hours) and L (half a day) to XL (a full day or more).
claimed_by is empty when unclaimed. When an agent starts work, it writes its identity here: a session ID, worktree name, or self-assigned label like agent-1.
acceptance lists concrete, verifiable criteria. "Works correctly" doesn't cut it. "Migration runs without errors on a fresh database" does.
The three gates
Every transition runs through a gate. No exceptions.
READY gate (inbox to in-progress)
Before an agent can start a task, five checks must pass:
| Check | What it verifies |
|---|---|
| WIP | This agent has no other task in in-progress |
| Claim | No other agent has claimed this task |
| Dependencies | Every task in depends_on is in done/ |
| Freshness | If the codebase changed since task creation, the description still applies |
| Clarity | At least one acceptance criterion exists |
If any check fails, the agent gets a specific resolution from the gate playbook. Finish your current task, pick a different one, work on a dependency first, or write acceptance criteria before starting.
DONE gate (in-progress to done)
Four checks before a task can move to done:
| Check | What it verifies |
|---|---|
| Acceptance | Every acceptance criterion passes. Run the test, check the file, verify the output. |
| Regression | Related features still work |
| Commit | Changes are committed or staged |
| Notes | Completion section filled: what was done, files changed, how it was verified |
The agent runs each acceptance criterion as a concrete check. "Migration runs without errors" means actually running the migration. "All tables have proper indexes" means querying the schema. Verbal confirmation doesn't count.
SWEEP (automatic maintenance)
SWEEP runs before every task pick. It scans the full board for problems:
- Pileup: inbox tasks with met dependencies that haven't started
- Drift: tasks whose referenced files changed since creation
- Zombies: in-progress tasks stuck for 2+ turns without progress
- Orphans: tasks with dependencies that don't exist
- Conflicts: multiple in-progress tasks touching the same files
SWEEP flags issues but doesn't block work. Problems get surfaced early, before they compound.
Working the board
Pick and complete a task
> What should I work on next?
The skill reads the index, runs SWEEP, finds the highest-priority non-stale inbox task with met dependencies, runs the READY gate, claims it, moves it to in-progress, and starts working.
When the work is done:
> Mark the current task as done
The skill runs the DONE gate. It checks acceptance criteria, looks for regressions, verifies the commit, fills completion notes, moves the file to done, and updates the index.
Check board status
> Show the kanban board
Returns a table of all tasks across all three columns with priority, owner, dependencies, and stale flags.
Split a task that's too big
If a task turns out to be larger than expected, split it instead of abandoning it:
> This task is too big, split it
The skill creates 2+ smaller task files with new sequential IDs, carries over dependencies, adds cross-dependencies if the subtasks are ordered, updates anything that depended on the original, and moves the original to done with a note: "Split into 004, 005."
Multi-agent usage
This is where it gets interesting. The board supports parallel execution. Each agent identifies itself with a tag (claimed_by), and the WIP limit is enforced per agent, not globally.
To run multiple agents, open separate Claude Code sessions (or use worktrees). Each session picks its own tasks. The skill coordinates through the shared files:
- Agent 1 claims task 001, moves it to in-progress
- Agent 2 tries to claim task 002, but it depends on 001, so the READY gate blocks it
- Agent 2 picks task 003 instead (no dependencies)
- Agent 1 finishes 001, moves it to done
- Agent 2 finishes 003, then picks up 002 now that the dependency is met
SWEEP warns when two in-progress tasks reference the same files, so agents can coordinate before they create merge conflicts.
The index file
index.md is the board controller. Every operation reads it first and updates it after. Three sections:
Config
yamlwip_limit_per_agent: 1
staleness_threshold: 3
last_sweep: "2026-05-26T10:30:00Z"
wip_limit_per_agent caps how many in-progress tasks a single agent can hold. Default is 1, meaning finish before you start. staleness_threshold is how many other tasks can complete before an idle inbox task gets flagged as stale.
Board state lists every task per column with ID, title, priority, dependencies, owner, and stale flag.
Changelog is a timestamped log of every move and decision. Who claimed what, what passed or failed gates, when SWEEP ran and what it found.
Gate playbook
When a gate check fails, the skill doesn't just say "blocked." It gives a specific resolution:
| Failure | Resolution |
|---|---|
| WIP exceeded | Finish your current task, split it, or move it back to inbox with an explanation |
| Task already claimed | Pick a different task |
| Dependencies not met | Work on the dependency first |
| Freshness failed | Re-read the referenced files, update the task description |
| Clarity failed | Write concrete acceptance criteria before starting |
| Acceptance criterion not met | Fix the issue, don't skip the check |
| Regression detected | Fix it now, or create a separate task if the fix is unrelated |
| Stale task | Revalidate. Is this still needed? Update or close it. |
| Zombie task | Assess scope, split if too large, document blockers if stuck |
Trade-offs
File-based, not real-time
The board is a set of markdown files. No live dashboard, no WebSocket updates, no drag-and-drop. You check status by asking Claude Code or reading the files directly. For solo or small-team agent workflows, that's enough. For a ten-person team, you'd want a proper project management tool.
Git conflicts on the index
If two agents update index.md at the same time and both commit, you get a merge conflict. In practice, agents working in separate worktrees avoid this. If it happens, the index can be regenerated from the task files. The files are the source of truth; the index is a cache.
No notifications
Nothing pings you when a task is done or blocked. You ask, or you check. SWEEP surfaces problems, but only when an agent runs it.
WIP limit is trust-based
The gate checks WIP before allowing a claim, but nothing prevents an agent from editing two files at once without going through the gate. The system works because the skill follows the protocol. It's discipline encoded in a prompt, not enforced by a lock.