Skip to main content
Back to Skills

New Project

Bootstrap a new child project from the prototype scaffold. Produces a fully configured repo with GitHub remote, Linear integration, CLAUDE.md, MCP config, and passing quality gates.

New Project Bootstrap

This skill codifies the full sequence to create a new child project from the prototype scaffold. When complete, the project has a private GitHub repo, a working Next.js app, Linear integration, and all configuration files in place.

Scope: This skill covers bootstrapping a new repo from scratch. It does NOT cover adding framework features to an existing project or migrating an old project.

Prerequisites

Before running this skill, have ready:

Required Where to find
Project name (slug form, e.g., my-app) Agree with user before starting
Linear project UUID Linear > Projects > project settings > copy ID from URL
Linear team UUID From .linear.json in framework root — team.id
Linear assignee UUID From .linear.json in framework root — assignee.id
Linear status UUIDs From .linear.json in framework root — statuses.*
Linear label UUIDs From .linear.json in framework root — labels.*
gh CLI authenticated gh auth status
pnpm installed pnpm --version

Read .linear.json from the framework root first. The child project's .linear.json reuses the same team UUID, assignee UUID, status UUIDs, and label UUIDs. Only the projects block changes.

Steps

Step 1 — Create the private GitHub repo

gh repo create <project-name> --private --description "<one-line description>"

Note the SSH remote URL from the output (format: git@github.com:<org>/<project-name>.git). You will use it in Step 10.

If the repo already exists, skip creation and retrieve the URL:

gh repo view <project-name> --json sshUrl --jq .sshUrl

Step 2 — Copy the prototype scaffold

rsync -av \
  --exclude=node_modules \
  --exclude=.next \
  --exclude=.git \
  --exclude=out \
  /Users/ameet/Sites/framework/tools/prototype-scaffold/ \
  ~/Sites/<project-name>/

After rsync, verify the target directory exists and contains package.json:

ls ~/Sites/<project-name>/package.json

Step 3 — Install dependencies

cd ~/Sites/<project-name> && pnpm install

This installs the full scaffold dependency tree (Next.js 16, shadcn/ui, Tailwind v4, Zod, Zustand, TanStack Query, Radix UI, Luxon, etc.).

Step 4 — Create .linear.json

Create ~/Sites/<project-name>/.linear.json with the following structure. All UUIDs except projects.<project-name> come verbatim from the framework's .linear.json. Replace <PROJECT_UUID> with the Linear project UUID the user provided.

{
  "team": {
    "id": "<team.id from framework .linear.json>",
    "key": "<team.key from framework .linear.json>",
    "name": "<team.name from framework .linear.json>"
  },
  "assignee": {
    "id": "<assignee.id from framework .linear.json>",
    "name": "<assignee.name from framework .linear.json>"
  },
  "statuses": {
    "triage": "<statuses.triage UUID>",
    "icebox": "<statuses.icebox UUID>",
    "backlog": "<statuses.backlog UUID>",
    "todo": "<statuses.todo UUID>",
    "in-design": "<statuses.in-design UUID>",
    "in-process": "<statuses.in-process UUID>",
    "in-review": "<statuses.in-review UUID>",
    "preview-testing": "<statuses.preview-testing UUID>",
    "done": "<statuses.done UUID>",
    "canceled": "<statuses.canceled UUID>",
    "duplicate": "<statuses.duplicate UUID>"
  },
  "labels": {
    "groups": {
      "type": "<labels.groups.type UUID>",
      "complexity": "<labels.groups.complexity UUID>",
      "mode": "<labels.groups.mode UUID>"
    },
    "type": {
      "bug": "<labels.type.bug UUID>",
      "feature": "<labels.type.feature UUID>",
      "chore": "<labels.type.chore UUID>",
      "docs": "<labels.type.docs UUID>",
      "planning": "<labels.type.planning UUID>",
      "spike": "<labels.type.spike UUID>"
    },
    "complexity": {
      "trivial": "<labels.complexity.trivial UUID>",
      "standard": "<labels.complexity.standard UUID>",
      "complex": "<labels.complexity.complex UUID>"
    },
    "mode": {
      "autonomous": "<labels.mode.autonomous UUID>",
      "interactive": "<labels.mode.interactive UUID>"
    },
    "awaiting-input": "<labels.awaiting-input UUID>"
  },
  "projects": {
    "<project-name>": "<PROJECT_UUID>"
  }
}

