luongnv89/website-builder

Website Builder

Executes the approved implementation plan (tasks.md) to build a working improved website using Vite + React + shadcn/ui + Tailwind CSS, deployable to GitHub Pages.

When to Use

Trigger when the user asks to:

• Build a website from an implementation plan
• Implement a PRD or tasks list
• Code a Vite/React website from a spec

Do not use for design review or planning — those are upstream phases.

Prerequisites

• tasks.md (Phase 4 plan) exists and is approved
• prd.md (Phase 3 proposal) exists for alignment reference
• Node.js and npm are available
• Git is available for repository management

Tech Stack

• Build tool: Vite
• Framework: React (JSX)
• UI components: shadcn/ui
• Styling: Tailwind CSS
• Deployment: GitHub Pages (static assets)
• Serverless: no backend, no server-side runtime

Workflow

1. Read tasks.md and prd.md
2. Sync to default branch
3. Execute tasks phase by phase (landing page first)
4. Collect assets from original site as specified
5. Create new assets as specified
6. Build and verify
7. Deploy to GitHub Pages
8. Emit builder metadata

Repo Sync Before Edits (mandatory)

Before modifying any project files:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If dirty, stash first:

git stash push -u -m "website-builder: pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If origin is missing or rebase fails, stop and ask.

Step 1: Read the Plan

Read tasks.md and prd.md:

Read file <path-to-tasks.md>
Read file <path-to-prd.md>

If either is missing, ask for paths.

Step 2: Initialize Project

Create the Vite + React project:

npm create vite@latest . -- --template react
npm install
npx shadcn@latest init
npm install tailwindcss @tailwindcss/vite
npm install class-variance-authority clsx tailwind-merge lucide-react

Configure Tailwind and shadcn/ui. Set up the GitHub Pages deployment target.

Step 3: Execute Tasks Phase by Phase

Process each phase from tasks.md in order. For each task:

1. Implement the specified components/features
2. Follow the PRD for improvement alignment
3. Collect assets from the original site as specified in the plan
4. Create new assets where specified
5. Verify the build succeeds: npm run build

Phase 1: Landing Page

Build the landing/home page first. This must be independently usable:

• Hero section with headline, subtext, CTA
• Navigation
• Footer
• Responsive layout (mobile + desktop)
• Applied style from the PRD (colors, typography, spacing)

Phase 2: Core Pages

Build additional pages per the plan:

• About, features, contact, or other specified pages
• Shared components (nav, footer, buttons)
• Routing between pages

Phase 3: Optimization

Apply performance, SEO, and security improvements:

• Image optimization (compress, lazy load)
• Code splitting (Vite handles this by default)
• SEO meta tags, structured data, Open Graph tags
• Security headers via meta tags where applicable

Step 4: Asset Management

For each asset listed in tasks.md:

• [Collect]: Fetch from the original site using WebFetch or direct URL access. Save to public/assets/ or src/assets/.
• [Create]: Generate or write new assets. This includes:
  • Rewritten copy/text content
  • New component code
  • Generated SVG icons
  • Brand color values from the PRD

Step 5: Build and Verify

After all tasks are complete:

npm run build

Verify:

• Build succeeds with no errors
• Output is static assets (no server required)
• Landing page renders correctly
• All pages are accessible via routing

Step 6: Deploy to GitHub Pages

Create or update a GitHub repository for the site:

git init
git remote add origin [email protected]:<user>/<repo>.git
git add .
git commit -m "chore: initial site build"
git push -u origin main

Configure GitHub Pages:

• Repository Settings → Pages → Source: main branch, / (root)

Report the GitHub Pages URL.

Step 7: Emit Builder Metadata

Write a JSON metadata file for the final report phase:

{
  "url": "https://<user>.github.io/<repo>/",
  "timestamp": "2026-05-07T12:00:00Z",
  "tasks_completed": 12,
  "tasks_total": 12,
  "assets_collected": ["logo.png", "brand-colors.json", ...],
  "assets_created": ["cta-copy.txt", "hero-icon.svg", ...],
  "deviations": [],
  "build_output_size_kb": 450,
  "tech_stack": {
    "bundler": "vite",
    "framework": "react",
    "ui": "shadcn/ui",
    "css": "tailwindcss"
  }
}

Write to: $PROJECT_DIR/builder-metadata.json

Step Completion Reports

◆ Build Phase 1 — Landing Page
······································································
  Project initialized:    √ pass
  Landing page built:     √ pass
  Assets collected:       √ pass (<N>)
  Build succeeds:         √ pass
  ____________________________
  Result:                 PASS

◆ Build Phase 2 — Core Pages
······································································
  Pages built:            √ pass (<pages>)
  Routing configured:     √ pass
  ____________________________
  Result:                 PASS

◆ Build Phase 3 — Optimization
······································································
  Performance applied:    √ pass
  SEO applied:            √ pass
  Security applied:       √ pass
  ____________________________
  Result:                 PASS

◆ Deploy
······································································
  Repository created:     √ pass
  GitHub Pages configured: √ pass (<url>)
  Metadata emitted:       √ pass
  ____________________________
  Result:                 PASS