Phased Development

Buildpad applications follow a mandatory 6-phase development methodology. Every app — regardless of size — is built incrementally through phases with clear deliverables and validation checkpoints. The AI agent uses this structure to plan and track all development work.

The /create-project skill sets up your Phase 0 foundation automatically. Use /start-phase [number] in your AI IDE to begin or continue any phase.

The 6 Phases

Phase	Name	Focus	Exit Criteria
0	Foundation	Project setup, auth, test infrastructure	App runs, tests configured
1	Data Foundation	Schema, API routes, types	All APIs tested
2	Core UI	List/detail pages, forms, navigation	Pages render, tests pass
3	Business Logic	Validation, workflows, permissions	Rules enforced
4	Relations	M2O, M2M, O2M, files, search	Relations work
5	Polish	Errors, performance, a11y, docs, E2E	Production ready

Phase Rules

Complete each phase before moving to the next — no skipping
Tests are part of each phase — not a separate activity
Document as you go — not at the end
Validate with the phase gate checklist — all deliverables checked before proceeding
Track progress in PHASES.md — single source of truth

Phase 0: Foundation

Phase 0 is the starting point for every app. It establishes the infrastructure everything else depends on. The /create-project skill handles this automatically and covers:

Deliverable	What it does
Next.js app scaffold	TypeScript, Mantine v8, Buildpad components installed via CLI
Environment config	`.env.local` with Supabase and DaaS backend URLs
DaaS CORS config	Allowlists your localhost and deployed URLs
Auth wiring	`DaaSProviderWrapper`, login/logout/callback proxy routes
Authenticated layout	`app/(authenticated)/layout.tsx` with scoped DaaS provider
Test infrastructure	Playwright (E2E) and Vitest (unit) configured
`PHASES.md`	Progress tracker file created at project root

Exit criteria: pnpm dev runs, the sign-in page loads, and at least one smoke test passes.

How `PHASES.md` Works

Every generated project includes a PHASES.md file at the root. The agent reads and updates this file as you progress through phases. It tracks:

Which phase is currently in progress
Which deliverables are complete (checkbox list)
Exit criteria status per phase

Check PHASES.md after each tutorial to see where you are.

Using `/start-phase`

To begin or continue a phase, open the AI chat in your IDE and type:


/start-phase 1

The agent will:

Read your current PHASES.md to check progress
Verify the previous phase’s exit criteria are met
List all deliverables for the requested phase with checkboxes
Implement each deliverable in sequence with tests
Update PHASES.md on completion

The agent enforces phase gates — it will flag incomplete exit criteria before letting you skip ahead. This is intentional: skipping phases leads to broken foundations that compound across later phases.

Why Phased Development

Building entire applications at once leads to untestable code, missed requirements, and hard-to-debug foundations. The phased approach ensures:

Working software at each checkpoint — every phase produces a runnable, testable increment
Catch mistakes early — foundation issues surface in Phase 0, not Phase 4
AI accuracy — the agent can reason about a bounded phase scope much more reliably than an entire application at once
Predictable progress — PHASES.md gives you and your team a shared view of where the project stands

Pair this with Specs-Driven Development — specs decide what gets built, phases govern how it gets built incrementally.

Specs-Driven Development — Plan requirements, design, and tasks before any code is written
AI IDE Setup — Download your starter project and configure MCP connections
Tutorial 1: Your First App — Walk through Phase 0 end-to-end