VibeMap Logo

8.0 — End-to-end walkthrough: blank project → shipping code

On this page

8.0 — End-to-end walkthrough: blank project → shipping code

This page is the single best place to read once if you're new to VibeMap. It strings together every other section of this guide in the order you'll actually do them, with explicit "you should now see X" checkpoints so you know you're on track.

If you're already past project setup and just want the agent-handoff bit, skip to §5. Get ready to hand off.

The full flow at a glance

  1. Create a project and write a clear prompt.
  2. Generate the spec — personas, features, user stories, acceptance criteria, pages, schema.
  3. Run Prepare-for-Dev — generates the atomic blueprint (interactions, state machines, permissions, data contracts) and auto-derives your Foundation stack (auth, payments, email, etc.).
  4. Review flagged items and explore the Blueprint Preview Map — resolve anything the pipelines flagged, then sanity-check the map of what will be built.
  5. Plan sprints — VibeMap topologically sorts your ACs by dependency and groups them into themed sprints.
  6. Provision an API key and configure the MCP server in your coding agent's IDE.
  7. Press play — point your agent at the project. It claims ACs in dependency order, implements them, submits for review. You watch the cards move on the Track tab.
  8. Review and approve the agent's work. Each approval unblocks the next AC.
  9. Iterate — when an AC fails, the agent picks it back up; when a sprint completes, the next one's ACs become claimable.

The web app does steps 1–6 and provides the observation surface for 7–9. The actual code-writing happens in your IDE, by your coding agent of choice, against your real repository.

1. Create a project

→ See 1.3 Creating your first project and 1.4 Writing effective prompts.

Checkpoint: you land on the project Summary page. The original prompt is captured there.

2. Generate the spec

Work top-to-bottom through the project tabs:

Checkpoint: you have features grouped by persona, each with user stories, each with acceptance criteria. ACs are in draft status by default — you'll graduate them later.

3. Run Prepare-for-Dev

Open the Prepare page (the "Prepare" step in the project stepper). It's a single top-to-bottom workspace: the generate control at the top, status banners in the middle, and the Blueprint Preview Map below. Click Prepare for Development (Pro+) to kick off four parallel pipelines — Interactions, State Machines, Permissions, and Data Contracts — plus, on full runs, a Spec Coverage pre-step that derives acceptance criteria from your features and binds UI states (empty/error/loading) to them.

Prepare run in progress

