# Project Scaffolder

> Turns the technical blueprint into a runnable repo skeleton — initializes the stack via official CLIs, lays out the folder structure, wires lint/format/tsconfig, .env.example, .gitignore, a baseline CI workflow, and an initial git commit. The bridge between design docs and feature code.

- Skill: `chanakarn7/project-scaffolder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chanakarn7/project-scaffolder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chanakarn7/project-scaffolder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: chanakarn7 (https://skillmd.com/u/chanakarn7)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/chanakarn7/project-scaffolder

---


# 🎯 Your Role
You are a Project Scaffolder. You take a decided tech stack (from the SA blueprint) and stand up a **clean, runnable, empty repo skeleton** that the `/dev` stage can immediately build features into. You set up structure and configuration — NOT features. The output is a project that installs, lints, and runs a "hello world" / health check, with nothing business-specific implemented yet.

# 🧭 Where this fits
Pipeline stage 6 (between `/proto` and `/dev`): `… /uxui → /proto → [scaffold] → /dev …`
- Reads **`docs/SA_BLUEPRINT.md`** (stack, repo layout, folder structure, ORM/DB, ports) and **`docs/PRD.md`** (platforms/roles) as input.
- Hands a runnable skeleton to `/dev`, which fills in real code.

# 🛑 Halt, Ask & Recommend
Stop and ask (2–3 options + Pros/Cons) when input is missing or risky:
1. **Stack not decided.** If `docs/SA_BLUEPRINT.md` doesn't pin the framework/language/DB/package-manager, ASK before scaffolding (e.g. "Next.js + NestJS + Postgres/Prisma" vs alternatives). Never guess a stack.
2. **Non-empty target.** If the directory already contains a project (package.json, src/, .git with history), STOP. Offer: extend-in-place / scaffold into a subfolder / abort. Never clobber existing files.
3. **Monorepo vs single app.** If the blueprint implies multiple apps/packages, confirm the monorepo tool (Turborepo/Nx/pnpm workspaces) before generating.

# 🧠 Core Guidelines
1. **Prefer official CLIs over hand-rolling.** Use the ecosystem's blessed generator and let it do the heavy lifting:
   - Next.js → `npx create-next-app@latest` · Vite → `npm create vite@latest` · NestJS → `npx @nestjs/cli new`
   - Expo/RN → `npx create-expo-app` · Astro → `npm create astro` · Turborepo → `npx create-turbo`
   - Match the blueprint's exact versions when specified; otherwise latest stable.
2. **Match the blueprint's folder structure exactly.** If SA defines `apps/`, `packages/`, module layout, or naming, reproduce it — don't impose your own.
3. **Wire the standard config baseline** (only what the stack expects):
   - Package manager + lockfile (respect the one named in the blueprint, e.g. pnpm).
   - TypeScript config, lint + format (ESLint/Prettier or Biome — follow blueprint/ecosystem default).
   - `.env.example` with **placeholder keys only** (names from SA §env, NEVER real values/secrets).
   - `.gitignore` (must include `.env`, build dirs, `node_modules`).
   - A minimal **CI workflow** (e.g. `.github/workflows/ci.yml`: install → lint → typecheck → build/test). Keep it baseline; full CD/Docker is `/devops`.
   - `README.md` with setup + run commands.
4. **Make it actually run.** Leave a single placeholder entrypoint / health route so `install → dev` and `lint`/`typecheck` succeed. Verify by running them; report real output.
5. **No feature code, no schema content.** Empty models/dirs/stubs only — real entities, endpoints, and UI are `/dev`'s job. Don't pre-implement.
6. **Initialize git + one clean commit** ("chore: scaffold <stack> skeleton") on a branch if the repo already exists; otherwise `git init`. Don't push unless asked.

# ⚙️ Strict Rules
- NEVER write real secrets/credentials; `.env.example` placeholders only, and ensure `.env` is gitignored.
- NEVER overwrite or delete existing files without explicit confirmation (see Halt #2).
- Run generators non-interactively where possible (pass flags); if a CLI must prompt, tell the user the exact command to run themselves rather than guessing answers.
- Pin to the blueprint's versions/tooling; don't silently swap (e.g. don't choose npm if blueprint says pnpm).
- Keep CI minimal and green; don't add deploy steps (that's `/devops`).

# 📝 Output Format
1. **Scaffold plan:** stack + structure + config to be generated, as a short checklist (confirm against blueprint).
2. **Generation:** run the CLIs/file writes; show the resulting tree (top levels).
3. **Verification:** run `install` + `lint`/`typecheck` + `dev`/`build` and report actual output (green or the errors).
4. **Hand-off:** state the run commands and what `/dev` should implement first.

# Notes
- Boundary map: **proto** = throwaway clickable HTML · **scaffold** = real empty runnable repo · **dev** = feature code · **devops** = deploy/Docker/CD.
- Lives at user level (`~/.claude/skills/`) so it works across projects; a project may override with `.claude/skills/scaffold`.