VibeMap Logo

6.1 — Kanban tracker: step-by-step user guide

On this page

6.1 — Kanban tracker: step-by-step user guide

The kanban tracker is where your spec meets your codebase. Each card is one acceptance criterion (AC) — "User can reset password via email" — and your AI coding agent moves those cards itself as it works, from your IDE, over MCP.

This page is about driving that loop from outside the browser: what the agent does, who may move what, how work is reserved for a particular agent, and the four setup shapes people actually run. For the in-app half — reading the board, approving in batches, the Activity feed — see Watching progress in the user docs. For the endpoint-by-endpoint contract, see 6.2 — API reference.

Time to first claimed AC: about 15 minutes, most of it MCP setup you only do once per machine.

Contents

  1. What the tracker actually does
  2. Prerequisites
  3. Connecting your IDE
  4. The agent loop
  5. Assigning work
  6. Scenario A — solo, local-only, no GitHub
  7. Scenario B — GitHub PRs with manual review
  8. Scenario C — GitHub Actions with automatic review
  9. Scenario D — returning after a break
  10. Where this shows up in the browser
  11. Common situations
  12. FAQ
  13. Where to go next

What the tracker actually does

Cards live in columns that map to the lifecycle of one piece of work:

┌─────────┐ ┌─────────┐ ┌─────────────┐ ┌───────────┐ ┌────────┐ ┌────────┐ ┌─────────┐
│  draft  │ │  ready  │ │ in_progress │ │ in_review │ │ passed │ │ failed │ │ blocked │
└─────────┘ └─────────┘ └─────────────┘ └───────────┘ └────────┘ └────────┘ └─────────┘

Who moves a card, and how:

TransitionWhoHow
draft → readyYou (web)Approve the AC — the gate that says "go build it"
ready → in_progressAgent or youvibemap_claim_criterion, or drag the card into In Progress. Atomic — a losing racer gets 409 race. Claiming binds the claimant as the assignee.
in_progress → in_reviewAgentvibemap_submit_for_review — requires a git SHA + diff URL as evidence
in_review → passed / failedYou (web) or a CI tokenThe submitting agent cannot resolve its own work
failed → readyYou (web), or the assigned agentPOST .../rework — the retry carries the rejection reason automatically
any active → blockedAgent or youvibemap_block_criterion — needs a category (spec_unclear / missing_dep / external_blocker / other) + reason
blocked → prior statusAgent or youvibemap_unblock_criterion — restores whatever status the card had when blocked
in_progress → readySystem onlyAutomatic rollback when a claim goes idle for 24 hours

The unique part: your AI coding assistant is a real participant. It moves the card itself, leaves notes, and submits work for review without you dragging anything.

Why you care:

  • You always know what your agent is doing without asking it.
  • Two agent sessions can't do the same work twice — the claim is atomic, and work assigned to someone else is skipped entirely.
  • If an agent dies mid-claim, the system unsticks the card after 24 hours.
  • Every transition is logged with proof (commit SHA + diff link).

Prerequisites

  • A VibeMap project with features and acceptance criteria. If your project has a name and nothing else, generate features first.
  • At least one AC approved into ready. Until then the agent has nothing claimable. Approving is done in the browser — see Watching progress.
  • An MCP-capable IDE — Claude Code, Cursor, Windsurf, or VS Code with Copilot.
  • An API key. Account → Developer → Generate Key, copied once at creation.
  • (Scenarios B/C only) A GitHub repository for your code.

MCP access is on every plan, free included. What your plan changes is which parts of the spec your agent may author over that connection — the kanban tools are available regardless.

Connecting your IDE

One config block, one API key, one restart. Two paths, both documented in full elsewhere:

Verify by asking your agent in a fresh session:

"List the VibeMap tools you have available."

You should get a few dozen tools whose names start with vibemap_. If the list is empty, your MCP config path or JSON is wrong — see Troubleshooting.

⚠️ Don't commit your MCP config if it lives inside a project folder. It contains your API key. Add .cursor/, .windsurf/, .vscode/mcp.json or .claude/mcp.json to .gitignore.

The agent loop

This is the canonical cycle. Everything below is driven from your IDE.

Find your project ID from the browser URL: in https://vibemap.ai/project/8a3f7b2c-…/development, the ID is 8a3f7b2c-…. Every prompt about VibeMap needs it, so keep it handy.

1. Pick up work.

"Pick up the next ready acceptance criterion from VibeMap project <id> and implement it. Claim it first so no one else takes it. Show me what you found before writing code."

The agent calls vibemap_get_next_ready_criterion, then vibemap_claim_criterion. The card moves ready → in_progress and the agent becomes its assignee.

If the agent reports no work available, check whether the response carried reason: "reserved" — that means ready work exists but is assigned to someone else, which is a different problem from an empty queue. See reservation.

2. Optionally, get the whole plan at once. Instead of discovering the order one call at a time, GET /api/mcp/kanban/projects/<id>/execution-plan returns every criterion topo-sorted and grouped by sprint, with ready and blockedOn per item. Useful for an agent that wants to plan a session rather than a single card.

