New project setup checklist

Purpose: Provides a complete step-by-step guide for bootstrapping a new child project with Framework inheritance, infrastructure, CI/CD, and core dependencies.

Complete guide for setting up a new project that inherits from Framework standards.

Prerequisites

• Workstation setup complete — See standards/reference/workstation-setup.md
• Accounts provisioned — GitHub, Linear, Vercel, Supabase, Clerk, Sentry, PostHog, Axiom

Part 1: Repository setup

1.1 Create repository

npx create-next-app@latest my-project --typescript --tailwind --app --no-src-dir
cd my-project && git init && git add . && git commit -m "chore: initial Next.js setup"

1.2 Create CLAUDE.md

Copy standards/reference/coding-conventions.md and add project-specific context (overview, domain concepts, external services). See standards/reference/coding-conventions.md § "Project Customization".

1.3 Copy .mcp.json and set up Linear API

cp path/to/framework/.mcp.json.example .mcp.json

This gives you Playwright MCP.

For Linear integration, set LINEAR_API_KEY in your shell profile:

export LINEAR_API_KEY=lin_api_...  # Get from Linear Settings > API > Personal API keys

The framework uses tools/scripts/linear-api.ts for direct GraphQL access to Linear (no MCP needed).

1.4 Create AGENTS.md

Use template at standards/reference/agents-template.md.

1.5 Copy PR template

mkdir -p .github/PULL_REQUEST_TEMPLATE
cp path/to/framework/.github/PULL_REQUEST_TEMPLATE/default.md .github/PULL_REQUEST_TEMPLATE/

1.6 Set up Framework inheritance

# Recommended: plugin install with domain selection
bash ../framework/tools/scripts/plugin-install.sh --domains core-pipeline,design-ui,backend-infra,testing-qa

# Or install all domains:
bash ../framework/tools/scripts/plugin-install.sh

Verify with: bash path/to/framework/tools/scripts/verify-inheritance.sh

See standards/reference/inheritance.md for full details, domain listing, rollback, and Turbopack protection.

1.7 Create specs directory

mkdir -p docs/specs

1.8 Set up Claude Code review

Copy the review workflow from framework:

mkdir -p .github/workflows
cp path/to/framework/.github/workflows/claude-review.yml .github/workflows/claude-review.yml

Set the Anthropic API key for the repo (one-time, stored in 1Password as ANTHROPIC_API_KEY):

gh secret set ANTHROPIC_API_KEY

Enable GitHub Actions to post formal PR reviews (approve/request_changes):

gh api "repos/OWNER/REPO/actions/permissions/workflow" \
  --method PUT \
  -F can_approve_pull_request_reviews=true \
  -F default_workflow_permissions="write"

This enables automated Claude Code review on every PR with formal GitHub reviews (approve/request_changes), a self-fix loop (up to 3 rounds), and standards reflection. The review protocol lives in standards/core/review-protocol.md (inherited via symlink).

1.9 Push to GitHub

git remote add origin git@github.com:your-username/your-repo.git
git branch -M main && git push -u origin main

Part 2: Project management (Linear)

1. Create Linear project — Matches repo name
2. Configure workflow states — Triage -> Backlog -> To-Do -> In Design -> In Process -> In Review -> Preview Testing -> Done (To-Do is optional — issues may skip from Backlog to In Design)
3. Create labels — type: feature, type: bug, type: debt, type: idea, type: discovery
4. Connect GitHub repo — Branch detection, PR linking, auto-close

Part 3: Infrastructure setup

3.1 Vercel

1. Import GitHub repo — Framework Preset: Next.js -> Deploy
2. Create a production branch — In git and push it:

   git branch production && git push origin production
   

3. Configure branch tracking — Settings -> Environments -> Production -> Branch Tracking: change from main to production -> Save
4. Scope environment variables — Settings -> Environment Variables: scope Preview vars to Preview, Production vars to Production
5. Verify — Push to main and confirm Vercel creates a Preview deployment (not Production)

Why: Pushes to main should create Preview deployments for testing, not go straight to Production. Production is promoted manually via the Vercel dashboard. See standards/reference/environments.md § "Branch Strategy".

3.2 Supabase

Create project, save connection details. Add to Vercel env vars:

• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY

3.3 Prisma

pnpm add prisma @prisma/client && npx prisma init

Add DATABASE_URL to your 1Password environment and .env.op. See standards/reference/environments.md for the secrets management architecture.

3.4 Clerk

Create application, get API keys. Install pnpm add @clerk/nextjs. Add to Vercel:

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY
• NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in, NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

3.5 Sentry

Create Next.js project, get DSN. Install: npx @sentry/wizard@latest -i nextjs. Add NEXT_PUBLIC_SENTRY_DSN, SENTRY_AUTH_TOKEN.

3.6 PostHog

Create project, get API key. Install pnpm add posthog-js. Add NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST.

3.7 Axiom

Create dataset, get API token. Install pnpm add next-axiom. Add AXIOM_TOKEN, AXIOM_DATASET.

3.8 Environment variables template

Create .env.local.example (committed, no values) with all vars from steps above.

Part 4: CI/CD

Vercel preview deploys are automatic. Add GitHub Actions for CI:

# .github/workflows/ci.yml
name: CI
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check
      - run: pnpm test
      - run: pnpm build

Part 5: Core dependencies

# UI
pnpm add class-variance-authority clsx tailwind-merge
pnpm dlx shadcn@latest init

# State + Validation + Dates
pnpm add @tanstack/react-query zustand zod luxon
pnpm add -D @types/luxon

# Testing
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/jest-dom
pnpm add -D playwright @playwright/test

# Email (if needed)
pnpm add @react-email/components @react-email/render resend

Part 6: Verification

pnpm dev          # App runs at localhost:3000
pnpm type-check   # No TypeScript errors
pnpm lint         # No ESLint errors
pnpm build        # Build succeeds
pnpm test         # Tests pass
npx prisma db push  # Connects to Supabase

Push to main and verify Vercel deploys successfully.

External agent runners

If the project will be triggered by external agent runners (Linear Agent, cloud runners, webhook handlers), create a separate CLAUDE-AGENT.md entry-point file. Do not point external runners at CLAUDE.md — it contains the orchestrator contract and will cause recursive pipeline execution.

See standards/.future/cloud-agent-entry-point.md for the design constraint and what to include/exclude.

Next steps

1. Create first Linear issue — type: feature
2. Run Monday Triage — Move from Triage to Backlog
3. Follow the Framework SDLC — DESIGN -> BUILD -> SHIP -> LEARN

See standards/core/sdlc.md for the full workflow.

---

New Project Checklist v2.2 -- March 2026