App Builder

---
name: app-builder
description: "Use when executing, coordinating, planning, or reviewing app builder agent workflows, cognitive loops, and architecture standards."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - nextjs-react-expert
  - react-specialist
  - project-idioms
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/lint_runner.js
  - .agent/scripts/verify_all.js
---

# App Builder — Application Orchestrator

## Mandatory Pre-Flight Context Inspection
Before reading, generating, or refactoring code in the `app-builder` domain, inspect these 5 critical parameters:
1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).


## Activation Boundaries
- **Activate when:** Use when executing, coordinating, planning, or reviewing app builder agent workflows, cognitive loops, and architecture standards.
- **DO NOT activate when:** The task falls outside the `app-builder` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


---

## 🛠️ Technical Architecture & Reference Recipes

## Hallucination Traps (Read First)

- ❌ Generating entire applications in one shot -> ✅ Build one module at a time, verify each
- ❌ Choosing a tech stack without asking the user -> ✅ Always ask about existing preferences, team skills, and deployment target
- ❌ Hardcoding API keys or secrets during scaffolding -> ✅ Use .env.example with placeholder values from day one

---
## When This Skill Activates

Activate when the user request involves:

- Creating a new application from scratch
- Building a major feature that spans frontend + backend + database
- Bootstrapping a project structure for a new stack

---

## Orchestration Flow

```
1. CLARIFY      → Understand what and who for
2. DECIDE       → Choose the stack
3. PLAN         → Break into ordered, dependency-aware tasks
4. COORDINATE   → Run specialists in the right sequence
5. INTEGRATE    → Verify boundaries are consistent
6. PREVIEW      → Start the dev server
```

---

## Phase 1 — Clarification

Before selecting a stack or writing a line of code, ask:

```
1. What is the core thing this app does? (not features — the primary purpose)
2. Who uses it? (internal tool, public-facing, B2B, mobile users?)
3. What constraints matter most? (time to ship, cost, performance, existing stack?)
4. What already exists that this integrates with?
```

Wait for answers. Stack decisions depend on these answers.

---

## Phase 2 — Stack Selection

|App Type|Frontend|Backend|Database|
|Content / marketing site|Next.js|Next.js API routes|PostgreSQL (if dynamic)|
|SaaS web app|Next.js|Next.js API routes / Fastify|PostgreSQL + Redis|
|Mobile app (cross-platform)|React Native (Expo)|Node.js API|PostgreSQL|
|Internal dashboard / admin|Next.js|Next.js API routes|Existing|
|Real-time (chat, collaboration)|Next.js|Fastify + WebSockets|PostgreSQL + Redis|
|Data-heavy API|—|FastAPI (Python)|PostgreSQL|
|AI assistant / RAG app|Next.js (streaming)|Fastify + LLM SDK|PostgreSQL + pgvector|
|Edge-global, latency-critical|Next.js|Hono (Cloudflare Workers)|Turso / Cloudflare KV|

**If unclear:** Next.js + PostgreSQL covers 80% of use cases and is the safest default for web apps.

---

## AI-Native App Orchestration

For RAG apps and AI assistants, the build order changes:

```
Step 1: vector-database-architect
  → Design the embedding schema and chunking strategy
  → Output: schema with vector column + indexing strategy

Step 2: ingest-pipeline (backend-specialist)
  → Build document ingestion: load → chunk → embed → store
  → Output: ingest API endpoint

Step 3: retrieval-api (backend-specialist, uses Steps 1+2)
  → Build: embed query → vector search → rerank → prompt assembly
  → Output: /api/generate endpoint with SSE streaming

Step 4: streaming-frontend (frontend-specialist, uses Step 3)
  → Build: EventSource consumer → streaming text UI → loading states
  → Output: AI chat or search interface
```

**Never wire the frontend to the LLM directly** — always proxy through your backend to keep API keys server-side.

---

## Phase 3 — Project Structure

**Web (Next.js):**

```
app/
  (auth)/       Auth pages — login, register
  (app)/        Protected app routes
  api/          API routes
components/
  ui/           Primitive components (button, input, modal)
  features/     Feature-specific components
lib/
  db/           Database client and utilities
  auth/         Auth helpers
  utils/        Shared utilities
```

**API-only (Node.js / Fastify):**

```
src/
  routes/       Route definitions (thin)
  handlers/     Request handling and response formatting
  services/     Business logic
  repositories/ Database access
  lib/          Shared utilities
```

---

## Phase 4 — Agent Coordination

Build in dependency order:

```
Step 1: database-architect
  → Design and document the schema
  → Output: SQL schema, type definitions

Step 2: backend-specialist (uses schema from Step 1)
  → Build API routes
  → Output: API endpoint spec (URL, method, request, response shapes)

Step 3: frontend-specialist (uses API spec from Step 2)
  → Build UI components
  → Connect to real API contracts
  → Output: Working pages

Step 4: test-engineer (uses all of the above)
  → Create integration and E2E tests
  → Output: Test suite
```

**Never run Step 2 against a guessed schema. Never run Step 3 against a guessed API.**

---

## Phase 5 — Integration Verification

Before presenting to the user, verify consistency:

- API endpoints the frontend calls → exist on the backend
- Database column names the backend queries → exist in the schema
- TypeScript types match across package boundaries
- Environment variables referenced in code → are in `.env.example`

---

## Phase 6 — Preview Launch

After integration verification, start the dev server:

```bash
# Check for dev script
node .agent/scripts/auto_preview.js start

# Or manually
npm run dev
```

Report the URL to the user.

---

## Template Index

|Template|Path|When to Use|
|Next.js Full-Stack|`templates/nextjs-app/`|Web app with API routes|
|React Native|`templates/react-native-app/`|Cross-platform mobile|
|API Only|`templates/api-only/`|Backend service, no UI|

---
## 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

---

### Next.js Full-Stack Structure (2025 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                       |

---

### Core Files

| File                   | Purpose                                    |
| ---------------------- | ------------------------------------------ |
| `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                            |

---

### 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
  bundler: Turbopack (Stable for Dev)

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           |

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |


## 🏛️ Tribunal Verification & Guardrails

**Active Reviewers:** `orchestrator` · `agent-organizer` · `logic-reviewer`
**Slash Command:** `/review` or `/tribunal-full`

### 🔬 Evidence Standard (Tri-State Verification)
Every finding, audit statement, or completion claim must classify its factual certainty:
- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.

### ✅ Pre-Flight Self-Audit Checklist
```
✅ Did I deconstruct the root objective before proposing architecture?
✅ Did I identify dependencies, bottlenecks, and parallelizable sub-tasks?
✅ Did I avoid over-engineering and select the simplest effective pattern?
✅ Did I verify assumptions with concrete file reads instead of speculation?
✅ Did I establish measurable verification criteria before completion?
```

### 🛑 Verification-Before-Completion (VBC) Protocol
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.