app-builder

# 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](templates/nextjs-fullstack/TEMPLATE.md) | Next.js + Prisma | Full-stack web app | | [nextjs-saas](templates/nextjs-saas/TEMPLATE.md) | Next.js + Stripe | SaaS product | | [nextjs-static](templates/nextjs-static/TEMPLATE.md) | Next.js + Framer | Landing page | | [nuxt-app](templates/nuxt-app/TEMPLATE.md) | Nuxt 3 + Pinia | Vue full-stack app | | [express-api](templates/express-api/TEMPLATE.md) | Express + JWT | REST API | | [python-fastapi](templates/python-fastapi/TEMPLATE.md) | FastAPI | Python API | | [react-native-app](templates/react-native-app/TEMPLATE.md) | Expo + Zustand | Mobile app | | [flutter-app](templates/flutter-app/TEMPLATE.md) | Flutter + Riverpod | Cross-platform mobile | | [electron-desktop](templates/electron-desktop/TEMPLATE.md) | Electron + React | Desktop app | | [chrome-extension](templates/chrome-extension/TEMPLATE.md) | Chrome MV3 | Browser extension | | [cli-tool](templates/cli-tool/TEMPLATE.md) | Node.js + Commander | CLI app | | [monorepo-turborepo](templates/monorepo-turborepo/TEMPLATE.md) | 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) ```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) ```yaml 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](https://github.com/HaoNgo232/agent-bridge)*