/web-project-kickstart

Web Project Kickstart

Guides a new web project from idea to a fully confirmed foundation — PRD, stack decision, and project scaffold — before any application code is written. Primary constraint: no application code is produced until all four steps are complete and each step is confirmed by the user.

MANDATORY WORKFLOW — Follow These Steps In Order

Steps are not optional and must not be reordered. If information is missing to complete a step, ask for the most important missing piece before proceeding. Do not ask multiple questions at once.

Step 0 — Capture the Project Brief

Confirm these inputs before anything else. If the user's message already answers all of them, proceed immediately without asking.

• What does this project do? (One sentence — the core value it delivers)
• Who is the end user? (Consumer, business, or internal team)
• What pages or screens are needed? (List every view, even roughly)
• Does it need user accounts or authentication?
• Does it need a backend and database, or is it frontend only?

If any are missing, ask for the single most important one first. Do not list all five as a form. Do not proceed to Step 1 until the scope is clear.

Step 1 — Write the PRD

Trigger: Project brief is confirmed from Step 0. This step is not optional. Action: Produce a structured PRD using the format below. Do not generate any code or scaffold until the user confirms this PRD is accurate.

Output format:

PROJECT NAME: [name]
ONE-LINE DESCRIPTION: [what it does and for whom]

PAGES / SCREENS:
- [Page name]: [purpose]
- [Page name]: [purpose]

AUTHENTICATION REQUIRED: Yes / No
BACKEND REQUIRED: Yes / No

DATA COLLECTIONS OR TABLES NEEDED:
- [Name]: [fields and types]
- [Name]: [fields and types]

KEY BUSINESS RULES:
- [Rule describing core logic, access control, or data constraint]
- [Rule describing core logic, access control, or data constraint]

Example — filled PRD:

PROJECT NAME: InvoiceFlow
ONE-LINE DESCRIPTION: A SaaS tool for freelancers to create, send,
and track client invoices.

PAGES / SCREENS:
- Landing page: marketing and sign-up CTA
- Register / Login: user authentication
- Dashboard: invoice list with status filters
- Invoice editor: create and edit invoice line items
- Trash: soft-deleted invoices with 30-day recovery

AUTHENTICATION REQUIRED: Yes
BACKEND REQUIRED: Yes

DATA COLLECTIONS OR TABLES NEEDED:
- Users: name, email, hashed password, plan (free/pro), createdAt
- Invoices: userId, clientName, lineItems[], total, status, createdAt
- Trash: invoiceId, userId, deletedAt

KEY BUSINESS RULES:
- Free plan users are limited to 5 active invoices
- Trash items are permanently deleted after 30 days automatically
- Only the invoice owner can view, edit, or delete their invoices

Wait for user confirmation before proceeding to Step 2.

Step 2 — Decide the Tech Stack

Trigger: PRD confirmed by user. This step is not optional. Action: Apply the decision rules below and recommend the exact stack. Output: Named stack with one-line justification per choice.

Stack decision rules:

Frontend: always React with Next.js and a utility-first CSS framework. Why: Next.js handles routing, server-side rendering, and image optimization out of the box — this eliminates setup decisions that slow early progress.

Backend (when required): Node.js with Express. Why: pairs fastest with AI-assisted development, JSON handling is native, and integrates cleanly with document databases.

Database — apply this rule:

• Complex multi-table relationships, financial transactions, e-commerce → SQL (PostgreSQL)
• Flexible documents, user profiles, content-heavy apps, fast iteration → NoSQL (MongoDB)
• Default when unsure → MongoDB, because AI models parse JSON document models faster than SQL schemas, speeding up iteration.

Hosting:

• Frontend → Vercel
• Backend → a VPS provider that supports hosting multiple domains on one server
• Database → managed cloud database (MongoDB Atlas or equivalent)

Output format:

STACK DECISION
Frontend:  Next.js + Tailwind CSS
Backend:   Node.js + Express       ← omit this line if frontend-only
Database:  MongoDB                 ← omit this line if frontend-only
Hosting:   Vercel (frontend) + VPS (backend) + MongoDB Atlas (database)

JUSTIFICATIONS:
- Next.js: [one sentence specific to this project's needs]
- MongoDB: [one sentence on why document model fits this project's data]

Wait for user confirmation before proceeding to Step 3.

Step 3 — Define the Project Scaffold

Trigger: Stack confirmed by user. This step is not optional. Action: Produce the project folder plan and global style token structure. Output: Folder plan with one-line purpose per folder, plus CSS token map.

Full-stack scaffold:

project-root/
├── .gitignore
├── frontend/
│   ├── public/
│   │   ├── branding/       ← logos, SVGs, brand assets
│   │   └── fonts/          ← custom font files
│   └── src/
│       ├── components/
│       │   ├── ui/         ← reusable: Button, Input, Modal, Card
│       │   ├── auth/       ← Login, Register, PasswordRecovery
│       │   └── dashboard/  ← Sidebar, DataGrid, StatsCard, NavBar
│       ├── styles/
│       │   └── global.css  ← all CSS root variables declared here
│       ├── services/       ← API call functions only — no DB calls here
│       └── app/            ← routing
└── backend/
    └── src/
        ├── models/         ← database schemas
        ├── controllers/    ← business logic per resource
        ├── routes/         ← path declarations and HTTP method mapping
        ├── middleware/     ← auth, CORS, rate limiting, error handling
        └── services/       ← external utilities: email, PDF, scheduled jobs

Frontend-only scaffold (when no backend needed):

project-root/
├── .gitignore
├── public/
│   ├── branding/
│   └── fonts/
└── src/
    ├── components/
    │   └── ui/
    ├── styles/
    │   └── global.css
    ├── services/           ← external API calls only
    └── app/

CSS token starter (global.css):

:root {
  --primary:        [replace with brand hex];
  --primary-hover:  [replace with hover variant];
  --accent:         [replace with vibrant CTA color];
  --background:     [replace with page background];
  --surface:        [replace with card/panel background];
  --border:         [replace with divider color];
  --foreground:     [replace with primary text color];
  --muted:          [replace with secondary text color];
  --danger:         #ef4444;
  --success:        #22c55e;
  --radius-sm:      8px;
  --radius-md:      12px;
  --radius-lg:      20px;
}

After the user confirms the scaffold, application code may begin.

Decision Table

Anti-Patterns