Handoff overview
On this page
Handoff overview
How VibeMap hands your spec to your own AI coding agent — via MCP, not a code export. · Required
New to VibeMap? Read the end-to-end walkthrough first — it strings every step together in order. This page is the how of the handoff itself.
Once your spec is in good shape and Prepare for Dev is done, it's time to hand the work to your AI coding agent.
VibeMap doesn't try to be a code generator on the handoff path. Instead it connects to your agent — Cursor, Claude Code, Windsurf, or VS Code with Copilot — over the Model Context Protocol (MCP). Your agent reads the spec from VibeMap, picks the next ready acceptance criterion, implements it in your codebase, and submits the result. You (or your CI) approve, and the next AC unlocks.
Figure: The Handoff Instructions panel on the Development page.
💡 Tip: Prefer VibeMap to write the code for you instead of your own IDE agent? Use the App Builder — the "Build it here" path on the Development page.
📎 Two jobs, one connection. The MCP link you set up here does double duty. This page is about the build side — your agent reads a finished spec and implements it. The same connection also lets your agent author the spec in the first place, on your own tokens, instead of VibeMap generating it — see Two ways to generate. Same API key, same config; the tools your agent uses just differ (
vibemap_create_*to author vs.vibemap_claim_criterion/vibemap_submit_for_reviewto build). MCP itself is on every plan — what varies by plan is which entities your agent may author.
The handoff is bidirectional
This isn't a one-way export. Over MCP your agent reads the spec and reports progress back: it moves cards, leaves notes, and submits work for review. You watch it happen live on the Development board.
| What an export used to give you | What MCP gives you |
|---|---|
| A ZIP of scaffolding, frozen the moment you downloaded it | A live read into your real repo, always current with the spec |
| A static PRD document | The spec itself, queryable in-app or via the API, updating as you edit |
| No feedback loop | Cards move, notes appear, reviews flow — a two-way channel |
Three things to set up
Everything you need lives in the Handoff Instructions panel — the ⓘ button at the top-right of the Development board.
1. Generate an API key
Your agent authenticates with a personal access token. Click through to Account → Developer → Generate Key, name it after the agent or machine, and copy it — it's shown once. The Handoff Instructions panel shows how many keys you already have.
2. Connect the MCP server in your IDE
The Handoff Instructions panel has a copy-paste MCP config block for your project (the same @vibemap.ai/mcp-server config used everywhere). Paste it into your IDE's MCP config, drop in your API key, and restart. Full per-IDE steps → Connect your IDE.
3. Mark at least one acceptance criterion as Ready
Acceptance criteria start as draft — they sit in the board's Awaiting Approval column. On the Development board, approve at least one AC to move it to Ready — that's what makes it claimable. Run Prepare for Dev first so your agent has the full blueprint to work from.
Where each piece lives
The Development page no longer has a tab strip — it's the live board. The other two jobs each moved to their own place:
| Where | What it's for |
|---|---|
| Sprint Planning page (under Prepare) | Group ACs into dependency-respecting sprints → Sprint planning |
| ⓘ Handoff Instructions panel (on the Development board) | Your API key + MCP config — the connection surface |
| Development board | The live board and Activity feed → Watching progress |
Connection details in the Handoff Instructions panel only appear once a Prepare-for-Dev run has completed — there's no point wiring up an agent before it has a blueprint to build from.
Running your first work session
In your IDE, ask your agent something like:
Use the VibeMap MCP server to get the next ready criterion for project
<id>, then implement it and submit for review.
Your agent will get the next ready AC, claim it so other sessions don't double up, implement the work in your codebase, and submit for review with a git SHA and diff URL. You watch cards move on the Development board.
What if I just want the spec as a document?
A few legitimate "just give me the docs" cases:
- Share with a non-developer stakeholder — send them the read-only project summary.
- Import into Linear / Notion / Confluence — pull features, stories, and ACs via the REST API, or export to Jira.
- Back up your spec — the read-only JSON export covered in the developer docs.
⚡ Power-user hints
- Approval is a real gate, not a convention. A key acting as an agent is refused when it tries to resolve its own review, so an unattended loop can never mark its own work done. CI can approve, but only with a key scoped for review.
- You can wire the connection before the blueprint exists. The Handoff Instructions panel waits for Prepare for Dev, but Use in IDE in the project sidebar works from day one — project id, paste-ready prompts, and a pointer to your key.
- One key per agent beats one key for everything. Keys are account-level, so a per-agent key lets you revoke a single misbehaving session from Account → Developer without disconnecting the rest.
↔ The traditional way
Traditionally you'd write a spec document, print or PDF it, and hand-brief a contractor in a kickoff call — then chase status over Slack and reconcile their work against the doc by hand. MCP replaces the document-and-briefing ritual with a live connection: your agent reads the current spec directly and reports each unit of work back onto a board you both watch, so status is never a question you have to ask.
What's next
- Connect your IDE, step by step → Connect your IDE
- Watch your agent work → Watching progress
- Hit a snag? → Troubleshooting