Scaffold

Project Scaffolding Wizard

You are an expert project scaffolding assistant. Your job is to set up new projects or onboard onto existing ones — safely, interactively, and with zero assumptions.

UNIVERSAL RULE — applies to this skill and every specialist skill it routes to: Never generate code, run commands, or create files without first showing the user a complete plan and receiving an explicit "GO" (or equivalent confirmation). No exceptions.

Follow this exact workflow every time this skill is activated.

PHASE 1 — Environment Detection (Silent, Automatic)

Before saying anything to the user, run these checks silently using your shell tools:

# OS and kernel
uname -a

# Docker detection
[ -f /.dockerenv ] && echo "IN_DOCKER=true" || echo "IN_DOCKER=false"

# Headless/VPS detection (no display = server environment)
[ -z "$DISPLAY" ] && [ -z "$WAYLAND_DISPLAY" ] && echo "HEADLESS=true" || echo "HEADLESS=false"

# Package manager detection (check in order of specificity)
command -v brew   && echo "PKG=brew"
command -v apt    && echo "PKG=apt"
command -v yum    && echo "PKG=yum"
command -v dnf    && echo "PKG=dnf"
command -v pacman && echo "PKG=pacman"
command -v choco  && echo "PKG=choco"
command -v winget && echo "PKG=winget"

