Project Scaffolding Skill

Read .hackathon/STACK.md (or stack-config.json), .hackathon/ARCHITECTURE.md, and .hackathon/contracts/shared-types.ts first.

Hard gate: Both stack and architect phases must be complete.

Important Context

This skill creates the foundation that developers will build on for the rest of the hackathon. Getting this right saves hours of debugging configuration issues. Getting it wrong can cascade into constant friction.

Pre-Scaffold: Documentation Research

Before writing any code, spin up the doc-researcher agent to fetch the latest documentation and best practices for the chosen tools. This is critical because:

• Framework APIs change frequently
• The agent's training data may be slightly outdated
• Best practices evolve

The doc-researcher should check:

• The chosen frontend framework's latest project setup guide
• The chosen backend framework's latest getting-started docs
• The monorepo tool's workspace configuration
• The ORM's setup and migration guide
• The deployment platform's requirements (what file structure it expects)

Scaffold Checklist

All items must be completed. The verification script (scripts/verify-scaffold.sh) checks each one.

1. Repository Root

• package.json with workspace configuration
• turbo.json (or equivalent monorepo config)
• .gitignore (comprehensive — node_modules, .env, .turbo, dist, etc.)
• .env.example with all required environment variables documented
• tsconfig.base.json (shared TypeScript config)
• .eslintrc or eslint.config.js (shared lint config)
• .prettierrc (shared formatting — critical for multi-dev consistency)
• README.md with project name, setup instructions, and available scripts

2. Frontend App (apps/web/)

• Framework initialized (Next.js / Vite+React)
• TypeScript configured, extending base tsconfig
• Tailwind CSS configured and working
• A layout component with basic navigation structure
• A home page that renders successfully
• API client configured (Hono RPC client or equivalent) pointing to backend
• Environment variable for API URL
• Dev script that starts with hot-reload

3. Backend App (apps/api/)

• Framework initialized (Hono / Elysia)
• TypeScript configured, extending base tsconfig
• A health check endpoint (GET /health → { status: "ok" })
• Route structure matching the architecture's API domains
• Database connection configured (even if empty schema)
• CORS configured for frontend dev server
• Environment variable handling (.env loaded)
• Dev script that starts with hot-reload
• Type exports for the RPC client

4. Shared Package (packages/shared/)

• package.json with name @project/shared
• TypeScript configured
• Types from .hackathon/contracts/shared-types.ts copied into src/types/
• src/index.ts that re-exports everything
• Both apps can import from @project/shared

5. UI Package (packages/ui/) — Placeholder

• package.json with name @project/ui
• Basic setup ready for the design system skill to populate
• Both frontend app can import from @project/ui

6. Config Package (packages/config/) — Optional

• Shared ESLint config
• Shared TypeScript config
• Shared Tailwind config (if applicable)

7. Development Experience

• Root-level pnpm dev starts both frontend and backend
• Root-level pnpm build builds everything
• Root-level pnpm lint lints everything
• Root-level pnpm typecheck runs type checking across all packages
• Changes in packages/shared are reflected in apps without restart

8. Full-Stack Verification

• Frontend renders a page
• Backend responds to health check
• Frontend can call backend and display the response
• Shared types are importable in both apps
• A sample typed API call works end-to-end (e.g., frontend calls backend health check and displays the result)

Process

1. Read the stack config
2. Run doc-researcher for latest docs
3. Create the directory structure
4. Initialize each package with its framework
5. Copy types from .hackathon/contracts/shared-types.ts into packages/shared/src/types/, restructuring into modules (api.ts, models.ts, enums.ts) as appropriate
6. Install dependencies
7. Configure TypeScript path aliases for cross-package imports
8. Set up the dev scripts
9. Create the hello-world end-to-end flow
10. Run the verification script
11. Fix any issues
12. Lock .hackathon/contracts/shared-types.ts (set frontmatter status to locked, locked-by: scaffold) — from now on, packages/shared/src/types/ is the canonical type location
13. Commit with message: "chore: scaffold project"

Deployment Prep (Baked In)

During scaffolding, also set up deployment configuration even though we won't deploy yet:

• Dockerfile or deployment config for the backend
• vercel.json or equivalent for the frontend
• Database migration setup (even if empty)
• Environment variable documentation in .env.example

This way, when the deploy skill is triggered later (via /hackathon-pilot:next deploy or by asking Claude to deploy), it's a single step rather than an hour of configuration.

Output

• Complete monorepo structure as described above
• Verification script output confirming everything works
• Update STATE.md: scaffold complete
• Log to changelog
• Print: "Project scaffolded. Run pnpm dev to start. Both apps should be running. Next: design system and work phasing."