zai-org/glmv-prd-to-app

GLM-V PRD-to-App: Full-Stack Application Builder

Language: Respond in the same language the user uses. Code comments should match.

Build a complete, deployed web application from PRD + prototypes + resources. The result must be fully reproducible via a single bash /workspace/start.sh.

---

Phase 0: Material Discovery & Analysis

Before anything else, understand what you're working with.

0a. Locate all inputs

/workspace/prd.md              ← Product requirement document
/workspace/prototypes/*.jpg    ← UI prototype images (the visual truth)
/workspace/resources/**/*      ← Images, videos, icons, and other assets

If the materials are in a different location, adapt accordingly. Read the PRD fully.

0b. Deep prototype analysis

For every prototype image:

1. Read each image using the Read tool — you are multimodal, examine them directly.

2. For each image, document:

   • Page identity: which page/view this represents
   • Layout structure: header, sidebar, main content, footer, modals
   • Component inventory: every button, form, card, table, list, nav element
   • Content inventory: all visible text, numbers, labels, placeholder content
   • Color extraction: primary, secondary, accent, background, text colors (hex values)
   • Typography: font sizes, weights, hierarchy observed
   • Interactive states: hover effects, active tabs, selected items, toggles
   • Data patterns: what data populates lists/tables/cards — this drives seed data

3. Build a page map showing navigation flow between prototype pages.

0c. Resource inventory

List all files in /workspace/resources/ and map each to where it appears in the prototypes. Every resource file must be used in the final application where relevant.

---

Phase 1: System Design Document

Produce a comprehensive design document at /workspace/docs/design.md.

1a. Data Model

For each entity, specify:

• Table/collection name
• All fields with types, constraints, defaults
• Relationships (foreign keys, many-to-many)
• Indexes needed for query patterns
• Content mapping: which prototype elements map to which fields

Example:

products table:
  id          SERIAL PRIMARY KEY
  name        VARCHAR(200) NOT NULL    ← from product card title
  price       DECIMAL(10,2) NOT NULL   ← from product card price label
  image_url   TEXT NOT NULL             ← from product card image
  category_id INTEGER REFERENCES categories(id) ← from category filter
  ...

1b. API Design

For every page interaction, define an API endpoint:

• Method + path
• Request params/body schema
• Response schema with example
• Which prototype interaction triggers this API
• Error responses

1c. Frontend Architecture

• Component hierarchy (tree structure)
• Route definitions mapping to prototype pages
• State management approach
• How each prototype page maps to components

1d. Technology Stack

Choose based on PRD complexity. Recommended defaults:

| Layer | Choice | When to use | |-------|--------|-------------| | Frontend | React + TypeScript + Vite | Default for SPAs | | Frontend | Next.js | If SSR/SEO needed | | Styling | Tailwind CSS | Default | | Backend | Node.js + Express | Simple APIs | | Backend | Python + FastAPI | If PRD mentions Python | | Database | SQLite | Simple apps, <10 tables | | Database | PostgreSQL | Complex apps, relationships | | ORM | Prisma (Node) / SQLAlchemy (Python) | Match backend |

Document the choice and reasoning.

1e. Directory Structure

/workspace/
├── frontend/          ← or client/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/   ← API client
│   │   ├── types/
│   │   └── assets/     ← copied from /workspace/resources
│   └── ...
├── backend/           ← or server/
│   ├── src/
│   │   ├── routes/
│   │   ├── models/
│   │   ├── controllers/
│   │   ├── middleware/
│   │   └── seed/
│   └── ...
├── docs/
│   ├── design.md
│   └── README.md
├── start.sh
└── prd.md

---

Phase 2: Seed Data Generation

Seed data is critical — it makes the app look real from the first launch.

Rules

1. Extract from prototypes: Every piece of visible text, image, number in the prototype images must appear in seed data. Read each prototype image again and transcribe content.

2. Complete coverage:

   • Every list/table must have the exact number of items shown in prototypes
   • Every card must have the content matching the prototype
   • Every dropdown must have options matching the prototype
   • Navigation items must match prototype navigation
   • Statistics/counters must match prototype numbers