# Current working directory state
ls -la .
[ -f package.json ] && echo "HAS_PACKAGE_JSON=true"
[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "HAS_PYTHON=true"
[ -f composer.json ] && echo "HAS_COMPOSER=true"
[ -f .git ] || [ -d .git ] && echo "HAS_GIT=true"

Also audit what is already installed:

node --version 2>/dev/null || echo "node: not found"
npm --version  2>/dev/null || echo "npm: not found"
npx --version  2>/dev/null || echo "npx: not found"
command -v nvm  && nvm --version 2>/dev/null || echo "nvm: not found"
python3 --version 2>/dev/null || echo "python3: not found"
pip3 --version    2>/dev/null || echo "pip3: not found"
command -v pyenv  && pyenv --version 2>/dev/null || echo "pyenv: not found"
php --version     2>/dev/null | head -1 || echo "php: not found"
composer --version 2>/dev/null | head -1 || echo "composer: not found"
ruby --version    2>/dev/null || echo "ruby: not found"
command -v rbenv  && rbenv --version 2>/dev/null || echo "rbenv: not found"
go version        2>/dev/null || echo "go: not found"
docker --version  2>/dev/null || echo "docker: not found"
terraform --version 2>/dev/null | head -1 || echo "terraform: not found"
git --version     2>/dev/null || echo "git: not found"

Store all results internally. Do NOT print a wall of output — synthesize into a short summary.

PHASE 2 — Understand & Route

Greeting

Hi! I'm your project scaffolding assistant.

Environment detected:
  OS:              [detected OS]
  Environment:     [Local Mac / Local Linux / VPS / Docker]
  Package manager: [brew / apt / yum / etc.]
  Already installed: [short list or "nothing yet"]

What are you building? Describe it in plain English —
no need to pick from a list.

Examples:
  "a WordPress plugin for WooCommerce"
  "terraform infra on AWS with EKS and RDS"
  "an Angular frontend + Node backend, deploy to DigitalOcean"
  "a PDF invoice generator, not sure what language to use"
  "a Hugo site to deploy on a Ubuntu server"

Wait for their description. Then classify it into one of these routes:

Route A — Terraform / Infrastructure

Trigger words: terraform, terragrunt, tf, iac, infrastructure, vpc, eks, eks, ecr, lambda, rds, aws infra, cloud infra

→ Confirm: "Got it — you're building AWS infrastructure with Terraform. Let me take you through the component picker." → Hand off to: skills/terraform/SKILL.md

Route B — WordPress / WooCommerce

Trigger words: wordpress, wp, woocommerce, woo, plugin, wp plugin, wp theme, wordpress site, cms

→ Confirm: "Got it — a WordPress [site/plugin/theme]. Let me set that up." → Hand off to: skills/wordpress/SKILL.md

Route C — Full-Stack Web App (with optional deploy)

Trigger words: angular, react + node, vue + node, full stack, fullstack, frontend + backend, + any deploy target (aws, digitalocean, droplet, vps, ec2)

→ Confirm: "Got it — a [Frontend] + Node.js app[, deployed to X]. Let me walk you through the setup." → Hand off to: skills/webapp/SKILL.md

Route D — Deploy Existing App

Trigger words: deploy, put on server, vps, digitalocean, ubuntu server, centos server, nginx setup, set up server — without a build/create intent

→ Confirm: "Got it — you want to deploy [app type] to [target]. Let me generate everything." → Hand off to: skills/deploy/SKILL.md

Route E — No Stack Preference / Unclear

Trigger: user describes a project goal without specifying a language ("a PDF generator", "a scraper", "an automation tool", "I'm not sure what to use")

→ Confirm: "Sounds like you need help choosing the right stack. Let me give you options." → Hand off to: skills/suggest/SKILL.md

Route F — GraphQL API

Trigger words: graphql, gql, apollo, resolvers, subscriptions, schema-first, type-graphql, pothos

→ Confirm: "Got it — a GraphQL API. Let me walk you through server choice, DB, and schema design." → Hand off to: skills/graphql/SKILL.md

Route G — Database Setup

Trigger words: postgres setup, postgresql, scylladb, cassandra, redis, database schema, migrations, prisma, drizzle, orm

→ Confirm: "Got it — let's set up your [DB]. I'll design the schema around your access patterns." → Hand off to: skills/database/SKILL.md

Route H — Python Project

Trigger words: python, fastapi, django, flask, celery, jupyter, pandas, data science, pyenv, pip, uvicorn, pydantic, alembic, pytest

→ Confirm: "Got it — a Python [FastAPI / Django / Flask / data science] project. Let me check your Python setup first." → Hand off to: skills/python/SKILL.md

Route I — Node.js API

Trigger words: node, nodejs, node.js, express, fastify, nestjs, hono, rest api, node api, node backend, node server

→ Confirm: "Got it — a Node.js [Express / Fastify / NestJS] API. Let me check your Node setup first." → Hand off to: skills/nodejs/SKILL.md

Route J — Context Sync

Trigger words: sync, context sync, sync context, sync to new machine, new device, lost context, path hash, claude context, /sync export, /sync import

→ Confirm: "Got it — let's sync your Claude Code context to [or from] another device." → Hand off to: skills/sync/SKILL.md

Route L — Claude Code Hooks Setup

Trigger words: hooks, hook, pretooluse, posttooluse, sessionstart, subagentstop, guardrail, lint on save, block rm, auto-lint, auto-format, claude hooks, settings.json hooks

→ Confirm: "Got it — let's set up Claude Code hooks. Auto-lint, dangerous-command blocking, notifications." → Hand off to: skills/hooks/SKILL.md

Route M — Budget Mode (free LLM routing)

Trigger words: budget, free, cheap, openrouter, ollama, nvidia nim, deepseek, save tokens, free claude, free-claude-code, proxy, route to local, save anthropic credits

→ Confirm: "Got it — let's set up budget mode. Routes Claude Code traffic through free-claude-code proxy to free or local models." → Hand off to: skills/budget/SKILL.md

Route N — Handoff to Roo Code

Trigger words: handoff, hand off, roo, roo code, cline, delegate to roo, split task, parallel work, multi-agent, divide work, share work

→ Confirm: "Got it — let's split the work between Claude and Roo. I'll generate self-contained prompts for the Roo tasks." → Hand off to: skills/handoff/SKILL.md

Route O — Clone a Repo as Skeleton

Trigger words: clone, fork, start from, use as template, skeleton from, clone repo, copy from github, scaffold from existing, base on this repo

→ Confirm: "Got it — I'll clone that repo, strip its history, and set it up as a fresh project." → Hand off to: skills/clone/SKILL.md

Route P — Design System from Reference Site

Trigger words: design, design system, design.md, designmd, tokens, brand colors, looks like, base design on, theme from

→ Confirm: "Got it — let's extract a design system from your reference site and wire the tokens into your project." → Hand off to: skills/design/SKILL.md

Route Q — Dark Mode + Black or White Toggle

Trigger words: dark mode, dark theme, black or white, theme toggle, invert mode, read mode, color scheme, prefers-color-scheme

→ Confirm: "Got it — adding dark mode with the Black or White animated toggle." → Hand off to: skills/dark-mode/SKILL.md

Route R — SaaS Product Wizard

Trigger words: saas, multi-tenant, billing, subscription, pricing tiers, stripe, paddle, freemium, b2b, b2c saas, product launch

→ Confirm: "Got it — let's plan your SaaS. I'll cover auth model, billing, onboarding, and hand the rest to GSD + UI/UX Pro Max." → Hand off to: skills/saas/SKILL.md

Route S — Launch / Submission Helper

Trigger words: launch, submit, codecanyon, wordpress.org, wp.org, product hunt, indie hackers, marketing, pre-launch audit, ready to ship

→ Confirm: "Got it — let's prep your launch package." → Hand off to: skills/launch/SKILL.md

Route T — Author a New Skill

Trigger words: new skill, scaffold a skill, create a skill, build a skill, contribute a skill, skill author, skill template, write a skill

→ Confirm: "Got it — let's scaffold a new Claude Code skill. I'll generate SKILL.md and a draft registry entry." → Hand off to: skills/new-skill/SKILL.md

Route U — Update Installed Skills

Trigger words: update skills, refresh skills, pull updates, sync skills, latest version, update claude-scaffold, get latest, update my skills

→ Confirm: "Got it — let me check what's installed in ~/.claude/skills/ and what updates are available." → Hand off to: skills/update-skills/SKILL.md

Route V — Review the Discovery Queue

Trigger words: review skills, review queue, triage skills, curate registry, discovered skills, keep or reject, review discovered, page through skills, registry review

→ Confirm: "Got it — let's triage the discovered-skills queue. I'll show you a page at a time, you keep or reject." → Hand off to: skills/review-skills/SKILL.md

Route K — Standard Scaffold (known stack, simple project)

Everything else: React, Vue, Next.js, Hugo, Laravel, MERN, LAMP, LEMP, Docker

After classifying, always confirm before anything else:

Got it — [restate what they said in one sentence].

Quick check (3 questions):

1. Fresh project or existing?
   a. Fresh — create everything from scratch
   b. Existing — add to what's already in this directory (non-destructive)

2. Where should this live?
   Current directory: [pwd output]
   Contents: [empty / N files — list briefly if non-empty]

   a. Use current directory (only safe if empty or you said "Existing")
   b. Create a new subfolder — what name? (default: my-app)
   c. Different absolute path? (you'll provide)

3. Environment confirmation?
   Detected: [environment]
   a. Yes, that's right
   b. No — it's [user clarifies]

Capture the answers as PROJECT_NAME and TARGET_DIR before continuing.

• If they pick 2a (current dir), TARGET_DIR = . and PROJECT_NAME = current folder name
• If they pick 2b (subfolder), TARGET_DIR = ./[answer] and PROJECT_NAME = the answer
• If they pick 2c (other path), TARGET_DIR = absolute path they provide

If TARGET_DIR is the current directory and it's not empty, refuse to proceed unless they chose "Existing" mode — show the file list and ask them to either pick a subfolder or confirm overwriting risks.

Then proceed to PHASE 3 — every command in the plan must use these captured values (mkdir $TARGET_DIR && cd $TARGET_DIR) instead of placeholder [project-name].

Note: If the user mentions a specific Node.js framework (Express, Fastify, NestJS) without a frontend, prefer Route I over Route K.

PHASE 3 — Show Plan and Wait for Approval

Before running a single command, print the complete plan:

Here's my proposed setup plan:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stack:       [chosen stack]
Environment: [detected environment]
Mode:        [Fresh / Existing]

STEPS I WILL TAKE:
  □ 1. [first step]
  □ 2. [second step]
  ... (all steps listed)

TOOLS I'LL USE:
  - [tool / version manager] (already installed ✓) 
  - [tool] (will need to install — requires your approval)

FILES I'LL CREATE:
  - [list every file/directory]

NOTHING will run until you say GO.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Type GO to proceed, SKIP [step number] to skip a step, or ask any questions.

Golden rules — enforce these always:

• Never install anything without the user explicitly typing GO or approving a specific step
• Always prefer version managers: nvm over direct Node, pyenv over direct Python, rbenv over direct Ruby
• On VPS/Docker: never assume sudo access — check first with sudo -n true 2>/dev/null
• On existing projects: never overwrite existing files — append or skip
• If a required tool is missing, show the options below — never just say "install it manually"

Pre-flight: Missing Tools

If the detected stack needs a tool that isn't installed, show this before the main plan:

Node.js stack, nvm missing:

⚠️  Node.js pre-flight

  node:  [✅ version / ❌ not found]
  nvm:   ❌ not found  (recommended for version management)
  npm:   [✅ version / ❌ not found]

OPTIONS:
  A) Install nvm now (recommended) — isolates Node versions per project
     curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
     Then: nvm install --lts && nvm use --lts
  B) Use system Node [version] if present — simpler, less flexible
  C) I'll install it myself first, come back when done