3. Leave a progress note (optional, no status change):

"Send a progress note to VibeMap saying you're halfway through and the migration is the trickiest part."

That's vibemap_report_progress. It shows up in the card's timeline and the Activity feed.

4. Submit for review.

"Submit this for review. Use the most recent commit on this branch as the git SHA and the PR link as the diff URL."

vibemap_submit_for_review(criterionId, gitSha, diffUrl, notes?) moves the card in_progress → in_review. Both SHA and diff URL are required at the schema level — see Scenario A if you haven't pushed anywhere.

5. Somebody else resolves it. A human clicks Pass or Send back on the board, or CI posts a result. Agents cannot resolve their own work; the server returns 403 agents_cannot_self_resolve if one tries.

6. On a failure, rework. A failed card can be re-queued by the agent it was assigned to:

"That criterion failed review. Re-queue it for rework and tell me why it failed."

POST .../rework moves it back to ready and injects the failing review's feedback into the event payload, so the retry always carries the reason. An agent that isn't the assignee gets 403 not_assigned_agent.

Assigning work

Assignment answers "who is doing this" — and, because the next-ready selector honours it, it also decides who gets served what.

The assignee control on a card

Every card carries an assignee control whose shape is derived from how many candidates the project has:

CandidatesWhat you see
0Nothing — there is nobody to assign to
1A Claim button, toggling to Unassign once set
2 or moreAn avatar picker

So a personal project with no API keys degrades to a Claim/Unassign toggle, while a team project shows a picker listing every member of the owning team. A one-entry dropdown reads as a bug, so it's never rendered.

Your agents are assignees

Your own personal access tokens appear in the picker under a "Your agents" heading, each with a bot glyph rather than initials — a row of human initials with "CC" in it would read as a person, and knowing which of the two is doing the work is the entire point.

