mvp-spec

The spec you write before touching any code. Turns a rough idea into a buildable v1 with a clean feature cut, data model, and stack recommendation.

How to start

Ask ONE question.

"What's the idea? One sentence."

Wait for the answer. Then immediately challenge scope before anything else.

Ask the narrowing question before moving to Phase 1:

"If you could only ship ONE feature this week and it had to deliver real value — what would it be?"

This is not optional. The spec is built around the answer to this question. If the user can't answer it, the idea isn't ready for a spec. Keep pushing until they name one thing.

If they list 3 features as "the one thing" — push back. "That's three things. Which one is first? If you had to cut the other two for launch, which one stays?"

Once you have the one core thing, proceed. Do not write the spec until you have it.

---

Phase 1: Capture the Idea

Ask for anything missing:

1. The idea — What does it do? One sentence.
2. Who is it for? — Target user. "Developers" is too vague. "Solo SaaS founders building with Next.js" is specific.
3. Monetization — Free, freemium, paid, credits? Skip for now if unclear.
4. Tech preferences — Any stack constraints? Or let the skill recommend.

If the user gives you a paragraph, extract these from it and confirm before continuing. Don't ask for what you already have.

Phase 2: The One-Build Rule

Before writing anything, validate the scope:

• Is this ONE product, or three ideas stapled together?
• Can v1 be built and shipped in 1–2 weeks by one person?
• Is there one clear action the user takes to get value?

If the idea is too broad, cut it. This spec covers v1 only — not the vision, not the roadmap.

The narrowing question: "If you could only ship ONE feature this week and it had to deliver real value — what would it be?" That's the core loop. Build the spec around that.

Phase 3: Feature Split

List every feature that came up. Then sort ruthlessly.

LAUNCH (ships in v1)

Only features that complete the core loop:

• User can sign up
• User can do the one thing
• User gets value from doing it
• You can see that they got value

LATER (month 2+)

Everything else. Default everything here unless it's provably required for launch:

• Settings, preferences, notifications
• Team features, collaboration, multi-user
• Admin dashboard
• Analytics dashboards
• Mobile optimization
• Integrations, webhooks, API access

The test: "If I remove this, can a user still get value from v1?" Yes → LATER.

Phase 4: Data Model

Design only for LAUNCH features. Don't model LATER features — the schema will change anyway.

users
├── id (uuid)
├── email
├── [plan | credits — if monetized in v1]
├── created_at
└── updated_at

[core resource]
├── id (uuid)
├── user_id → users.id
├── [core fields]
├── created_at
└── updated_at

Relationships:
- users has many [resources]
- [resource] belongs to user

One table per entity. No join tables unless collaboration is in v1 (it almost never is).

Phase 5: API Routes

Only routes LAUNCH features actually need.

Auth
POST   /api/auth/signup
POST   /api/auth/login
GET    /api/auth/me

[Resource]
GET    /api/[resource]           — list (current user only)
POST   /api/[resource]           — create
GET    /api/[resource]/:id       — get one
DELETE /api/[resource]/:id       — delete

No PUT/PATCH unless editing is core to the loop in v1.

Phase 6: Pages

Every screen the user sees in v1.

/                  — Landing page
/login             — Auth
/signup            — Auth
/dashboard         — Main view after login
/[resource]/:id    — Detail view (if needed)
/settings          — Only if required for launch

Phase 7: Tech Stack

Match the recommendation to the user's stated constraints.

Priority	Stack
Ship fastest, solo	Next.js + Supabase + Vercel
Full backend control	Next.js + Postgres + Prisma + Railway
AI-heavy	Next.js + Vercel AI SDK + Supabase
Python backend	FastAPI + Postgres + Supabase Auth

Always explain why — one sentence per choice. "Supabase: auth + postgres in one service, no separate backend needed for v1."

Phase 8: Scope Cut List

The most important section. Explicitly list what v1 does NOT build.

v1 does NOT include:
- Team workspaces or multi-user support
- Email notifications
- API access for external integrations
- Mobile app
- Custom domains
- [anything that came up but got cut]

This prevents scope creep during the build. Reference it every time someone says "just one more thing."

Verify

[ ] Problem statement is one sentence
[ ] 2-3 user personas with specific pain — not demographic labels
[ ] Core loop identified — one action, one value delivered
[ ] Feature list split into LAUNCH and LATER
[ ] LAUNCH features cover exactly one core loop, nothing else
[ ] Data model covers LAUNCH features only — no speculative tables
[ ] API routes listed with HTTP methods
[ ] All pages listed — no screens without a route
[ ] Tech stack recommended with one-sentence reasoning per choice
[ ] Scope cut list explicitly names what v1 does NOT build
[ ] Entire spec is buildable in 1-2 weeks by one person