app-builder

name	app-builder
description	Analyzes user's requests, determines tech stack, plans structure, and coordinates agents.

App Builder - Application Building Orchestrator

Analyzes user's requests, determines tech stack, plans structure, and coordinates agents.

🎯 Selective Reading Rule

Read ONLY files relevant to the request! Check the content map, find what you need.

File	Description	When to Read
project-detection.md	Keyword matrix, project type detection	Starting new project
tech-stack.md	2026 default stack, alternatives	Choosing technologies
agent-coordination.md	Agent pipeline, execution order	Coordinating multi-agent work
scaffolding.md	Directory structure, core files	Creating project structure
feature-building.md	Feature analysis, error handling	Adding features to existing project
templates/SKILL.md	Project templates	Scaffolding new project

---

📦 Templates (13)

Quick-start scaffolding for new projects. Read the matching template only!

Template	Tech Stack	When to Use
nextjs-fullstack	Next.js + Prisma	Full-stack web app
nextjs-saas	Next.js + Stripe	SaaS product
nextjs-static	Next.js + Framer	Landing page
nuxt-app	Nuxt 3 + Pinia	Vue full-stack app
express-api	Express + JWT	REST API
python-fastapi	FastAPI	Python API
react-native-app	Expo + Zustand	Mobile app
flutter-app	Flutter + Riverpod	Cross-platform mobile
electron-desktop	Electron + React	Desktop app
chrome-extension	Chrome MV3	Browser extension
cli-tool	Node.js + Commander	CLI app
monorepo-turborepo	Turborepo + pnpm	Monorepo

---

🔗 Related Agents

Agent	Role
project-planner	Task breakdown, dependency graph
frontend-specialist	UI components, pages
backend-specialist	API, business logic
database-architect	Schema, migrations
devops-engineer	Deployment, preview

---

Usage Example

User: "Make an Instagram clone with photo sharing and likes"

App Builder Process:
1. Project type: Social Media App
2. Tech stack: Next.js + Prisma + Cloudinary + Clerk
3. Create plan:
   ├─ Database schema (users, posts, likes, follows)
   ├─ API routes (12 endpoints)
   ├─ Pages (feed, profile, upload)
   └─ Components (PostCard, Feed, LikeButton)
4. Coordinate agents
5. Report progress
6. Start preview

---

Agent Coordination

How App Builder orchestrates specialist agents.

Agent Pipeline

┌─────────────────────────────────────────────────────────────┐
│                   APP BUILDER (Orchestrator)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     PROJECT PLANNER                          │
│  • Task breakdown                                            │
│  • Dependency graph                                          │
│  • File structure planning                                   │
│  • Create {task-slug}.md in project root (MANDATORY)             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              CHECKPOINT: PLAN VERIFICATION                   │
│  🔴 VERIFY: Does {task-slug}.md exist in project root?       │
│  🔴 If NO → STOP → Create plan file first                    │
│  🔴 If YES → Proceed to specialist agents                    │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ DATABASE        │ │ BACKEND         │ │ FRONTEND        │
│ ARCHITECT       │ │ SPECIALIST      │ │ SPECIALIST      │
│                 │ │                 │ │                 │
│ • Schema design │ │ • API routes    │ │ • Components    │
│ • Migrations    │ │ • Controllers   │ │ • Pages         │
│ • Seed data     │ │ • Middleware    │ │ • Styling       │
└─────────────────┘ └─────────────────┘ └─────────────────┘
          │                   │                   │
          └───────────────────┼───────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 PARALLEL PHASE (Optional)                    │
│  • Security Auditor → Vulnerability check                   │
│  • Test Engineer → Unit tests                               │
│  • Performance Optimizer → Bundle analysis                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     DEVOPS ENGINEER                          │
│  • Environment setup                                         │
│  • Preview deployment                                        │
│  • Health check                                              │
└─────────────────────────────────────────────────────────────┘

Execution Order

Phase	Agent(s)	Parallel?	Prerequisite	CHECKPOINT
0	Socratic Gate	❌	-	✅ Ask 3 questions
1	Project Planner	❌	Questions answered	✅ PLAN.md created
1.5	PLAN VERIFICATION	❌	PLAN.md exists	✅ File exists in root
2	Database Architect	❌	Plan ready	Schema defined
3	Backend Specialist	❌	Schema ready	API routes created
4	Frontend Specialist	✅	API ready (partial)	UI components ready
5	Security Auditor, Test Engineer	✅	Code ready	Tests & audit pass
6	DevOps Engineer	❌	All code ready	Deployment ready

🔴 CRITICAL: Phase 1.5 is MANDATORY. No specialist agents proceed without PLAN.md verification.

---

Feature Building

How to analyze and implement new features.

Feature Analysis

Request: "add payment system"

Analysis:
├── Required Changes:
│   ├── Database: orders, payments tables
│   ├── Backend: /api/checkout, /api/webhooks/stripe
│   ├── Frontend: CheckoutForm, PaymentSuccess
│   └── Config: Stripe API keys
│
├── Dependencies:
│   ├── stripe package
│   └── Existing user authentication
│
└── Estimated Time: 15-20 minutes

Iterative Enhancement Process

1. Analyze existing project
2. Create change plan
3. Present plan to user
4. Get approval
5. Apply changes
6. Test
7. Show preview

Error Handling

