---
name: app-builder
description: "App scaffolding: Next.js, Vite, Nuxt, Astro, FastAPI, Django, Laravel, RN, Flutter. Triggers: scaffold, bootstrap, new project, starter, dashboard, mobile app."
effort: medium
user-invocable: false
allowed-tools: Read
---

# App Builder Skill

## Project Type Detection

| Keywords | Project Type | Primary Agents |
|----------|--------------|----------------|
| landing, website, marketing | Static Site | frontend-specialist |
| dashboard, admin, crud | Web App | frontend + backend |
| api, rest, graphql | API Only | backend-specialist |
| mobile, ios, android | Mobile App | mobile-developer |
| cli, command, terminal | CLI Tool | backend-specialist |
| game, unity, godot | Game | game-developer |
| ai, ml, rag | AI/ML | ai-engineer |
| e-commerce, shop, store | E-commerce | backend + frontend |

---

## Tech Stack Selection (2025)

### Web Applications

| Scenario | Stack |
|----------|-------|
| Full-stack, SSR | Next.js 14+ (App Router) |
| SPA with API | React + Vite |
| Vue ecosystem | Nuxt 3 |
| Static/Blog | Astro |
| E-commerce | Next.js + Medusa/Shopify |

### Mobile Applications

| Scenario | Stack |
|----------|-------|
| Cross-platform (JS team) | React Native + Expo |
| Cross-platform (any) | Flutter |
| iOS only | SwiftUI |
| Android only | Kotlin + Jetpack Compose |

### Backend/API

| Scenario | Stack |
|----------|-------|
| Node.js, edge-ready | Hono |
| Node.js, high perf | Fastify |
| Python, async | FastAPI |
| PHP, full-featured | Laravel |
| E-commerce | Magento/Sylius/PrestaShop |

### Database

| Scenario | Stack |
|----------|-------|
| General purpose | PostgreSQL |
| Serverless | Neon (PG), Turso (SQLite) |
| Document store | MongoDB |
| Vector search | PostgreSQL + pgvector |
| Cache | Redis / Upstash |

---

## Project Templates

### Next.js Full-Stack

```
project/
├── src/
│   ├── app/              # App Router
│   │   ├── (auth)/       # Auth group
│   │   ├── api/          # API routes
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/       # Shared components
│   │   └── ui/           # UI primitives
│   ├── lib/              # Utilities
│   └── server/           # Server-only code
├── prisma/               # Database schema
├── public/
├── next.config.ts
├── tailwind.config.ts
└── package.json
```

### FastAPI Backend

```
project/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── endpoints/
│   ├── core/             # Config, security
│   ├── models/           # Pydantic models
│   ├── db/               # Database
│   └── main.py
├── tests/
├── alembic/              # Migrations
├── pyproject.toml
└── Dockerfile
```

### React Native + Expo

```
project/
├── app/                  # Expo Router
│   ├── (tabs)/
│   ├── _layout.tsx
│   └── index.tsx
├── components/
├── hooks/
├── store/                # State management
├── services/             # API clients
├── app.json
└── package.json
```

---

## Design Context Gate & Pre-Flight Discipline (Web & UI Projects)

Before scaffolding UI pages, establish the design foundation to avoid generic "AI slop":

### 1. Design Context Gate
Gather 3 essential dimensions (ask once, or infer with clear stated assumptions):
- **Audience**: Who will use this? What do they care about?
- **Use Case**: What is the single primary action the page drives? (Sign up, purchase, explore, read, configure?)
- **Tone**: Pick an explicit extreme — *editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere* ("clean and modern" is not a tone).

### 2. Pre-Flight Scan (Existing Projects)
Before generating new pages or components, scan:
- **`design.md`** (or `DESIGN.md`) — if present, it is the locked design system and overrides defaults.
- **Font Stack** — inspect package dependencies and CSS imports (preserve existing font pairings).
- **Palette Tokens** — read `:root` variables, Tailwind `@theme` definitions, and OKLCH color spaces.
- **Motion Stance** — detect installed motion libraries (`framer-motion`, `motion`, `gsap`) vs motion-cut projects.
- **Framework & Spacing Scale** — conform to existing grid and spacing scale (4-pt / 8-pt).

