The Spec-First Protocol: How We Build SaaS MVPs in 6 Hours Using Cursor Composer

Vibe Coding is one of the most exciting shifts in software engineering history, but it is also one of the most misunderstood. Too many developers open an AI-native code editor, open a multi-file chat session, and input a vague prompt like: "Build me a micro-SaaS with Stripe billing and a beautiful glassmorphic dashboard."

For the first thirty minutes, the experience feels magical. The AI generates dozens of files, sets up routing tables, and builds a sleek landing page. But as soon as they try to run npm run dev, the errors start piling up. Next.js hydration mismatches, duplicate package installations (e.g., both Axios and Fetch imported in different components), and state managers mismatching database types. The developer spends the next five hours in a frustrating loop copying terminal error outputs back into the chat. This is the "AI Doom Loop."

To build at warp speed without getting trapped in compilation hell, you must shift your workflow from "prompt-and-pray" to a structured, disciplined methodology: The Spec-First Protocol.

---

1. Why Vague Prompts Fail: Context Bloat & Architectural Drift

Large Language Models (LLMs) are incredibly powerful, but they operate within a finite context window and lack permanent project memory. When you prompt without strict boundaries, you invite three main failure modes:

Architectural Guesswork: If the database schema isn't explicitly defined, the AI will invent variable names (e.g., using user_id in one file and userId in another). Package Bloat: The AI doesn't check your package.json unless you explicitly tell it to. It might try to install a package you don't need or rewrite code using a deprecated version of a library. * Monolithic Files: AI models naturally write long, all-in-one code files because it's easier to verify in a single output. This quickly leads to files exceeding 1,000 lines, which saturates the LLM's context window and degrades its reasoning capability.

By writing a specification file first, you anchor the LLM to a single source of truth. You define the boundaries, and the AI fills in the implementation.

---

2. Step-by-Step Blueprint of the Spec-First Protocol

Step A: Write the SPEC.md File

• Core Tech Stack: Specify framework versions, database adapters, state management libraries, and CSS frameworks.
• Database Schema: Define collections, fields, data types, and relations.
• API Contracts: Outline request body structures, query parameters, and expected JSON response models.
• Key Features & User Flows: Map out the exact step-by-step pages and user interactions.

```markdown

Product Specification: SaaS Billing Tracker

Tech Stack

• Framework: Next.js 15 (App Router, JavaScript)
• Styling: Vanilla CSS Modules (Variables in globals.css)
• Database: Firebase Firestore
• Payments: Stripe SDK

Database Schema

collection: users

• uid: string (Firebase Auth UID)
• email: string
• tier: 'free' | 'pro'
• stripeCustomerId: string | null

collection: subscriptions

• id: string
• userId: string (indexed)
• priceId: string
• status: 'active' | 'canceled' | 'past_due'
• currentPeriodEnd: string (ISO timestamp)

Core API Endpoints

POST /api/checkout

• Request: { priceId: string, email: string }
• Response: { url: string } (Stripe Checkout Session URL)

POST /api/webhooks/stripe

• Action: Process Stripe webhook events (checkout.session.completed, customer.subscription.updated)
• Security: Signature verification using stripe-signature header

---

## 3. Orchestrating Cursor Composer & Windsurf

Once your `SPEC.md` is ready, do not ask the AI to build the entire app at once. Build it incrementally like a professional software engineer.

### Phase 1: Establish the Database and Auth Layers (Hour 1-2)
Use the `@SPEC.md` context reference in your composer chat and prompt:
> *"Using the database schema defined in SPEC.md, implement the Firestore initialization and client wrappers inside `app/lib/db.js`. Do not build any UI components yet. Focus strictly on getting the connection and collection references established."*

Verify that the database code compiles and run a test script to check that writes succeed.

### Phase 2: Implement API Routes (Hour 3-4)
Next, focus on routing and business logic. Prompt:
> *"Using the API contracts in SPEC.md, implement the POST route for `/api/checkout`. Make sure to check the user profile tier in Firebase Firestore first. Implement standard try-catch blocks and return consistent JSON structures for error states."*

### Phase 3: Construct the Frontend Components (Hour 5-6)
Only after your database and APIs are verified should you generate the visual interfaces. Prompt:
> *"Now we are ready to implement the frontend user dashboard at `app/dashboard/page.js`. Refer to the styles defined in `app/globals.css` and use CSS modules for styling. Connect the frontend state directly to our `/api/checkout` endpoint."*

---

## 4. The 6-Hour Milestone Timeline

Following this protocol, a typical micro-SaaS MVP build conforms to this clean, predictable timeline:

By decoupling system architecture from UI creation, you keep the AI's context focused, prevent compiler errors, and build standard, robust software in a fraction of the time.