When: Need formal test suite (optional) Scope: E2E tests, integration tests Files: Test files Duration: 3-6 hours Verification: Tests pass, coverage meets threshold
Phase Validation Rules
Every phase you generate MUST follow these constraints:
Context-Safe Sizing
Max files: 5-8 files touched per phase
Max dependencies: Phase shouldn't require deep understanding of >2 other phases
Max duration: Implementation + verification + fixes should fit in one 2-4 hour session
Required Elements
Every phase MUST have:
Type - Infrastructure / Database / API / UI / Integration / Testing
Estimated duration - In hours (and minutes of human time)
Files - Specific files that will be created/modified
Task list - Ordered checklist with clear actions
Verification criteria - Checkbox list of tests to confirm phase works
Exit criteria - Clear definition of "done"
Verification Requirements
API phases: Test all HTTP status codes (200, 400, 401, 404, 500)
UI phases: Test user flows, form validation, error states
Database phases: Test CRUD, constraints, relationships
Integration phases: Test service connectivity, webhooks, error handling
Auto-Split Logic
If a phase violates sizing rules, automatically suggest splitting:
⚠️ Phase 4 "Complete User Management" is too large (12 files, 8-10 hours).
Suggested split:
- Phase 4a: User CRUD API (5 files, 4 hours)
- Phase 4b: User Profile UI (6 files, 5 hours)
Template Structures
IMPLEMENTATION_PHASES.md Template
# Implementation Phases: [Project Name]
**Project Type**: [Web App / Dashboard / API / etc]
**Stack**: Cloudflare Workers + Vite + React + D1
**Estimated Total**: [X hours] (~[Y minutes] human time)
---
## Phase 1: [Name]
**Type**: [Infrastructure/Database/API/UI/Integration/Testing]
**Estimated**: [X hours]
**Files**: [file1.ts, file2.tsx, ...]
**Tasks**:
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
- [ ] Test basic functionality
**Verification Criteria**:
- [ ] Specific test 1
- [ ] Specific test 2
- [ ] Specific test 3
**Exit Criteria**: [Clear definition of when this phase is complete]
---
## Phase 2: [Name]
[... repeat structure ...]
---
## Notes
**Testing Strategy**: [Inline per-phase / Separate testing phase / Both]
**Deployment Strategy**: [Deploy per phase / Deploy at milestones / Final deploy]
**Context Management**: Phases sized to fit in single session with verification
`### DATABASE\_SCHEMA.md Template`
# Database Schema: [Project Name]
**Database**: Cloudflare D1
**Migrations**: Located in `migrations/`
**ORM**: [Drizzle / Raw SQL / None]
---
## Tables
### `users`
**Purpose**: User accounts and authentication
| Column | Type | Constraints | Notes |
|--------|------|-------------|-------|
| id | INTEGER | PRIMARY KEY | Auto-increment |
| email | TEXT | UNIQUE, NOT NULL | Used for login |
| created_at | INTEGER | NOT NULL | Unix timestamp |
**Indexes**:
- `idx_users_email` on `email` (for login lookups)
**Relationships**:
- One-to-many with `tasks`
---
### `tasks`
[... repeat structure ...]
---
## Migrations
### Migration 1: Initial Schema
**File**: `migrations/0001_initial.sql`
**Creates**: users, tasks tables
### Migration 2: Add Tags
**File**: `migrations/0002_tags.sql`
**Creates**: tags, task_tags tables
---
## Seed Data
For development, seed with:
- 3 sample users
- 10 sample tasks across users
- 5 tags
`### API\_ENDPOINTS.md Template`
# API Endpoints: [Project Name]
**Base URL**: `/api`
**Auth**: Clerk JWT (custom template with email + metadata)
**Framework**: Hono (on Cloudflare Workers)
---
## Authentication
### POST /api/auth/verify
**Purpose**: Verify JWT token
**Auth**: None (public)
**Request**:
```json
{
"token": "string"
}
Authentication: Clerk JWT with custom claims
Authorization: Middleware checks user ownership before mutations
Input Validation: Zod schemas on client AND server
CORS: Restricted to production domain
Secrets: Environment variables in wrangler.jsonc (not committed)
### UI\_COMPONENTS.md Template (Enhanced with Phase-Aligned Installation)
**Use when**: Project uses shadcn/ui OR needs component planning
UI Components: [Project Name]
Framework: shadcn/ui + Tailwind v4
Installation: Components copied to @/components/ui (fully customizable)
Strategy: Install components as needed per phase (not all upfront)
Installation Strategy: By Phase
Phase [N]: [Phase Name] ([X] components)
When: During [description of when this phase happens]
Components:
button - [specific use cases in this phase]
input - [specific use cases]
card - [specific use cases]
[... list all components for this phase ...]
Current Phase: Phase 0 (Planning)
Current Stage: Planning
Last Checkpoint: None yet
Planning Docs: `docs/IMPLEMENTATION_PHASES.md`, `docs/CRITICAL_WORKFLOWS.md` (if exists)
Phase 0: Planning ✅
Completed: [YYYY-MM-DD]
Summary: Planning docs created
Deliverables: [List generated docs]
Phase 1: [Name] ⏸️
Spec: `docs/IMPLEMENTATION_PHASES.md#phase-1`
Type: [Infrastructure/Database/API/UI/Integration]
Time: [X hours]
Progress: Not started
Next Action: [Specific file + line + what to do]
Phase 2: [Name] ⏸️
Spec: `docs/IMPLEMENTATION_PHASES.md#phase-2`
Type: [Type]
Time: [X hours]
Progress: Not started
[Collapse remaining phases to 2-3 lines each...]
Critical Reminders
Before Starting:
Read `docs/CRITICAL_WORKFLOWS.md` (if exists)
Review `docs/INSTALLATION_COMMANDS.md` for phase commands
Check `docs/ENV_VARIABLES.md` for required secrets
Critical Workflows:
[Link to specific workflows from CRITICAL_WORKFLOWS.md, if exists]
Known Risks
High-Risk Phases:
Phase [N]: [Name] - [Why risky]
Phase [N+1]: [Name] - [Why risky]
Mitigation: [Strategy]
Status Legend: ⏸️ Pending | 🔄 In Progress | ✅ Complete | 🚫 Blocked | ⚠️ Issues
* * *
## File-Level Detail in Phases
**Purpose**: Help Claude navigate code with file maps, data flow diagrams, and gotchas.
**Include for**: API, UI, Integration phases (optional for Infrastructure, Database, Testing)
### File Map Example