### 3. Structural Variety & Macrostructures
Break the repetitive "Hero → 3 features → CTA → footer" template. Select a named whole-page macrostructure matched to the brief:
- **Bento Grid**: Modular irregular grid where visual rhythm comes from varying card sizes and asymmetric spans.
- **Long Document**: Literature-led, memo/journal prose format with inline section heads.
- **Marquee Hero**: The hero fills the viewport above the fold; content shifts below the fold into a list or dense grid.
- **Stat-Led**: A massive metric/number anchors the narrative; subsequent content qualifies the data.
- **Workbench**: Guided product tour with real screenshots in frames; focus on functional workflow over marketing copy.
- **Conversational FAQ**: Bold questions and honest accordion answers reading like an interview with the product.
- **Manifesto**: Large declaration typography; establishes core philosophy before presenting product.
- **Photographic / Quote-Led**: Led by primary imagery or borrowed credibility pull-quotes.

---

## Agent Coordination

### New Project Flow

```
1. project-planner     → Task breakdown & tech selection
2. database-architect  → Schema design & migrations
3. backend-specialist  → API & business logic implementation
4. frontend-specialist → UI implementation (anti-slop, 8 states)
5. test-engineer       → Unit, integration, and E2E test coverage
6. devops-implementer  → Deployment & CI/CD setup
```

### Feature Addition Flow

```
1. explorer-agent      → Understand codebase
2. project-planner     → Plan changes
3. [appropriate agent] → Implement
4. test-engineer       → Add tests
5. code-reviewer       → Review
```

---

## Common Patterns

### Authentication
- JWT for APIs
- Session for web apps
- OAuth for third-party

### State Management
- Server state: TanStack Query
- Client state: Zustand/Jotai
- Form state: React Hook Form

### Styling
- Tailwind CSS as default
- CSS Modules for isolation
- Styled Components for dynamic

### Testing
- Unit: Jest/Vitest
- E2E: Playwright
- API: Supertest

---

## Best Practices

- ✅ Start with TypeScript
- ✅ Add linting (ESLint/Biome)
- ✅ Use environment variables
- ✅ Set up CI/CD from start
- ✅ Document as you build

- ❌ Don't skip tests
- ❌ Don't hardcode config
- ❌ Don't ignore accessibility
- ❌ Don't over-engineer early

## Rules

- **MUST** confirm the stack selection with the user before scaffolding — the matrix above is a default, not a verdict
- **MUST** include `.gitignore`, `.env.example`, a README, a linter config, and a working test harness in every scaffold
- **NEVER** overwrite an existing project directory without the user's explicit go-ahead
- **NEVER** scaffold Create React App or other EOL starters — steer to Vite, Next.js, or Astro instead
- **CRITICAL**: prefer the team's existing expertise over trend-chasing. If the team ships Laravel, scaffolding FastAPI "because it's faster" creates training debt that outweighs the runtime gain.

## Gotchas

- Next.js App Router (`app/`) and Pages Router (`pages/`) can coexist technically, but middleware, layouts, and loading-state conventions diverge. Pick one router per project and never mix inside a single feature — debugging the overlap wastes hours.
- Expo Router (file-based, Expo SDK 49+) and React Navigation (imperative) use completely different navigation APIs. Tutorials mix freely; an agent copying code across the split produces uncompilable projects.
- Prisma on SQLite silently ignores features that work on Postgres: no `CHECK` constraints, no deferrable foreign keys, no array columns, limited `enum` support. Dev-on-SQLite / prod-on-Postgres teams hit this at deploy time.
- FastAPI `--reload` uses a file watcher that rebuilds Pydantic models on every edit — startup time doubles and benchmark numbers are unreliable. Disable reload for perf tests.
- `npm create vite@latest` respects `--template` but `npx create-next-app@latest` prompts interactively even with flags. Fully unattended scaffolds need `--ts --tailwind --eslint --app --src-dir --import-alias` spelled out.

## When NOT to Load

- For modifying an **existing** project's stack — use `/migrate` or `/refactor-plan`
- For adding a feature to a running app — use `/plan` and the relevant language-pattern skill (`/typescript-patterns`, etc.)
- For onboarding to an unfamiliar codebase — use `/onboard` or `/explore`
- For deciding between 2-3 specific stacks under stated constraints — use `/architecture-decision`
- For plugin or agent scaffolding inside ai-toolkit itself — use `/plugin-creator`, `/agent-creator`