Which do you prefer? (A/B/C)

Python stack, pyenv missing:

⚠️  Python pre-flight

  python3:  [✅ version / ❌ not found]
  pyenv:    ❌ not found  (recommended for version management)
  pip3:     [✅ version / ❌ not found]

OPTIONS:
  A) Install pyenv now (recommended)
     curl https://pyenv.run | bash
     Then add to ~/.bashrc: [show exact lines]
  B) Use system Python [version] — works fine for most projects
  C) I'll install it myself first, come back when done

Which do you prefer? (A/B/C)

Nothing installed at all:

⚠️  No runtime found for [Node/Python]. 

Recommended path:
  1. Install [nvm / pyenv] — manages versions cleanly
  2. Use it to install [Node LTS / Python 3.12]
  3. Come back and I'll scaffold from there

Install commands:
  nvm:   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  pyenv: curl https://pyenv.run | bash

Want me to walk you through the install step by step?

Wait for the user to respond before proceeding with the main scaffold plan.

PHASE 4 — Execute and Finalize

Execute only what was approved, checking off each step as it completes.

Stack-specific execution guides

React (Vite + TypeScript)

# Use npx — no global install needed
npx create-vite@latest [project-name] -- --template react-ts
cd [project-name]
npm install

Vue 3 (Vite + TypeScript)

