mvp-scaffold

Overview

Generates a complete, production-ready project skeleton optimized for startup speed. From zero to deployable in minutes, not days.

---

1. When to Apply

| Trigger | Behavior | |---------|----------| | New project creation | Full scaffolding with interactive stack selection | | Adding a new service to monorepo | Service scaffolding within existing structure | | "scaffold", "init", "bootstrap" keywords | Activate scaffolding workflow |

---

2. Supported Stacks

Frontend

| Stack | Template | Best For | |-------|----------|----------| | Next.js 15 (App Router) | next-startup | Full-stack web app | | React + Vite | react-vite | SPA / Dashboard | | React Native (Expo) | expo-startup | Mobile-first product |

Backend

| Stack | Template | Best For | |-------|----------|----------| | Next.js API Routes | (included in next-startup) | Simple API | | FastAPI | fastapi-startup | Python / AI / Data | | Spring Boot (Kotlin) | spring-startup | Enterprise B2B | | NestJS | nest-startup | Complex Node.js API |

Database

| Choice | Setup Included | |--------|----------------| | Supabase (PostgreSQL) | Auth + DB + Storage + Realtime | | Prisma + PostgreSQL | ORM + migrations + seeding | | Drizzle + PostgreSQL | Lightweight ORM + type-safe | | MongoDB Atlas | Mongoose models + connection |

---

3. Scaffolding Flow

Phase 1: Stack Selection

1. Ask product type (web/mobile/api/full-stack)
2. Ask backend preference (or recommend based on team skills)
3. Ask database preference (or recommend based on data model)
4. Ask auth method (Supabase Auth / Clerk / NextAuth)
5. Ask deployment target (Vercel / Railway / Docker)

Phase 2: Project Generation

Next.js Startup Template Structure:

{project-name}/
├── src/
│   ├── app/
│   │   ├── layout.tsx          # Root layout with providers
│   │   ├── page.tsx            # Landing page
│   │   ├── (auth)/
│   │   │   ├── login/page.tsx
│   │   │   └── signup/page.tsx
│   │   ├── (dashboard)/
│   │   │   └── page.tsx
│   │   └── api/
│   │       └── health/route.ts # Health check endpoint
│   ├── components/
│   │   ├── ui/                 # shadcn/ui components
│   │   └── layout/
│   ├── lib/
│   │   ├── supabase.ts        # DB client
│   │   ├── utils.ts
│   │   └── constants.ts
│   └── types/
│       └── index.ts
├── prisma/                     # If Prisma selected
│   └── schema.prisma
├── public/
├── .env.example                # Environment template
├── .env.local                  # (gitignored)
├── .gitignore
├── package.json
├── tsconfig.json
├── tailwind.config.ts
├── next.config.ts
├── docker-compose.yml          # Local dev DB
├── Dockerfile                  # Production build
├── .github/
│   └── workflows/
│       └── ci.yml              # CI pipeline
├── CLAUDE.md                   # AI context
└── README.md

FastAPI Startup Template Structure:

{project-name}/
├── src/
│   ├── main.py                 # FastAPI app entry
│   ├── config.py               # Settings with pydantic
│   ├── api/
│   │   ├── __init__.py
│   │   ├── deps.py             # Dependencies
│   │   └── v1/
│   │       ├── __init__.py
│   │       └── endpoints/
│   ├── models/                 # SQLAlchemy models
│   ├── schemas/                # Pydantic schemas
│   ├── services/               # Business logic
│   └── core/
│       ├── security.py
│       └── database.py
├── tests/
├── alembic/                    # DB migrations
├── .env.example
├── pyproject.toml
├── Dockerfile
├── docker-compose.yml
├── .github/workflows/ci.yml
└── README.md

Phase 3: Essential Configurations

Always Include:

• .env.example with all required env vars (no real values)
• .gitignore with comprehensive ignore patterns
• docker-compose.yml for local development
• GitHub Actions CI pipeline (lint + test + build)
• CLAUDE.md with project context for AI assistants
• Health check endpoint (/api/health)

Phase 4: Post-Scaffold Checklist

## Setup Checklist
- [ ] Copy .env.example to .env.local and fill in values
- [ ] Run `docker-compose up -d` for local DB
- [ ] Run `npm install` / `pip install -e .`
- [ ] Run `npm run dev` / `uvicorn src.main:app --reload`
- [ ] Verify health check: http://localhost:3000/api/health
- [ ] Make your first commit

---

4. Key Principles

1. Start with Auth: Every SaaS needs login. Include it from Day 1.
2. Database Migrations: Set up migration tooling immediately.
3. CI from Start: Even a simple lint+test pipeline prevents regressions.
4. Environment Variables: Never hardcode secrets. .env.example as contract.
5. Docker for Dev: Consistent local development across team.

---

5. Tool Coordination

| Tool | Purpose | |------|---------| | Bash | npx create-next-app, pip install, docker-compose | | Write | Generate config files, boilerplate code | | Read | Check existing project files for conflicts | | Glob | Verify generated structure |

---

6. Boundaries

Will:

• Generate complete project structure with all essential configurations
• Set up auth, database, CI/CD boilerplate
• Create .env.example with all required variables
• Provide post-scaffold setup instructions

Will Not:

• Deploy the project (use deploy-pipeline skill)
• Write business logic beyond boilerplate
• Choose the stack for you (use tech-stack-advisor agent)
• Set up monitoring or observability (Phase 2 concern)