Prototype Bootstrapper

Set up a new prototype monorepo using Bun workspaces with the following standard package structure. Follow this exactly — do not improvise the structure.

Monorepo Structure

[project-name]/
├── package.json              # Root workspace config
├── bunfig.toml               # Bun configuration
├── biome.json                # Biome linting + formatting config
├── tsconfig.json             # Base tsconfig
├── justfile                  # Quick setup and dev actions
├── CLAUDE.md                 # Project-specific context for Claude Code
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions CI
├── .claude/
│   └── settings.json         # Project-level Claude Code settings
├── packages/
│   ├── core/                 # Core business logic (variable tech)
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── types/                # Shared TypeScript types + Zod schemas
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── api/                  # Hono API (follows prototyping-skills:generate-api conventions)
│   │   ├── CLAUDE.md
│   │   ├── src/
│   │   │   ├── index.ts
│   │   │   └── routes/
│   │   │       └── health.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── ui/                   # Next.js dashboard (follows prototyping-skills:generate-ui conventions)
│   │   ├── CLAUDE.md
│   │   ├── src/
│   │   │   └── app/
│   │   │       ├── layout.tsx
│   │   │       ├── page.tsx
│   │   │       └── globals.css
│   │   ├── components.json
│   │   ├── next.config.ts
│   │   ├── tailwind.config.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── mcp/                  # MCP server (follows prototyping-skills:generate-mcp conventions)
│       ├── CLAUDE.md
│       ├── src/
│       │   ├── index.ts
│       │   └── tools/
│       ├── package.json
│       └── tsconfig.json

Step-by-Step Bootstrap Process

1. Root workspace configuration

package.json:

{
  "name": "[project-name]",
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "dev": "bun --filter '*' dev",
    "dev:api": "bun --filter api dev",
    "dev:ui": "bun --filter ui dev",
    "dev:mcp": "bun --filter mcp dev",
    "check": "bunx @biomejs/biome check .",
    "fix": "bunx @biomejs/biome check --write .",
    "test": "bun test"
  },
  "devDependencies": {
    "@biomejs/biome": "^1.9"
  }
}

bunfig.toml:

[install]
peer = false

tsconfig.json (base config):

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "paths": {
      "@repo/*": ["./packages/*/src"]
    }
  }
}

biome.json:

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": { "recommended": true }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "tab",
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "semicolons": "always"
    }
  }
}

justfile:

# Default: list available recipes
default:
    @just --list

# Install all dependencies
setup:
    bun install

# Run all packages in dev mode
dev:
    bun run dev

# Run only the API
dev-api:
    bun run dev:api

# Run only the UI
dev-ui:
    bun run dev:ui

# Lint and format with Biome
check:
    bunx @biomejs/biome check .

# Lint and format with auto-fix
fix:
    bunx @biomejs/biome check --write .

# Run all tests
test:
    bun test

# Run tests in watch mode
test-watch:
    bun test --watch

.github/workflows/ci.yml:

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx @biomejs/biome check .
      - run: bun test

Add @biomejs/biome as a root dev dependency in package.json:

{
  "devDependencies": {
    "@biomejs/biome": "^1.9"
  }
}

2. Types package (create first — others depend on it)

Hold all shared TypeScript types AND Zod schemas used across packages.

{
  "name": "@repo/types",
  "version": "0.1.0",
  "type": "module",
  "exports": { ".": "./src/index.ts" },
  "dependencies": {
    "zod": "^3"
  }
}

Starter src/index.ts:

import { z } from "zod";

// Entity modeling: use Schema.org property names where a relevant type exists.
// See https://schema.org/CreativeWork — only include fields you actually need.
export const ItemSchema = z.object({
  id: z.string(),
  name: z.string(),
  dateCreated: z.string().datetime(),
});

export type Item = z.infer<typeof ItemSchema>;

3. Core package

The core package is where the prototype's unique functionality lives. Its tech stack varies per prototype. Set up the shell and let the user define what goes here.

{
  "name": "@repo/core",
  "version": "0.1.0",
  "type": "module",
  "exports": { ".": "./src/index.ts" },
  "dependencies": {
    "@repo/types": "workspace:*"
  }
}

4. API, UI, MCP packages

Set these up following the conventions in the prototyping-skills:generate-api, prototyping-skills:generate-ui, and prototyping-skills:generate-mcp skills respectively. Create minimal working starters:

• API: Health check route, CORS middleware, Swagger UI mounted
• UI: Root layout with sidebar, home page with placeholder content, shadcn/ui initialised
• MCP: Server entry point with stdio transport, one placeholder tool

5. Generate the project CLAUDE.md

After scaffolding, create a CLAUDE.md at the project root. Ask the user what the prototype is about and fill in this template:

# [Project Name]

## What This Prototype Does
[Description from user]

