| name | new-project-scaffold |
| description | Scaffolds a brand-new project with a clean, best-practice folder structure, pinned latest-stable dependencies, and a Docker Compose–ready layout. Designed to bootstrap production-ready codebases from day one. |
Skill: New Project Scaffold
Purpose
Create a production-oriented project foundation before any feature development begins.
This skill ensures the project starts with:
- A clear, layered folder structure
- Latest stable dependencies, properly pinned
- A Docker Compose–ready setup that runs consistently across environments
The goal is to avoid early technical debt and make the project immediately runnable, testable, and deployable.
When to Run
Run this skill when:
- The user says they are starting a new project
- The user asks to scaffold, bootstrap, or initialize a codebase
- The user wants a clean structure before writing any logic
- The user explicitly wants the project to be Docker-ready from the beginning
Output Expectations
By the end of this skill, the agent should deliver:
- A complete folder and file layout
- Clear dependency choices (language/framework aware)
- Docker and Docker Compose configuration that can run immediately
- A README that explains how to start the project
Step-by-Step Workflow
Step 1: Determine the Stack
From user input (or defaults if not specified), infer:
- Programming language (e.g. Node.js, Python, Go)
- Framework (if any)
- Runtime expectations (e.g. Node 20 LTS, Python 3.11+)
If unclear, assume modern defaults and state them explicitly.
Step 2: Generate a Best-Practice Folder Structure
Use a layered, intention-revealing layout.
Avoid placing application logic in the project root.
Generic Scaffold Template (adapt as needed)
project-root/
├── src/ # Application source code
│ └── main.* # Single entrypoint (framework-specific)
├── tests/ # Unit/integration tests
├── config/ # Non-secret configuration
├── scripts/ # Dev, build, or deployment scripts
├── docs/ # Optional: design docs, ADRs, runbooks
├── docker/ # Optional: Dockerfile(s), overrides
├── .env.example # Environment variable template (no secrets)
├── .gitignore
├── .dockerignore
├── README.md
├── docker-compose.yml
└── [lockfile] # package-lock.json / poetry.lock / go.sum
Structural Rules
- Exactly one application entrypoint
- Tests live outside
src/
- No secrets committed (ever)
- Configurable values come from environment variables
- Framework conventions may override naming, but not layering
For stack-specific layouts (Node/TypeScript, Python, Go) and Docker Compose with a database, see reference.md.
Step 3: Select and Pin Latest Stable Dependencies
Dependency rules are strict:
- Use latest stable releases only
- Avoid
alpha, beta, rc, next, or preview tags
- Pin versions explicitly
- Always include and commit a lockfile
Stability Verification
- Node.js: Use LTS (e.g. Node 20), confirm
latest npm tag
- Python: Stable PyPI releases only, no
--pre
- Go: Tagged semantic versions only
Document:
- Runtime version
- Package manager version (if relevant)
Step 4: Make It Docker Compose–Ready
Assume the project will be containerized.
Required Files
Dockerfiledocker-compose.yml.dockerignore.env.example
Docker Rules
- No secrets inside images or compose files
- All runtime config via environment variables
- One service initially (the app)
- Additional services (DB, cache) added only when needed
- Prefer official base images and pin tags (e.g.
postgres:16-alpine)
Minimal docker-compose.yml
services:
app:
build: .
env_file: .env
ports:
- "${APP_PORT:-8080}:8080"
Minimal .env.example
APP_PORT=8080
NODE_ENV=development
DATABASE_URL=
Step 5: Create README.md
The README must answer only what a new developer needs:
- What the project is
- Required runtime
- How to run locally
- How to run with Docker Compose
Avoid deep architecture explanations (those belong in /docs).
Constraints (Do Not Violate)
- Do not introduce secrets
- Do not assume experimental dependencies
- Do not over-engineer (no microservices on day one)
- Do not create unused folders or files
- Do not omit Docker readiness
Quality Checklist
Before finishing, ensure:
Expected Outcome
After running this skill:
- The project can be started immediately
- Local and Docker environments behave consistently
- The codebase is structured for long-term maintainability
- Future features can be added without restructuring
This skill establishes a strong technical foundation before any business logic exists.
Additional Resources
- For language/framework-specific structure and examples, see reference.md.
