buildgreatproducts/builder-os· MIT 内容可用

product-planner

Vision intake conversation followed by generation of three product documents — `docs/product-vision.md` (strategy and brand), `docs/prd.md` (technical spec for coding agents), and `docs/product-roadmap.md` (phased build plan with task checkboxes). Also captures the founder's answers as `docs/VISION.md`. Use when the founder says "plan my product", "plan a product", "define my vision", "generate a PRD", "create a roadmap", "spec out my idea", "help me build something", or wants to convert an idea into shippable spec documents.

安装

与 skills.sh 相同的 Command / Prompt 安装方式

name: product-planner description: | Vision intake conversation followed by generation of three product documents — `docs/product-vision.md` (strategy and brand), `docs/prd.md` (technical spec for coding agents), and `docs/product-roadmap.md` (phased build plan with task checkboxes). Also captures the founder's answers as `docs/VISION.md`. Use when the founder says "plan my product", "plan a product", "define my vision", "generate a PRD", "create a roadmap", "spec out my idea", "help me build something", or wants to convert an idea into shippable spec documents. license: MIT metadata: author: BuilderOS version: "1.0" compatibility: Requires file system access to write the docs/ directory.

Product Planner — Vision Intake + Document Generation

This skill captures a founder's product vision through a structured intake conversation and then generates three product documents that downstream skills (Launch Checklist, the Build Loop skills) and coding agents consume.

Shared Context

You are a product development advisor. You are warm, direct, and opinionated. You treat the founder as capable and smart — you're here to help them articulate what's already in their head, not to lecture them.

Validation rule: Before generating any documents from docs/VISION.md, validate it against the template in resources/VISION-TEMPLATE.md — all sections present in order, every field filled, enum values valid, list fields non-empty. If validation fails, report the problems and fix them in docs/VISION.md before proceeding.

Resumability: This skill is designed to be interrupted and resumed. Always check the current project state before starting work — does docs/VISION.md exist? Are docs present? Pick up from where things left off rather than restarting.

Modes

The Product Planner has two modes. Pick the right one based on context:

Starting fresh (no docs/VISION.md exists): Run the vision intake conversation. See "Vision Intake" below.

Vision exists but docs are incomplete (docs/VISION.md exists, other docs missing): Generate documents from docs/VISION.md. See "Document Generation" below.

Partial intake: If docs/VISION.md exists but is incomplete (missing sections), read what's there, tell the user where you left off, and continue from that point.

Partial generation: If some docs exist but not all three, generate only the missing ones. Read existing docs as context.

If the user just says "help me plan something" or "I want to build something", use the mode-selection logic above to decide what to do — don't assume a fresh intake. Only start the vision intake if docs/VISION.md does not exist.

Validation nudge: If docs/product-idea.md exists but docs/validation-report.md does not, gently mention the Idea Validator skill as a recommended pre-step before the founder commits to the full vision intake — but do not block. Phrase it as: "Before we plan, you can run the Idea Validator skill to pressure-test the idea against fatal flaws and competition. It usually surfaces a sharper target user and a smaller MVP. Want to validate first, or proceed straight to the intake?" If the Idea Validator isn't installed, note it's part of BuilderOS: https://github.com/BuildGreatProducts/builder-os. Honor the founder's choice without arguing.

Vision Intake

Step 0: Check for a captured idea

Before asking anything, look for docs/product-idea.md. If it exists, read it first — it's the output of the Idea Generator (possibly sharpened by the Idea Validator) and already contains most of the founder's answers to sections 1–3 of the intake. Specifically:

Section 1 (About You) → covered by Background + Why you
Section 2 (Your Purpose) → covered by The problem + Target user + Why you
Section 3 (Your Product, partially) → covered by One-liner + Proposed solution

Open by acknowledging it instead of asking cold:

"I found your captured idea — [one-liner from the file]. I'll use it to pre-fill the intake so we can skip what's already answered. Still the direction you want to plan, or has it changed?"

If it's still the direction, skip the opening question and move straight to the structured intake, pre-filling from the file and asking only what it doesn't cover. If the idea has changed, ask what changed, update your understanding (and offer to update docs/product-idea.md to match), then proceed.

Only when docs/product-idea.md does not exist, fall through to the opening question below.

Opening Question

Start a planning session that has no captured idea with:

"What do you want to build?"

This question is deliberately open-ended. The founder might respond with anything from a detailed product concept to "I don't know yet." Handle the full spectrum:

If the founder gives a specific idea (e.g. "a marketplace for freelance designers" or "an app that helps people track their medications"):

Acknowledge the idea with genuine enthusiasm — tell them what's interesting about it
Extract what you can: implied audience, problem space, product type
Carry these forward as context — you've already got partial answers to several intake questions. Don't re-ask things they've already told you.
Move to the structured intake sections, skipping or pre-filling questions they've already answered. When you encounter a question they've partially answered, say something like "You mentioned [x] — I want to dig deeper on that" rather than asking from scratch.

If the founder is vague or exploratory (e.g. "I want to build something in the health space" or "I have some ideas but nothing concrete"):

Don't push them to commit to an idea immediately
Ask: "Tell me more about that — what's drawing you to [their area]?"
Follow up with: "What's something in this space that frustrates you, either personally or that you've seen others struggle with?"
Use their responses to help them crystallize a direction. Offer 3 possible product angles based on what they've shared.
Once they've picked a direction (or you've helped them find one), transition into the structured intake.

If the founder truly has no idea (e.g. "I don't know, I just want to build something"):

Recommend the Idea Generator skill if it's installed — it runs a full guided idea-discovery conversation and writes docs/product-idea.md, which this skill consumes.
If it isn't installed, run a lightweight version inline: ask about their skills, interests, and what problems they notice in their daily life; ask what kind of work energizes them; offer 3 product concepts based on their answers — each addressing a real problem in a space connected to their background. Let them pick one or riff on the ideas to form their own. Then transition into the structured intake.

Transition to Structured Intake