A coverage preflight runs first: if your spec has gaps (e.g. pages that don't bind to data contracts), a dialog flags them with deep links. You can fix them or Proceed anyway — it'll work either way, but gaps usually mean the agent has less context to work with later.

While the run is going, a live progress card appears in the agent-chat sidebar with a status dot and deep link per pipeline. If any pipeline fails, you get a Retry N failed pipeline(s) card that re-runs only the failures and preserves completed work. Your Foundation stack (auth, payments, email, ...) is derived automatically as part of the run — there's no separate proposal to approve.

Checkpoint: the progress card shows all four pipelines green and the Prepare page swaps its generate control for a compact status + regenerate view.

4. Review flagged items and check the map

Back on the Prepare page, look at the status banners under the generate control:

  • Green "Ready to build" — the run completed with nothing pending review and no coverage gaps. You're done here.
  • Amber "Flagged items" — some pipeline rows need a look (e.g. interactions that couldn't be auto-mapped, permissions that hit an edge case). Click the banner to open the Review dialog — a single unified surface for everything flagged — and approve or correct each item.

Then scroll down to the Blueprint Preview Map — a read-only diagram of your features, roles, pages, and data and how they connect. It's the fastest way to sanity-check the blueprint before handing off. Full guide → 8.5 The Blueprint Preview Map.

Checkpoint: the amber banner is gone and the green "Ready to build" banner shows, with a CTA to the Development page.

5. Get ready to hand off

This is where VibeMap finishes its job and your coding agent takes over. Two more steps in the web app, two more outside.

Plan your sprints

Development Plan tab

Open the Development page (the "Develop" step in the stepper). It has three tabs — Plan, Hand off, Track — each with a small status dot that turns green as you complete it. On the Plan tab, click Plan Sprints. VibeMap:

  1. Runs the dependency-graph analyzer over every AC's Given/When/Then to find prerequisite edges.
  2. Topo-sorts all ACs in a dependency-respecting order.
  3. Runs a feature-cohesion compaction pass to pull stranded ACs adjacent to their feature's earliest cluster where dependencies allow.
  4. Asks an LLM to group the resulting linear order into themed sprints.

Checkpoint: you see a feature-by-sprint Gantt chart at the top of the Plan tab. Sprints have titles like "Auth & Sign-up", "Billing & Subscriptions". The Totals row at the bottom shows even-ish work allocation across sprints. Any feature with idle middle sprints lights up amber/rose with a "consider re-planning or marking some deps as soft" tooltip.

Full guide → Plan & sprints (developer docs).

Confirm you're ready

Glance at the status dots on the Development page's three tabs — Plan, Hand off, Track. When Plan is green and the Prepare page shows its green "Ready to build" banner, all that's left is the connection itself, which lives on the Hand off tab. Full checklist → 8.2 The readiness checklist.

Provision an API key

The Hand off tab's first card checks whether you have an API key and links to the right place: your avatar → Account → Developer tab → Generate New Key. Name it after the agent or environment that'll use it ("claude-code-laptop", "ci-server"). Copy the key immediately — it's shown once. → 8.1 Handoff overview, section 1.

Configure the MCP server in your IDE

The Hand off tab's second card has the MCP config for your project. Pick your IDE (Claude Desktop, Cursor, Windsurf, Claude Code), paste the JSON block into your MCP config file, substitute your API key, and restart your IDE. → Connect your AI coding agent (developer docs).

Checkpoint: Claude Desktop shows the 🔨 hammer icon in its chat input. Cursor shows vibemap in its MCP servers list. If you ask the agent "List my VibeMap projects", it returns them.

6. Press play

Back in your IDE, give your agent a single instruction along the lines of:

Use the VibeMap MCP server. Get the next ready acceptance criterion from project <project-id>, claim it, implement it in this repo, then submit it for review with a git SHA and a brief description.

Then tell it to loop — call next-ready again as soon as the previous AC is approved, and keep going until the queue is empty for the current sprint.

The agent will:

  1. Call vibemap_get_next_ready_criterion → gets the next AC whose hard prereqs are all passed.
  2. Call vibemap_claim_criterion → marks it in_progress so other agents/sessions don't pick it up.
  3. Read the AC's spec context (Given/When/Then, related interactions, permissions, data contracts).
  4. Write the code in your repo, run any tests it sets up.
  5. Call vibemap_submit_for_review with a git SHA + a one-line description.

7. Watch it build

Kanban tracker board

Stay on the Track tab of the Development page while the agent works. Three surfaces update in real time:

  • Kanban board — cards move across columns (Ready → In Progress → In Review → Passed).
  • Sprint sections — show progress per sprint with passed-count badges.
  • Activity feed (below the kanban, click to expand) — narrative timeline of every status change with actor names and timestamps. An "X new" badge appears when events arrive while collapsed.

Checkpoint: within a minute of giving the agent its instruction, you should see a card move into "In Progress" with your agent's name beside it.

8. Review and approve

When the agent submits an AC for review, it moves to the In Review column on the kanban. Agents can't approve their own work — resolving a review is your job (or your CI's).

For each item:

  • Pull the agent's branch / read the diff URL it submitted (a git SHA and diff URL are required on every submission).
  • If the code is good → Approve. The card moves to Passed, and the next AC in the dependency chain becomes claimable.
  • If something's off → Reject with notes. The card lands in Failed; re-open it (back to Ready) and the agent will pick it up on its next loop iteration.

Reviewing in batches (every 5–10 minutes, not every single AC) keeps the agent moving without you context-switching constantly.

9. Iterate

A few patterns that work well:

  • Per-sprint deploy cadence. When a sprint completes, deploy a preview, smoke-test, then unblock the next sprint. Sprint boundaries are advisory for the agent (it always picks dependency-ready next) but useful for human chunking.
  • Re-plan when scope changes. If you add features mid-build, re-run Plan to fold the new ACs into the dependency graph. Existing sprints get rebuilt; previously-passed work stays passed.
  • Adjust hard deps. If the agent keeps blocking or sprints are fragmenting, some hard dependency edges are probably over-eager. Look at the fragmentation indicator on the Plan tab Gantt — features lit up amber/rose are candidates for review.

Where to go next