gh-greyhaven-ai-claude-code-config-grey-haven-plugins-core/skills/project-scaffolding/checklists/scaffold-quality-checklist.md

Scaffold Quality Checklist

Comprehensive checklist for validating generated scaffolds before delivery.

---

Configuration Files

TypeScript Projects

• package.json present with correct project name
• tsconfig.json with strict mode enabled
• Scripts configured (dev, build, test, deploy)
• Dependencies at correct versions
• devDependencies include linting/testing tools

Python Projects

• pyproject.toml present with project metadata
• Dependencies specified with version ranges
• Dev dependencies include pytest, ruff, mypy
• Tool configurations (ruff, mypy, pytest) configured

All Projects

• .gitignore includes node_modules, .env, build artifacts
• .env.example provided for environment variables
• README.md with setup instructions
• License file (if applicable)

---

Source Code Structure

Directory Organization

• src/ directory exists
• routes/ for API endpoints or pages
• components/ for UI components (frontend)
• services/ for business logic
• utils/ for helper functions
• types/ for TypeScript definitions

Entry Points

• Main file exists (index.ts, main.py, App.tsx)
• Exports correctly configured
• Health check endpoint implemented
• Error handling middleware included

---

Code Quality

TypeScript

• Strict mode enabled in tsconfig.json
• Type annotations on all functions
• Interfaces defined for props/config
• ESLint configuration present
• Prettier configuration present
• No any types (except explicit)

Python

• Type hints on all functions
• Pydantic models for validation
• Async/await used correctly
• Docstrings on public functions
• Ruff configuration present
• mypy strict mode enabled

All Languages

• Consistent naming (camelCase, snake_case)
• No hard-coded secrets or API keys
• Environment variables used correctly
• Error handling implemented
• Logging configured

---

Testing

Test Files

• tests/ directory exists
• Test files mirror src/ structure
• Test fixtures configured (conftest.py, setup.ts)
• Coverage configuration present

Test Quality

• Sample tests included
• Tests pass out of the box
• Health check test present
• Test commands in package.json/pyproject.toml

---

Deployment

Cloudflare Workers

• wrangler.toml configured
• Database bindings defined (if D1)
• Environment sections (production, staging)
• Secrets documented in README

Cloudflare Pages

• Build command configured
• Output directory specified
• Environment variables documented

Python

• Dockerfile (if containerized)
• Requirements frozen
• Database migrations configured (Alembic)

---

Documentation

README.md

• Project description clear
• Quick start instructions
• Setup steps documented
• Development commands listed
• Deployment instructions
• Environment variables documented
• API endpoints listed (if API)

Additional Docs

• Architecture diagram/description (full-stack)
• API documentation (FastAPI auto-docs, etc.)
• Contributing guidelines (if open source)

---

Security

Secrets Management

• No secrets committed to git
• .env in .gitignore
• .env.example provided
• Secret management documented

Authentication

• Auth middleware included (if applicable)
• JWT handling implemented correctly
• CORS configured properly

Input Validation

• Zod/Pydantic validation on inputs
• SQL injection prevention (parameterized queries)
• XSS prevention (sanitized outputs)

---

Dependencies

Version Management

• Package versions pinned or ranged appropriately
• No deprecated packages
• Security vulnerabilities checked
• License compatibility verified

Peer Dependencies

• React version compatible (if React)
• Node version specified (engines field)
• Python version specified (requires-python)

---

CI/CD

GitHub Actions

• .github/workflows/ directory exists
• Test workflow configured
• Deploy workflow configured
• Lint workflow configured

Workflow Quality

• Tests run on PR
• Deployment on main branch
• Secrets properly configured
• Environment variables set

---

User Experience

Developer Experience

• Setup time < 5 minutes
• All commands work (dev, test, build)
• Hot reload functional
• Error messages helpful

Production Readiness

• Health endpoint returns 200
• Error handling doesn't expose internals
• Logging configured
• Monitoring hooks present

---

Checklist Summary

Must Have (Critical)

• ✅ Configuration files present and correct
• ✅ Source code structure follows Grey Haven conventions
• ✅ Tests included and passing
• ✅ README with setup instructions
• ✅ No secrets committed

Should Have (Important)

• ✅ Type safety (TypeScript strict, Python type hints)
• ✅ Linting and formatting configured
• ✅ CI/CD pipeline included
• ✅ Health check endpoint
• ✅ Error handling

Nice to Have (Optional)

• ✅ Architecture documentation
• ✅ API documentation
• ✅ Storybook (components)
• ✅ Database migrations
• ✅ Monitoring setup

---

Quick Validation Script

#!/bin/bash
# Quick scaffold validation

echo "Checking scaffold quality..."

# Check files exist
test -f package.json && echo "✅ package.json" || echo "❌ package.json"
test -f README.md && echo "✅ README.md" || echo "✅ README.md"
test -d src && echo "✅ src/" || echo "❌ src/"
test -d tests && echo "✅ tests/" || echo "❌ tests/"

# Check no secrets
! grep -r "api[_-]key" . && echo "✅ No API keys" || echo "⚠️  API key found"

# Install and test
npm install && npm test && echo "✅ Tests pass" || echo "❌ Tests fail"

---

Version: 1.0 Last Updated: 2024-01-15