## Monorepo Structure
- `packages/core` — Core logic: [what the core does + any special tech]
- `packages/types` — Shared TypeScript types and Zod schemas
- `packages/api` — Hono API with @hono/zod-openapi (port 3001)
- `packages/ui` — Next.js dashboard with shadcn/ui (port 3000)
- `packages/mcp` — MCP server using @modelcontextprotocol/sdk

## Stack & Conventions
- **Runtime**: Bun
- **Monorepo**: Bun workspaces
- **Linting + Formatting**: Biome (not ESLint/Prettier)
- **Testing**: bun:test
- **CI**: GitHub Actions (.github/workflows/ci.yml)
- **Task runner**: justfile
- **API**: Hono + @hono/zod-openapi — all routes use `createRoute` + `app.openapi()`, JSON:API spec paths
- **UI**: Next.js 15 App Router + shadcn/ui — Server Components by default, Server Actions for mutations
- **MCP**: @modelcontextprotocol/sdk with stdio transport
- **Database**: bun:sqlite when persistence is needed
- **Types**: Shared via @repo/types, never duplicate across packages

## Team
Multiple people work on this prototype. Follow the global skill conventions unless
a deviation is documented below.

## Deviations from Team Defaults
<!-- Document any approved deviations here so all team members understand why -->
<!-- Format: what was changed, why, who approved it, what to watch out for -->
_None yet._

## Core Package — Prototype-Specific Tech
<!-- This section is for tech unique to THIS prototype's core package -->
[Libraries, patterns, or approaches specific to this prototype's core functionality]

## Commands
- `bun install` — Install all dependencies
- `bun run dev` — Run all packages in dev mode
- `bun run dev:api` — API only
- `bun run dev:ui` — UI only
- `bun run check` — Lint and format check (Biome)
- `bun run fix` — Lint and format with auto-fix (Biome)
- `bun test` — Run all tests (bun:test)
- `just` — List all available tasks (justfile)

## Development Workflow

### Adding a Feature
1. Write tests first: use `superpowers:test-driven-development`
2. Implement the feature
3. Run `/simplify` before committing (enforced by hook)
4. Run `superpowers:verification-before-completion` to verify completeness
5. Run `superpowers:requesting-code-review` before merging

### Commit Messages
Use conventional commit format: `type(scope): description`
Types: feat, fix, refactor, test, docs, chore, style, perf, ci, build
Minimum description: 15 characters

### After a Burst Session
Before merging, run the full verification chain:
1. `bun check` (Biome lint + format)
2. `bun test` (all packages)
3. `superpowers:verification-before-completion`
4. `superpowers:requesting-code-review`

## Rules
- Types are defined ONLY in @repo/types
- Business logic is defined ONLY in @repo/core
- API handlers are thin wrappers around @repo/core
- MCP tools are thin wrappers around @repo/core
- Deviations from defaults must be documented in this file

6. Generate per-package CLAUDE.md signposts

Create a small CLAUDE.md in each stable package directory to point Claude at the right skill. These get committed to git so every team member's Claude Code session picks up the same context.

packages/api/CLAUDE.md:

# API Package

This package follows the `prototyping-skills:generate-api` skill conventions.
Hono + @hono/zod-openapi patterns. Handlers are thin wrappers around @repo/core.

Key rules:
- All routes use `createRoute()` + `app.openapi()` — never raw `app.get()`
- Business logic in @repo/core, not in handlers
- Types from @repo/types, never duplicated
- Use `Bun.env`, not `process.env`

packages/ui/CLAUDE.md:

# UI Package

This package follows the `prototyping-skills:generate-ui` skill conventions.
Next.js 15 App Router + shadcn/ui patterns.

Key rules:
- Server Components by default — only add "use client" when genuinely needed
- Server Actions for mutations, not client-side POST calls
- Data fetching in async Server Components, not useEffect + fetch
- Types from @repo/types, never duplicated

packages/mcp/CLAUDE.md:

# MCP Package

This package follows the `prototyping-skills:generate-mcp` skill conventions.
@modelcontextprotocol/sdk with stdio transport.

Key rules:
- Tool handlers are thin wrappers around @repo/core
- Zod `.describe()` on every parameter
- Return structured JSON as text content
- Types from @repo/types, never duplicated

7. Commit the scaffolding

After all files are created and bun install has run, initialise git and create the initial commit:

git init
git add .
git commit -m "Bootstrap [project-name] prototype monorepo"

This ensures every team member's Claude Code session picks up the CLAUDE.md files from the first clone.

Important Notes

• Always ask the user what the prototype is about before generating core package contents.
• The core package is the ONLY package whose tech stack varies. API, UI, and MCP are standardised.
• If the user specifies special libraries for the core (e.g., a specific AI SDK, a database driver, a processing library), add them only to the core package.