mvp-creator

name

mvp-creator

description

Create comprehensive MVP documentation for Rails applications. Use this skill whenever a user describes a new app idea, wants to explore a SaaS concept, needs competitor research, or is starting a new project from scratch — even if they don't explicitly say "MVP". Triggers on "I have an idea for...", "I want to build...", "help me plan...", "research competitors for...", "create a business plan for...", "design a brand for my app", "set up Claude for my Rails project", "bootstrap an app", or any request to plan, research, or document a new application concept.

MVP Creator

Create comprehensive MVP documentation for Rails applications through guided research and discovery.

Overview

This skill produces 5 deliverables for a new Rails application:

1. Research Report — Competitor analysis, market overview, feature comparison
2. MVP Business Plan — Vision, features, user flows, success metrics
3. Brand Guide — Logo, colors, typography, components, voice
4. Technical Guide — Architecture, patterns, data models, code style
5. Claude Setup — CLAUDE.md, .mcp.json, commands for Claude Desktop/Code

Workflow

Topic/Idea → Research → Discovery Questions → Generate Deliverables → Handoff to SDD

Phase 1: Research

When user provides a topic or app idea:

1. Conduct web search for 2-5 similar apps/competitors
2. Research business models, features, pricing
3. Identify market gaps and opportunities
4. Present findings and ask for feedback before proceeding

Output: Research Report (saved to docs/RESEARCH_REPORT.md)

Phase 2: Discovery Questions

After research is approved, gather project-specific information using the templates in the Discovery Question Templates section below. Do not re-list the questions here — go directly to the templates.

Ask the Core Questions first. Ask Feature Questions after research review. Ask Brand Questions just before generating the Brand Guide.

Phase 3: Generate Deliverables

Generate each deliverable sequentially. Before presenting any deliverable, run its checklist from the Quality Checklist section below. Get approval before moving to the next.

1. MVP Business Plan → docs/MVP_BUSINESS_PLAN.md
   • Template: mvp-business-plan.md
2. Brand Guide → docs/BRAND_GUIDE.md (with logo SVGs generated inline — see Logo Generation below)
   • Template: brand-guide.md
   • Reference: rails-ui-patterns.md
   • Use frontend-design skill only for UI screen mockups, not for the brand guide itself
3. Technical Guide → docs/TECHNICAL_GUIDE.md
   • Template: technical-guide.md
   • References: rails-philosophy.md, rails-implementation-patterns.md
   • If the app requires a JSON API (mobile app, external integrations): also load rails-api-patterns.md
4. Claude Setup → CLAUDE.md, .mcp.json, .claudeignore, .claude/commands/
   • Template: claude-setup.md

Phase 4: Handoff to SDD

After all deliverables are approved, always suggest:

"Your MVP foundation is ready. The natural next step is to initialize Spec-Driven Development and convert these documents into feature specs, task breakdowns, and implementation prompts for Claude Code. Start with:

'Initialize SDD using the MVP documents we created.'"

---

Technical Stack (Non-Negotiable)

All projects use this Rails stack. See rails-philosophy.md for the "why".

Component	Choice	Reference
Framework	Rails 8.x	Vanilla Rails
Frontend	Hotwire (Turbo + Stimulus)	No JS frameworks
CSS	Tailwind CSS 4	CSS-first config
Components	maquina_components	maquina.app
Database	SQLite (dev) / PostgreSQL (prod)	Solid Queue/Cache/Cable
Auth	Rails 8 built-in	Not Devise
Testing	Minitest + Fixtures	Not RSpec
Deployment	Kamal 2	Docker-based

Architecture Patterns

• Rich domain models with concerns (no service objects)
• CRUD resources for everything (no custom actions)
• State as records, not booleans
• Money as integer cents
• Turbo Morph by default, Frames sparingly

See rails-implementation-patterns.md for the "how".

---

Discovery Question Templates

Core Questions (Always Ask First)

I'd like to learn more about your app idea to create comprehensive documentation.

1. **App Name:** Do you have a name in mind? If it has meaning in another language, what does it mean?

2. **Core Problem:** In one sentence, what problem does this app solve?

3. **Target Users:** Who is the primary user? (demographics, behaviors, pain points)

4. **Region:** Any geographic focus? (affects language, payment methods, API availability)

5. **Differentiator:** What makes this different from existing solutions?

Feature Questions (After Research Review)

Based on my research, I have some feature questions:

1. **Main Sections:** What are the primary app sections/tabs?
   (e.g., Today, Transactions, Settings)

2. **Critical Flow:** What's the ONE action that must be fast and frictionless?
   (This becomes the UX we obsess over)

3. **Data Model:** What are the main things users create/track?
   (e.g., transactions, projects, bookings)

Brand Questions (Before Brand Guide)

Before I create the brand guide:

1. **Personality:** How should the app feel?
   - Professional / Playful
   - Minimal / Bold
   - Serious / Friendly

2. **Colors:** Any preferences or brand colors to incorporate?
   Or should I propose a palette based on the app's personality?

3. **Logo:** Want me to create SVG logo proposals?
   I can generate 2-3 concepts representing the app's core idea.

---

Logo Generation

Always generate logos yourself, as SVG code written inline in the Brand Guide (rather than delegating to another skill).

1. Concept first: Describe the visual metaphor before generating SVG
2. Simple shapes: Use basic geometric forms only
3. Two versions: Full logo (wordmark + icon) + standalone icon/mark
4. Monochrome requirement: Must be legible in a single color

Example approach:

The logo represents [concept]. Using [shape] to symbolize [meaning].
Primary version: [description]
Icon version: [description]

Then generate actual SVG code inline in the brand guide.

---

Interaction Patterns

Starting a New Project

User: "Help me create an MVP for a personal finance app"

Response:

1. Acknowledge the idea
2. Conduct web research (2-5 competitors)
3. Present research findings
4. Ask Core discovery questions
5. Generate deliverables sequentially with approval gates

Continuing Previous Work

User: "Let's continue with the brand guide"

Response:

1. Summarize what is known so far
2. Ask Brand Questions if not yet answered
3. Generate the brand guide
4. Ask for feedback before moving on

Specific Deliverable Request

User: "Just create a technical guide for my app called Resto"

Response:

1. Ask minimum required questions (stack preferences, locale, key features)
2. Load technical guide template and Rails references
3. Generate the technical guide
4. Save to docs/TECHNICAL_GUIDE.md

Revising a Deliverable

User: "The brand guide doesn't feel right — too corporate"

Response:

1. Acknowledge specifically what missed the mark
2. Ask 1–2 targeted questions to redirect (e.g., "What aesthetic would feel more right — can you point to an app or brand as reference?")
3. Re-generate the deliverable from scratch rather than patching it
4. Note explicitly what changed in the new version

---

Quality Checklist

Run the relevant checklist before presenting each deliverable.

Research Report

• 2-5 competitors analyzed
• Feature comparison matrix included
• Differentiation opportunities identified
• Sources cited

MVP Business Plan

• Clear problem statement
• User personas defined
• Feature set organized by section
• User flows documented
• Success metrics defined

Brand Guide

• Logo SVG code included (primary + icon), generated inline
• Full color palette with hex values
• Typography scale defined
• Component patterns documented
• Tailwind CSS @theme configuration included
• Bilingual voice examples (if applicable)

Technical Guide

• Tech stack decisions documented
• File organization defined
• Data models with relationships
• Turbo patterns specified
• I18n strategy with file structure
• Anti-patterns listed

Claude Setup

• CLAUDE.md with project context
• .mcp.json configured
• .claudeignore comprehensive
• Custom commands created
• Setup instructions included

---

Output File Structure

[project_name]/
├── docs/
│   ├── RESEARCH_REPORT.md
│   ├── MVP_BUSINESS_PLAN.md
│   ├── BRAND_GUIDE.md
│   ├── TECHNICAL_GUIDE.md
│   └── assets/
│       ├── logo.svg
│       └── logo-icon.svg
├── CLAUDE.md
├── .mcp.json
├── .claudeignore
└── .claude/
    └── commands/
        ├── test.md
        ├── db.md
        ├── analyze.md
        ├── generate.md
        └── guide.md

---

Tips

1. Show, don't tell — ground every deliverable in concrete examples from the user's own domain.
2. Bilingual by default — for a LATAM or multilingual audience, show Spanish/English examples throughout.

(The core discipline — research first, ask before assuming, one deliverable at a time with approval — is the Workflow above.)

---

Related Skills

Skill	When to Use
frontend-design	UI screen mockups and design rationale — after brand guide is approved
spec-driven-development	Implementation planning — convert MVP docs into specs and tasks
maquina-ui-standards	When building UI for Rails apps with maquina_components