Project Delivery

This is a Hybrid skill. Primary type: Gatekeeper. Secondary type: Generation. Runs a mandatory pre-launch audit across visual QA, security, infrastructure, and code quality — then generates missing documentation and handoff materials. Primary constraint: nothing ships until every CRITICAL and HIGH item is resolved. Medium items must be documented if deferred. Low items are noted.

Standard Finding Format

Every issue found must use this exact format. No exceptions.

[SEVERITY] | [Category] | [What is wrong] | [Risk if unaddressed] | [Exact fix]

Example:

CRITICAL | Security | JWT access token stored in localStorage | XSS scripts can steal
the token and gain full account access | Move to React state or Context — never localStorage

Severity Calibration:

Level	Definition	Blocks launch?
CRITICAL	Data breach, credential exposure, or app-breaking bug	Yes — must fix first
HIGH	Meaningful production risk or broken user flow	Yes — fix before launch
MEDIUM	Suboptimal but acceptable with documented risk	No — document and defer
LOW	Polish or nice-to-have improvement	No — optional

MANDATORY AUDIT WORKFLOW — Run In Order

This workflow is not optional. Do not skip sections. Do not deliver until all CRITICAL and HIGH findings are resolved or confirmed fixed by the user.

Audit 1 — Security Gate

Check these in order. Flag every issue found using the standard finding format.

1.1 Secrets & Credentials:

.env is in .gitignore — confirm no secrets are in any committed file
No hardcoded API keys, DB URIs, or JWT secrets in source code
Production env vars set in hosting dashboard — not uploaded as .env file

1.2 Authentication:

JWT access tokens stored in React state/Context — NOT in localStorage
Refresh tokens set by backend in HttpOnly cookies — NOT accessible to JS
Password hashed with bcrypt — no plaintext stored in database
Protected routes redirect unauthenticated users to /login

1.3 Database & API Security:

MongoDB Atlas / database IP whitelist contains production server IP only — NOT 0.0.0.0/0
CORS origin set to exact production domain — NOT wildcard *
All database queries filtered by userId — no cross-user data leakage
Direct DB connections from frontend: none

1.4 Error Handling:

Global error middleware registered — server never returns raw stack traces
All controllers wrapped in try-catch with next(err) pattern

Audit 2 — Visual & Frontend QA

2.1 Responsive Layout:

Desktop sidebar collapses to drawer on mobile — not inline-shrink
Multi-column grids stack vertically on mobile — no overflow or clipping
All text is legible at mobile viewport — no clipped labels or truncated headings

2.2 UI Polish:

All interactive elements have cursor: pointer
All animations use ease-in-out — no linear transitions
No hardcoded hex values in component files — all mapped to CSS variables
Modals and drawers slide in/out smoothly — no sudden snaps

2.3 Hydration & Performance:

No Next.js hydration warnings in console — server/client output matches
Heavy components use dynamic imports with loading skeletons
All images use Next.js <Image /> with explicit dimensions
No infinite useEffect loops — all dependency arrays defined

2.4 Puppeteer Visual QA (recommended): Run a Puppeteer script that navigates key views and captures screenshots across Mobile (375px), Tablet (768px), and Desktop (1280px) viewports. Feed screenshots to AI for self-correction of layout bugs before launch.

Audit 3 — Infrastructure & Deployment

3.1 Git & Repository:

Repository is private — never public for client work
.gitignore blocks: .env, .env.local, node_modules/, dist/, .next/, .cursor/, .vscode/
Frontend and backend in separate root directories

3.2 Hosting Configuration:

Frontend deployed to Vercel — build succeeds with no errors
Backend deployed to Kloudbean or equivalent VPS
Backend port mapped correctly to hosting provider's assigned port
All environment variables set in hosting dashboard

3.3 Database:

Production database separate from development database
Database IP whitelist updated to production server IP
Database connection tested from production environment

3.4 Common Post-Launch Pitfalls — verify none are present:

Authenticated users hitting /login are not redirected to dashboard
API calls from production frontend use production NEXT_PUBLIC_API_URL (not localhost)
PDF generation uses shared persistent Puppeteer instance — not one Chromium process per request

Audit 4 — Code Quality Gate

4.1 TypeScript:

No any types in codebase — all payloads and models have interfaces
TypeScript build compiles without errors (tsc --noEmit)

4.2 Component Architecture:

No duplicated component code — shared elements abstracted to components/ui/
No database calls from React component files — all through services/

4.3 CSS Architecture:

All colors in component files reference CSS root variables
global.css contains complete variable map for this project's brand

