New Project Scaffold

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

• Dockerfile
• docker-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