Setup Project

Setup Project

Browser access. Use the built-in browser tools. mcp__Claude_Browser__* covers navigation, DOM reads (read_page), screenshots and resize_window; reach for chrome-devtools emulate when a mobile device gate has to fire, which resize_window alone does not guarantee. The browser skill and the agent-browser steps were dropped in 8.79.0 — do not reach for that CLI here. (The binary itself is still installed for kb-factory's JS-rendered crawls; that is a separate consumer, not a fallback for page verification.)

Mode Detection

Check the working directory:

• No package.json or user says "new/create project" → Create mode
• Existing package.json → Onboard mode

Create Mode (Greenfield)

Step 1: Gather Requirements

Infer from user description, or ask if unclear:

1. Project type: SaaS, e-commerce, marketing, API, library/CLI, full-stack app
2. Structure: monorepo (multiple packages) or single-app
3. Services: Supabase, Stripe, Trigger.dev, Sentry, PostHog, Resend, R2, etc.

If the user said "build a SaaS with Supabase and Stripe" — infer all three, don't ask.

Step 2: Scaffold

Single-app:

pnpm create next-app . --typescript --tailwind --app --src-dir --use-pnpm --skip-install

Then delete eslint.config.mjs and remove eslint / eslint-config-next from devDeps — we use Biome.

Monorepo: load references/monorepo-scaffold.md for the full directory layout, pnpm-workspace.yaml, root package.json, and shared-package package.json templates. Run pnpm create next-app into packages/web/ and clean up the nested .git / .gitignore / README / ESLint config.

Step 3: Configure Tooling

Load references/tooling-config.md — it has the ready-to-paste templates for TypeScript (strict with noUncheckedIndexedAccess et al.), Biome (replaces ESLint + Prettier, excludes CSS for Tailwind v4), shadcn/ui v4, .gitattributes (cross-platform EOLs), .gitignore additions beyond create-next-app, and .npmrc.

Step 4: Install and Verify

pnpm install
pnpm typecheck       # must pass clean
pnpm run build       # must pass clean
pnpm run lint        # biome check must pass clean

Fix any issues before proceeding. Auto-fix Biome lint: biome check --write .

Step 5: Generate CLAUDE.md

Read real project state with Read and Glob tools (not node -e one-liners). Include:

• Project name + one-line description
• Stack (from actual deps: "Next.js 15 + Tailwind 4 + shadcn v4 + Supabase + Biome")
• Every script from all package.json files
• Key directories (from file tree)
• Environment variables (from .env.example)
• Test runner (whatever is installed)

If CLAUDE.md already exists, merge new info — don't overwrite.

Step 6: Environment Setup

Create .env.example with variables for detected/requested services:

Step 7: Create prd.json (only if user has a plan)

If the user described features or provided a plan:

• Parse into real stories with acceptance criteria
• Group into sprints (5-8 stories, max 40 points)
• Follow the core skill's story format

Do NOT generate generic starters ("Auth flow", "Dashboard layout"). If there is no plan, skip prd.json entirely.

Step 8: Git Init + First Commit

If not already a git repo:

git init
git add -A
git commit -m "feat: initial project scaffold"

Step 9: Report

Project created:
- Structure: [monorepo/single-app] with [N] packages
- Stack: [detected]
- Tooling: Biome 2.4 (strict), TS 5.8 (strict + noUncheckedIndexedAccess)
- Components: shadcn v4 (base-nova, oklch)
- CLAUDE.md: Created
- .env.example: [N] services configured
- [prd.json: N stories in sprint 1] (if created)

All checks pass: typecheck, build, lint

Say 'auto' to start working, or describe what to build next.

Onboard Mode (Existing Project)

Step 1: Stack Detection

Read package.json dependencies and scan for config files using Read and Glob.

Dependency signals:

Config file signals:

Step 2: Generate CLAUDE.md

Same as Create mode Step 5. Read real project state, generate from actual data.

Step 3: Recommend Skills

Always: review, commit, fix

Conditional:

Step 4: Check for Gaps

• .env.example missing → create it
• .gitignore missing .claude/, .env → add entries
• .gitattributes missing → create it
• TypeScript missing noUncheckedIndexedAccess → suggest enabling
• No linter → suggest Biome
• .claude/agent-memory/ missing → create it (audit and brainstorm will seed the files themselves on first run)
• .env.local has 3+ vars AND no doppler.yaml → offer to migrate to Doppler via the doppler skill (hub/spoke pattern, rotate everywhere)

Step 5: Report

Project onboarded:
- Stack: [detected]
- CLAUDE.md: Created/Updated
- Gaps fixed: [list]
- Recommended skills: [list]

Say 'auto' to start working, or describe what to build.

Step 6: Recommend Context7 MCP (optional)

Check if Context7 tools are already available (mcp__plugin_context7_context7__*). If not, suggest installing:

Context7 MCP — real-time library docs for migrate/fix (optional but recommended):
  npx ctx7 setup --claude

claude-auto-dev skills (migrate, fix) will use Context7 automatically when available.

Version Defaults

Load references/version-defaults.md for the pinned safe-version table (Next 15.3, React 19.2, TS 5.8, Tailwind 4.2, Biome 2.4, Supabase 2.101 / SSR 0.10, Zod 3.24, shadcn 4.1, pnpm 10.x, Vitest 4.1, Playwright 1.59, Stripe 21.x, Sentry 10.47, PostHog 1.364, Trigger.dev 4.4, Drizzle 0.45, lucide-react 1.7). Updated April 2026.