3. Use resource files: Map resource files (images, videos, icons) from /workspace/resources/ to seed data entries. Use relative paths or copy to public/static dir.

4. No placeholders: No "Lorem ipsum", no "Test Item 1", no placeholder.com images.

5. Support all states: Include data that exercises empty states, loaded states, error scenarios as specified in the PRD.

Output

Save seed data as:

• SQL seed files, or
• JSON fixtures, or
• ORM seed scripts

Place in /workspace/backend/src/seed/ (or equivalent).

---

Phase 3: Backend Implementation

3a. Database schema

• Create migration files for all tables
• Include proper constraints, indexes, foreign keys
• Run migrations to verify they work

3b. API endpoints

For each endpoint from the design doc:

1. Implement route handler
2. Add input validation (validate types, required fields, ranges)
3. Add error handling with proper HTTP status codes
4. Test with curl or equivalent to verify response format

3c. Seed data loading

• Implement a seed script that:
  • Clears existing data (for idempotent re-seeding)
  • Inserts all seed data in correct dependency order
  • Copies resource files to the correct static serving location
• Verify seed data loads without errors

3d. Static file serving

• Configure the backend to serve resource files (images, videos, etc.)
• Ensure frontend can access them via proper URLs

---

Phase 4: Frontend Implementation

This is where visual fidelity matters most. The prototypes are the definitive reference.

4a. Global styles and tokens

Before building components, establish:

• Color variables matching prototype colors
• Typography scale matching prototype fonts
• Spacing/sizing system matching prototype spacing
• Common component styles (buttons, cards, inputs, etc.)

4b. Page-by-page implementation

For each prototype image, in order:

1. Re-read the prototype image — keep it fresh in your context
2. Build the page component matching the layout exactly:
   • Match spacing and proportions
   • Match colors and typography
   • Match visual hierarchy
   • Match content placement
3. Wire up API calls to the backend
4. Implement all interactions visible or implied:
   • Navigation between pages
   • Form submissions
   • Search and filter
   • Sorting
   • Modals and dialogs
   • Loading states
   • Error states
   • Hover effects
   • Active/selected states

4c. Resource integration

• Copy all resources from /workspace/resources/ to frontend assets
• Reference them correctly in components
• Ensure images render at proper sizes matching prototypes

4d. Responsive considerations

• Match the viewport width shown in prototypes
• If prototypes show mobile views, implement responsive breakpoints

---

Phase 5: Visual Verification Loop

This phase is what separates a good implementation from a great one. Repeat this loop for every page.

5a. Render the page to a screenshot

Use Playwright to capture the running application:

python ${SKILL_DIR}/scripts/render_page.py \
  --url "http://localhost:3000/page-path" \
  --output "/workspace/docs/screenshots/page_name.png" \
  --width 1280

5b. Visual comparison

Read both images (prototype and screenshot) side by side:

1. Read the prototype image from /workspace/prototypes/
2. Read the rendered screenshot
3. Compare systematically:
   • Layout: Are sections in the right positions?
   • Colors: Do colors match?
   • Typography: Are font sizes/weights correct?
   • Content: Is all prototype content present?
   • Spacing: Are margins and paddings close?
   • Images: Are all images rendering?
   • Components: Are all UI components present and correct?

5c. Fix discrepancies

For each difference found:

1. Identify the specific CSS/component change needed
2. Apply the fix
3. Re-render and re-compare

5d. Repeat until satisfied

Max 3 iterations per page. Focus on the most impactful differences first.

---

Phase 6: Integration Testing

6a. API health check

Run the API health checker to verify all endpoints:

python ${SKILL_DIR}/scripts/check_api.py \
  --base-url "http://localhost:3000/api" \
  --endpoints-file "/workspace/docs/endpoints.json"

Or manually test each endpoint with curl:

curl -s http://localhost:3000/api/products | head -c 200

6b. End-to-end flow verification

Walk through every user flow defined in the PRD:

1. Open the app at http://localhost:3000
2. Navigate to each page
3. Test each interactive feature
4. Verify data loads from the database
5. Verify forms submit correctly
6. Verify search/filter/sort work

6c. Fix any issues found

Address integration issues: CORS, API URL mismatches, data format mismatches, etc.

---

Phase 7: Deployment Script