Error Type	Solution Strategy
TypeScript Error	Fix type, add missing import
Missing Dependency	Run npm install
Port Conflict	Suggest alternative port
Database Error	Check migration, validate connection

Recovery Strategy

1. Detect error
2. Try automatic fix
3. If failed, report to user
4. Suggest alternative
5. Rollback if necessary

---

Project Type Detection

Analyze user requests to determine project type and template.

Keyword Matrix

Keywords	Project Type	Template
blog, post, article	Blog	astro-static
e-commerce, product, cart, payment	E-commerce	nextjs-saas
dashboard, panel, management	Admin Dashboard	nextjs-fullstack
api, backend, service, rest	API Service	express-api
python, fastapi, django	Python API	python-fastapi
mobile, android, ios, react native	Mobile App (RN)	react-native-app
flutter, dart	Mobile App (Flutter)	flutter-app
portfolio, personal, cv	Portfolio	nextjs-static
crm, customer, sales	CRM	nextjs-fullstack
saas, subscription, stripe	SaaS	nextjs-saas
landing, promotional, marketing	Landing Page	nextjs-static
docs, documentation	Documentation	astro-static
extension, plugin, chrome	Browser Extension	chrome-extension
desktop, electron	Desktop App	electron-desktop
cli, command line, terminal	CLI Tool	cli-tool
monorepo, workspace	Monorepo	monorepo-turborepo

Detection Process

1. Tokenize user request
2. Extract keywords
3. Determine project type
4. Detect missing information → forward to conversation-manager
5. Suggest tech stack

---

Project Scaffolding

Directory structure and core files for new projects.

---

Next.js Full-Stack Structure (2026+ Next.js 16 Optimized)

project-name/
├── src/
│   ├── app/                        # Routes only (thin layer)
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── globals.css
│   │   ├── (auth)/                 # Route group - auth pages
│   │   │   ├── login/page.tsx
│   │   │   └── register/page.tsx
│   │   ├── (dashboard)/            # Route group - dashboard layout
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   └── api/
│   │       └── [resource]/route.ts
│   │
│   ├── features/                   # Feature-based modules
│   │   ├── auth/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── actions.ts          # Server Actions
│   │   │   ├── queries.ts          # Data fetching
│   │   │   └── types.ts
│   │   ├── products/
│   │   │   ├── components/
│   │   │   ├── actions.ts
│   │   │   └── queries.ts
│   │   └── cart/
│   │       └── ...
│   │
│   ├── shared/                     # Shared utilities
│   │   ├── components/ui/          # Reusable UI components
│   │   ├── lib/                    # Utils, helpers
│   │   └── hooks/                  # Global hooks
│   │
│   └── server/                     # Server-only code
│       ├── db/                     # Database client (Prisma)
│       ├── auth/                   # Auth config
│       └── services/               # External API integrations
│
├── prisma/
│   ├── schema.prisma
│   ├── migrations/
│   └── seed.ts
│
├── public/
├── .env.example
├── .env.local
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── README.md

---

Structure Principles

Principle	Implementation
Feature isolation	Each feature in features/ with its own components, hooks, actions
Server/Client separation	Server-only code in server/, prevents accidental client imports
Thin routes	app/ only for routing, logic lives in features/
Route groups	(groupName)/ for layout sharing without URL impact
Shared code	shared/ for truly reusable UI and utilities

---

File	Purpose
proxy.ts	Next.js 16 Network boundary logic (auth, redirects)
package.json	Dependencies
tsconfig.json	TypeScript + path aliases (@/features/*)
tailwind.config.ts	Tailwind config
.env.example	Environment template
README.md	Project documentation
.gitignore	Git ignore rules
prisma/schema.prisma	Database schema
src/server/cache-handler.ts	Next.js 16 Cache Components Manager

---

Path Aliases (tsconfig.json)

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/features/*": ["./src/features/*"],
      "@/shared/*": ["./src/shared/*"],
      "@/server/*": ["./src/server/*"]
    }
  }
}

---

When to Use What

Need	Location
New page/route	app/(group)/page.tsx
Feature component	features/[name]/components/
Server action	features/[name]/actions.ts
Data fetching	features/[name]/queries.ts
Reusable button/input	shared/components/ui/
Database query	server/db/
External API call	server/services/

---

Tech Stack Selection (2026)

Default and alternative technology choices for web applications.

Default Stack (Web App - 2026)

Frontend:
  framework: Next.js 16 (Stable)
  language: TypeScript 5.7+
  styling: Tailwind CSS v4
  state: React 19 Actions / Server Components
  caching: Next.js 16 Cache Components (Stable)
  bundler: Turbopack (Stable for Dev & Build)

Backend:
  runtime: Node.js 23
  framework: Next.js API Routes / Hono (for Edge)
  validation: Zod / TypeBox

Database:
  primary: PostgreSQL
  orm: Prisma / Drizzle
  hosting: Supabase / Neon

Auth:
  provider: Auth.js (v5) / Clerk

Monorepo:
  tool: Turborepo 2.0

Alternative Options

Need	Default	Alternative
Real-time	-	Supabase Realtime, Socket.io
File storage	-	Cloudinary, S3
Payment	Stripe	LemonSqueezy, Paddle
Email	-	Resend, SendGrid
Search	-	Algolia, Typesense

---

Generated by Agent Bridge