Tech Stack Selection Skill

Read .hackathon/IDEA-FINAL.md and .hackathon/STATE.md first.

Soft gate: Can run after ideation (in parallel with architecture). Must be complete before scaffold.

Important Principles

For a hackathon with agentic AI coding:

1. Documentation quality matters more than developer preference. The AI agent writes most of the code. Frameworks with extensive, up-to-date documentation produce better agent output. A well-documented framework you've never used beats a poorly-documented one you know.

2. Community size = fewer edge cases. Popular frameworks have more training data in the model, more StackOverflow answers, and more examples. This directly translates to fewer "the agent doesn't know how to do X" moments.

3. Convention over configuration. Frameworks that are opinionated (Next.js, Hono, Drizzle) produce more consistent agent output than flexible ones (Express, Knex) because there's one right way to do things.

4. TypeScript is non-negotiable for multi-developer hackathon projects. The type system is the only thing preventing "it works on my machine" when two people push at the same time.

Stack Decision Tree

Walk through each category interactively with the user. For each, present 2-3 options with a recommended default and explain the tradeoff.

1. Package Manager

• pnpm (recommended for monorepos) — strict, fast, great workspace support
• npm — universal, works everywhere, slightly less monorepo-native
• bun — fast, but ecosystem edge cases in monorepos

2. Monorepo Tool

• Turborepo (recommended) — simple, fast, minimal config
• Nx — powerful but heavier setup
• pnpm workspaces alone — works for simple cases

3. Frontend Framework

• Next.js (recommended if SSR matters) — huge ecosystem, great docs, agents know it cold
• Vite + React (recommended for SPA) — faster dev server, simpler mental model
• Other (ask user)

4. Backend Framework

• Hono (recommended) — lightweight, great TypeScript, RPC mode for type-safe clients, multi-runtime
• Elysia — elegant, Eden Treaty for types, but Bun-only
• Express — everyone knows it, but less typed, more boilerplate
• Fastify — fast, well-typed, but slightly less agent familiarity

5. Database

• SQLite (recommended for hackathon) — zero setup, file-based, deploy anywhere. Use with Drizzle ORM or better-sqlite3 directly
• PostgreSQL — production-grade, but requires hosting. Use if the project needs advanced queries.
• None/In-memory — for truly simple projects

6. ORM / Query Builder

• Drizzle (recommended) — TypeScript-first, great DX, lightweight, well-documented
• Prisma — more established, but heavier and slower in dev
• Raw queries — only if the data layer is trivial

7. Styling

• Tailwind CSS (recommended) — agents produce excellent Tailwind, consistent output, utility-first
• CSS Modules — good isolation, but more verbose for agents
• Styled-components — runtime overhead, less predictable agent output

8. UI Component Base

• shadcn/ui (recommended) — copy-paste components, full control, Tailwind-native, well-documented
• Radix UI — lower-level primitives, more work to style
• Headless UI — fewer components, but very accessible

9. Testing (if time allows)

• Vitest — fast, Vite-native, great TypeScript support
• Jest — well-known, but slower

10. Deployment Target

• Vercel (recommended for Next.js) — zero-config deploy, free tier
• Railway — great for fullstack (frontend + backend + DB)
• Fly.io — good for containerized apps
• Local only — valid for hackathon demo if time is tight

Output

Write to .hackathon/STACK.md:

---
owner: [lead dev]
status: draft
created-at: [timestamp]
last-modified: [timestamp]
phase: stack
---

# Technology Stack

## Decisions

| Category | Choice | Rationale |
|----------|--------|-----------|
| Package Manager | pnpm | Best monorepo support |
| Monorepo Tool | Turborepo | Minimal config |
| Frontend | Next.js 15 | SSR, great docs, agents write it well |
| Backend | Hono | RPC types, lightweight, multi-runtime |
| Database | SQLite + Drizzle | Zero setup, TypeScript-first ORM |
| Styling | Tailwind CSS 4 | Agent-friendly, consistent output |
| UI Components | shadcn/ui | Copy-paste, full control, Tailwind-native |
| Testing | Vitest | Fast, Vite-native |
| Deployment | Vercel + Railway | Frontend on Vercel, API on Railway |

## Key Packages

### Frontend
- next, react, react-dom
- tailwindcss, @tailwindcss/postcss
- shadcn/ui components (installed as needed)
- hono/client (for typed API calls)

### Backend
- hono, @hono/node-server
- drizzle-orm, better-sqlite3
- @anthropic-ai/sdk (for Claude API integration)

### Shared
- typescript
- zod (for runtime validation matching types)
- @project/shared (internal types package)

## Dev Environment
- Node.js 20+
- pnpm 9+
- Turbo for monorepo orchestration

Also create .hackathon/stack-config.json — a machine-readable version the scaffold skill consumes:

{
  "packageManager": "pnpm",
  "monorepoTool": "turborepo",
  "frontend": { "framework": "nextjs", "version": "15" },
  "backend": { "framework": "hono", "runtime": "node" },
  "database": { "type": "sqlite", "orm": "drizzle" },
  "styling": { "framework": "tailwindcss", "componentLib": "shadcn" },
  "testing": "vitest",
  "deployment": { "frontend": "vercel", "backend": "railway" },
  "typescript": true
}

Update STATE.md, log to changelog.