Audit Summary Output Format

After completing all four audits, output this summary before generating docs:

PRE-LAUNCH AUDIT SUMMARY
========================
CRITICAL findings: [N]
HIGH findings:     [N]
MEDIUM findings:   [N]
LOW findings:      [N]

LAUNCH STATUS: [BLOCKED / CLEAR]

CRITICAL & HIGH FINDINGS:
[list using standard finding format — one per line]

MEDIUM FINDINGS (deferred):
[list with reason for deferral]

LOW FINDINGS (optional):
[list]

If LAUNCH STATUS: BLOCKED — do not proceed to documentation generation until the user confirms all CRITICAL and HIGH findings are resolved.

Secondary Output — Documentation Generation

Trigger: Audit is clean (no CRITICAL or HIGH findings), or user confirms all blockers are resolved.

Generate these documents if they do not already exist:

API Documentation (`api.md`)

# API Reference

Base URL: https://api.yourdomain.com/api/v1
Authentication: Bearer token in Authorization header

## Endpoints

### POST /auth/register
Creates a new user account.
Body: { "email": "string", "password": "string", "name": "string" }
Success: 201 { "success": true, "data": { "user": { ... } } }
Errors: 400 (missing fields), 409 (email exists)

### POST /auth/login
Authenticates user. Returns access token in body + refresh token in HttpOnly cookie.
Body: { "email": "string", "password": "string" }
Success: 200 { "success": true, "data": { "accessToken": "..." } }
Errors: 400 (missing fields), 401 (invalid credentials)

[continue for all active routes]

Environment Setup Guide (`.env.example`)

# Frontend
NEXT_PUBLIC_API_URL=https://api.yourdomain.com

# Backend
PORT=50001
MONGO_URI=
JWT_ACCESS_SECRET=
JWT_REFRESH_SECRET=
CLIENT_URL=https://app.yourdomain.com

Cursor Rules File (`.cursorrules`)

Generate a .cursorrules or .mdc file that pre-programs the AI IDE with this project's standards:

CSS variable names and brand colors for this project
Component directory structure rules
Security boundaries (no DB from frontend, no localStorage tokens)
TypeScript interface requirements

Decision Guide

Situation	Correct action
CRITICAL finding in security audit	Block launch — do not proceed until fixed
MEDIUM finding user wants to defer	Document it in audit summary with reason — launch is not blocked
API docs already exist	Review and update them — do not regenerate from scratch
Puppeteer QA not set up	Still complete visual QA manually across three viewport sizes
User says "it's fine, just ship it" on a CRITICAL	Explain the risk clearly — do not remove from findings

Anti-Patterns

❌ Never do this	✅ Do this instead
Skip audit because "it works locally"	Run all four audit sections — local and production are different environments
Mark everything CRITICAL	Calibrate severity precisely — inflation makes real criticals invisible
Generate docs before audit is clean	Complete audit first; docs are the final step
Leave `.env.example` out of the repo	Always commit `.env.example` — it documents required vars without exposing values
Ship without verifying production env vars	Test one protected API call from production frontend before declaring launch

Gotchas

The most common production failure is environment variables not set in the hosting dashboard. Always make a real API call from the production URL before declaring the deployment successful.
HttpOnly cookies work differently in production behind a proxy. If refresh tokens stop working in production, check sameSite and secure cookie settings — they must be secure: true and sameSite: "none" for cross-origin.
A "clean" TypeScript build (tsc --noEmit) is not the same as no runtime errors. Type correctness prevents many bugs but does not catch logic errors.
.cursorrules files are excluded from git by default in some setups. Confirm they are either committed (if not project-specific) or documented in the handoff notes so the next developer can recreate them.

Handoff

Skill: project-delivery
Type: Hybrid (Primary: Gatekeeper, Secondary: Generation)
Trigger phrases covered: "ready to launch", "deploy this", "going live",
  "final checks", "deliver to client", "is this ready to ship?"
DO NOT TRIGGER for: mid-development feature building, general coding questions,
  debugging during active development
Test prompts to verify:
  1. "I think the project is done, can you check if it's ready to launch?"
     → Should trigger; all four audits run, findings reported in standard format
  2. "Help me write the API documentation for my project"
     → Should trigger; secondary generation output produces api.md
  3. "Add a delete button to my invoice list component"
     → Should NOT trigger; active feature development, not delivery
Pass/fail rubric score: 5/5
Suggested next iteration: add performance audit section (Lighthouse scores,
  Core Web Vitals) if client delivery requires documented performance benchmarks

/project-delivery

SKILL.md