App Builder

App Builder Skill

Project Type Detection

Tech Stack Selection (2025)

Web Applications

Mobile Applications

Backend/API

Database

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