2.1 — How VibeMap works

VibeMap is a pipeline. You feed in a product description; you get out a buildable, sprinted spec; your AI agent works through it.

This page explains the pipeline at a high level. You don't need to know any of this to use VibeMap — but it'll help you understand why the editor is laid out the way it is.

The four phases

Phase 1 — Generation

When you create a project, VibeMap runs through a sequenced pipeline:

1. Summary — A tightened-up restatement of your prompt that surfaces product positioning.
2. Personas — 2-5 user types your product serves, with goals and pain points.
3. Features — The product's major capabilities, grouped logically.
4. User stories — Per-feature "As a … I want … so that …" statements, tied to a specific persona.
5. Acceptance criteria — Testable, atomic units of work, each tied to a user story. These are what your AI agent will actually claim and work on.
6. Pages — The page-by-page UX outline (page name, purpose, sections, auth rules).
7. Schema — A relational database schema sized for the feature set.
8. Files — A starter file/folder structure for your codebase.

Each step is its own AI generation. Each one is editable. You can regenerate any one of them without redoing the others.

Phase 2 — Review & approve

Before any of this can drive your agent's work, you need to approve it. Each artifact has its own page in the project sidebar — read it, edit what's wrong, approve the acceptance criteria you're happy with.

Only approved acceptance criteria (status ready) become claimable by your agent. Unapproved ones stay in the draft pile.

Optionally, Prepare for Dev (Pro+) enriches the approved spec into an atomic blueprint: interactions, state machines, permissions and data contracts, derived in four parallel pipelines. Your agent reads a much richer spec afterwards, but nothing requires it.

Phase 3 — Plan

The Sprint Planning page (Pro+) analyzes dependencies across your acceptance criteria and groups them into themed sprints, sequenced so prerequisites resolve first. It's a page in its own right, under Prepare in the sidebar — not a tab on the Development page.

Without a sprint plan, your agent works the criteria in approval order. That's the free-tier and Starter behaviour, and it's a valid way to run a small project.

Phase 4 — Build

The Development page (Hand off to IDE, or Sync with IDE on a code-first project) is a single full-page kanban board — no tab strip. Its columns:

• Blocked — needs attention; carries a category and a reason
• Awaiting Approval — still draft
• Ready — approved, prerequisites passed, claimable
• In Progress — claimed, work underway
• In Review — submitted with a git SHA + diff URL
• Done — resolved; passed and failed both land here

Your agent picks up work from Ready, moves it through, and you (or your CI workflow) close it out. The ⓘ Handoff Instructions button at the board's top-right holds the MCP connection details.

The entity hierarchy

Everything in VibeMap nests like this:

Project
├── Personas
├── Features
│   └── User Stories
│       └── Acceptance Criteria  ← these are what your agent claims
├── Pages
├── Schema (tables + relations)
└── Files (folder + file outline)

When an acceptance criterion (AC) is "ready" to work on, that means:

1. It's been approved.
2. All of its prerequisite ACs (ACs it depends on) are themselves passed.
3. It belongs to the active sprint (if you've planned sprints).

What you control vs what the AI controls

On the handoff path, VibeMap is never writing your application code — it's writing your spec and orchestrating your agent. (The one exception is the App Builder, a separate Pro+ path where VibeMap does compile and deploy an app for you.)

Plans & capabilities

Every "requires X plan" sentence in these docs traces back to one feature flag. The ones that change what an API or MCP caller can do:

Three things this table is regularly misread on:

1. MCP is not Pro-gated. It's true on every plan, deliberately — a user on their own tokens costs VibeMap almost nothing. What's gated is the capability behind each entity: your agent still can't author pages or schema on Free, because pages and schema are false there.
2. Team workspaces are the Team plan, not Pro. Pro is a single-seat plan.
3. Entitlement denials are 402, not 403. Branch on the code field — PLAN_UPGRADE_REQUIRED or TOKEN_BUDGET_EXCEEDED. A 403 means "not your project". There is no automatic downgrade when premium tokens run out; the run is refused.

Team-owned projects resolve against the team's plan

Worth knowing before you debug a confusing entitlement: a project belonging to a team is evaluated against the team's plan, not the caller's personal one. A Free-plan user acting on a Team project gets Team capabilities there — and the identical API call against their own personal project doesn't. If a capability check surprises you, check who owns the project before you check who's calling.

Where to go next

→ 2.2 — The data model in plain English