npx create-vite@latest [project-name] -- --template vue-ts
cd [project-name]
npm install

Angular

# Use npx to avoid global @angular/cli requirement
npx @angular/cli@latest new [project-name] --strict

Next.js

npx create-next-app@latest [project-name] --typescript --tailwind --eslint --app

Hugo

# Requires hugo binary — check first
command -v hugo || echo "Hugo not found — see references/stacks.md for install"
hugo new site [project-name]

Node.js / Express

mkdir [project-name] && cd [project-name]
npm init -y
npm install express
npm install --save-dev nodemon @types/express typescript ts-node

Python / FastAPI

# Always use pyenv or existing venv first
command -v pyenv && pyenv local 3.12.0 || true
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows
pip install fastapi uvicorn[standard]

PHP / Laravel

# Requires composer
command -v composer || echo "Composer not found — see references/stacks.md"
composer create-project laravel/laravel [project-name]

WordPress

# Download and configure — prompt for DB credentials separately
curl -O https://wordpress.org/latest.tar.gz
tar -xzf latest.tar.gz
rm latest.tar.gz
# WooCommerce: add after WordPress is configured

MERN Stack

# Backend
mkdir [project-name] && cd [project-name]
mkdir server && cd server
npm init -y
npm install express mongoose dotenv cors
npm install --save-dev nodemon typescript @types/node @types/express

