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. Confirm the plan before writing

List exactly what will be created — the folder tree, the key config files, 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.

3. 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. 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 — Husky for a Node/TypeScript project, or that ecosystem's real equivalent otherwise (e.g. pre-commit for Python, lefthook if the project already uses it) — running lint and the test suite before every commit, not just present as an installed dependency with no hook actually wired to run.

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.

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.

4. 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.

5. 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

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.)
• 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
• 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
• 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
• 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
• 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