Generate /workspace/start.sh — the single command that makes everything work from scratch.

Requirements

The script must:

1. Be fully self-contained — no prior setup assumed
2. Work in a fresh environment
3. Install all system dependencies (Node.js, Python, DB, etc.)
4. Clean any previous state
5. Set up the database from scratch
6. Run all migrations
7. Load all seed data
8. Build the frontend (if needed)
9. Start both backend and frontend
10. Make the app available at http://localhost:3000

Template

#!/bin/bash
set -e

echo "=== PRD-to-App: Starting deployment ==="

# 1. System dependencies
echo "[1/7] Checking system dependencies..."
# Install Node.js, npm, etc. if missing
# Install database if needed

# 2. Backend setup
echo "[2/7] Setting up backend..."
cd /workspace/backend
npm install  # or pip install -r requirements.txt

# 3. Database initialization
echo "[3/7] Initializing database..."
# Drop existing DB / reset
# Run migrations
# Load seed data

# 4. Frontend setup
echo "[4/7] Setting up frontend..."
cd /workspace/frontend
npm install

# 5. Copy resources
echo "[5/7] Copying resource files..."
# cp -r /workspace/resources/* /workspace/frontend/public/assets/

# 6. Start backend
echo "[6/7] Starting backend server..."
cd /workspace/backend
npm run dev &   # or equivalent
BACKEND_PID=$!

# 7. Start frontend
echo "[7/7] Starting frontend..."
cd /workspace/frontend
PORT=3000 npm run dev &
FRONTEND_PID=$!

echo ""
echo "=== Application is running at http://localhost:3000 ==="
echo "Backend PID: $BACKEND_PID"
echo "Frontend PID: $FRONTEND_PID"
echo "To stop: kill $BACKEND_PID $FRONTEND_PID"

wait

Verification

After generating start.sh:

1. chmod +x /workspace/start.sh
2. Run it: bash /workspace/start.sh
3. Wait for startup
4. Verify http://localhost:3000 responds
5. Spot-check a few API endpoints
6. Fix any startup issues

---

Phase 8: Documentation

8a. Software Design Document (/workspace/docs/design.md)

Already created in Phase 1 — update with any changes made during implementation:

• Final system architecture
• Final data model (with any fields added during dev)
• Technology stack
• Deployment architecture
• API reference

8b. README (/workspace/README.md)

# [Project Name]

## Overview
[From PRD product overview]

## Technology Stack
- Frontend: ...
- Backend: ...
- Database: ...

## Quick Start
\`\`\`bash
bash start.sh
\`\`\`
Then visit http://localhost:3000

## Project Structure
[Directory tree]

## Database
[Schema overview, how to re-seed]

## API Reference
[Key endpoints]

---

Deliverables Checklist

Before declaring done, verify every item:

• [ ] All PRD features implemented — no features skipped
• [ ] All prototype pages built — no pages merged or omitted
• [ ] Visual match with prototypes — verified via screenshot comparison
• [ ] All resource files used where they appear in prototypes
• [ ] Seed data matches prototype content exactly
• [ ] All API endpoints working and returning correct data
• [ ] All interactive elements functional (forms, search, filters, modals, navigation)
• [ ] bash /workspace/start.sh works from a clean state
• [ ] App accessible at http://localhost:3000
• [ ] Design document complete
• [ ] README with deployment instructions

---

Critical Principles

1. Prototypes are truth — when PRD text and prototype images conflict, the prototype wins for visual/layout decisions.

2. No shortcuts on data — every piece of content visible in prototypes must come from the database via APIs. No hardcoded data in frontend components.

3. Complete implementation — every page, every feature, every interaction. Don't skip "minor" features. Don't merge separate pages into one.

4. Resources must be used — if the prototype shows an image and a matching file exists in /workspace/resources/, use that file. Don't substitute with placeholder URLs.

5. Reproducibility — start.sh must work from absolute zero. If it needs Node 18+, it installs Node 18+. If it needs PostgreSQL, it sets up PostgreSQL.

6. Verify, don't assume — use the visual verification loop (Phase 5) to actually compare your output against prototypes. Use API checks to verify endpoints. Run start.sh to verify deployment.