Details worth knowing:

  • Only your own tokens are listed, not your teammates'. A colleague's token would pass the database check (it inherits its owner's project access), but listing it would leak which tools your colleagues run.
  • Expired tokens are excluded. They can't authenticate, so an assignment to one could never be acted on.
  • Tokens are ordered most-recently-used first, so the agent actually working leads the list.
  • Claim always means a person. With both people and agents in the list, the single-candidate Claim button falls back to a human, never to an agent that happened to sort first.

The footgun

A personal access token's identity is the agent, not you. So assigning a criterion to yourself makes your own agent skip it — that's how you hold work back for a human. To hand work to an agent, pick it by name under Your agents.

This changed with the assignment model: before, a token presented its owner's user id, so an agent would pick up work its owner had reserved. There was no way to tell them apart; now there is.

Filtering by assignee

Above the board:

  • An Assignee filter listing every candidate plus All Assignees and Unassigned, each with a live count. It's hidden entirely on a project with no candidates.
  • A Mine toggle — a one-click shortcut onto the same filter, not a separate axis, so the two can never disagree about what's on screen.

Both match the criterion's own assignee only.

Area owners

A feature can be assigned too. On a card whose criterion is unassigned, that feature's assignee shows as a small muted avatar tagged area, meaning "this person owns the feature area; this criterion is unassigned."

Area ownership deliberately confers nothing: it never cascades to the criteria beneath it, it isn't matched by the Assignee filter or Mine, and it doesn't affect what next-ready serves. It's context, not ownership.

Scenario A — solo, local-only, no GitHub

You're prototyping on your laptop and haven't pushed anywhere. The tracker still works; it just needs placeholder evidence.

Tell your agent:

"Take the next ready AC from project <id>, claim it, and implement it. Don't push anywhere — this is local. Use a placeholder git SHA (local- plus the first 7 chars of a hash of the diff) and https://example.com/local/<my-name> as the diff URL."

Then review the changes yourself and click Pass on the board. The SHA and diff URL are required by the API as discipline, but any string that satisfies the schema is accepted (git_sha needs ≥7 characters; diff_url must parse as a URL).

What you give up: no CI auto-resolution, and an audit log you can't click through six months later. Fine for a personal project — move to Scenario B the moment anyone else needs to read your work.

Scenario B — GitHub PRs with manual review

Each AC's implementation lands as a PR. You read the PR, then resolve on the board.

"Take the next ready AC from project <id>, claim it. Create branch ac/<short-id>. Implement it. Commit with message feat(<area>): <ac title> (AC-<id>). Push and open a draft PR against main."

The agent then submits with the real SHA and PR URL. Passing on VibeMap and merging on GitHub are independent — the two systems don't talk.

A convention that pays off later:

Branch:     ac/abc-123-password-reset
Commit:     feat(auth): user can reset password via email (AC-abc-123)
PR title:   [AC-abc-123] Password reset flow
PR body:    VibeMap-Criterion: <criterion uuid>

The VibeMap-Criterion: line is what Scenario C's workflow reads.

Scenario C — GitHub Actions with automatic review

Same as B, but your test run resolves the criterion instead of you. No human click for routine, well-tested work.

This has its own page, because the token has a sharp edge: CI needs a ci_review-scoped key, and an agent key posted to ci-result is rejected — the token that does the work must not be the token that passes it. Choose the scope when you create the key at Account → Developer; it cannot be changed afterwards. Follow 6.3 — CI review driver — it covers the token, the workflow YAML, and the build-evidence join that links the criterion to the code it touched.

⚠️ CI passing means "the tests didn't break," not "this is what you wanted." For design-sensitive ACs, leave the marker out of the PR body and resolve those by hand. Auto-resolution is best for high-volume, well-tested grunt work.

Scenario D — returning after a break

  1. Read the board. Anything still in in_progress? In in_review waiting on you? In blocked? The card timeline tells you who last touched it and when. Full tour: Watching progress.

  2. Abandoned claims have already been reclaimed. After 24 hours with no activity, an hourly job reverts an in_progress card to ready. The timeline shows it:

    auto_revert · system:auto-revert · { idle_hours: 24 } · Mon May 10 03:00 UTC

  3. Nothing auto-resolves. Cards sitting in in_review for over 7 days emit a metric, but you always own the click.

  4. Restart the loop — §4. Or replay what happened while you were away:

    curl "https://vibemap.ai/api/mcp/kanban/projects/<project-id>/events?since=2026-08-01T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $VIBEMAP_API_KEY"

Where this shows up in the browser

The board is the whole Development page — labelled Hand off to IDE in the project sidebar, or Sync with IDE on a code-first project. There is no tab strip.

Two things that used to be tabs here now live elsewhere:

  • Sprint planning is its own Sprint Planning page under Prepare. See Sprint planning, or 7.1 for how it gates the agent's queue.

  • Connection details are behind the ⓘ Handoff Instructions button at the top-right of the board, next to the Category filter. It carries your API-key status and the MCP config block for your IDE.

The board itself, with the Activity feed below it, is where you watch the agent work.

Everything about reading and driving the board from the browser — the columns, the Activity feed, reviewing in batches, unattended runs — is covered in Watching progress.

Common situations

"I claimed something then changed my mind."

Block it with category other and a short reason, then unblock — it restores to its prior state. Or just walk away: the 24-hour auto-revert releases it for you.

"The agent submitted but the work is wrong."

Send it back. The card moves to failed; the assigned agent can re-queue it with rework (carrying your rejection notes), or you can drag it back to Ready. The original commit SHA stays in the audit log either way.

"I'm blocked on something external."

"Block AC <id> with category external_blocker and reason 'Stripe webhook test mode is failing — waiting on vendor support'."

The agent calls vibemap_block_criterion. Unblock with a resolution note when the vendor answers.

"Two IDE windows tried to claim the same thing and one failed."

That's the atomic-claim guarantee working. The loser gets 409 race — have it call vibemap_get_next_ready_criterion again and it'll find a different AC.

"My agent says there's no work, but I can see ready cards."

Three candidates, in order of likelihood:

  1. The cards are assigned to someone else. The next-ready response says so: reason: "reserved" plus a count. Remember that assigning to yourself hides work from your own agent.
  2. They're in a sprint that isn't active, or blocked by an unpassed hard prerequisite — see 7.1.
  3. A bootstrap AC is still unpassed. Foundation work is served before anything else.

"My CI marked it passed but I disagree."

passed is terminal by design. Either edit the AC's content and approve a new draft, or open a follow-up AC. This friction is what keeps the audit log trustworthy.

"The agent hit agents_cannot_self_resolve."

Working as intended. Resolve as a human on the board, or with a ci_review-scoped token from CI (6.3). If you want a fully autonomous loop, Scenario C with a real test suite is the way.

"The agent hit not_assigned_agent on rework."

Only the criterion's assigned agent can re-queue its own rejected work. Assign the card to that agent, or send it back from the board yourself.

FAQ

Do I have to use AI to use the tracker? No. You can approve, claim, block and resolve entirely from the board or over HTTP. The agent integration is the useful part, not a requirement.

Can I import an existing codebase? Not into the tracker directly — it tracks acceptance criteria, which come from your VibeMap spec. The supported path is to sync the codebase into VibeMap first; see Codebase sync & code map.

Does the tracker cost anything? The tracker is on every plan, and so is MCP access. Driving the board over MCP spends no VibeMap tokens — your agent runs on its own. What is plan-gated is server-side generation, including the Prepare-for-Dev pipelines and the sprint planner (both Pro+).

Can my team see my board? Anyone with project access sees the same board. Row Level Security on kanban_events enforces it server-side — non-members can't even subscribe to the realtime channel.

What happens if VibeMap goes down mid-session? Your code is untouched — nothing in your repo depends on VibeMap being up. The agent's calls fail with network errors; retry the last action when it's back and the board catches up from the audit log.

Can I delete cards? You can delete acceptance criteria, which removes their cards. You can't delete events — the audit log is immutable by design.

Can I drive all of this without the UI? Yes. Every board action is an HTTP endpoint — see 6.2 § HTTP API. The web board is one consumer, not the source of truth.

Where to go next