gh-greyhaven-ai-claude-code-config-grey-haven-plugins-core/skills/project-scaffolding/reference/scaffold-specifications.md

Scaffold Specifications

Technical specifications for each Grey Haven scaffold type.

---

Cloudflare Worker API Specification

Purpose: Production REST/GraphQL API on Cloudflare edge network

Minimum Files (18):

• wrangler.toml, package.json, tsconfig.json
• src/index.ts (entry), routes/ (3 files), middleware/ (4 files)
• services/ (2 files), types/ (1 file), utils/ (1 file)
• tests/ (3 files), .github/workflows/, README.md

Dependencies:

{
  "dependencies": {
    "hono": "^4.0.0"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20240117.0",
    "typescript": "^5.3.3",
    "vitest": "^1.2.0",
    "wrangler": "^3.25.0"
  }
}

Features:

• Hono framework
• D1 database binding
• JWT authentication middleware
• CORS configuration
• Request logging
• Error handling
• Health check endpoint
• Vitest tests

---

React Component Specification

Purpose: Reusable UI component with tests and stories

Minimum Files (6):

• Component.tsx, Component.test.tsx, Component.stories.tsx
• Component.module.css, index.ts, README.md

Dependencies:

{
  "devDependencies": {
    "@testing-library/react": "^14.1.0",
    "@testing-library/user-event": "^14.5.0",
    "@storybook/react-vite": "^7.6.0",
    "vitest": "^1.2.0"
  }
}

Features:

• TypeScript prop types
• CSS modules styling
• Vitest + Testing Library tests
• Storybook stories
• Accessible markup
• JSDoc documentation

---

Python API Specification

Purpose: Production-ready FastAPI with async PostgreSQL

Minimum Files (22):

• pyproject.toml, alembic.ini, .env.example
• app/main.py, config.py, dependencies.py
• app/api/ (3 files), models/ (2 files), schemas/ (2 files)
• app/services/ (2 files), db/ (3 files)
• tests/ (4 files), alembic/versions/, README.md

Dependencies:

[project]
dependencies = [
  "fastapi[standard]>=0.109.0",
  "pydantic>=2.5.0",
  "sqlalchemy[asyncio]>=2.0.25",
  "alembic>=1.13.0",
  "asyncpg>=0.29.0",
]

Features:

• FastAPI with async
• Pydantic v2 validation
• SQLAlchemy 2.0 async
• Alembic migrations
• pytest with asyncio
• uv package manager
• Ruff linting
• mypy type checking

---

Full-Stack Specification

Purpose: Complete monorepo with frontend and backend

Minimum Files (35):

• package.json (root), pnpm-workspace.yaml
• frontend/ (15 files), backend/ (12 files)
• packages/types/ (4 files), docs/ (4 files)

Structure:

my-app/
├── frontend/     # React + Vite + TanStack
├── backend/      # Cloudflare Worker + D1
├── packages/     # Shared TypeScript types
└── docs/         # Architecture docs

Features:

• pnpm workspaces
• Shared types package
• TanStack Router + Query
• Cloudflare deployment
• CI/CD pipeline
• Monorepo scripts

---

Total Specs: 4 scaffold types Coverage: Frontend, backend, component, full-stack