setup

First-time project setup that detects the stack, installs dependencies, configures the environment, starts required services, runs database migrations and seeds, and verifies the application starts. Interactive: prompts for missing environment values and confirms before starting services.

When to use

• When cloning a new project and setting it up for the first time.
• When onboarding to a project and the README setup steps are unclear or incomplete.
• When returning to a project after a long time and the environment may be stale.
• When a teammate asks "how do I get this running?"

When NOT to use

• For managing production infrastructure. Use /infra instead.
• For deploying to staging or production. Use /deploy instead.
• For generating a README. Use /readme instead.
• For updating dependencies. Use /audit deps instead.

Arguments

This skill takes no arguments. Run /setup and it walks through everything interactively.

Steps

1. Detect the project type. Read the root directory for manifest files. Check for these in order:

   • package.json: Node.js project. Check for pnpm-lock.yaml, yarn.lock, or package-lock.json to determine the package manager.
   • go.mod: Go project.
   • Cargo.toml: Rust project.
   • pyproject.toml or requirements.txt: Python project.
   • Makefile: check for language-specific targets.
   • docker-compose.yml or compose.yml: containerized services.
   • If multiple manifest files exist, report all detected project types.

2. Check prerequisites. For each detected project type, verify the required runtime is installed:

   • Node.js: node --version. Check against the .node-version, .nvmrc, or engines field in package.json.
   • Go: go version.
   • Rust: rustc --version and cargo --version.
   • Python: python3 --version. Check against .python-version or pyproject.toml requires-python.
   • Docker: docker --version and docker compose version.
   • If a prerequisite is missing, report it and stop. Do not attempt to install runtimes.

3. Install dependencies.

   • Node.js with pnpm: pnpm install.
   • Node.js with yarn: yarn install.
   • Node.js with npm: npm ci.
   • Go: go mod download.
   • Rust: cargo build.
   • Python with pip: pip install -r requirements.txt or pip install -e ..
   • Python with poetry: poetry install.
   • Report the result: success or failure with the error output.

4. Environment setup. Check for .env.example or .env.template in the project root.

   • If .env already exists, read it and compare against .env.example. List any variables present in the example but missing from .env.
   • If .env does not exist, copy .env.example to .env.
   • For each missing or placeholder variable, prompt the user:
     • Show the variable name.
     • Show the description from comments in .env.example if available.
     • Show the default value if one exists.
     • Ask for the value. Accept the default if the user presses enter.
   • Never overwrite values the user has already set in .env.

5. Detect required services. Scan these sources for service dependencies:

   • docker-compose.yml or compose.yml: list all services defined.
   • .env.example: look for connection strings or host variables that imply services: DATABASE_URL, REDIS_URL, MONGODB_URI, ELASTICSEARCH_URL, RABBITMQ_URL, KAFKA_BROKERS.
   • For each detected service, check if it is already running:
     • PostgreSQL: pg_isready -h localhost or check the port.
     • Redis: redis-cli ping.
     • MongoDB: mongosh --eval "db.runCommand({ping:1})" or check the port.
     • Docker services: docker compose ps.

6. Offer to start services. For each service that is not running:

   • If a docker-compose file defines the service, offer to start it: docker compose up -d <service>.
   • Wait for health checks to pass before proceeding. Use docker compose ps to verify the service reports as healthy.
   • If the service is not in docker-compose, inform the user that the service needs to be started manually and provide the typical connection details from the env vars.

7. Run database setup. Detect the ORM or migration tool:

   • Prisma: npx prisma migrate dev or npx prisma db push depending on the project stage. Then npx prisma db seed if a seed script exists.
   • Knex: npx knex migrate:latest then npx knex seed:run if seeds exist.
   • TypeORM: npx typeorm migration:run.
   • Django: python manage.py migrate then python manage.py loaddata if fixtures exist.
   • SQLAlchemy with Alembic: alembic upgrade head.
   • If no ORM is detected but DATABASE_URL exists, inform the user that manual database setup may be needed.

8. Verify the application starts. Detect the start command:

   • Node.js: check package.json scripts for dev, start:dev, or start.
   • Go: go run . or check a Makefile target.
   • Python: check for a main.py, app.py, or framework-specific entry point.
   • Start the application. Wait up to 15 seconds for a health check endpoint or for the process to stabilize.
   • If the app starts and responds to a health check, report success.
   • If the app crashes, capture the error output and report it with diagnostic suggestions.
   • Stop the application after verification. This is a setup check, not a long-running process.

9. Present the setup report.

   ## Setup Complete
   
   **Project:** <detected type and framework>
   **Runtime:** <version>
   **Package manager:** <name and version>
   
   ### Dependencies
   Installed successfully.
   
   ### Environment
   - .env created from .env.example
   - N variables configured
   
   ### Services
   | Service | Status |
   |---------|--------|
   | PostgreSQL | running on localhost:5432 |
   | Redis | running on localhost:6379 |
   
   ### Database
   - Migrations applied: N
   - Seed data loaded: yes/no
   
   ### Application
   Started successfully on http://localhost:3000
   
   ### Next steps
   - Run `pnpm dev` to start development
   - Run `pnpm test` to verify tests pass
   

Rules

• Never overwrite an existing .env file. Merge missing values only.
• Always check if services are already running before attempting to start them. Starting a second instance on the same port causes errors.
• Always verify the application actually starts. "Dependencies installed" is not "setup complete."
• Never install runtimes or system-level tools automatically. Report what is missing and let the user decide how to install.
• When a step fails, report the error clearly and continue with the remaining steps where possible. A failed database migration should not prevent reporting what else was configured.
• Prefer pnpm for JavaScript and TypeScript projects. Only use npm or yarn when the lockfile indicates otherwise.
• When docker-compose starts a service, wait for its health check before running migrations. A started container is not a ready service.

Related skills

• /onboard - Understand the codebase structure and architecture.
• /infra - Manage infrastructure for local development.
• /health - Check project quality after setup is complete.
• /test - Run the test suite to verify everything works.