# Project Scaffolding

> Scaffolds a new project's initial file/folder structure, tooling, and config based on its tech stack and project type (a Python service, a Next.js app, a monorepo, a CLI tool, etc.) — asking which stack and project type apply before generating anything, rather than assuming. Use when asked to "scaffold a project", "set up a new [stack] project", "bootstrap this repo", "create the initial structure for", or similar, before meaningful code exists.

- Skill: `ghosteken/project-scaffolding` (Agent Skill)
- Install (CLI): `npx get-skill add ghosteken/project-scaffolding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ghosteken/project-scaffolding/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Ghosteken (https://skillmd.com/u/ghosteken)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/ghosteken/project-scaffolding

---


# Project Scaffolding

## Overview

Creates a new project's starting structure — folder layout, package/dependency config, linter/formatter setup, a minimal working entry point, and test scaffolding — grounded in the real, current conventions for its actual tech stack and project type, not a generic template. Unlike most skills in this library, its output belongs inside the project's own repo — scaffolding a project *is* creating the project's files, so this is one of the deliberate exceptions to the external-output-path convention (alongside `context-engineering` and `figma-design-to-code`).

## When to Use

- A new project (or a new package/app inside an existing monorepo) needs its initial structure, and nothing meaningful exists yet
- The user names a stack, framework, or project type ("a Next.js app," "a Python FastAPI service," "a pnpm monorepo") — or needs to be asked which applies
- NOT when the project already has real code and structure — that's an existing codebase, not a scaffold; use `acquire-codebase-knowledge` to understand it instead
- NOT when what to build is still unclear — scaffolding sets up *how* the code will be organized, not *what* it does; run `spec-driven-development` first if the feature set itself isn't decided yet

## Process

### 1. Determine stack, project type, and structure — before generating anything

Use the `AskUserQuestion` tool, batched, before creating a single file:

- **Language/runtime** (if not already stated) — Python, TypeScript/Node, Go, etc.
- **Framework** (if applicable to the stack) — Next.js, FastAPI/Django, NestJS/Express, or none (plain library/CLI).
- **Application layer** — frontend only, backend only, or full-stack (both) — whenever the stack/framework alone doesn't settle it (Next.js, SvelteKit, and similar can legitimately be any of the three; FastAPI or a CLI tool usually doesn't need asking). This decides whether frontend and backend get separate top-level structures or a single one.
- **Project topology** — single app/package, or a monorepo/workspace (and if a monorepo: which workspace tool — pnpm workspaces, npm workspaces, Turborepo, Nx, a uv workspace).
- **Package manager** — npm/pnpm/yarn/bun, pip/poetry/uv, Go modules, etc.

Skip asking anything the user already stated directly — same rule `breakdown-feature-implementation` uses for resolving its stack: stated beats detected beats asked. If the project directory already has *some* files (a partial start, not a full codebase), detect and match what's already there instead of re-asking.

### 2. Resolve the tooling — decide most of it, ask only the genuine forks

A scaffold is more than folders: it's also which testing framework, validation library, ORM, logging, and git-hook setup the project starts with. Get this right the same way `breakdown-feature-implementation` and `spec-driven-development` do: read `references/library-reuse.md` for the stack Step 1 resolved — both its main category table and the "Project Scaffolding & Developer Tooling" section — and use its "Decide vs. Ask" guidance as the actual rule, not a suggestion:

- **Decide without asking** for everything that reference marks as a settled default for this ecosystem — linter + formatter + type-checking, git hooks + lint-staged, structured logging, security headers, env-var validation at startup paired with a `.env.example` template committed alongside the real (gitignored) `.env`, secret detection, dependency vulnerability scanning wired into CI, a CI pipeline skeleton, `.gitignore`, a health endpoint. Don't turn these into questions; a question for something with one clearly-correct answer is friction, not thoroughness.
- **Ask, batched in one `AskUserQuestion` round**, for two different kinds of question — don't conflate them:
  - **Genuine forks** — the capability is needed, but which option isn't settled by the framework: test framework when the framework itself doesn't already dictate one, ORM/database shape, validation approach when the framework doesn't dictate one, and self-managed vs. managed-provider auth.
  - **Optional add-ons** — capabilities that are genuinely nice-to-have rather than required for any project: API docs/OpenAPI generation, error tracking (Sentry), distributed tracing (OpenTelemetry), load testing setup, commit-message linting, a dependency-update bot. Don't silently decide these are wanted just because `references/library-reuse.md` lists a good default for them — ask.

  Mark the recommended option in each question rather than presenting a bare unranked list. Skip a question entirely when the framework from Step 1 already settles it (e.g. NestJS settles validation toward `class-validator`/`class-transformer` and testing toward Jest + `@nestjs/testing` — don't ask what the framework already answers).

  **Every question in this round includes an explicit opt-out — "Skip / not needed right now" — not just a choice among the recommended libraries.** This applies even to a genuine-fork question: "none, I'll do this myself" or "not needed for this project" is always a valid fourth answer alongside the 2-3 real options, never forced into picking one of the libraries on offer. Choosing skip means that category is simply left out of the scaffold entirely — not stubbed in with a placeholder, a commented-out config, or an installed-but-unconfigured dependency "in case it's needed later."
- **For a stack genuinely not covered in `references/library-reuse.md`** (a language or framework the table doesn't list), search the web for that ecosystem's current, actually-recommended defaults for the same categories — don't fall back to a different ecosystem's library, and don't guess from memory alone when a quick search would confirm what's current.

Once resolved, state the full recommended stack back to the user as a labeled list before moving on — the same shape a senior engineer would hand you unprompted:

```
Recommended for this [stack/framework] [project type]:
- Runtime: ...
- Framework: ...
- Validation: ...
- Database: ...
- Testing: ...
- Logging: ...
- Security: ...
- API docs: ...
- Code quality: ...
- Git hooks: ...
```

Omit any line that's genuinely not applicable (no "API docs" line for a CLI tool, no "Database" line for a stateless library) or that the user skipped in the round above. This list is what gets confirmed in the next step alongside the file tree — not a separate, later decision made silently while generating files.

### 3. Confirm the plan before writing

List exactly what will be created — the folder tree, the key config files, the resolved tooling stack from Step 2, and the initial dependencies — and confirm it with the user before generating anything. Scaffolding writes many files in one pass; that's expensive to undo compared to one file at a time, so the confirmation gate matters more here than in most skills.

### 4. Create the structure

Generate the folder layout, package/dependency manifest, linter/formatter config, a minimal working entry point (not a placeholder that doesn't run), `.gitignore`, and test scaffolding — following that stack and framework's real, current conventions, and installing exactly the tooling resolved and confirmed in Step 2, not whatever feels natural while generating. For a monorepo: the workspace config, the `apps/`/`packages/` layout, and shared base configs (tsconfig, eslint) that apps/packages extend rather than duplicate.

**Tests and git hooks are part of every scaffold, not an optional extra.** Include the test runner already wired up with at least one real, passing test against the entry point (a genuine smoke test, not an empty test directory with nothing in it) — see `test-driven-development` for what a real test looks like versus a placeholder. Install and configure a pre-commit git hook per Step 2's resolved choice (Husky + lint-staged for Node/TypeScript, `pre-commit` for Python, `lefthook` as the cross-language option) running lint and the test suite before every commit, not just present as an installed dependency with no hook actually wired to run. **A git hook is never a substitute for CI** — also scaffold a basic CI pipeline (GitHub Actions, or the project's existing CI) running the same checks independently, since hooks can be bypassed.

**Structure by concern, not by convenience.** Every layer gets dedicated folders for its own distinct responsibilities, matching that stack's real convention — a backend separates routes/controllers from services/business logic from models/data access from config; a frontend separates components from pages/routes from hooks from lib/api-clients/utils. Never collapse these into one flat folder or a single catch-all file, even for a minimal starting scaffold — the tree itself should make the separation obvious, not just file naming within one folder. For a full-stack project, keep frontend and backend as clearly separated top-level concerns — either their own packages in a monorepo, or clearly separated top-level folders — never intermixed in one undifferentiated structure.

This applies regardless of language or framework — the specific folder names below are illustrative, not a template to copy literally; use whatever that ecosystem's own convention actually calls each one:

- **A shared/common area for cross-cutting code** — types/interfaces, constants, utility functions, error classes, config loading — that more than one layer or module genuinely depends on. This is a single named place (`shared/`, `common/`, `lib/`, `internal/common/`, whatever the ecosystem calls it), not duplicated independently wherever it's next needed, and not a dumping ground for anything that doesn't obviously belong elsewhere — only code with more than one real consumer goes here.
- **The shape of data crossing a boundary, kept separate from how that data is stored.** Whatever a request/response, an API contract, or a message payload looks like (DTOs, schemas, view models — whatever the ecosystem's own term is) lives in its own place, distinct from the persistence layer's own representation (entities, models, database rows) — even when the two look identical today for a trivial case. Collapsing them into one type is exactly what breaks the first time they need to diverge (an API field that's computed, not stored; a stored field that's never exposed).
- **Database/persistence access isolated behind its own layer** — queries, the ORM/model definitions, migrations — never inlined directly into route handlers or business logic. A service or controller calls into this layer; it doesn't construct queries itself.
- **For any project exposing an API, a versioning strategy stated from the first endpoint** — a URL prefix (`/v1/...`), a header, or whatever convention `api-and-interface-design` recommends for this stack — not deferred until a breaking change actually forces the question. Retrofitting versioning onto an already-shipped unversioned API is far more disruptive than starting with it.

Each of these is a real folder or module in the generated tree, not merely a naming convention within one flat directory — if genuinely unsure what that ecosystem calls one of these concerns, ask rather than invent a name no one in that ecosystem would recognize.

Ground every generated file in the ecosystem's actual current convention, not a remembered one that may be stale — if genuinely unsure of a specific version or convention, ask rather than guess.

### 5. Verify it actually runs

Install dependencies and run the stack's equivalent of a smoke test — the dev server starts, the entry point runs, the test suite's at-least-one real test actually passes (not zero tests, not an error), and the git hook actually fires on a trial commit and runs lint/tests. A scaffold that doesn't actually run — or whose test or hook is present but silently does nothing — is a broken deliverable, not a starting point.

### 6. Hand off

Tell the user what was created and where. Point to the natural next step: `spec-driven-development` if the feature set isn't defined yet, or straight into `incremental-implementation`/`test-driven-development` if it is.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I can guess the stack from context" | A wrong guess means regenerating everything — ask via `AskUserQuestion` up front; that's one round before dozens of files, not after. |
| "I'll use a generic folder structure that works for any stack" | Every ecosystem has its own real convention (Next.js's `app/` router, a Python package's `src/` layout) — a generic structure reads as unfamiliar to anyone who actually knows that stack. |
| "I don't need to confirm the plan, I'll just build it" | Scaffolding writes many files in one pass — confirm the plan first, the same way a large diff gets reviewed before it lands, not after. |
| "The files are there, that's good enough" | A scaffold that doesn't actually install and run is a broken starting point — verify it before calling it done. |
| "I'll skip the monorepo tooling setup, they can add it later" | A monorepo without its workspace config isn't a monorepo yet — set that up as part of the scaffold, not as a follow-up. |
| "It's small right now, I'll put everything in one folder" | A scaffold models the structure the project grows into — separation of concerns is far cheaper to keep in place from the start than to retrofit once real code has accumulated in one flat folder. |
| "The request shape and the database model look identical right now, I'll just use one type" | They diverge the moment either side needs something the other doesn't — a computed response field, a stored-but-never-exposed column. Keep them as separate concerns from the start even when today's version would technically work collapsed. |
| "I'll put this shared util wherever it's needed first, not a dedicated shared folder" | That's how the same logic ends up duplicated in two or three places independently — one named shared/common location is what makes it a single thing to find and change. |
| "I'll just build the query inline in the handler, it's one line" | That's exactly how persistence access stops being isolated — the handler calls into a data-access layer, it doesn't construct queries itself, regardless of how small the query looks today. |
| "It's a full-stack-capable framework, I don't need to ask which layer" | The framework name alone doesn't settle it — some can legitimately be frontend-only, backend-only, or full-stack; ask when it's genuinely ambiguous rather than assuming full-stack by default. |
| "An empty test directory is enough, they'll add real tests later" | A test suite with nothing in it doesn't prove the test runner is actually wired correctly — include one real, passing smoke test now, the same way the entry point itself has to actually run, not just exist. |
| "I'll add the git hook package but skip wiring an actual hook script" | An installed-but-unconfigured Husky/pre-commit dependency enforces nothing — the hook has to actually fire and run lint/tests on a real commit, not just sit in `package.json`. |
| "I'll just ask which library for each category, the user can always say no" | A pick-one question with no opt-out forces an answer even when the real answer is "I don't want this capability at all" — every question needs an explicit skip option, not an implicit one the user has to invent themselves. |
| "`references/library-reuse.md` lists a good default for Swagger/Sentry/etc., I'll just include it" | A good default for a category doesn't mean the project wants that category at all — optional add-ons (API docs, error tracking, tracing, load testing, commit linting) get asked, with skip as a real answer, not silently included because a default exists. |
| "They skipped this category, I'll add a placeholder so it's easy to turn on later" | A skip means leave it out entirely — a commented-out config or an installed-but-unused dependency is exactly the "stubbed in" outcome skip was meant to avoid. |

## Red Flags

- Files generated before the stack/project type was confirmed
- A generic structure that doesn't match the actual ecosystem's real convention
- No confirmation of the plan before writing dozens of files
- A scaffold that was never actually run/installed to confirm it works
- A monorepo missing its workspace config
- A flat structure with no dedicated folder per concern (routes, services, models, components, etc.)
- No shared/common area for cross-cutting code, or the same utility/type/constant duplicated in more than one place instead of living there once
- Request/response or API-contract types collapsed into the same type as the database model/entity, instead of kept as separate concerns
- A query or ORM call constructed directly inside a route handler or controller instead of going through a dedicated data-access layer
- No `.env.example` committed alongside a gitignored `.env`, or no secret-detection/dependency-vulnerability-scanning step at all
- An API scaffold with no versioning strategy stated for its first endpoint
- Frontend and backend code intermixed in one undifferentiated structure on a full-stack project
- Application layer (frontend/backend/full-stack) assumed instead of asked, on a framework where it was genuinely ambiguous
- A tooling question with no "skip / not needed" option, forcing a choice among libraries when the real answer might be "none of these"
- An optional add-on (API docs, error tracking, tracing, load testing, commit linting) included without ever asking whether it was wanted
- A skipped category left in anyway as a placeholder, commented-out config, or unused installed dependency
- Every single tool asked about one at a time, including ones `references/library-reuse.md` already marks as a settled default (over-asking is also a Red Flag, not just under-asking)
- An empty test directory with no real test in it
- Husky (or the ecosystem's equivalent) installed as a dependency but no hook script actually wired to run on commit

## Verification

- [ ] Stack, project type, application layer (frontend/backend/full-stack), and topology were determined via `AskUserQuestion` (or already stated), not guessed
- [ ] `references/library-reuse.md` (main table + Project Scaffolding & Developer Tooling section) was read for this stack before any tooling question was asked or decided
- [ ] Settled-default tooling (lint/format/type-check, git hooks, logging, env validation, CI skeleton) was decided without asking; genuine forks and optional add-ons were asked, batched, each with a "skip / not needed" option
- [ ] The resolved tooling stack was stated back to the user as a labeled list and confirmed alongside the file tree, before any file was written
- [ ] Any category the user skipped was left out entirely — no placeholder, commented-out config, or unused dependency for it
- [ ] The generated structure has dedicated folders per concern (routes/services/models, or components/pages/hooks/lib, as applicable) — not a flat or catch-all layout
- [ ] Cross-cutting code (types, constants, utilities, error classes) lives in one shared/common area, not duplicated wherever it's next needed
- [ ] Data-contract types (DTOs/schemas/view models) are kept separate from the persistence layer's own models/entities, in whatever ecosystem-appropriate location, not collapsed into one type
- [ ] Database/persistence access is isolated in its own layer, not constructed inline inside route handlers or business logic
- [ ] A `.env.example` is committed alongside a gitignored real `.env`, and secret detection + dependency vulnerability scanning are wired into the scaffold (pre-commit and/or CI)
- [ ] An API-exposing project states its versioning strategy from the first endpoint, not deferred
- [ ] On a full-stack project, frontend and backend are clearly separated (own packages or own top-level folders), not intermixed
- [ ] At least one real, passing test exists against the entry point — not an empty test directory
- [ ] A pre-commit git hook (Husky, or the ecosystem's real equivalent) is installed, actually wired to run lint/tests, and was confirmed to fire on a trial commit
- [ ] Any partial existing files in the project were detected and matched, not overwritten or ignored
- [ ] The planned structure was confirmed with the user before any file was written
- [ ] Every generated file follows that stack/framework's real, current convention
- [ ] The scaffold was actually installed and run to confirm it works, not just assumed to
- [ ] The user was told what was created and the natural next step

## See Also

- `spec-driven-development` — upstream, if the feature set itself isn't decided yet; this skill sets up *how* code is organized, not *what* it does
- `references/library-reuse.md` — the per-ecosystem default libraries this skill decides or asks about for every tooling category (validation, ORM, testing, logging, git hooks, CI, and the rest)
- `context-engineering` — for agent rules files (`.cursorrules`, `AGENTS.md`, etc.), a related but distinct kind of in-repo setup
- `incremental-implementation` / `test-driven-development` — the natural next step once the scaffold exists
- `acquire-codebase-knowledge` — for understanding an *existing* codebase's structure, rather than creating a new one