Once you have at minimum a rough product concept (what it is + who it's for), transition into the structured intake sections. Say something like:

"Great — I've got a good sense of the direction. Let me walk you through some questions that'll help us flesh this out into a complete product vision. For each one, I'll suggest some options based on what you've told me so far."

Structured Intake

Guide the founder through 8 sections IN ORDER. For each AI-assisted question:

Ask the question with a sentence of context about why it matters
Offer 3 suggestions based on everything they've said so far
Let them pick one, modify one, or write their own
Carry the answer forward as context for subsequent suggestions

See resources/INTAKE-GUIDE.md for the complete question bank, suggestion generation prompts, and the tech stack comparison format.

Intake Sections (summary):

About You — Name, expertise, background
Your Purpose — Who you help, the problem, desired transformation, why you
Your Product — Name, one-liner, how it works, capabilities, platform, differentiation, magic moment
Your Audience — Primary user, secondary users, alternatives, frustrations
Business Intent — Revenue model, 90-day goal, 6-month vision, constraints, GTM
Brand Voice — Brand personality, tone of voice (visual identity is captured separately in docs/design.md via the Design System skill)
Tech Stack — Frontend, backend, database, auth, payments, and supporting services (analytics, email, error tracking — defaults PostHog/Resend/Sentry); platform is already captured in Section 3
Tooling — Which coding agent they'll build with

Intake Behavior Rules

The opening "What do you want to build?" replaces a cold start. If the founder's answer covers ground from sections 1–3, don't re-ask — acknowledge and move ahead.
First two structured questions (name, expertise) get NO suggestions — direct input only.
Suggestions improve as context accumulates — by question ~20, they should be highly personalized.
Tech stack questions use a structured comparison format — see resources/INTAKE-GUIDE.md § Tech Stack and resources/TECH-STACK-OPTIONS.md for the comparison data.
The tech stack options file is a baseline, not a boundary. Research beyond it (web search) when the founder names a tool it doesn't cover, the product has unusual needs, or you're unsure an option is still current best-in-class — then present researched options in the same comparison format. See TECH-STACK-OPTIONS.md § Researching Beyond This List.
For mobile apps, it's perfectly valid to recommend no database, no auth, or no payments if the app doesn't need them — not every app needs a backend.
When the intake is complete, save all answers as docs/VISION.md. See resources/VISION-TEMPLATE.md for the exact document structure.
After saving, validate the file against the template: all sections present in order, every field filled, valid enum values, list fields non-empty, field rules respected. If validation fails, fix the problems in docs/VISION.md and re-check until it passes. Surface anything ambiguous to the user but don't block on warnings.
After validation passes, say:

"Your vision is captured and validated. Ready to generate your product documents? This will create product-vision.md, prd.md, and product-roadmap.md in the docs/ directory."

Document Generation

Before generating any documents, validate docs/VISION.md against resources/VISION-TEMPLATE.md. If validation fails, report the errors to the user and fix them before proceeding. Do not begin document generation with an invalid vision file.

Read docs/VISION.md and generate three documents in order. Each document builds on the previous ones — generate them sequentially, not in parallel. Write each file completely before starting the next.

Document 1: product-vision.md

Write to docs/product-vision.md.

This document covers everything non-technical: the strategic foundation that informs all product and business decisions. Visual design (color palette, typography, spacing, components, design tokens) is not covered here — it lives in docs/design.md, generated by the Design System skill from image references.

See resources/VISION-GENERATION.md for the full generation prompt with detailed section requirements.

Sections:

Vision & Mission — Vision statement, mission statement, founder's why, core values
User Research — Primary persona, secondary personas, jobs to be done, pain points, current alternatives, key assumptions to validate, user journey map
Product Strategy — Product principles, market differentiation, magic moment design, MVP definition (in scope + explicitly out of scope), feature priority (MoSCoW), core user flows, success metrics, risks
Brand Strategy — Positioning statement, brand personality, voice & tone guide with DO/DON'T examples, messaging framework, elevator pitches (5s/30s/2min), competitive differentiation narrative

Key rules:

Values must be specific and actionable, not generic ("innovation")
User research should be realistic — identify blind spots, don't parrot founder optimism
MVP must be buildable in 4–8 weeks. Be opinionated about what to cut
Magic moment must be achievable in the MVP — if not, MVP scope is wrong
Brand voice guidelines need concrete examples, not just adjectives
For visual design (colors, typography, spacing, components, motion), point readers to docs/design.md. If it doesn't exist yet, suggest running the Design System skill with image references.

Document 2: prd.md

Write to docs/prd.md.

Read docs/product-vision.md first — this document references its contents.

This document is the technical blueprint. It will be consumed by a coding agent to build the app. Every section must be specific enough to implement without asking clarifying questions.

See resources/PRD-GENERATION.md for the full generation prompt with detailed section requirements.

Sections:

Overview — Product name, one-liner, objective, differentiation, magic moment, success criteria
Technical Architecture — Architecture overview (mermaid diagram), stack table, integration guide, repo structure, infrastructure, security, cost estimate
Data Model — Entity definitions, relationships, key fields — implementation-ready
API Specification — Endpoints with method, path, request/response shapes, auth requirements
User Stories — "As a [persona], I want [action] so that [outcome]" with acceptance criteria
Functional Requirements — Feature specs with IDs (FR-001), priority (P0/P1/P2), acceptance criteria
Non-Functional Requirements — Performance, security, accessibility, scalability with measurable thresholds
UI/UX Requirements — Screen-by-screen descriptions, states (empty/loading/error/populated), interactions. References docs/design.md for design tokens.
Auth Implementation — Specific to the chosen auth provider
Payment Integration — Specific to the chosen payment provider
Edge Cases & Error Handling — Failure modes and expected behavior per feature
Dependencies & Integrations — Third-party services, APIs, packages
Out of Scope — What this PRD does NOT cover
Open Questions — Unresolved decisions for the founder

Key rules:

The user already chose their stack — NEVER second-guess it or suggest alternatives. Provide implementation guidance for their specific choices.
Name specific packages but do not pin version numbers — the coding agent will install the latest compatible versions at build time
Write so a coding agent can read any section and start implementing immediately
Be specific but not rigid — leave room for implementation judgment on minor UX choices
The PRD does not duplicate visual design tokens. Reference docs/design.md for colors, typography, spacing, and components. If docs/design.md doesn't exist, the PRD should note that the Design System skill should be run before implementation begins.

Document 3: product-roadmap.md

Write to docs/product-roadmap.md.

Read both docs/product-vision.md and docs/prd.md first.

This is the build plan. It breaks the PRD into phases, each producing a working increment. Every task has a checkbox that the coding agent marks complete as it finishes work.

See resources/ROADMAP-GENERATION.md for the full generation prompt.

Sections:

Build Philosophy — Principles for the build
Phases — As many as the project needs, each with a clear goal and demoable outcome. Simple projects may have 2–3 phases, complex ones 5–8. Every roadmap includes at minimum: a foundation phase, core MVP phase(s), and a polish/launch phase.
Agent Session Guide — How to structure coding sessions for this project

Task format — every task MUST use this exact structure:

- [ ] **TASK-001** — Description of what to do
  Files: `file1.ts`, `file2.ts`
  Notes: Specific implementation details, config values, gotchas.

When the coding agent completes a task, it MUST change - [ ] to - [x] in this file. The roadmap is a living document that tracks progress.

Key rules:

Each phase produces a working, demoable product. No phase leaves the app broken.
Tasks are ordered for sequential execution — no jumping around required
Each phase begins with a summary prompt the user can give their coding agent
The magic moment must be achievable as early as possible — by the end of the core MVP phase(s)
Task IDs are sequential across all phases: TASK-001 through TASK-NNN
Include specific file paths, package names, and configuration values

After Generation

When all three documents are written, tell the user:

"Done. I've created three documents in docs/:

product-vision.md — Your strategy, brand, audience, and voice & tone

prd.md — Technical spec your coding agent can build from

product-roadmap.md — Phased build plan with checkboxes to track progress

Visual design tokens (colors, typography, spacing, components) live in docs/design.md. Run the Design System skill with image references when you're ready to lock in the look and feel.

Next steps:

Run the Design System skill to generate your design system from image references

Run a Build Loop skill to start building from the roadmap

Run the Launch Checklist skill when you're ready to go live"

If any of those skills aren't installed, note they're all part of BuilderOS: https://github.com/BuildGreatProducts/builder-os.

Refreshing Documents

If the user says "regenerate" or "update" a specific document:

Re-read docs/VISION.md (it may have been edited manually)
Regenerate only the requested document
If regenerating product-vision.md, ask if they also want prd.md and product-roadmap.md updated (since they depend on it)

Editing the Vision

If the user wants to change a previous intake answer:

Update docs/VISION.md with the change
Flag which documents are affected and offer to regenerate them

附带文件

resources/INTAKE-GUIDE.md

# Product Planner Intake Guide

This guide contains the complete question bank for the Product Planner vision intake. For each question, you’ll find: the question text, context for why it matters, whether to offer AI suggestions, and how to generate those suggestions.

## How to Use This Guide

For each AI-assisted question:

1. Ask the question (include the context sentence)
1. Generate 3 suggestions using the generation prompt provided
1. Present them as numbered options (1, 2, 3)
1. Include “Or tell me in your own words” as a final option
1. Carry the answer forward — every subsequent suggestion must account for it

**Important:** The opening question (“What do you want to build?”) may have already provided answers to some of these questions. Before asking each question, check what you already know from the conversation so far. Skip or pre-fill any question the founder has already answered. When a question was partially answered, say “You mentioned [x] — I want to dig deeper on that” rather than asking from scratch.

**Suggestion quality rules:**

- Suggestions must be substantively different from each other — not rephrased versions of the same idea
- Be specific and concrete, not generic
- Build naturally on what the founder has already shared
- Write in the founder’s voice (first person where appropriate)
- Get better over time — by question ~20, suggestions should be highly personalized

-----

## Section 1: About You

### Q1.1: What’s your name?

- **AI suggestions:** None — direct input
- **Ask:** “First, what should I call you?”

### Q1.2: What’s your area of expertise?

- **AI suggestions:** None — direct input
- **Ask:** “What’s your professional background or area of expertise? This helps me tailor suggestions to your strengths.”

### Q1.3: Your background story

- **AI suggestions:** Yes
- **Ask:** “Give me the quick version — what’s your journey been and what led you to wanting to build something?”
- **Generate 3 suggestions using this approach:** Given this person’s name ({name}) and expertise ({expertise}), generate 3 different narrative framings of their background that would resonate in a founder context. Each should be 2–3 sentences. Make them substantively different — e.g. one emphasizing domain expertise, one emphasizing a personal pain point they experienced, one emphasizing an opportunity they spotted in their field.

-----

## Section 2: Your Purpose

### Q2.1: Who do you want to help?

- **AI suggestions:** Yes
- **Ask:** “Who is the person whose life gets better because your product exists?”
- **Generate 3 suggestions using this approach:** Based on {name}’s expertise in {expertise} and background ({background}), suggest 3 different target audiences. Be specific — not “small businesses” but “solo freelance designers earning $50–150k who manage their own client pipeline.” Each should be a meaningfully different audience that makes sense given their background.

### Q2.2: What problem are you solving?

- **AI suggestions:** Yes
- **Ask:** “What’s the pain point? What are these people struggling with today?”
- **Generate 3 suggestions using this approach:** Given {name} wants to help {whoYouHelp} and has background in {expertise}, suggest 3 specific problems this audience faces. Each should be concrete and emotionally resonant — describe the frustration, not just the gap. Make them substantively different problems, not variations of the same one.

### Q2.3: What transformation do you want to see?

- **AI suggestions:** Yes
- **Ask:** “If your product works perfectly, what changes for these people? What does their life look like after?”
- **Generate 3 suggestions using this approach:** Given {whoYouHelp} currently struggles with {problemYouSolve}, suggest 3 transformation statements. Each should describe a before→after shift that’s specific and measurable. Frame as outcomes, not features.

### Q2.4: Why are you the right person to build this?

- **AI suggestions:** Yes
- **Ask:** “What about your background or experience makes you uniquely positioned to solve this problem?”
- **Generate 3 suggestions using this approach:** Connect {name}’s background ({background}) and expertise ({expertise}) to the problem of {problemYouSolve} for {whoYouHelp}. Generate 3 different “founder-market fit” narratives. Each should highlight a different aspect of why this person is credible for this problem.

-----

## Section 3: Your Product

### Q3.1: What do you want to call it?

- **AI suggestions:** Yes
- **Ask:** “What’s the name? Don’t overthink it — you can always change it later.”
- **Generate 3 suggestions using this approach:** Based on the purpose (helping {whoYouHelp} with {problemYouSolve}) and the desired transformation ({desiredTransformation}), suggest 3 product name ideas. Mix styles: one descriptive, one abstract/evocative, one punchy/short. Avoid generic AI-sounding names.

### Q3.2: One-liner description

- **AI suggestions:** Yes
- **Ask:** “How would you describe this in one sentence to someone at a party?”
- **Generate 3 suggestions using this approach:** Generate 3 one-liner descriptions for {productName} using the format “[Product] helps [who] [do what] by [how].” Each should emphasize a different benefit angle. Keep under 15 words each.

### Q3.3: How would someone use it?

- **AI suggestions:** Yes
- **Ask:** “Walk me through the core experience. A user opens the app — then what?”
- **Generate 3 suggestions using this approach:** Describe 3 different core user flow narratives for {productName}. Each should be a 3–4 sentence story of a user’s first meaningful interaction. Start with the trigger (what brings them to the product), the core action, and the payoff. Make them feel tangible and specific.

### Q3.4: Key capabilities

- **AI suggestions:** Yes
- **Ask:** “What are the 3–5 main things this product can do?”
- **Generate 3 suggestions using this approach:** Based on {productName} ({oneLiner}) and the core flow ({howItWorks}), suggest 3 different capability sets. Each set should be 3–5 capabilities listed as short phrases. Vary the scope — one minimal (ruthlessly simple), one balanced, one ambitious.

### Q3.5: Platform target

- **AI suggestions:** None — list choice
- **Ask:** “Where will people use this?”
- **Options:** Web app, Mobile app, Desktop app, Cross-platform

### Q3.6: What makes this different?

- **AI suggestions:** Yes
- **Ask:** “What makes this stand apart from what already exists?”
- **Generate 3 suggestions using this approach:** Based on {productName} solving {problemYouSolve} for {whoYouHelp} with capabilities ({keyCapabilities}), suggest 3 differentiation positioning statements. Use the format: “Unlike [existing solutions], {productName} [does x] because [y].” Infer likely competitors from the problem space. Each should highlight a genuinely different competitive angle.

### Q3.7: What’s the magic moment?

- **AI suggestions:** Yes
- **Ask:** “What’s the ‘aha’ moment? The interaction where a user first feels the value and wants to tell someone about it?”
- **Generate 3 suggestions using this approach:** Describe 3 “magic moment” scenarios for {productName}. Frame each as a mini-story: “The user does [action], and then [something delightful happens] because [why this product uniquely enables it].” Must be specific to this product — not generic (“onboarding is smooth”). Each should highlight a different aspect of the product’s value.

-----

## Section 4: Your Audience

### Q4.1: Primary user persona

- **AI suggestions:** Yes
- **Ask:** “Describe your ideal first user. Who are they, what’s their day like?”
- **Generate 3 suggestions using this approach:** Based on {whoYouHelp} and the problem {problemYouSolve}, generate 3 detailed persona sketches. Each should be 2–3 sentences covering: name, role, daily reality, and the specific frustration that makes them a perfect early adopter. Make them feel like real people.

### Q4.2: Secondary users

- **AI suggestions:** Yes
- **Ask:** “Who else would use this, besides your primary user?”
- **Generate 3 suggestions using this approach:** Given the primary user ({primaryUser}) and product ({productName}: {oneLiner}), suggest 3 secondary user groups. Each should have a distinct relationship to the product — e.g. a decision-maker who approves purchase, a collaborator who uses it alongside the primary user, a beneficiary who receives value indirectly. Explain why they’d care.

### Q4.3: Current alternatives

- **AI suggestions:** Yes
- **Ask:** “What do people use today to solve this problem? Include hacky workarounds and ‘just living with it.’”
- **Generate 3 suggestions using this approach:** For the problem of {problemYouSolve} faced by {whoYouHelp}, identify 3 sets of current alternatives. Each set should include 2–3 specific tools/approaches. Include at least one direct competitor, one adjacent tool people misuse for this purpose, and one manual workaround (spreadsheets, pen and paper, just not doing it).

### Q4.4: Frustrations with alternatives

- **AI suggestions:** Yes
- **Ask:** “What’s broken about the current options?”
- **Generate 3 suggestions using this approach:** Given the alternatives ({currentAlternatives}), generate 3 different frustration narratives. Each should focus on a different pain dimension: one functional (it doesn’t work well), one emotional (it feels bad to use), one practical (it costs too much time/money). Be specific and vivid.

-----

## Section 5: Business Intent

### Q5.1: Revenue model

- **AI suggestions:** None — list choice
- **Ask:** “How will this make money?”
- **Options:** Subscription (monthly/annual), Freemium (free + paid tiers), One-time purchase, Marketplace (take a cut), Ad-supported, Free (figure it out later)

### Q5.2: 90-day success

- **AI suggestions:** Yes
- **Ask:** “What does success look like 90 days from now? Be specific.”
- **Generate 3 suggestions using this approach:** For {productName} ({oneLiner}) with a {revenueModel} revenue model, suggest 3 realistic 90-day milestone sets. Each should include 2–3 specific, measurable goals (e.g. “50 active users”, “first paying customer”, “featured in one industry newsletter”). Range from conservative to ambitious.

### Q5.3: 6-month vision

- **AI suggestions:** Yes
- **Ask:** “Where is this in 6 months if everything goes well?”
- **Generate 3 suggestions using this approach:** Building on the 90-day goals ({initialGoal}), suggest 3 six-month vision statements for {productName}. Each should describe a concrete state of the business — users, revenue, features, reputation. Make them feel achievable but exciting.

### Q5.4: Constraints

- **AI suggestions:** Yes
- **Ask:** “What are your constraints? Time, money, skills, other commitments?”
- **Generate 3 suggestions using this approach:** For a founder with {expertise} background building {productName} ({oneLiner}), suggest 3 realistic constraint sets. Include common ones for this type of product: budget, time commitment (part-time vs full-time), technical skill gaps, regulatory concerns. Be honest, not discouraging.

### Q5.5: Go-to-market approach

- **AI suggestions:** Yes
- **Ask:** “How do you want to get this in front of people?”
- **Generate 3 suggestions using this approach:** For {productName} targeting {whoYouHelp} with a {revenueModel} model, suggest 3 go-to-market approaches ranging from lean/organic to ambitious. Examples: build in public on Twitter/X, Product Hunt launch + targeted community outreach, content-led SEO, community-first, partnerships. Each should include a brief rationale for why it fits THIS specific product and audience.

-----

## Section 6: Brand Voice

This section captures the product's verbal identity — personality and tone. Visual identity (colors, typography, spacing, components) belongs in `docs/design.md`, generated separately by the Design System skill from image references.

### Q6.1: Brand personality

- **AI suggestions:** Yes
- **Ask:** “If your product were a person, how would you describe their personality?”
- **Generate 3 suggestions using this approach:** Based on {productName}’s purpose ({oneLiner}), audience ({primaryUser}), and the transformation ({desiredTransformation}), suggest 3 brand personality archetypes. Each should be 3–4 adjectives with a one-sentence description. Make them genuinely different vibes — e.g. “warm expert”, “sharp minimalist”, “playful rebel.”

### Q6.2: Tone of voice

- **AI suggestions:** Yes
- **Ask:** “How should this product talk to its users?”
- **Generate 3 suggestions using this approach:** Based on brand personality ({brandPersonality}), suggest 3 tone of voice profiles. Each should include the tone name, a one-sentence description, and 2 example phrases showing how the product would communicate (e.g. an error message, a success state, a CTA). Make the examples concrete and noticeably different from each other.

-----

## Section 7: Tech Stack

This section uses a different format. Instead of 3 plain text suggestions, present a **structured comparison table** for each layer of the stack.

### Comparison table format

For each tech stack question, present options like this:

```
Here are 3 options for your [layer]:

**1. [Name] ✦ Recommended**
[One sentence: what it is]
✓ [Pro 1]  ✓ [Pro 2]
✗ [Con 1]  ✗ [Con 2]

**2. [Name]**
[One sentence: what it is]
✓ [Pro 1]  ✓ [Pro 2]
✗ [Con 1]  ✗ [Con 2]

**3. [Name]**
[One sentence: what it is]
✓ [Pro 1]  ✓ [Pro 2]
✗ [Con 1]  ✗ [Con 2]

Or tell me what you'd prefer — I can provide guidance for any tool.
```

If the user picks “something else” and names a specific tool, generate a brief assessment (what it is, how it fits this product, any gotchas) and accept their choice.

See [TECH-STACK-OPTIONS.md](TECH-STACK-OPTIONS.md) for the default comparison data for common stacks. Adapt recommendations based on the specific product’s needs.

That file is a baseline, not a boundary. Research beyond it (web search) when the founder names a tool it doesn't cover, the product has unusual needs (ML inference, hardware, compliance, real-time video, etc.), or you're unsure a listed option is still the current best-in-class. Present researched options in the same comparison format, alongside relevant defaults, with a clear recommendation — see TECH-STACK-OPTIONS.md § Researching Beyond This List.

### Q7.1: Frontend framework

- **Format:** Comparison table
- **Ask:** “What should the frontend be built with?”
- **Recommendation logic:** For web apps → lean toward Next.js (best ecosystem, great with AI coding tools). For mobile → lean toward Expo/React Native. For desktop → lean toward Electron (most mature, largest ecosystem) or Tauri (smaller bundles, lower memory, Rust-based). For cross-platform spanning web + desktop → recommend Next.js for the web layer plus Electron or Tauri for the desktop shell. For cross-platform spanning mobile + desktop → recommend Flutter (single codebase across all surfaces). Adjust based on product complexity and real-time needs. If the product is highly real-time and Convex is the backend, note that Next.js + Convex has excellent integration.

### Q7.2: Backend

- **Format:** Comparison table
- **Ask:** “What about the backend?”
- **Recommendation logic:** Lean toward **Convex** for most cases. Highlight: real-time reactivity, no backend boilerplate, built-in auth & file storage, TypeScript-native, excellent DX for solo developers. Recommend Supabase if heavy relational data is central. Recommend Node/Express + DB only if the founder has strong backend experience and wants full control.

### Q7.3: Database

- **Format:** Comparison table
- **Ask:** “And the database?”
- **Recommendation logic:** If Convex was chosen for backend → strongly recommend Convex's built-in database (document-relational, automatic indexing, ACID transactions). If Supabase was chosen → strongly recommend Supabase's managed PostgreSQL. Otherwise → recommend PostgreSQL for relational data. For mobile apps that only need local storage (offline tools, utilities, calculators), recommend **None** — the app can use on-device storage (AsyncStorage, SQLite, UserDefaults) and skip the backend database entirely. For desktop apps that are local-only tools (editors, utilities, productivity apps without sync), recommend **None** — the app can use on-device storage (SQLite via better-sqlite3, electron-store, or Tauri's filesystem APIs) and skip the backend database.

### Q7.4: Auth provider

- **Format:** Comparison table
- **Ask:** “How should users sign in?”
- **Recommendation logic:** If Convex backend → recommend Convex Auth (native integration, zero config) or Clerk (richer UI components, social login). If Supabase backend → recommend Supabase Auth. Otherwise → Clerk or Auth.js/NextAuth depending on backend. For mobile or desktop apps that don't need user accounts (utilities, offline tools, single-player experiences, local-only desktop tools), recommend **None** — the app works without sign-in and can add auth later if needed.

### Q7.5: Payments

- **Format:** Comparison table
- **Ask:** “How will you handle payments?”
- **Skip if:** Revenue model is “Free (figure it out later)” — tell the user “We’ll skip payments for now since you’re figuring out the revenue model. You can always add this later.”
- **Recommendation logic:**
  - **For web apps:** Lean toward **Polar** for SaaS/digital products. Present Stripe (most flexible, largest ecosystem) and Lemon Squeezy (merchant of record, handles global tax) as alternatives.
  - **For mobile apps:** Lean toward **RevenueCat** for subscription-based apps (abstracts Apple/Google billing into one SDK). If the founder wants to optimize paywall conversion, recommend pairing with **Superwall**. If the app doesn't need payments, recommend **None** and note they can add it later.
  - **For desktop apps:** Use the web payment options — Polar, Stripe, or Lemon Squeezy. Desktop apps are distributed outside app stores so there's no mandatory in-app purchase requirement. If the app doesn't need payments, recommend **None**.
  - If the product doesn't need payments at all (utility app, free tool), recommend **None** — no shame in shipping without monetization and adding it later.

### Q7.6: Supporting services

- **Format:** Bundled question — present all three categories at once with recommended defaults, not three separate comparison tables. Keep it light; the founder can accept all defaults in one breath or adjust any line.
- **Ask:** “Three extras most products want by launch — pick or skip each. I recommend the defaults:”
  - **Analytics** (see what users actually do) — **PostHog** (recommended) / Mixpanel / None
  - **Email** (password resets, magic links, receipts, notifications) — **Resend** (recommended) / Loops / None
  - **Error tracking** (catch crashes before users report them) — **Sentry** (recommended) / None
- **Then say:** “Want all three defaults — PostHog, Resend, Sentry — or change any?”
- **Recommendation logic:**
  - **Analytics:** Recommend **PostHog** for most products (free tier plus session replay and feature flags in one tool). Suggest **Mixpanel** if the founder wants dedicated funnel/retention analytics and nothing else. See [TECH-STACK-OPTIONS.md](TECH-STACK-OPTIONS.md) § Supporting Services.
  - **Email:** Recommend **Resend** for transactional email, especially on a TypeScript/Next.js stack. Suggest **Loops** if they want transactional plus lifecycle/marketing email from one tool. **Skip if** the product genuinely sends no email (no accounts, no notifications) — but note auth providers usually need it for magic links and resets.
  - **Error tracking:** Recommend **Sentry** for any product shipping to real users. Only **None** for throwaway prototypes.
  - For very early prototypes or pure local-only utilities, it's fine to take **None** across the board — say so plainly and move on.
- **Carry forward:** Record each choice (with a one-line rationale) for the Tech Stack section of `docs/VISION.md`. These flow into the PRD's Dependencies & Integrations and the roadmap's polish/launch phase.

-----

## Section 8: Tooling

### Q8.1: Coding agent

- **Format:** List choice
- **Ask:** “Last one — what coding agent will you use to build this?”
- **Options:** Claude Code, Cursor, Windsurf, GitHub Copilot, Other
- If “Other”: ask “What’s the tool called?”

-----

## After Intake Is Complete

1. Assemble all answers into a vision document following the template in [VISION-TEMPLATE.md](VISION-TEMPLATE.md)
1. Save as `docs/VISION.md` (create the `docs/` directory if it doesn't exist)
1. Confirm with the user: list a brief summary of the key decisions (product name, audience, stack choices)
1. Offer to begin document generation

resources/PRD-GENERATION.md

# PRD Generation Guide

You are generating `docs/prd.md` — the technical blueprint for building this product. This document will be consumed directly by AI coding agents (Claude Code, Cursor, Windsurf, etc.) to build the application. Every section must be specific enough to implement without asking clarifying questions.

## Persona

You are a senior product manager and technical architect who writes specs that engineers and AI coding agents can build from directly. You've shipped dozens of products and know that a good PRD eliminates ambiguity. You write with precision — concrete endpoint paths, real field names, specific implementation guidance. You don't hand-wave.

## Input

1. Read `docs/VISION.md` — the founder’s intake answers
1. Read `docs/product-vision.md` — the strategic foundation you’re building on

Reference both throughout. The vision document contains brand, design, and strategy decisions that inform technical choices.

## Output

Write a single markdown file: `docs/prd.md`

Use the exact heading structure specified below.

## Critical Rules

- The user already chose their tech stack during intake. **NEVER second-guess their choices or suggest alternatives.** Your job is to provide detailed implementation guidance for their specific stack.
- Name specific packages — not "use a form library" but "use react-hook-form with zod for validation". Do NOT pin version numbers — the coding agent will install the latest compatible versions at build time.
- Write so a coding agent can read ANY section in isolation and start implementing immediately
- Be specific but not rigid — leave room for implementation judgment on minor UI/UX choices
- **Do not duplicate design tokens.** Visual design (colors, typography, spacing, components, motion) lives in `docs/design.md`, generated separately by the Design System skill. Reference token names from that file rather than redefining them here. If `docs/design.md` does not exist, note that the founder should run the Design System skill before implementation begins.
- Data models should be implementation-ready, not conceptual diagrams
- API specs should include real paths, methods, and request/response shapes

## Section Requirements

### 1. Overview

```markdown
# PRD — {productName}

## 1. Overview

### Product Summary
### Objective
### Market Differentiation
### Magic Moment
### Success Criteria
```

**Product Summary:** Product name, one-liner from intake, and a 2–3 sentence expanded description.

**Objective:** What this PRD covers — the MVP as defined in product-vision.md § Product Strategy. Reference the scope explicitly.

**Market Differentiation:** One paragraph from the competitive narrative in the vision doc, focused on what the technical implementation must deliver to achieve differentiation.

**Magic Moment:** The magic moment from intake and how the technical implementation enables it. What must be fast, what must be seamless, what must work perfectly.

**Success Criteria:** Measurable technical criteria for “done.” E.g. “Time to magic moment < 60 seconds from sign-up”, “Page load < 2s on 3G”, “All P0 features functional with test coverage.”

-----

### 2. Technical Architecture

```markdown
## 2. Technical Architecture

### Architecture Overview
### Chosen Stack
### Stack Integration Guide
### Repository Structure
### Infrastructure & Deployment
### Security Considerations
### Cost Estimate
```

**Architecture Overview:** A mermaid diagram showing the major system components and how they connect. Include: client, server/backend, database, auth, payments, any external APIs. Keep it high-level — this is the “boxes and arrows” view.

**Chosen Stack:** A table listing every layer of the stack from the intake:

|Layer   |Choice                     |Rationale                     |
|--------|---------------------------|------------------------------|
|Frontend|{techStack.frontend.choice}|{techStack.frontend.rationale}|
|Backend |{techStack.backend.choice} |{techStack.backend.rationale} |
|Database|{techStack.database.choice}|{techStack.database.rationale}|
|Auth    |{techStack.auth.choice}    |{techStack.auth.rationale}    |
|Payments|{techStack.payments.choice}|{techStack.payments.rationale}|
|Analytics|{techStack.analytics.choice}|{techStack.analytics.rationale}|
|Email   |{techStack.email.choice}   |{techStack.email.rationale}   |
|Error tracking|{techStack.errorTracking.choice}|{techStack.errorTracking.rationale}|

Include the analytics, email, and error-tracking rows whenever the founder chose them in intake (defaults: PostHog, Resend, Sentry). Omit any row set to "None."

**Stack Integration Guide:** How the chosen pieces fit together. Include: setup order (what to install/configure first), known integration patterns, common gotchas, required environment variables. This is the section that saves hours of debugging. Be specific to the exact stack combination.

**Repository Structure:** A file tree showing the expected project structure. Include all major directories and key files with brief descriptions:

```
project-root/
├── src/
│   ├── app/                  # Next.js App Router pages
│   ├── components/           # React components
│   │   ├── ui/               # Design system primitives
│   │   └── features/         # Feature-specific components
│   ├── lib/                  # Utilities, helpers, config
│   └── ...
├── convex/                   # Backend functions (if Convex)
│   ├── schema.ts             # Database schema
│   └── ...
├── public/                   # Static assets
└── ...
```

Adapt this to the actual stack chosen.

**Infrastructure & Deployment:** Where to deploy, how to deploy, CI/CD recommendations. For the chosen stack, recommend the path of least resistance (e.g. Vercel for Next.js, Convex Cloud for Convex). Include environment variables needed.

**Security Considerations:** Authentication flow, data protection, API security, input validation strategy. Specific to the chosen auth provider and backend. If an error-tracking service was chosen (default Sentry), note that it must be configured to scrub PII and secrets from captured events and breadcrumbs — error payloads should never leak tokens, passwords, or personal data.

**Cost Estimate:** Monthly cost estimate for the first 6 months at low scale (< 1000 users). Break down by service — include the supporting services (analytics, email, error tracking) the founder chose, noting each one's free-tier limit (e.g. PostHog 1M events/mo, Resend 3,000 emails/mo, Sentry's free error quota). Include free tier limits.

-----

### 3. Data Model

```markdown
## 3. Data Model

### Entity Definitions
### Relationships
### Indexes
```

**Entity Definitions:** For each entity/table: name, all fields with types, which fields are required, default values, validation rules. Use the syntax appropriate for the chosen database:

For Convex:

```typescript
// users table
{
  name: v.string(),           // Display name, required
  email: v.string(),          // Unique, from auth provider
  role: v.union(v.literal("admin"), v.literal("member")),
  avatarUrl: v.optional(v.string()),
  createdAt: v.number(),      // Unix timestamp
}
```

For SQL/Postgres:

```sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  role VARCHAR(50) NOT NULL DEFAULT 'member',
  avatar_url TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
```

**Relationships:** How entities connect. For each relationship: type (1:1, 1:many, many:many), which fields link them, cascade behavior.

**Indexes:** Which fields need indexes for query performance. Explain why each index exists.

-----

### 4. API Specification

```markdown
## 4. API Specification

### API Design Philosophy
### Endpoints
```

**API Design Philosophy:** REST vs RPC vs GraphQL (based on stack), authentication approach for API calls, error response format, pagination strategy.

For Convex backends, describe queries and mutations instead of REST endpoints:

```typescript
// Get all projects for the current user
query("projects.list", {
  args: {},
  returns: v.array(v.object({ ... })),
  handler: async (ctx) => { ... }
})

// Create a new project
mutation("projects.create", {
  args: { name: v.string(), description: v.optional(v.string()) },
  returns: v.id("projects"),
  handler: async (ctx, args) => { ... }
})
```

For REST backends, use this format:

```
POST /api/projects
Auth: Required (Bearer token)
Body: { name: string, description?: string }
Response 201: { id: string, name: string, description: string | null, createdAt: string }
Response 400: { error: string, details: ValidationError[] }
Response 401: { error: "Unauthorized" }
```

Cover all CRUD operations for each entity, plus any special operations (e.g. batch update, search, export).

-----

### 5. User Stories

```markdown
## 5. User Stories
```

Group by epic/feature area. Use this format:

```markdown
### Epic: [Feature Area]

**US-001: [Title]**
As a {primary persona name}, I want to {action} so that {outcome}.

Acceptance Criteria:
- [ ] Given [context], when [action], then [expected result]
- [ ] Given [context], when [action], then [expected result]
- [ ] Edge case: [scenario] → [expected behavior]
```

Cover all MVP features. Each story should map clearly to functional requirements.

-----

### 6. Functional Requirements

```markdown
## 6. Functional Requirements
```

Use this format for each requirement:

```markdown
**FR-001: [Title]**
Priority: P0
Description: [What the feature does — specific enough to implement]
Acceptance Criteria:
- [Criterion 1]
- [Criterion 2]
Related Stories: US-001, US-003
```

Priority levels:

- **P0:** Must have for MVP launch. Product is broken without it.
- **P1:** Should have for MVP. Product works without it but feels incomplete.
- **P2:** Nice to have. Deferred to post-launch unless trivial to add.

Organize by feature area. Number sequentially: FR-001 through FR-NNN.

-----

### 7. Non-Functional Requirements

```markdown
## 7. Non-Functional Requirements

### Performance
### Security
### Accessibility
### Scalability
### Reliability
```

Each requirement must have a **measurable threshold:**

- **Performance:** Page load time < 2s (LCP), Time to Interactive < 3s, API response < 200ms (p95), bundle size < 200KB initial
- **Security:** OWASP Top 10 addressed, auth tokens expire in [x] hours, rate limiting on auth endpoints
- **Accessibility:** WCAG 2.1 AA compliance, keyboard navigable, screen reader tested
- **Scalability:** Support [x] concurrent users on [chosen infrastructure tier]
- **Reliability:** 99.5% uptime target, graceful degradation when third-party services fail

-----

### 8. UI/UX Requirements

```markdown
## 8. UI/UX Requirements
```

Visual styling (colors, typography, spacing, component appearance) is **not** specified here — it lives in `docs/design.md`. This section covers structural and behavioral UX: layouts, states, interactions, and which components appear on which screens. Reference component names from `docs/design.md` rather than re-describing their styling.

For each screen/page:

```markdown
### Screen: [Name]
Route: /path
Purpose: [What the user does here]
Layout: [Description of the layout — header, sidebar, main content area, etc.]

States:
- **Empty:** [What shows when there's no data]
- **Loading:** [Skeleton/spinner approach]
- **Populated:** [Normal view with data]
- **Error:** [What shows when something fails]

Key Interactions:
- [Interaction 1: trigger → behavior → result]
- [Interaction 2: trigger → behavior → result]

Components Used: [List of components from docs/design.md, e.g. button-primary, card, input-text]
```

Cover: all pages in the MVP, the onboarding flow, settings/account page, and any modal/dialog flows.

If `docs/design.md` does not yet exist, add a note at the top of this section: "Visual tokens not yet defined. Run the Design System skill before implementation begins."

-----

### 9. Auth Implementation

```markdown
## 9. Auth Implementation

### Auth Flow
### Provider Configuration
### Protected Routes
### User Session Management
### Role-Based Access
```

Specific to the chosen auth provider ({techStack.auth.choice}). Include:

- Step-by-step setup instructions
- Configuration code snippets
- How to protect routes/pages
- How to access user data in components and API calls
- Social login setup if applicable
- Session/token management

Skip this section entirely if the auth choice is “None.” Instead, add a brief note: “This app does not require authentication. If auth is added later, revisit this section.”

-----

### 10. Payment Integration

```markdown
## 10. Payment Integration

### Payment Flow
### Provider Setup
### Pricing Model Implementation
### Webhook Handling
### Subscription Management
```

Specific to the chosen payment provider ({techStack.payments.choice}). Include:

- Setup and configuration
- How to create checkout sessions (web) or configure products/entitlements (mobile IAP)
- Webhook endpoints and event handling
- How to gate features based on subscription status
- Testing with test/sandbox mode
- Price IDs and product configuration

For mobile in-app payments (RevenueCat, Superwall): include App Store Connect / Google Play Console product setup, entitlement configuration, and how to check subscription status in the app.

Skip this section entirely if the revenue model is “Free” or the payment choice is “None.”

-----

### 11. Edge Cases & Error Handling

```markdown
## 11. Edge Cases & Error Handling
```

For each major feature area, list:

```markdown
### Feature: [Name]
| Scenario | Expected Behavior | Priority |
|----------|-------------------|----------|
| [What goes wrong] | [What the app should do] | P0/P1/P2 |
```

Cover: network failures, auth expiry mid-session, invalid data, concurrent edits, rate limiting, payment failures, empty states, permission denied scenarios.

-----

### 12. Dependencies & Integrations

```markdown
## 12. Dependencies & Integrations

### Core Dependencies
### Development Dependencies
### Third-Party Services
```

**Core Dependencies:** Every npm package needed (do not pin versions — the coding agent will install the latest compatible versions at build time):

```json
{
  "next": "...",
  "react": "...",
  "convex": "...",
  ...
}
```

**Development Dependencies:** Linting, formatting, testing:

```json
{
  "typescript": "^5.x.x",
  "eslint": "^9.x.x",
  ...
}
```

**Third-Party Services:** Any external APIs or services, with: what it’s used for, pricing tier, API key requirements, rate limits. This includes the supporting services chosen in intake — analytics (default PostHog), transactional email (default Resend), and error tracking (default Sentry) — each with its required environment variables (e.g. `POSTHOG_KEY`, `RESEND_API_KEY`, `SENTRY_DSN`) and the events/emails it handles. Skip any the founder set to "None."

-----

### 13. Out of Scope

```markdown
## 13. Out of Scope
```

Explicit list from product-vision.md § Product Strategy. For each item: what it is, why it’s excluded, and when to reconsider.

-----

### 14. Open Questions

```markdown
## 14. Open Questions
```

Unresolved technical or product decisions. For each: the question, the options, the tradeoffs, and a recommended default if the founder doesn’t have a strong opinion.

-----

## Output Structure Example

```markdown
# PRD — {productName}

## 1. Overview
## 2. Technical Architecture
## 3. Data Model
## 4. API Specification
## 5. User Stories
## 6. Functional Requirements
## 7. Non-Functional Requirements
## 8. UI/UX Requirements
## 9. Auth Implementation
## 10. Payment Integration
## 11. Edge Cases & Error Handling
## 12. Dependencies & Integrations
## 13. Out of Scope
## 14. Open Questions
```

Visual design tokens are not a section in the PRD. They live in `docs/design.md`, generated by the Design System skill. The PRD references token names from that file rather than redefining them.

resources/ROADMAP-GENERATION.md

# Product Roadmap Generation Guide

You are generating `docs/product-roadmap.md` — a phased build plan with checkboxes that a coding agent marks complete as it executes tasks. This document is the project’s source of truth for what’s been done and what’s next.

## Persona

You are a technical project manager and AI-assisted development expert. You know how to break a product into buildable phases where each phase produces a working, demoable increment. You deeply understand how AI coding agents (Claude Code, Cursor, Windsurf) work and structure tasks for maximum agent effectiveness — clear scope, specific files, no ambiguity.

## Input

1. Read `docs/VISION.md`
1. Read `docs/product-vision.md` — strategy, brand, voice & tone
1. Read `docs/prd.md` — technical spec, data models, requirements
1. Read `docs/design.md` if it exists — visual design tokens (colors, typography, spacing, components)

The PRD is your primary input. Every task in the roadmap should trace back to a requirement in the PRD.

If `docs/design.md` does not exist, the foundation phase should include a task that prompts the founder to run the Design System skill before scaffolding the design system, or the roadmap should call out that visual tokens are TBD and reference the eventual `docs/design.md` once generated.

## Output

Write a single markdown file: `docs/product-roadmap.md`

## Critical Rules

### Checkbox format is non-negotiable

Every task MUST use this exact format:

```markdown
- [ ] **TASK-001** — Description of what to do
  Files: `file1.ts`, `file2.ts`, `file3.tsx`
  Notes: Specific implementation details, config values, gotchas.
```

The three-line structure is: checkbox + ID + description, indented file list, indented notes.

When a coding agent completes a task, it MUST update this file to change `- [ ]` to `- [x]`. This is the mechanism that tracks progress.

### Task IDs are sequential across ALL phases

TASK-001 through TASK-NNN, never resetting. This makes it easy to reference any task by ID regardless of which phase it’s in.

### Each phase produces a working product

No phase should leave the app in a broken or unrunnable state. After completing any phase, the user should be able to run the app and see something functional. The foundation phase should produce a running app shell. The core MVP phase(s) should produce a usable product with the primary flow working.

### Tasks are ordered for sequential execution

A coding agent should be able to start at the first unchecked task and work through them in order without needing to jump around. Dependencies are resolved by ordering, not by cross-references.

### Task granularity

Each task should represent roughly one coding agent session — approximately 15–45 minutes of work. A task that takes 2+ hours should be split. A task that takes 2 minutes should be combined with related work.

### The magic moment is the milestone

The founder’s magic moment (from `docs/VISION.md` and `product-vision.md`) must be achievable by the end of the core MVP phase(s). If it can’t be, the task breakdown needs restructuring until it can. This is the most important design constraint for the roadmap.

-----

## Section Requirements

### Header

```markdown
# Product Roadmap — {productName}

> Generated by the Product Planner skill. Checkboxes are updated as tasks are completed.
> The coding agent MUST mark tasks `- [x]` as they are finished.

**Status:** {X}/{Y} tasks complete
**Current Phase:** Phase 0 — {Phase Title}
```

The status line should be set to `0/Y tasks complete` and `Phase 0` when first generated. The coding agent updates this as it works.

-----

### 1. Build Philosophy

```markdown
## Build Philosophy

1. **Each phase ships something usable.** No phase leaves the app broken. After any phase, you can demo what you've built.
2. **Infrastructure before features.** The first phase sets up everything so feature work in later phases is fast and clean.
3. **Magic moment first.** The core value proposition works as early as possible. Everything else builds on top.
4. **Test as you go.** Don't save testing for the end. Each task includes verification.
5. **Progressive enhancement.** Start with the simplest working version, then layer on polish.
6. **Review before proceeding.** Push each completed phase as a PR and let a review agent (e.g. CodeRabbit) review it before starting the next phase. External review catches issues the coding agent won't flag.
```

Adapt these principles to the specific product but keep all 6. Add 1–2 product-specific principles if relevant.

-----

### 2. Phases

The number and scope of phases should reflect the actual complexity of the product. Don’t force a fixed structure — design phases that make sense for this specific project and that are well-scoped for AI coding agent sessions.

#### How to decide the number of phases

- **Simple products** (utility apps, single-feature tools, local-only mobile apps): 2–3 phases may be enough. Foundation → Core Feature → Polish.
- **Medium products** (standard SaaS, CRUD apps with auth and payments): 4–5 phases is typical. Foundation → Core MVP → Remaining Features → Polish → Post-Launch.
- **Complex products** (multi-user collaboration, real-time features, multiple integrations, complex data models): 5–8 phases may be needed. Break feature work into logical groups rather than cramming everything into one phase.

The right number of phases is the one where each phase has a clear goal, a demoable outcome, and a manageable number of tasks (8–20 per phase). If a phase has 25+ tasks, split it. If a phase has 3 tasks, combine it.

#### Phase design principles

Every phase MUST follow this structure:

```markdown
## Phase {N}: {Descriptive Title}

> **Goal:** One sentence describing what's true when this phase is complete.

**Reference sections — read these before starting this phase:**
- PRD: § Technical Architecture, § Data Model, § Auth Implementation
- Design: docs/design.md (token YAML + Components prose)

**Phase prompt — give this to your coding agent:**
> "Read docs/product-roadmap.md and find Phase {N}. Then read only the Reference sections listed above from docs/prd.md, docs/product-vision.md, and docs/design.md. Continue from the first unchecked task. After each task, mark it complete in the roadmap. When all tasks are done, create a branch `phase-{N}/{slug}`, commit, push, and open a PR for review."

- [ ] **TASK-XXX** — ...
  Files: ...
  Notes: ...
```

Every phase needs:

- A **descriptive title** that communicates the theme (not just "Phase 2")
- A **goal statement** — one sentence describing the demoable outcome
- A **reference sections list** — the specific PRD and vision doc sections relevant to this phase (see below)
- A **phase prompt** the user can give their coding agent to kick off the phase
- **8–20 tasks** ordered for sequential execution

#### Reference sections

Each phase MUST include a "Reference sections" block listing the specific sections of `docs/prd.md` and `docs/product-vision.md` the coding agent should read for that phase. This prevents the agent from loading entire documents into context when only a few sections are relevant.

Rules for reference sections:

- List only the sections the agent actually needs for the tasks in that phase
- Use the exact heading text from the PRD, vision, and design docs so the agent can navigate directly (e.g. `§ Data Model`, not "the data stuff")
- Include subsections when only part of a top-level section is needed (e.g. `§ Components` from `docs/design.md` rather than the whole file)
- The foundation phase typically references: PRD `§ Technical Architecture`, PRD `§ Auth Implementation`, and `docs/design.md` (token YAML front matter + `§ Colors`, `§ Typography`, `§ Layout`, `§ Components`)
- Core MVP phases typically reference: PRD `§ Data Model`, PRD `§ API Specification`, PRD `§ User Stories`, PRD `§ Functional Requirements`, PRD `§ UI/UX Requirements` for the relevant screens, and `docs/design.md § Components` for styling
- Polish/launch phases typically reference: PRD `§ Non-Functional Requirements`, PRD `§ Edge Cases & Error Handling`, and `docs/design.md § Do's and Don'ts`
- Visual design tokens always come from `docs/design.md`, never from `docs/product-vision.md` (which no longer carries them)
- If a go-to-market plan exists (e.g. `docs/gtm.md`), the polish/launch phase may optionally reference it for launch-related tasks
- If `docs/design.md` does not exist, flag it in the foundation phase notes — visual tokens must be generated via the Design System skill before any styling work begins
- If a task needs a section not listed in the phase references, include it in the task's Notes line (e.g. "Notes: See also docs/prd.md § Payment Integration for webhook setup.")

#### Required phase types

Regardless of total phase count, every roadmap must include these phase types (they may be combined for simple projects):

**Foundation phase (always first):**
The first phase is always infrastructure. A running app shell with core tooling configured. No features yet, but the project is set up correctly and every subsequent task builds on a working foundation. Covers: project init, config, backend/database setup, auth setup (if needed), base layout, design system tokens, environment variables, dev workflow verification.

**Core MVP phase(s):**
The phase(s) where the primary user flows come to life. The magic moment MUST be achievable by the end of the core MVP work — this is the most important constraint. For simple products this is one phase. For complex products, split by feature area (e.g. “Phase 2: Document Management”, “Phase 3: Collaboration & Sharing”).

When splitting core MVP work across multiple phases, follow this task pattern per feature:

1. Data layer (schema/model + API/queries/mutations)
1. UI components for the feature
1. Wire up data to UI
1. Basic error handling and loading states

**Polish & launch phase (always present):**
A phase dedicated to quality, not new features. Covers: comprehensive error handling, empty states, loading states, form validation, landing/marketing page, SEO basics, responsive design, accessibility pass, performance check, and wiring the supporting services the founder chose — analytics (default PostHog: install the SDK and instrument the key funnel events, including the magic moment), error tracking (default Sentry: initialize on client and server, confirm a test error reports), and any transactional email not already wired in an earlier phase. For simple products this can be the final phase. For complex products it comes before any post-launch phase.

Place supporting services by when they're needed, not all in polish: error tracking can be initialized in the foundation phase so crashes are caught from day one; transactional email (default Resend) belongs in whatever phase first needs it — usually the auth phase for magic links and password resets, or the payments phase for receipts; analytics instrumentation fits the polish phase once the flows exist. Only include tasks for services the founder actually chose — skip any set to "None" in `docs/VISION.md`.

**Post-launch phase (optional):**
Only include this for products with P2 features or planned iteration. Covers: nice-to-have features, performance optimization, scale considerations, placeholder tasks for user feedback. Mark this phase as evolving — priorities will shift based on real usage. Skip entirely for simple utility apps or MVPs where the scope is fully covered in earlier phases.

#### Phase naming

Name phases by what they accomplish, not by number alone. Good names tell the founder what they’re building:

- ✓ “Phase 0: Foundation & Setup”
- ✓ “Phase 1: Core Search Experience”
- ✓ “Phase 2: Team Collaboration”
- ✓ “Phase 3: Payments & Subscription Gating”
- ✓ “Phase 4: Polish & Launch Prep”
- ✗ “Phase 2: More Features”
- ✗ “Phase 3: Stuff We Didn’t Finish”

#### Examples by complexity

**Simple — Habit tracker mobile app (3 phases, ~25 tasks):**

- Phase 0: Foundation & Setup (project init, local storage, base navigation)
- Phase 1: Core Tracking Experience (habit CRUD, daily check-ins, streak tracking, the magic moment)
- Phase 2: Polish & Launch Prep (empty states, animations, app store assets, analytics)

**Medium — SaaS dashboard with auth and payments (5 phases, ~55 tasks):**

- Phase 0: Foundation (project scaffold, Convex, Clerk auth, Tailwind design tokens)
- Phase 1: Core Dashboard (primary data model, main dashboard view, key CRUD flows, magic moment)
- Phase 2: Complete Features (settings, secondary flows, data export, payment integration)
- Phase 3: Polish & Launch Prep (error handling, landing page, SEO, analytics, responsive)
- Phase 4: Post-Launch Iteration (P2 features, performance, user-requested improvements)

**Complex — Collaborative research tool (7 phases, ~90 tasks):**

- Phase 0: Foundation (project scaffold, Convex, Clerk with orgs, design system)
- Phase 1: Document Management (upload, extraction, tagging, storage)
- Phase 2: Search & Discovery (semantic search, filters, results UI, magic moment)
- Phase 3: Team Collaboration (sharing, permissions, activity feed, comments)
- Phase 4: Payments & Subscription Gating (Polar integration, feature gating, billing portal)
- Phase 5: Polish & Launch Prep (error handling, empty states, landing page, analytics)
- Phase 6: Post-Launch (P2 features, advanced search, integrations, scale)

-----

### Phase Review Workflow

After completing every phase, the coding agent pushes the work as a pull request for external review. This is a quality gate — the next phase should not start until the PR is reviewed and merged.

#### Branch naming

Create a branch per phase: `phase-{N}/{phase-slug}` — the slug is the phase title in lowercase kebab-case.

Examples:
- `phase-0/foundation-and-setup`
- `phase-1/core-search-experience`
- `phase-3/payments-and-subscription-gating`

#### PR format

```
Title: Phase {N}: {Phase Title}

Body:
## Goal
{The phase's goal statement from the roadmap}

## Completed
- {X} tasks completed (TASK-{first} through TASK-{last})

## What to verify
- {Key things to test manually after merging — derived from task verification notes}

## Reference sections used
- PRD: § {sections}
- Vision: § {sections}
```

#### Review agent

The PR should be reviewed by an automated review agent before merging. Recommend [CodeRabbit](https://coderabbit.ai) as the default — it's free for open-source and provides automated code review on every PR. Other options (GitHub Copilot code review, Codacy, etc.) work too. The key is that each phase gets external eyes before the next phase builds on top of it.

If the review agent flags issues:
1. Address the feedback in follow-up commits on the same branch
2. Let the review agent re-review
3. Merge only when the review is clean

#### When the user doesn't use GitHub

If the user isn't using GitHub or doesn't want PR-based review, skip this step. Mention what they're giving up ("automated review catches bugs, security issues, and style problems the coding agent may miss") and continue to the next phase. The per-task verification still applies regardless.

#### Generated roadmap integration

When generating `docs/product-roadmap.md`, include a brief note about the Phase Review workflow in the Build Philosophy section and in the Agent Session Guide. The phase prompt templates should remind the user to open a PR after completing the phase. This way the generated roadmap itself documents the workflow, not just these instructions.

-----

### 3. Agent Session Guide

```markdown
## Agent Session Guide

### How to Use This Roadmap with Your Coding Agent

1. **Start a session:** Give your coding agent the phase prompt at the beginning of each phase.
2. **Read selectively:** Each phase lists its Reference sections — the specific parts of the PRD and vision doc needed for that phase. The agent should read only those sections, not the entire documents.
3. **Let it work:** The agent reads the roadmap, finds the first unchecked task, implements it, and marks it complete.
4. **One session = one phase (ideally):** Try to complete a full phase in one session for best continuity. If you need to stop, the agent can resume from the last unchecked task.
5. **Push a PR for review:** When a phase is complete, push the work as a PR and let a review agent (e.g. [CodeRabbit](https://coderabbit.ai)) review it before starting the next phase. See the Phase Review section below.
6. **Need more context?** If a task references a section not in the phase's Reference sections, the agent should read just that section on demand.

### Session Tips

- **Don't read everything:** The PRD and vision doc can be large. Each phase's Reference sections tell the agent exactly what to read. Loading the full documents wastes context.
- **Don't skip tasks:** Tasks are ordered intentionally. Skipping creates dependency issues.
- **Verify after each phase:** Run the app after completing a phase to confirm everything works before moving on.
- **Review before moving on:** Push a PR for each completed phase and let your review agent check it. Don't start the next phase until the PR is merged. This catches issues early when they're cheap to fix.
- **Update the status line:** After completing tasks, update the header status: `**Status:** X/Y tasks complete` and `**Current Phase:** Phase N`.

### Prompt Templates

**Starting a new phase:**
> "Read docs/product-roadmap.md and find the current phase. Read only the Reference sections listed for that phase from docs/prd.md, docs/product-vision.md, and docs/design.md. Start working on the first unchecked task. After completing each task, update the checkbox to [x] in the roadmap file. Continue through the phase."

**Resuming after a break:**
> "Read docs/product-roadmap.md. Find where we left off (first unchecked task). Read only the Reference sections listed for the current phase from docs/prd.md, docs/product-vision.md, and docs/design.md. Continue from the first unchecked task."

**After completing a phase:**
> "Phase [N] is complete. Create a branch called phase-{N}/{slug}, commit all work, push, and open a PR targeting main. Title it 'Phase {N}: {Title}' and include the phase goal and completed task count in the body."

**Fixing an issue:**
> "There's a problem with [description]. Read the relevant section of docs/prd.md for the expected behavior and fix it. Don't mark any new tasks complete until the fix is verified."
```

-----

## Task Writing Guidelines

When writing individual tasks, follow these principles:

**Be specific about files:** Don’t say “create the user component” — say “Files: `src/components/features/UserProfile.tsx`, `src/components/features/UserAvatar.tsx`”

**Be specific about behavior:** Don’t say “add error handling” — say “Notes: Show toast notification on save failure. Retry once automatically. After retry failure, show inline error with ‘Try again’ button.”

**Include config values:** When a task involves configuration, include the actual values. Not “set up Tailwind” but “Notes: Configure tailwind.config.ts with the design tokens from the YAML front matter of docs/design.md. Set content paths to include `./src/**/*.{ts,tsx}`.”

**Include verification:** Each task’s Notes should end with how to verify it works. E.g. “Verify: Run dev server, navigate to /dashboard, confirm the sidebar renders with all nav items.”

**Reference PRD sections:** When a task implements a specific feature, reference the PRD section. E.g. “Notes: Implement per FR-012 in docs/prd.md. See § UI/UX Requirements > Dashboard for layout spec.”

-----

## Output Structure

```markdown
# Product Roadmap — {productName}

> Generated by the Product Planner skill. Checkboxes are updated as tasks are completed.
> The coding agent MUST mark tasks `- [x]` as they are finished.

**Status:** 0/{total} tasks complete
**Current Phase:** Phase 0 — {Foundation Title}

## Build Philosophy
...

## Phase 0: {Foundation Title}
> Goal: ...

Reference sections:
- PRD: § ...
- Vision: § ...

> Phase prompt: ...

- [ ] **TASK-001** — ...
- [ ] **TASK-002** — ...
...

## Phase 1: {Core MVP Title}
> Goal: ...

Reference sections:
- PRD: § ...
- Vision: § ...

> Phase prompt: ...

- [ ] **TASK-0XX** — ...
...

## Phase {N}: {Title}
...
(as many phases as the project requires)
...

## Phase {last}: {Polish / Post-Launch Title}
...

## Agent Session Guide
...
```

resources/TECH-STACK-OPTIONS.md

# Tech Stack Options

Default comparison data for the Product Planner tech stack questions. Use these as a baseline and adapt recommendations based on the specific product's needs. The comparison format and pros/cons should be adjusted to reflect how each option fits the founder's particular product.

**This list is a starting point, not a boundary.** The ecosystem moves fast and no static list stays current. Research beyond it whenever:

- The founder names a tool that isn't listed here — research it and give a fair assessment rather than steering them back to this list
- The product has unusual needs this list doesn't serve well (e.g. heavy ML inference, hardware integration, blockchain, real-time video, HIPAA compliance)
- You're unsure whether an option here is still the current best-in-class — verify with a web search before presenting it as the recommendation
- The founder asks "what else is out there?" — do a fresh search of the category, not just a recital of this file

When you research, evaluate candidates with the same lens used here: maturity and community size, AI-coding-tool familiarity, integration with the rest of the chosen stack, pricing and free tier, and operational burden for a small team. Present researched options in the same comparison format so the founder can weigh them against the defaults.

-----

## Frontend Frameworks

### Web Apps

**Next.js** — React framework with server-side rendering, file-based routing, and excellent deployment options.

- ✓ Largest React ecosystem, huge community, extensive documentation
- ✓ App Router with server components for performance
- ✓ Excellent integration with Vercel, Convex, Clerk, and most services
- ✓ Best-supported by AI coding tools (most training data)
- ✗ Can be complex — many ways to do things (server vs client components)
- ✗ Opinionated about project structure
- **Best for:** Most web apps. Default recommendation unless there's a specific reason not to.

**Vite + React (SPA)** — Single-page React app with Vite's fast build tooling, no server-rendering framework.

- ✓ Simplest mental model — it's just React, no server/client component split
- ✓ Extremely fast dev server and builds
- ✓ Pairs naturally with backend-as-a-service platforms (Convex, Supabase, Firebase) that handle the server side
- ✓ Deploys anywhere static files can be hosted
- ✗ No server-side rendering — weaker SEO for content-heavy public pages
- ✗ Routing, data fetching, and head management are assembled from libraries rather than built in
- **Best for:** App-like products behind a login (dashboards, tools, SaaS apps) where SEO doesn't matter and a BaaS handles the backend.

**React Router (formerly Remix)** — Full-stack React framework focused on web standards and progressive enhancement; Remix merged into React Router v7.

- ✓ Excellent form handling and data loading patterns (loaders + actions)
- ✓ Progressive enhancement — works without JavaScript
- ✓ Simpler mental model than Next.js
- ✗ Smaller ecosystem than Next.js
- ✗ Less AI coding tool familiarity
- **Best for:** Form-heavy apps, content-heavy sites, apps that need to work without JS.

**SvelteKit** — Svelte framework with file-based routing and server-side rendering.

- ✓ Significantly less boilerplate than React
- ✓ Excellent performance — smaller bundle sizes
- ✓ Built-in state management (no Redux/Zustand needed)
- ✗ Smaller ecosystem and community than React
- ✗ Fewer component libraries available
- ✗ Less AI coding tool support
- **Best for:** Performance-critical apps, developers who prefer less boilerplate.

**Nuxt** — Vue framework with server-side rendering, file-based routing, and a strong module ecosystem.

- ✓ Vue's gentle learning curve with batteries-included conventions
- ✓ Strong module ecosystem (auth, content, images) with minimal wiring
- ✓ Good performance defaults and hybrid rendering options
- ✗ Vue ecosystem is smaller than React's — fewer component libraries and integrations
- ✗ Less AI coding tool familiarity than Next.js
- **Best for:** Teams that know or prefer Vue. Don't switch to React just for the ecosystem if Vue expertise already exists.

**Astro** — Content-first framework that ships zero JavaScript by default, with islands of interactivity in any UI framework.

- ✓ Outstanding performance for content sites — HTML-first output
- ✓ Use React, Svelte, or Vue components only where interactivity is needed
- ✓ First-class markdown/MDX content handling
- ✗ Not designed for highly interactive app experiences — islands have limits
- ✗ App-like features (auth flows, dashboards) require more assembly
- **Best for:** Marketing sites, blogs, docs, and content-heavy products where speed and SEO are the priority. Often paired with a separate app framework for the product itself.

### Mobile Apps

**Expo / React Native** — Cross-platform mobile framework with managed workflow.

- ✓ Write once, run on iOS and Android
- ✓ Expo managed workflow eliminates native build complexity
- ✓ React knowledge transfers directly
- ✓ Over-the-air updates
- ✗ Performance can lag behind native for graphics-heavy apps
- ✗ Some native APIs require custom native modules
- **Best for:** Most mobile apps. Default recommendation for mobile.

**Flutter** — Google's cross-platform UI toolkit using Dart.

- ✓ Excellent performance — compiles to native
- ✓ Beautiful, customizable UI components
- ✓ Single codebase for iOS, Android, web, desktop
- ✗ Dart is a separate language to learn
- ✗ Less ecosystem integration with JS/TS backends
- ✗ Less AI coding tool support than React Native
- **Best for:** Apps needing pixel-perfect custom UI or very high performance.

**SwiftUI (native iOS)** — Apple's declarative UI framework for iOS, iPadOS, watchOS, and macOS.

- ✓ Best possible iOS experience — native performance, platform conventions, immediate access to new Apple APIs
- ✓ Tight integration with Apple frameworks (HealthKit, ARKit, widgets, App Intents)
- ✓ Strong AI coding tool support for Swift
- ✗ iOS-only — an Android version means a second codebase
- ✗ Requires a Mac to build; TestFlight/App Store only distribution
- **Best for:** iOS-first products, apps leaning on Apple-specific capabilities, or founders who accept iOS-only for v1.

**Jetpack Compose (native Android)** — Google's declarative UI toolkit for native Android in Kotlin.

- ✓ Best possible Android experience — native performance and platform integration
- ✓ Kotlin is modern and pleasant; strong tooling in Android Studio
- ✗ Android-only — an iOS version means a second codebase
- ✗ Smaller indie/startup mindshare than cross-platform options
- **Best for:** Android-first products or markets where Android dominates.

### Desktop Apps

**Electron** — Build cross-platform desktop apps with Chromium and Node.js. Powers VS Code, Slack, Discord, Figma, and Notion.

- ✓ Most mature desktop framework — battle-tested at massive scale
- ✓ Full web technology stack (HTML, CSS, JS/TS) — no new language to learn
- ✓ Largest ecosystem of plugins, tools, and community resources
- ✓ Excellent AI coding tool support (most training data)
- ✗ Heavy memory footprint — each app bundles its own Chromium instance
- ✗ Large bundle sizes (100MB+ minimum)
- ✗ Can feel non-native on macOS — requires extra work to match platform conventions
- **Best for:** Most desktop apps. Default recommendation for desktop. Especially strong when the team already knows web technologies.

**Tauri** — Lightweight desktop framework using the OS's native webview and a Rust backend.

- ✓ Dramatically smaller bundles than Electron (often 5-10MB vs 100MB+)
- ✓ Lower memory usage — uses the OS webview instead of bundling Chromium
- ✓ Rust backend for performance-critical operations and system access
- ✓ Strong security model — fine-grained permission system for system APIs
- ✗ Younger ecosystem — fewer community resources and plugins than Electron
- ✗ Rust knowledge needed for backend plugins and system integrations
- ✗ OS webview inconsistencies can cause cross-platform rendering differences
- **Best for:** Desktop apps where bundle size and memory matter, or when deep system integration is needed. Good for developers comfortable with Rust.

**Flutter (Desktop)** — The same Flutter framework listed under Mobile, with support for macOS, Windows, and Linux.

- ✓ Single codebase across mobile, web, and desktop — true cross-platform
- ✓ Compiles to native — good performance without a webview
- ✓ Consistent UI across all platforms
- ✗ Desktop support is less mature than mobile — some platform APIs are missing
- ✗ Dart ecosystem is smaller than JS/TS for desktop-specific needs
- ✗ Apps don't follow native platform UI conventions by default
- **Best for:** Projects that need a single codebase across mobile AND desktop. Not recommended for desktop-only apps — Electron or Tauri are better choices there.

-----

## Backend

**Convex** — Reactive backend-as-a-service with built-in database, real-time sync, and TypeScript-native functions.

- ✓ Real-time data sync out of the box — no WebSocket setup
- ✓ Zero backend boilerplate — define functions, they just work
- ✓ Built-in auth, file storage, scheduling, search
- ✓ TypeScript end-to-end with full type safety
- ✓ Excellent DX for solo developers — fast iteration
- ✓ ACID transactions on the database
- ✗ Newer ecosystem — fewer community resources
- ✗ Vendor dependency — data lives on Convex Cloud
- ✗ Different mental model from traditional REST APIs
- **Best for:** Real-time and collaborative apps, solo developers, fast-moving MVPs in TypeScript.

**Supabase** — Open-source Firebase alternative built on PostgreSQL.

- ✓ PostgreSQL under the hood — full SQL power, relational data
- ✓ Real-time subscriptions, auth, storage, edge functions
- ✓ Open source — can self-host if needed
- ✓ Large and growing community
- ✗ More setup than Convex — manual schema migrations
- ✗ Real-time requires explicit subscription setup
- ✗ Edge functions are less integrated than Convex functions
- **Best for:** Products with complex relational data, teams that want SQL and open-source.

**Firebase** — Google's mature backend-as-a-service: Firestore, auth, storage, cloud functions, push notifications.

- ✓ Very mature — over a decade of production hardening, deep docs
- ✓ Best-in-class mobile SDKs and push notification support (FCM)
- ✓ Generous free tier; scales automatically
- ✓ Tight Google Cloud integration when you outgrow it
- ✗ Firestore's NoSQL model makes complex relational queries painful
- ✗ Vendor lock-in is real — migrating off Firestore is hard
- ✗ Pricing can spike with chatty read/write patterns
- **Best for:** Mobile-first products (especially with push notifications), or founders already in the Google ecosystem.

**Hono / lightweight TypeScript API** — Minimal, fast TypeScript web framework that runs on Node, Bun, and edge runtimes (Cloudflare Workers, Vercel).

- ✓ Tiny, fast, modern — Express-style routing without the legacy baggage
- ✓ Runs on edge runtimes for low latency worldwide
- ✓ Full control with far less boilerplate than Express
- ✗ You still assemble the rest: database client, auth, validation, deployment
- ✗ Smaller middleware ecosystem than Express
- **Best for:** Founders who want a real API server with full control but minimal framework weight; pairs well with Neon/Turso and Better Auth.

**Node.js + Express + PostgreSQL** — Traditional server setup with full control.

- ✓ Maximum flexibility — build exactly what you need
- ✓ Largest ecosystem of packages and middleware
- ✓ Full control over infrastructure and hosting
- ✗ Significant boilerplate — auth, validation, error handling, CORS, etc.
- ✗ You manage everything: database migrations, deployment, scaling
- ✗ Slower to iterate as a solo developer
- **Best for:** Experienced backend developers who want full control, or products with unusual requirements.

**FastAPI (Python)** — Modern Python API framework with automatic OpenAPI docs and async support.

- ✓ The natural choice when the product's core is Python (ML, data science, AI pipelines)
- ✓ Type-hint-driven validation and auto-generated API docs
- ✓ Huge Python ecosystem for ML/AI/data work
- ✗ Two-language stack if the frontend is TypeScript — duplicated types and tooling
- ✗ You assemble auth, ORM (SQLAlchemy/SQLModel), and deployment yourself
- **Best for:** Products whose differentiation is ML/AI/data processing in Python. Otherwise prefer a TypeScript-native option to keep one language end to end.

**Ruby on Rails** — The original batteries-included full-stack framework.

- ✓ Extremely productive conventions — auth, ORM, jobs, mailers all standard
- ✓ Mature ecosystem with decades of solved problems
- ✓ Hotwire/Turbo gives interactive UIs without a separate frontend framework
- ✗ Ruby talent and AI-tool familiarity are thinner than TypeScript's
- ✗ Separate language from a JS frontend if you go SPA
- **Best for:** Founders who know Rails, or server-rendered CRUD-heavy products where one framework doing everything is an advantage.

-----

## Database

**Convex Database** — Document-relational database built into the Convex platform.

- ✓ Automatic reactive queries — UI updates when data changes
- ✓ ACID transactions with optimistic concurrency
- ✓ Automatic indexing — define indexes in schema, they just work
- ✓ TypeScript schema validation built-in
- ✗ Only available with Convex backend
- ✗ Document-oriented — different from SQL thinking
- **Best for:** Any product using Convex backend. Use this — it's part of the package.

**Supabase Database (PostgreSQL)** — Managed PostgreSQL via the Supabase platform with a dashboard, auto-generated APIs, and real-time subscriptions.

- ✓ Full PostgreSQL — complex queries, joins, extensions, relational power
- ✓ Auto-generated REST and GraphQL APIs from your schema
- ✓ Real-time subscriptions built in
- ✓ Row Level Security for fine-grained access control
- ✓ Dashboard with table editor — visual schema management
- ✗ Only makes sense with Supabase backend
- ✗ Migrations still needed for production schema changes
- **Best for:** Supabase backends — use this, it's part of the package. Excellent for relational data.

**PostgreSQL (self-managed or generic host)** — The gold-standard open-source relational database.

- ✓ Rock-solid reliability and ACID compliance
- ✓ Full SQL power — complex queries, joins, aggregations
- ✓ Excellent for relational data with complex relationships
- ✓ Massive ecosystem of tools and extensions
- ✗ Requires migrations for schema changes
- ✗ No built-in real-time — need separate pub/sub
- **Best for:** Products with complex relational data on traditional backends.

**Neon (serverless PostgreSQL)** — Managed Postgres with serverless scaling, branching, and scale-to-zero.

- ✓ Real PostgreSQL with a generous free tier and scale-to-zero pricing
- ✓ Database branching — spin up a copy per environment or PR
- ✓ Works with any backend that speaks Postgres; great with serverless/edge functions
- ✗ Cold starts after scale-to-zero on the free tier
- ✗ It's just the database — auth, APIs, and storage live elsewhere
- **Best for:** Custom backends (Hono, Express, FastAPI) that want managed Postgres without running a server.

**Turso / SQLite (libSQL)** — SQLite-compatible database, either embedded locally or hosted at the edge.

- ✓ Tiny, fast, zero-ops — SQLite's simplicity with optional hosted replication
- ✓ Great fit for local-first and offline-capable apps
- ✓ Per-tenant database patterns are cheap (one DB per user/team)
- ✗ Not built for high-concurrency write-heavy workloads
- ✗ Smaller ecosystem than Postgres for tooling and extensions
- **Best for:** Local-first apps, desktop/mobile embedded storage, read-heavy edge apps, and per-tenant architectures.

**MongoDB (Atlas)** — The most widely used document database, managed via Atlas.

- ✓ Flexible document model — easy to evolve schemas early on
- ✓ Mature managed offering with search and vector search built in
- ✓ Huge ecosystem and driver support in every language
- ✗ Relational integrity and multi-document joins are weaker than SQL
- ✗ Easy to make data-modeling mistakes that hurt later
- **Best for:** Document-shaped data, teams already fluent in Mongo. For most new SaaS products, Postgres-family options are the safer default.

**None (local-only / no database)** — The app stores data on-device only (AsyncStorage, SQLite, UserDefaults, local files).

- ✓ Zero infrastructure — no backend costs, no latency
- ✓ Works offline by default
- ✓ Simpler architecture — no sync, no API calls
- ✗ Data is lost if the user deletes the app (unless backed up)
- ✗ No cross-device sync
- ✗ No server-side logic or shared data
- **Best for:** Mobile apps that are primarily tools (calculators, trackers, utilities), offline-first apps, or MVPs that don't need shared data. Consider adding a backend later if the product grows.

-----

## Auth Providers

**Convex Auth** — Native auth built into the Convex platform.

- ✓ Zero-config integration with Convex backend
- ✓ Supports email/password, OAuth providers, magic links
- ✓ User data lives in Convex — no external service calls
- ✗ Only works with Convex backend
- ✗ Fewer pre-built UI components than Clerk
- **Best for:** Convex backends where simplicity is priority.

**Clerk** — Drop-in auth with pre-built UI components.

- ✓ Beautiful, pre-built sign-in/sign-up components
- ✓ Social login, MFA, organization management out of the box
- ✓ Excellent React/Next.js integration
- ✓ Generous free tier (10,000 MAUs)
- ✗ External service dependency
- ✗ Monthly cost at scale
- **Best for:** Products that want polished auth UI fast. Works with any backend.

**Better Auth** — Open-source, framework-agnostic TypeScript auth library you own and host.

- ✓ Open source and self-hosted — user data stays in your database, no per-MAU fees
- ✓ Comprehensive: email/password, OAuth, magic links, 2FA, organizations, plugins
- ✓ Works across Next.js, Hono, Express, and most TS backends
- ✗ You build the UI and own the security configuration
- ✗ Younger project — smaller community than Auth.js or Clerk
- **Best for:** TypeScript founders who want full ownership of auth and user data without vendor fees.

**Auth.js (NextAuth)** — Open-source auth for Next.js.

- ✓ Open source — no vendor dependency
- ✓ Supports many OAuth providers
- ✓ Database adapters for most databases
- ✗ More setup and configuration than Clerk
- ✗ Less polished UI — you build your own forms
- ✗ Session management can be tricky
- **Best for:** Next.js developers who want open-source auth with full control.

**Supabase Auth** — Auth built into the Supabase platform.

- ✓ Integrated with Supabase — Row Level Security uses auth
- ✓ Email/password, magic links, OAuth providers
- ✓ Free with Supabase
- ✗ Only makes sense with Supabase backend
- ✗ Less polished than Clerk's UI components
- **Best for:** Supabase backends — use this, it's part of the package.

**Firebase Auth** — Auth built into the Firebase platform.

- ✓ Mature, battle-tested, generous free tier
- ✓ Excellent mobile SDK support — phone auth, anonymous auth, social providers
- ✓ Integrates with Firestore security rules
- ✗ Only makes sense with Firebase backend
- ✗ Customizing flows beyond the defaults gets awkward
- **Best for:** Firebase backends and mobile apps needing phone or anonymous auth.

**WorkOS / Auth0 (enterprise-grade)** — Hosted identity platforms with enterprise SSO (SAML, OIDC), directory sync, and compliance features.

- ✓ The fastest route to "Sign in with [corporate SSO]" — required for selling to enterprises
- ✓ Compliance, audit logs, and directory sync handled for you
- ✗ Overkill for consumer or early-stage products
- ✗ Cost scales steeply (Auth0 especially)
- **Best for:** B2B products whose buyers will demand SSO. Usually a later addition, not an MVP choice — but plan for it if enterprise is the explicit go-to-market.

**None (no auth needed)** — The app doesn't require user accounts or sign-in.

- ✓ Simpler UX — no sign-up friction, instant access
- ✓ Less infrastructure to manage
- ✓ Better for tools, utilities, and single-player experiences
- ✗ No personalization or saved preferences across devices
- ✗ Can't gate features behind subscription tiers (without device-level checks)
- **Best for:** Mobile utility apps, offline tools, calculators, single-player experiences, or MVPs testing core value before adding accounts. Can always add auth later.

-----

## Payment Providers

### Web / SaaS Payments

**Polar** — Developer-first payment platform for SaaS and digital products.

- ✓ Built specifically for developers and SaaS products
- ✓ Handles subscriptions, one-time payments, and licensing
- ✓ Merchant of record — handles global tax compliance for you
- ✓ Excellent API and webhook support; built-in customer portal
- ✗ Newer platform — smaller community than Stripe
- ✗ Less suitable for physical goods or complex billing
- **Best for:** SaaS products, digital products, developer tools sold by small teams.

**Stripe** — The most flexible and widely-used payment platform.

- ✓ Supports virtually any payment model
- ✓ Largest ecosystem — extensive documentation, libraries, integrations
- ✓ Stripe Checkout for quick integration
- ✓ Billing portal, invoicing, subscription management
- ✗ Complex — many concepts to learn (Products, Prices, Subscriptions, etc.)
- ✗ You are the merchant of record — tax registration and compliance is on you (or Stripe Tax at extra cost)
- **Best for:** Products with complex billing needs, marketplaces, or maximum flexibility.

**Lemon Squeezy** — Merchant of record for digital products (acquired by Stripe).

- ✓ Handles global tax compliance — they're the merchant of record
- ✓ Simple setup for subscriptions and one-time payments
- ✓ Built-in affiliate program
- ✗ Higher fees than raw Stripe (they take on tax liability)
- ✗ Less flexible than Stripe for complex billing
- **Best for:** Solo founders selling internationally who don't want to deal with tax compliance.

**Paddle** — Established merchant of record for SaaS billing.

- ✓ Merchant of record — global tax, compliance, and chargebacks handled
- ✓ Mature platform with strong subscription and invoicing features
- ✓ Good for selling to both consumers and businesses internationally
- ✗ Approval process before you can sell — not instant setup
- ✗ Checkout customization is more limited than Stripe
- **Best for:** SaaS businesses that want the merchant-of-record model from an established provider.

### Mobile In-App Payments

For mobile apps distributed through the App Store or Google Play, in-app purchases (IAP) are often required by platform policies. These tools manage subscriptions and purchases through the native store billing systems.

**RevenueCat** — Cross-platform in-app subscription management.

- ✓ Abstracts Apple and Google billing APIs into one SDK
- ✓ Handles receipt validation, entitlements, and subscription status server-side
- ✓ Excellent dashboard with analytics, cohorts, and churn tracking
- ✓ Generous free tier — free up to $2,500/month in tracked revenue
- ✓ Works with React Native/Expo, Flutter, Swift, Kotlin
- ✓ Webhook support for backend integration
- ✗ Another dependency and point of failure in the payment flow
- ✗ Paid tiers add up as revenue grows (1% of tracked revenue after free tier)
- **Best for:** Any mobile app with subscriptions or one-time IAP. Default recommendation for mobile payments.

**Superwall** — Paywall A/B testing and management platform.

- ✓ Build and deploy paywalls remotely — no app update needed to change pricing UI
- ✓ Built-in A/B testing for paywall designs, pricing, and placement
- ✓ Pre-built paywall templates that convert well
- ✓ Works with RevenueCat or handles purchases directly via StoreKit/Billing
- ✗ Focused on paywall presentation — not a full subscription backend (pair with RevenueCat for that)
- ✗ Free tier is limited — paid plans required for A/B testing
- **Best for:** Mobile apps that want to optimize subscription conversion through paywall experimentation. Best paired with RevenueCat.

**Adapty** — RevenueCat alternative with built-in paywall builder and A/B testing.

- ✓ Subscription infrastructure plus no-code paywall builder in one SDK
- ✓ A/B testing and remote paywall config included on lower tiers
- ✓ Strong analytics on funnels and cohorts
- ✗ Smaller community and integration ecosystem than RevenueCat
- ✗ Pricing scales with revenue like RevenueCat
- **Best for:** Mobile apps that want subscriptions and paywall experimentation from a single vendor.

**None (no payments needed)** — The app is free with no monetization, or monetization will be added later.

- ✓ Ship faster — no payment integration complexity
- ✓ No App Store commission considerations
- ✓ Focus entirely on core product value
- ✗ No revenue from day one
- ✗ Adding payments later requires an app update and review
- **Best for:** Free utility apps, apps exploring product-market fit before monetizing, or apps monetized through other channels (ads, enterprise contracts, etc.).

-----

## Supporting Services

Three services most products want by launch, even though they aren't part of the core build: product analytics (so you can see what users do), transactional email (password resets, magic links, receipts, notifications), and error tracking (so you find crashes before users report them). Recommend the defaults below unless the product clearly needs something else, and let the founder skip any they don't want yet — each can be added later.

### Analytics

**PostHog** — Open-source product analytics suite with events, funnels, session replay, feature flags, and A/B testing.

- ✓ All-in-one: analytics, session replay, feature flags, and experiments in one tool
- ✓ Generous free tier (1M events/month); open-source and self-hostable
- ✓ Autocapture plus custom events — start getting data with minimal instrumentation
- ✓ First-class SDKs for web, React Native, and most backends
- ✗ Broad surface area can feel heavy if you only want basic metrics
- ✗ Self-hosting is real ops work — most teams use the cloud
- **Best for:** Most products. Default recommendation — the free tier and feature-flag/replay bundle are hard to beat for a solo founder.

**Mixpanel** — Mature, focused product analytics built around events, funnels, and retention.

- ✓ Best-in-class funnel, cohort, and retention analysis
- ✓ Polished, fast dashboards non-technical teammates can use
- ✓ Generous free tier (up to ~1M monthly events)
- ✗ Analytics only — no session replay, flags, or experiments (separate tools needed)
- ✗ Event taxonomy needs deliberate planning to stay clean
- **Best for:** Teams that want deep, dedicated funnel/retention analytics and don't need PostHog's wider toolkit.

### Email

**Resend** — Developer-first transactional email API from the team behind React Email.

- ✓ Clean, modern API — sending email takes minutes
- ✓ React Email for type-safe, component-based templates
- ✓ Generous free tier (3,000 emails/month); simple domain + DNS setup
- ✓ Great fit with Next.js / TypeScript stacks
- ✗ Younger than SendGrid/Postmark — smaller track record at huge scale
- ✗ Transactional-focused — not a marketing automation platform
- **Best for:** Most products' transactional email (auth, receipts, notifications). Default recommendation, especially on a TypeScript stack.

**Loops** — Email platform combining transactional sending with lightweight marketing automation.

- ✓ Transactional email plus drip campaigns, onboarding sequences, and broadcasts in one place
- ✓ Visual editor and automation loops aimed at SaaS lifecycle email
- ✓ Simple API and good defaults for founders who want marketing + transactional together
- ✗ Less of a pure-developer primitive than Resend
- ✗ Younger platform; marketing features are simpler than dedicated tools like Customer.io
- **Best for:** Founders who want both transactional and lifecycle/marketing email from one tool without wiring up two services.

### Error Tracking

**Sentry** — The standard for application error and performance monitoring.

- ✓ Captures exceptions with stack traces, breadcrumbs, and release/context tagging
- ✓ SDKs for every major frontend, backend, and mobile framework
- ✓ Performance monitoring and session tracking alongside errors
- ✓ Free tier covers a solo founder's early volume
- ✗ Quota management needs attention as traffic grows
- ✗ Full feature set is more than a tiny app strictly needs (but the defaults are sensible)
- **Best for:** Every product that ships to real users. Default recommendation — find crashes before your users tell you about them.

**None (add later)** — Skip a supporting service for the MVP.

- ✓ Fewer integrations and accounts to set up before launch
- ✗ Flying blind: no usage data, no error alerts, or manual email wiring later
- **Best for:** The earliest throwaway prototypes. For anything real, analytics and error tracking are cheap insurance — recommend at least PostHog and Sentry.

-----

## Researching Beyond This List

When a category here doesn't fit the product — or the founder asks for alternatives — run a fresh comparison:

1. **Search the current landscape** (e.g. "best [category] for [product type] [current year]") rather than relying on this file or training data alone.
2. **Shortlist 2–3 candidates** that fit the product's platform, the rest of the chosen stack, and the founder's experience level.
3. **Present them in the standard comparison format** (one-line description, ✓ pros, ✗ cons, "Best for") alongside any relevant defaults from this list, and mark a clear recommendation.
4. **Note verification dates for volatile facts** — pricing, free tiers, and acquisition status change; say "as of [date]" when quoting them.

Categories intentionally not covered here (research when relevant): hosting/deployment platforms, AI/LLM APIs, vector databases, search services, CMS, and file storage. The PRD generation step picks sensible defaults for these based on the chosen core stack. (Analytics, email, and error tracking now have first-class recommendations under Supporting Services above.)

resources/VISION-GENERATION.md

# Product Vision Generation Guide

You are generating `docs/product-vision.md` — the non-technical strategic foundation for a product. This document informs all product, business, and design decisions. It will be read by both humans and AI coding agents.

## Persona

You are a strategic advisor for early-stage tech products. You combine the skills of a brand strategist, product strategist, UX researcher, and design director. You are direct, specific, and opinionated. You don't hedge with consultant-speak — you make clear recommendations and back them up.

## Input

Read `docs/VISION.md`. This contains the founder’s answers from the Product Planner intake conversation.

## Output

Write a single markdown file: `docs/product-vision.md`

Use the exact heading structure below. Write in complete prose paragraphs — avoid bullet-point-heavy sections. Where lists are necessary (e.g. values, features), give each item a substantive explanation, not just a label.

## Tone Rules

- Write as if advising a smart founder who doesn’t need hand-holding
- Be specific and actionable — every section should contain something the founder can act on immediately
- Don’t repeat information between sections — each section adds new value
- Use the founder’s own language where they expressed something clearly. Amplify and sharpen it, don’t replace it with consultant jargon.
- Be realistic about challenges. Identify blind spots. Don’t just validate the founder’s optimism.

## Section Requirements

### 1. Vision & Mission

```markdown
# Product Vision — {productName}

## 1. Vision & Mission

### Vision Statement
### Mission Statement
### Founder's Why
### Core Values
### Strategic Pillars
### Success Looks Like
```

**Vision Statement:** One sentence describing the future state this product creates. Not what the product does — what the world looks like when it succeeds. Should be ambitious but not delusional.

**Mission Statement:** One sentence describing how the product achieves the vision. Concrete and specific to this product.

**Founder’s Why:** 2–3 paragraphs connecting the founder’s background ({creator.background}) to this problem. This is the narrative — why THIS person is building THIS thing. Use their own words from the intake where they were compelling.

**Core Values:** 3–5 values. Each MUST be specific and actionable — not “Innovation” but “Ship weekly, even if it’s small” or “Explain the why behind every design decision.” Each value gets a 2–3 sentence explanation of what it means in practice for this product.

**Strategic Pillars:** 3–4 pillars that guide major decisions. Each is a principle the team can use to resolve debates. E.g. “Speed over perfection for v1” or “The primary user’s workflow comes first, always.”

**Success Looks Like:** A vivid paragraph describing what this product and business looks like in 12 months if everything goes right. Specific numbers, specific milestones, specific feelings.

-----

### 2. User Research

```markdown
## 2. User Research

### Primary Persona
### Secondary Personas
### Jobs To Be Done
### Pain Points
### Current Alternatives & Competitive Landscape
### Key Assumptions to Validate
### User Journey Map
```

**Primary Persona:** A detailed profile of the #1 target user. Include: name, role, age range, daily routine relevant to the problem, tech comfort level, what they currently do about this problem, emotional state around the problem, what would make them switch to something new. This should feel like a real person, not a marketing abstraction.

**Secondary Personas:** 2–3 additional user types. Each gets a shorter profile (3–4 sentences) with their relationship to the primary user and the product.

**Jobs To Be Done:** Frame user needs as JTBD. Include functional jobs (what they need to accomplish), emotional jobs (how they want to feel), and social jobs (how they want to be perceived). Each job should be specific to this product.

**Pain Points:** Ranked by severity. For each: describe the pain, how frequently it occurs, what the user currently does about it, and how severe the consequences are. Be honest — if a pain point is real but minor, say so.

**Current Alternatives:** Based on {audience.currentAlternatives} from intake. For each alternative: what it is, what it does well, where it falls short for this audience, and what switching would require. Include indirect competitors and “do nothing” as an alternative.

**Key Assumptions to Validate:** 5–8 assumptions the founder is making that could be wrong. Frame as testable hypotheses: “We assume [x] because [y]. To validate: [method].” Be constructive but honest — this is where you push back on founder optimism.

**User Journey Map:** A narrative walkthrough of the primary persona’s experience from first hearing about the product through becoming a regular user. Include: awareness → consideration → first use → magic moment → habit formation → advocacy. Note emotions and friction points at each stage.

-----

### 3. Product Strategy

```markdown
## 3. Product Strategy

### Product Principles
### Market Differentiation
### Magic Moment Design
### MVP Definition
### Explicitly Out of Scope
### Feature Priority (MoSCoW)
### Core User Flows
### Success Metrics
### Risks
```

**Product Principles:** 4–6 principles that guide product decisions. These should be opinionated and specific to this product — not generic (“user-first”) but tied to the product’s unique value proposition.

**Market Differentiation:** Expand the founder’s stated differentiation ({product.marketDifferentiation}) into a full competitive narrative. Don’t just say what’s different — explain why it matters to the target user and why it’s defensible.

**Magic Moment Design:** Take the founder’s magic moment ({product.magicMoment}) and design around it. What needs to be true in the product for this moment to happen reliably? What’s the shortest path from sign-up to this moment? If the magic moment can’t happen in the MVP, the MVP scope is wrong — flag this and suggest adjustments.

**MVP Definition — In Scope:** The features that MUST be in v1. Be ruthless — the MVP should be buildable in 4–8 weeks by a solo founder using AI coding tools. For each feature: what it does, why it’s essential (tie to magic moment or core value prop), and what “done” looks like.

**Explicitly Out of Scope:** Features that are deliberately excluded from v1 with clear reasoning. This is as important as the in-scope list. For each: what it is, why it’s tempting to include, and why it’s deferred. Include a suggested timeline for when to reconsider.

**Feature Priority (MoSCoW):** Organize ALL mentioned features into Must Have, Should Have, Could Have, Won’t Have (this time). This provides a clear prioritization framework.

**Core User Flows:** 2–3 critical user flows described step-by-step. Each flow should map directly to an MVP feature. Include: trigger → steps → outcome → success criteria.

**Success Metrics:** Specific, measurable metrics aligned with {business.initialGoal}. Include: primary metric (the one number that matters most), secondary metrics, and leading indicators. Define “good” vs “great” thresholds for each.

**Risks:** 5–8 risks that could derail the product. For each: the risk, its likelihood, its impact, and a mitigation strategy. Include both market risks and execution risks.

-----

### 4. Brand Strategy

```markdown
## 4. Brand Strategy

### Positioning Statement
### Brand Personality
### Voice & Tone Guide
### Messaging Framework
### Elevator Pitches
### Competitive Differentiation Narrative
```

**Positioning Statement:** Use the format: “For [target user] who [need], [product] is the [category] that [key benefit]. Unlike [alternatives], [product] [key differentiator].”

**Brand Personality:** Expand on {feeling.brandPersonality}. Describe the personality as if it were a real person — how they’d talk in different situations, what they’d wear, what they’d never do. This becomes the reference point for all brand decisions.

**Voice & Tone Guide:** Define the voice (constant personality) and how tone shifts across contexts. Include a table with DO and DON’T examples for at least 5 contexts: onboarding, error states, empty states, success messages, marketing copy. Each example should be a complete sentence or phrase, not just an adjective.

**Messaging Framework:** Key messages for different audiences and contexts. Include: tagline, homepage headline, value propositions (3), feature descriptions, objection handlers.

**Elevator Pitches:** Three versions — 5-second (one line), 30-second (2–3 sentences), 2-minute (full story arc: problem → solution → why now → why us → ask).

**Competitive Differentiation Narrative:** Build on the founder’s own words about differentiation. Write a compelling paragraph that a founder could use in a pitch deck or investor conversation. Be specific about what competitors do, what they miss, and why this product’s approach is better.

-----

## Visual Design

Visual design — colors, typography, spacing, components, motion, design tokens — is **not** part of `product-vision.md`. It lives in `docs/design.md`, generated separately by the Design System skill from image references.

After writing `product-vision.md`, end the document with a short pointer:

```markdown
## 5. Visual Design

Visual design tokens (colors, typography, spacing, components, motion) live in `docs/design.md`. If that file does not yet exist, run the Design System skill with image references to generate it before building.
```

Do not duplicate or pre-fill design tokens here. The PRD and roadmap will reference `docs/design.md` for implementation values.

-----

## Output Structure Example

The final document should follow this header structure exactly:

```markdown
# Product Vision — {productName}

## 1. Vision & Mission
### Vision Statement
### Mission Statement
### Founder's Why
### Core Values
### Strategic Pillars
### Success Looks Like

## 2. User Research
### Primary Persona
### Secondary Personas
### Jobs To Be Done
### Pain Points
### Current Alternatives & Competitive Landscape
### Key Assumptions to Validate
### User Journey Map

## 3. Product Strategy
### Product Principles
### Market Differentiation
### Magic Moment Design
### MVP Definition
### Explicitly Out of Scope
### Feature Priority (MoSCoW)
### Core User Flows
### Success Metrics
### Risks

## 4. Brand Strategy
### Positioning Statement
### Brand Personality
### Voice & Tone Guide
### Messaging Framework
### Elevator Pitches
### Competitive Differentiation Narrative

## 5. Visual Design
(Pointer to docs/design.md — see "Visual Design" section above.)
```

resources/VISION-TEMPLATE.md

# Vision Template

`docs/VISION.md` captures all founder answers from the Product Planner intake conversation. It is the single input for document generation, and it's a plain markdown file the founder can read and edit directly.

## Document Template

Use this exact structure. Every field is a bold label followed by the answer. Multi-item fields use bullet lists.

```markdown
# Vision — {Product Name}

> Captured by the Product Planner skill. This file is the source of truth for
> generating product-vision.md, prd.md, and product-roadmap.md. Edit it directly
> and re-run the Product Planner to regenerate downstream documents.

**Created:** {ISO 8601 date}
**Updated:** {ISO 8601 date}

## Founder

- **Name:** {founder's name}
- **Expertise:** {professional background / area of expertise}
- **Background:** {their story — what led them here}

## Purpose

- **Who you help:** {target audience description}
- **Problem you solve:** {the pain point}
- **Desired transformation:** {before → after for the user}
- **Why you:** {founder-market fit narrative}

## Product

- **Name:** {product name}
- **One-liner:** {one-sentence description}
- **How it works:** {core user flow narrative}
- **Key capabilities:**
  - {capability 1}
  - {capability 2}
  - {capability 3, up to 5 total}
- **Platform:** {web | mobile | desktop | cross-platform}
- **Market differentiation:** {what makes it different}
- **Magic moment:** {the "aha" moment description}

## Audience

- **Primary user:** {detailed primary persona}
- **Secondary users:**
  - {secondary user group 1}
  - {secondary user group 2, up to 3 total}
- **Current alternatives:** {what people use today}
- **Frustrations:** {what's broken about alternatives}

## Business

- **Revenue model:** {subscription | freemium | one-time | marketplace | ad-supported | free}
- **90-day goal:** {success definition for the first 90 days}
- **6-month vision:** {where this should be in 6 months}
- **Constraints:** {time, money, skills, etc.}
- **Go-to-market:** {GTM approach}

## Brand Voice

- **Personality:** {brand personality archetype}
- **Tone of voice:** {how the product communicates, with example phrases}

> Visual identity (mood, anti-patterns, design tokens) is deliberately not
> captured here — it lives in docs/design.md, generated by the Design System
> skill from image references.

## Tech Stack

- **App type:** {web | mobile | desktop | cross-platform}
- **Frontend:** {choice} — {rationale}
- **Backend:** {choice} — {rationale}
- **Database:** {choice} — {rationale}
- **Auth:** {choice} — {rationale}
- **Payments:** {choice} — {rationale}
- **Analytics:** {choice} — {rationale}
- **Email:** {choice} — {rationale}
- **Error tracking:** {choice} — {rationale}

## Tooling

- **Coding agent:** {Claude Code | Cursor | Windsurf | GitHub Copilot | other: name}
```

## Field Rules

- **No empty fields.** If the founder skipped a question, use the AI-suggested default and note it was suggested.
- **List fields** (Key capabilities, Secondary users) must have at least 1 item. Key capabilities: 3–5 items. Secondary users: 2–3 items.
- **Enum fields** (Platform, Revenue model, App type) must use one of the listed values exactly.
- **Payments** may be `None — {rationale}` if the revenue model is "free" or monetization comes later.
- **Database** and **Auth** may be `None — {rationale}` for apps that don't need them (e.g. "App uses on-device storage only").
- **Analytics**, **Email**, and **Error tracking** are the supporting services from intake Q7.6. Defaults are PostHog, Resend, and Sentry; each may be `None — {rationale}` if the founder skipped it.
- **Created/Updated** are ISO 8601 dates. Set both on first write; bump **Updated** on every edit.
- **Section order and headings are fixed** — downstream generation navigates by heading. Don't rename, reorder, or remove sections.

## Validation

There is no validator script — validate by reading `docs/VISION.md` against this document directly:

1. All nine sections present, in order, with the exact headings above.
2. Every field label present with a non-empty answer.
3. Enum fields contain only the listed values.
4. The Field Rules above all hold.

Report every violation found, fix them in the file (asking the founder where the answer is genuinely unknown), and re-check before generating documents.

## Example (abridged)

```markdown
# Vision — InsightHub

> Captured by the Product Planner skill. This file is the source of truth for
> generating product-vision.md, prd.md, and product-roadmap.md. Edit it directly
> and re-run the Product Planner to regenerate downstream documents.

**Created:** 2026-06-11
**Updated:** 2026-06-11

## Founder

- **Name:** Sarah Chen
- **Expertise:** UX design and user research — 8 years at enterprise SaaS companies
- **Background:** I've spent nearly a decade watching enterprise software make simple tasks painful. I ran user research at two B2B SaaS companies and saw the same pattern: research insights that lived in slide decks nobody read. I want to build the tool I wished I had.

## Purpose

- **Who you help:** Product managers and UX researchers at mid-size SaaS companies (50–500 employees) who need to make user research a continuous practice
- **Problem you solve:** Research insights get trapped in documents and individual people's heads. When a PM needs to make a decision, they can't find what the team already knows — so they guess, re-run research, or skip it.
- **Desired transformation:** Product teams make every decision with confidence because user insights are organized, searchable, and connected to the features they inform.
- **Why you:** I've been the researcher whose work got ignored and the PM who couldn't find the research. I've lived both sides of this problem.

## Product

- **Name:** InsightHub
- **One-liner:** InsightHub helps product teams find and use their user research when making decisions.
- **How it works:** A researcher uploads interview notes or recordings. InsightHub extracts key insights, tags them by theme and segment, and links them to product areas. When a PM works on a feature, they search and instantly see every relevant insight.
- **Key capabilities:**
  - Automatic insight extraction from research documents and recordings
  - Semantic search across all research
  - Insight-to-feature linking
- **Platform:** web
- **Market differentiation:** Unlike Dovetail and Condens which focus on analysis workflows, InsightHub focuses on the moment of decision. It's not a research tool, it's a research memory the whole team shares.
- **Magic moment:** A PM debating a feature in a meeting searches InsightHub and finds three interview quotes that answer the question in 10 seconds.

## Audience

- **Primary user:** Maya, 32, Senior PM at a 200-person B2B SaaS company managing 3 squads. Her researchers do great work but she can never find it when she needs it.
- **Secondary users:**
  - UX Researchers who want their work to be discoverable and have impact
  - Design leads who need research context when reviewing designs
- **Current alternatives:** Dovetail (analysis-focused, expensive), Notion databases (manual, hard to search), Google Drive folders, or asking the researcher directly
- **Frustrations:** Tools are either heavyweight (Dovetail needs extensive tagging) or lightweight with no semantic understanding. The gap is between "we did the research" and "we used the research."

## Business

- **Revenue model:** subscription
- **90-day goal:** 5 paying teams, $2,000 MRR, one documented case study
- **6-month vision:** 50 paying teams, $15,000 MRR, recognized in the PM community
- **Constraints:** Building part-time (20 hrs/week). Budget $500/month. Strong on design, moderate frontend, limited backend — hence a managed backend.
- **Go-to-market:** Build in public on X and LinkedIn targeting the PM/UXR community. Product Hunt beta launch. Partner with 2–3 PM community leaders.

## Brand Voice

- **Personality:** The sharp, organized friend who always knows where to find things. Calm confidence, not flashy. Professional but warm.
- **Tone of voice:** Clear, helpful, quietly confident. Plain language, never jargon. Example error: "We couldn't find that insight — try broader search terms." Example success: "Found 12 insights across 4 studies. The most relevant are highlighted."

> Visual identity (mood, anti-patterns, design tokens) is deliberately not
> captured here — it lives in docs/design.md, generated by the Design System
> skill from image references.

## Tech Stack

- **App type:** web
- **Frontend:** Next.js — largest ecosystem, best AI coding tool support, deploys easily to Vercel
- **Backend:** Convex — real-time reactivity for team collaboration, zero backend boilerplate, TypeScript end-to-end
- **Database:** Convex Database — included with the backend, reactive queries, ACID transactions
- **Auth:** Clerk — pre-built UI components, organization/team management, generous free tier
- **Payments:** Polar — built for SaaS subscriptions, merchant of record, developer-friendly API
- **Analytics:** PostHog — free tier covers early volume, session replay and feature flags bundled in
- **Email:** Resend — transactional email for magic links and notifications, clean fit with the Next.js stack
- **Error tracking:** Sentry — catch crashes in production before users report them

## Tooling

- **Coding agent:** Claude Code
```