Spec-Driven Kanban: A Board Where Every Card Has a Spec

A traditional kanban card is a title and a short description: “Add rate limiting to checkout.” For a human teammate that is enough, because a human fills the gaps from shared context, asks a question in standup, and knows implicitly which files are off-limits. The card is a pointer to a conversation, and the conversation carries the real definition of done.

Hand that same one-line card to a coding agent and the pointer dangles. The agent has no standup, no shared history, and no instinct for what is out of bounds. It reads “add rate limiting,” decides for itself that this means a new middleware layer, a Redis dependency, and edits to eight routes, and produces a 400-line diff that technically satisfies the title and satisfies nothing you actually wanted. This is drift: with no written definition of done, the agent optimizes for a plausible interpretation instead of the intended one, and you find out only when you open the PR.

A board full of one-line cards is a board managed by vibes, and vibes do not survive contact with an autonomous executor. Managing agents as work items, covered more broadly in project management for AI agents, needs the card itself to carry the contract. That is the single change spec-driven kanban makes.

A spec-driven card replaces the title-and-hope with a small, structured spec. It does not need to be long, a good one fits on a screen, but it must answer four questions the agent would otherwise guess at: what is the goal, which files may change, what does done mean, and what must stay untouched. Here is the checkout card from above, written as a spec instead of a wish:

## Story: Add rate limiting to the checkout API

Goal:
  Protect POST /api/checkout from abuse with a per-IP rate limit.

In-scope files:
  - src/app/api/checkout/route.ts   (add the limiter)
  - src/lib/ratelimit.ts            (new; token-bucket helper)
  - src/lib/ratelimit.test.ts       (new; unit tests)

Acceptance criteria:
  - 11th request from one IP within 60s returns HTTP 429
    with { error: "rate_limited" } and a Retry-After header.
  - Requests under the limit are unaffected (still 200).
  - ratelimit.test.ts covers the boundary (10 ok, 11th blocked).

Out of scope (do NOT change):
  - The Stripe session logic in route.ts.
  - Any other /api/* route.
  - The User schema or database migrations.

Each block does load-bearing work. The goal gives the agent a one-sentence outcome to aim at. The in-scope files collapse the hallucinated-scope failure mode, the agent is told exactly where it may write. The acceptance criteria are a testable definition of done, so the agent has something concrete to verify its work against before you ever see it. And the out-of-scope list, often the most valuable block, is what stops a rate-limiting story from quietly rewriting your Stripe logic. The full craft of writing these lives in spec-driven AI development; on the board, the point is simply that this spec rides on the card.

On a vibe board, columns are decoration: someone drags a card from “Doing” to “Done” when they feel like it. On a spec-driven board, the columns encode the workflow's actual checkpoints, and two of the transitions are hard gates that nothing crosses without passing a check. A card walks this lane:

1. 1

   Backlog

   A plain-language story sits here as a title and maybe a sentence of intent. It is a candidate, not yet a brief. Nothing is committed and no agent is involved.
2. 2

   Spec drafted

   The card gets a draft spec, goal, in-scope files, acceptance criteria, exclusions, generated from the title plus an analysis of the codebase. It is a proposal for how the work should be bounded, ready for a human to read.
3. 3

   Spec approved (the human gate)

   A person reads the draft, tightens anything too broad, adds a missing constraint, and approves. This is the load-bearing gate: no agent starts coding until a human has signed off on the spec. It is the one place the workflow forces you to think before an autonomous process runs.
4. 4

   In progress (agent in its own worktree)

   The approved spec becomes the agent's brief. The agent runs in its own git worktree on its own branch, so its changes are physically isolated from every other card. The card shows the branch, the agent's current action, and a live output tail.
5. 5

   In review (the PR gate)

   The agent opens a pull request. The reviewer checks the diff against the acceptance criteria on the card, not against a vibe. This is the second gate: work does not advance until the PR is approved and merged.
6. 6

   Done

   The PR is merged and the worktree is cleaned up. The card, its approved spec, agent log, and final diff stay searchable, so six months later you can reconstruct exactly what was decided and why.

The two gates, spec approval and PR review, are where a human is deliberately in the loop, and they bracket the one column where the agent runs unattended. That shape is intentional: you spend your attention defining the work and verifying it, and let the agent own the middle.

Kanban's oldest lesson, limit work in progress, matters more with agents than it ever did with humans, and for a second reason on top of the classic one. The classic reason is throughput: a card in In review that nobody reviews is a stalled card, and starting a fifth agent while four PRs wait unread just grows a review backlog you cannot clear. Your review throughput, not agent speed, is the real bottleneck on a spec-driven board.

The second reason is collision. Multiple agents editing one working tree will overwrite each other and produce a tangle no spec can untangle. The fix is a two-part isolation rule that a spec-driven board enforces by construction:

Bounded scope from the spec and physical isolation from the worktree are complementary: the spec keeps an agent from wanting to touch a neighbouring card's files, and the worktree makes it impossible for it to accidentally do so. The mechanics of running agents this way, and how many is sane at once, are in parallel agents with git worktrees.

The quiet payoff of putting a spec on the card is that review stops being a leap of faith. Without a written intention, reviewing an agent's PR means reading the whole diff cold and guessing whether it does the right thing, which is why most people skim and merge, and skimming is when bugs ship. The spec turns review into a checklist: you read the diff against the acceptance criteria, one line at a time.

Did the 11th request return a 429 with a Retry-After header? Did the tests cover the boundary? Did anything outside the in-scope files change, which the exclusion list forbids? These are binary questions with answers you can find in the diff, not judgment calls about intent. The same document that briefed the agent now scores its work, and because it was approved before the code existed, it is an honest contract rather than a rationalization written after the fact. Turning that reviewed PR into a merge is the last step of the AI PR automation workflow.

The two boards look identical, cards in columns, but they behave differently the moment an agent picks up a card. The difference is entirely in what the card carries and what the columns enforce:

None of this makes plain kanban wrong for humans, who supply the missing context themselves. It makes plain kanban wrong for agents, who cannot. The broader case for agent-native boards is in AI kanban for developers, and the Claude-Code- specific version, with the honest tool landscape, is in the Claude Code kanban guide.

The method is only as good as the discipline behind it. Three failure modes hollow out a spec-driven board until it is a vibe board with extra ceremony:

AIDEN's board is not a plain kanban with a spec field bolted on, it is spec-first by construction. Its model is Project → Epic → Story → Spec, and the story is where the board lives. When you add a story card, AIDEN drafts its spec, goal, in-scope files, acceptance criteria, exclusions, from the card title plus an analysis of your codebase, and parks the card in Spec Review. Nothing runs yet.

The approval gate is enforced, not advisory: since v1.5.21, no agent starts coding until you have read and approved the spec on the card. Once you do, AIDEN opens a dedicated git worktree on a new branch (one worktree per story, so parallel stories never collide), launches your Claude Code or Codex CLI with the approved spec as its working brief, and shows the branch, action, and live output on the card. When the agent finishes, the work lands as a PR per story with the spec attached as the description, so your reviewer reads the diff against the exact criteria you approved. Because AIDEN orchestrates the CLIs you already run, you bring your own inference, it is a cockpit over your agents, not a new model. Every gate this article describes, the human approval gate and the PR gate, is wired into the board rather than left to discipline.