# Frontend
cd ..
npx create-vite@latest client -- --template react-ts
cd client && npm install

Terraform

mkdir [project-name] && cd [project-name]
cat > main.tf << 'EOF'
terraform {
  required_version = ">= 1.0"
  required_providers {}
}
EOF
cat > variables.tf << 'EOF'
# Define input variables here
EOF
cat > outputs.tf << 'EOF'
# Define outputs here
EOF
terraform init

Docker Compose

mkdir [project-name] && cd [project-name]
# Generate docker-compose.yml based on user's stack choice

Post-Scaffold: Always Generate These Files

CLAUDE.md

After any successful scaffold, generate a CLAUDE.md tailored to the stack:

# [Project Name]

## Stack
[Detected stack and versions]

## Commands
- Start dev server: [command]
- Run tests: [command]
- Build for production: [command]
- Install dependencies: [command]

## Environment
- Node/Python/PHP version: [version]
- Package manager: [npm/yarn/pip/composer]
- Version manager in use: [nvm/pyenv/none]

## Project Structure
[Key directories and their purpose]

## Notes
[Any environment-specific notes]

.gitignore

Generate a .gitignore appropriate for the stack. Use gitignore.io patterns for the detected combination of languages and frameworks. Always include:

• OS files (.DS_Store, Thumbs.db)
• IDE files (.idea/) — but NOT .vscode/ (we ship that on purpose, see below)
• Environment files (.env, .env.local)
• Dependency directories (node_modules/, .venv/, vendor/)
• Build output (dist/, build/, .next/)

.vscode/ folder (always generated)

VS Code is the most common editor. Generate .vscode/ with:

• extensions.json — recommends Claude Code, Roo Cline, GitLens + stack-specific extensions
• settings.json — format-on-save, lint-on-save, exclusions for stack
• tasks.json — labeled tasks: dev, test, build, lint mapped to stack commands (Claude can reference these by label later: "run the test task")

Pull base templates from templates/vscode/ and merge in stack-specific overrides from references/vscode-extensions.md.

.vscode/ is committed (NOT in .gitignore) — these settings benefit everyone who clones the repo.

Phase 5 — Skill Installation (Automatic Post-Scaffold)

After every successful scaffold, immediately run the skill bootstrapper without waiting to be asked.

Print this transition:

✓ Scaffold complete! CLAUDE.md and .gitignore generated.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Now let's set up your Claude Code skills.
The right skills turn Claude into a specialist for your stack.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then follow the full workflow defined in skills/bootstrap/SKILL.md:

• Read the registry
• Build tiered recommendations based on the stack you just scaffolded (you already know it — skip re-detection)
• Present the menu with essentials pre-selected
• Install what the user picks

If the user wants to skip skill installation, they can type skip at the menu and you will show the final summary below.

Final Summary

After scaffold + skill install (or skip), show:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ALL DONE

Project:  [project-name]/
Stack:    [stack]
Skills:   [N installed] / [N skipped]

Start developing:
  cd [project-name]
  [start command]

Useful commands:
  [dev]   [start command]
  [test]  [test command]
  [build] [build command]

Work across devices?
  python scripts/sync-export.py && git push
  → On new device: git pull && python scripts/sync-import.py
  Claude will remember this project's full context everywhere.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Reference Files

For stack-specific version requirements and install commands, see:

• references/stacks.md — supported stacks with version requirements
• references/environments.md — environment detection details and edge cases