Important: The projects key name should match the project slug (same as the directory name).

Step 5 — Create CLAUDE.md

Create ~/Sites/<project-name>/CLAUDE.md with the framework inheritance preamble followed by project-specific sections. Replace all <placeholders> with the correct values.

# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Framework Inheritance

This project inherits from the [rajababa framework](https://github.com/ameetraina/framework). All standards, agents, and skills in the framework apply here.

Core standards: `standards/core/` in the framework repo.
Reference standards: `standards/reference/` in the framework repo.

## Project Overview

**Name:** <project-name>
**Description:** <one-line description>
**Stack:** Next.js 16, shadcn/ui, Tailwind CSS v4, TypeScript, Zod, Zustand, TanStack Query, Luxon

## Repository Structure

- `app/` — Next.js App Router pages and layouts
- `components/` — Shared UI components
- `components/ui/` — shadcn/ui components (do not edit directly)
- `lib/` — Utilities, hooks, data schemas
- `lib/data/` — Zod schemas and static seed data
- `public/` — Static assets
- `tools/scripts/` — Utility scripts including `linear-api.ts`

## Linear Workflow

Linear project: **<project-name>**
Issue tracking via `npx tsx tools/scripts/linear-api.ts <command>`.
Requires `LINEAR_API_KEY` env var (personal API key from Linear Settings > API).

## Key Commands

**Package manager:** pnpm (always use pnpm, not npm or yarn)

**Development:** `pnpm dev`
**Build:** `pnpm build`
**Lint:** `pnpm lint`
**Type check:** `pnpm type-check` (if configured) or `npx tsc --noEmit`

**Verification (before pushing PR):**
```bash
pnpm type-check && pnpm lint && pnpm test:run && pnpm build

Linear API:

npx tsx tools/scripts/linear-api.ts get-issue <ID>
npx tsx tools/scripts/linear-api.ts create-issue --team UUID --title TEXT
npx tsx tools/scripts/linear-api.ts list-todo

Locked Decisions

Inherited from framework. See standards/reference/tech-stack.md in the framework repo for full rationale.

Decision Choice
Date/time Luxon
Validation Zod
State (client) Zustand
State (server) TanStack Query
CSS Tailwind CSS 4
Components shadcn/ui + Radix UI
Forms React Hook Form
Package manager pnpm
Logging Axiom
Errors Sentry
Analytics PostHog

MCP Configuration

Copy .mcp.json.example to .mcp.json (gitignored) to enable Playwright MCP for browser testing.

Critical Rules

  1. No any types — Use proper TypeScript typing
  2. No console.log — Use Axiom/Sentry logging
  3. No TODO without issue reference — Every TODO must reference a Linear issue
  4. No native Date — Always use Luxon
  5. Validate at edge — Zod schemas for all external inputs
  6. Verify before claiming done — Run the full verification command and confirm output
  7. Sequential git writes — One branch at a time: branch, implement, verify, push, merge, next

---

### Step 6 — Copy `linear-api.ts`

```bash
mkdir -p ~/Sites/<project-name>/tools/scripts
cp /Users/ameet/Sites/framework/tools/scripts/linear-api.ts \
   ~/Sites/<project-name>/tools/scripts/linear-api.ts

Verify the copy:

ls ~/Sites/<project-name>/tools/scripts/linear-api.ts

Step 7 — Copy .mcp.json.example

cp /Users/ameet/Sites/framework/.mcp.json.example \
   ~/Sites/<project-name>/.mcp.json.example

The .mcp.json.example file contains the Playwright MCP configuration. Users copy it to .mcp.json (gitignored) when they need browser automation.

Step 8 — Scaffold .env.local

Create ~/Sites/<project-name>/.env.local with placeholder keys. This file is gitignored by the scaffold's .gitignore.

cat > ~/Sites/<project-name>/.env.local << 'EOF'
# Supabase (V2 — not required for V1 launch)
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=

# Linear API
LINEAR_API_KEY=

# Sentry
SENTRY_DSN=
NEXT_PUBLIC_SENTRY_DSN=

# PostHog
NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

# Axiom
AXIOM_TOKEN=
AXIOM_DATASET=

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
EOF

Deferred: Supabase connection vars (NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY) — left blank in V1. Supabase integration is a V2 addition. Users fill these in when ready to add a database layer.

Step 9 — Verify quality gates pass

Run the full verification sequence from the project directory:

cd ~/Sites/<project-name> && pnpm type-check && pnpm lint && pnpm test:run && pnpm build

If type-check is not a defined script in package.json, use:

cd ~/Sites/<project-name> && npx tsc --noEmit && pnpm lint && pnpm test:run && pnpm build

Note: If the scaffold has no test suite yet, pnpm test:run may fail. In that case, add a placeholder test or configure the test script before proceeding. Tests are part of the standard verification — do not skip them.

Do not proceed to Step 10 until all three commands exit cleanly. If any fail:

  1. Read the error output
  2. Fix the issue (common: missing tsconfig.json fields, missing type-check script)
  3. Re-run until all three pass
  4. Document any scaffold fixes needed for the framework

Step 10 — Initialize git and push

cd ~/Sites/<project-name>
git init
git add -A
git commit -m "chore: initial scaffold from framework"
git remote add origin <repo-url-from-step-1>
git push -u origin main

If the default branch is master instead of main:

git branch -M main
git push -u origin main

Verify the push landed:

gh repo view <project-name> --json defaultBranchRef --jq .defaultBranchRef.name

Post-Bootstrap Checklist

After completing all steps, confirm:

  • GitHub repo exists and is private: gh repo view <project-name>
  • ~/Sites/<project-name>/package.json exists
  • .linear.json has the correct project UUID
  • CLAUDE.md has the correct project name and description
  • tools/scripts/linear-api.ts copied
  • .mcp.json.example copied
  • .env.local scaffolded with placeholder keys
  • Quality gates passed: pnpm type-check && pnpm lint && pnpm test:run && pnpm build
  • Initial commit pushed to main

Wodify Gap Checklist

This checklist documents gaps discovered during the Wodify assistant build and how this skill addresses each one.

Gap (Wodify build) How this skill addresses it
No .linear.json — pipeline commands failed on first run Step 4 creates .linear.json with all required UUIDs before any issue work begins
No tools/scripts/linear-api.ts — /new, /go couldn't run Step 6 copies linear-api.ts from the framework explicitly
No CLAUDE.md — agents had no project context or locked decisions Step 5 creates a full CLAUDE.md with framework preamble and project-specific sections
No .env.local — developers encountered missing var errors on first pnpm dev Step 8 scaffolds all expected env vars as blank placeholders so the shape is clear
No .mcp.json.example — Playwright MCP couldn't be enabled Step 7 copies the example file so users can opt in immediately
Quality gates not verified before first push — TypeScript errors in initial commit Step 9 runs type-check && lint && build before the first git push
Supabase added immediately when not needed — added complexity before value Step 8 explicitly defers Supabase to V2 with a Deferred callout

V2 Additions (Out of Scope for V1)

These items are intentionally excluded from V1 to keep the bootstrap minimal:

  • Supabase project creation — Create a Supabase project, link it, and write the NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY into .env.local
  • Vercel project creation — vercel link + set env vars in Vercel dashboard
  • Sentry project creation — Create a Sentry project, install the SDK, and write SENTRY_DSN
  • PostHog setup — Create a PostHog project and write NEXT_PUBLIC_POSTHOG_KEY
  • Axiom dataset creation — Create a dataset and write AXIOM_TOKEN + AXIOM_DATASET
  • First Linear issue creation — Run /new "feat: <first feature>" to queue the first issue

Deferred: The above V2 items are tracked but not yet implemented. They will be added when the bootstrap sequence has been validated on at least two real child projects.

Search Framework Explorer

Search agents, skills, and standards