Setup Guide

Setup Guide Skill

When generating a setup guide, follow this structured process. Don't just read the README — actually verify each step works on the current system.

1. Detect the Project Stack

Scan the project to understand what needs to be installed:

Language & Runtime

# Node.js
cat package.json 2>/dev/null | grep -E '"node"|"engines"'
cat .nvmrc .node-version 2>/dev/null

# Python
cat .python-version 2>/dev/null
cat pyproject.toml 2>/dev/null | grep -E "python_requires|requires-python"
cat runtime.txt 2>/dev/null
cat setup.py 2>/dev/null | grep "python_requires"

# Go
cat go.mod 2>/dev/null | head -3

# Ruby
cat .ruby-version 2>/dev/null
cat Gemfile 2>/dev/null | grep "ruby"

# Java
cat pom.xml 2>/dev/null | grep -E "<java.version>|<maven.compiler"
cat build.gradle 2>/dev/null | grep -E "sourceCompatibility|targetCompatibility"

# Rust
cat rust-toolchain.toml rust-toolchain 2>/dev/null

# PHP
cat composer.json 2>/dev/null | grep -E '"php"'

Package Manager

# Node.js — detect package manager
ls package-lock.json 2>/dev/null && echo "npm"
ls yarn.lock 2>/dev/null && echo "yarn"
ls pnpm-lock.yaml 2>/dev/null && echo "pnpm"
ls bun.lockb 2>/dev/null && echo "bun"

# Python
ls requirements.txt Pipfile pyproject.toml poetry.lock 2>/dev/null

# Ruby
ls Gemfile.lock 2>/dev/null

# PHP
ls composer.lock 2>/dev/null

Database & Services

# Docker services
cat docker-compose.yml docker-compose.yaml compose.yml compose.yaml 2>/dev/null | grep -E "image:|postgres|mysql|mongo|redis|elasticsearch|rabbitmq|kafka"

# Environment variables that hint at services
cat .env.example .env.sample .env.template 2>/dev/null | grep -E "DATABASE|REDIS|MONGO|ELASTIC|RABBIT|KAFKA|S3|SMTP"

# Prisma / ORM
cat prisma/schema.prisma 2>/dev/null | head -20
cat src/db/config* 2>/dev/null

Infrastructure Tools

# Check for required CLI tools
ls Makefile 2>/dev/null && echo "make"
ls Dockerfile 2>/dev/null && echo "docker"
ls docker-compose.yml compose.yml 2>/dev/null && echo "docker-compose"
ls .terraform/ terraform/ 2>/dev/null && echo "terraform"
ls k8s/ kubernetes/ 2>/dev/null && echo "kubectl"
ls .github/workflows/ 2>/dev/null && echo "github-actions"

2. Check Current System

Verify what's already installed and what's missing:

System Info

# OS
uname -a
cat /etc/os-release 2>/dev/null | head -5

# Shell
echo $SHELL

Required Tools Check

# Common tools — check versions
node --version 2>/dev/null || echo "❌ Node.js not installed"
npm --version 2>/dev/null || echo "❌ npm not installed"
yarn --version 2>/dev/null || echo "❌ yarn not installed"
pnpm --version 2>/dev/null || echo "❌ pnpm not installed"
python3 --version 2>/dev/null || echo "❌ Python not installed"
pip3 --version 2>/dev/null || echo "❌ pip not installed"
go version 2>/dev/null || echo "❌ Go not installed"
ruby --version 2>/dev/null || echo "❌ Ruby not installed"
java --version 2>/dev/null || echo "❌ Java not installed"
rustc --version 2>/dev/null || echo "❌ Rust not installed"
php --version 2>/dev/null || echo "❌ PHP not installed"
docker --version 2>/dev/null || echo "❌ Docker not installed"
docker compose version 2>/dev/null || echo "❌ Docker Compose not installed"
git --version 2>/dev/null || echo "❌ Git not installed"
make --version 2>/dev/null | head -1 || echo "❌ make not installed"

3. Generate Step-by-Step Setup

Based on discovery, generate a complete setup guide:

Guide Structure

# [Project Name] — Local Development Setup

## Prerequisites

Everything you need before starting:

| Tool | Required Version | Your Version | Status |
|------|-----------------|-------------|--------|
| Node.js | >= 18.0.0 | v20.10.0 | ✅ |
| npm | >= 9.0.0 | 10.2.0 | ✅ |
| Docker | >= 24.0.0 | 24.0.7 | ✅ |
| PostgreSQL | 15.x | — | ⚠️ Via Docker |

### Install Missing Prerequisites

[Provide install commands for each missing tool, specific to their OS]

Stack-Specific Setup Steps

Node.js / TypeScript Project

## Step 1: Clone and Install

git clone <repo-url>
cd <project-name>

# Install dependencies (uses [detected package manager])
npm install          # or yarn / pnpm install

## Step 2: Environment Configuration

# Copy the example environment file
cp .env.example .env

# Required variables to fill in:
# DATABASE_URL    → Your local PostgreSQL connection string
# REDIS_URL       → Your local Redis connection string
# JWT_SECRET      → Any random string for local dev (e.g., "dev-secret-change-me")
# [list each required variable with explanation and example value]

## Step 3: Start Infrastructure

# Start database and other services
docker compose up -d

# Verify services are running
docker compose ps

## Step 4: Database Setup

# Run migrations
npm run db:migrate

# Seed development data (optional)
npm run db:seed

## Step 5: Start Development Server

npm run dev

# Server should be running at http://localhost:3000

Python / Django Project

## Step 1: Clone and Set Up Virtual Environment

git clone <repo-url>
cd <project-name>

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
# or: poetry install / pipenv install

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

python manage.py migrate
python manage.py createsuperuser  # Create admin account
python manage.py loaddata fixtures/dev_data.json  # Optional seed data

## Step 5: Start Development Server

python manage.py runserver

# Server should be running at http://localhost:8000
# Admin panel at http://localhost:8000/admin

Go Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

go mod download

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

go run cmd/migrate/main.go up
# or: make migrate-up

## Step 5: Build and Run

go run cmd/server/main.go
# or: make run

# Server should be running at http://localhost:8080

Ruby on Rails Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

bundle install

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

# Install JavaScript dependencies (if applicable)
yarn install

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

rails db:create
rails db:migrate
rails db:seed

## Step 5: Start Development Server

rails server
# or: bin/dev (if using Foreman/Procfile)

# Server should be running at http://localhost:3000

Java / Spring Boot Project

## Step 1: Clone and Build

git clone <repo-url>
cd <project-name>

# Maven
./mvnw clean install -DskipTests

# Gradle
./gradlew build -x test

## Step 2: Environment Configuration

cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml
# Fill in required properties...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

# Flyway migrations run automatically on startup
# or: ./mvnw flyway:migrate

## Step 5: Start Development Server

# Maven
./mvnw spring-boot:run -Dspring.profiles.active=local

# Gradle
./gradlew bootRun --args='--spring.profiles.active=local'

# Server should be running at http://localhost:8080
# Swagger UI at http://localhost:8080/swagger-ui.html

PHP / Laravel Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

composer install
npm install

## Step 2: Environment Configuration

cp .env.example .env
php artisan key:generate

# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d
# or use Laravel Sail: ./vendor/bin/sail up -d

## Step 4: Database Setup

php artisan migrate
php artisan db:seed

## Step 5: Start Development Server

php artisan serve
npm run dev  # Vite dev server for frontend assets

# Server should be running at http://localhost:8000

Rust Project

## Step 1: Clone and Build

git clone <repo-url>
cd <project-name>

cargo build

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

# Using sqlx
sqlx database create
sqlx migrate run

# Using diesel
diesel setup
diesel migration run

## Step 5: Run Development Server

cargo run
# or: cargo watch -x run (for auto-reload, requires cargo-watch)

# Server should be running at http://localhost:8080

Mobile (React Native) Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

npm install

# iOS specific
cd ios && pod install && cd ..

## Step 2: Environment Configuration

cp .env.example .env
# Fill in required variables...

## Step 3: Start Backend (if included)

docker compose up -d
# or connect to staging API

## Step 4: Run on Simulator

# iOS
npx react-native run-ios

# Android
npx react-native run-android

# Expo
npx expo start

Flutter Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

flutter pub get

## Step 2: Environment Configuration

cp lib/config/env.example.dart lib/config/env.dart
# Fill in required variables...

## Step 3: Run on Simulator

# List available devices
flutter devices

# Run on a device
flutter run -d <device-id>

# Run in Chrome (web)
flutter run -d chrome

Monorepo / Turborepo Project

## Step 1: Clone and Install Dependencies

git clone <repo-url>
cd <project-name>

# Install all workspace dependencies
npm install  # or pnpm install / yarn install

## Step 2: Environment Configuration

# Root level
cp .env.example .env

# Per-package (check each app)
cp apps/web/.env.example apps/web/.env
cp apps/api/.env.example apps/api/.env
# Fill in required variables...

## Step 3: Start Infrastructure

docker compose up -d

## Step 4: Database Setup

npm run db:migrate --workspace=packages/database
npm run db:seed --workspace=packages/database

## Step 5: Start All Services

npm run dev  # Starts all workspaces via Turbo

# Web: http://localhost:3000
# API: http://localhost:4000
# Docs: http://localhost:3001

4. Verification Checklist

After setup, verify everything works:

## Verify Your Setup

Run these checks to confirm everything is working:

### Infrastructure
- [ ] `docker compose ps` — all services show "Up"
- [ ] Database is accessible: `npm run db:check` or connect with your DB client
- [ ] Redis is accessible: `redis-cli ping` returns "PONG"

### Application
- [ ] Dev server starts without errors
- [ ] Homepage loads at http://localhost:[PORT]
- [ ] API health check returns OK: `curl http://localhost:[PORT]/api/health`
- [ ] Can log in with seed user credentials (if applicable)

### Development Tools
- [ ] Tests pass: `npm test`
- [ ] Linter passes: `npm run lint`
- [ ] Hot reload works: make a small change and verify it updates
- [ ] Debugger works: set a breakpoint and verify it pauses

### Common First-Run Issues
| Problem | Solution |
|---------|----------|
| Port already in use | Kill the process: `lsof -i :3000` then `kill -9 <PID>` |
| Database connection refused | Check Docker is running: `docker compose ps` |
| Module not found | Delete node_modules and reinstall: `rm -rf node_modules && npm install` |
| Permission denied | Check file permissions: `chmod +x scripts/*.sh` |
| Env variable missing | Compare your .env against .env.example |
| Migration failed | Reset DB: `npm run db:reset` or `docker compose down -v && docker compose up -d` |
| Python version mismatch | Use pyenv: `pyenv install 3.11 && pyenv local 3.11` |
| Node version mismatch | Use nvm: `nvm install && nvm use` |
| Docker out of space | Clean up: `docker system prune -a` |
| Seed data missing | Run seed command: check package.json for seed script |

5. IDE & Editor Setup

## Recommended Editor Setup

### VS Code
Install these extensions for the best experience:
- [List extensions detected from .vscode/extensions.json or project type]

Recommended settings (`.vscode/settings.json`):
- Format on save: enabled
- Default formatter: [Prettier/Black/gofmt/rustfmt based on project]
- ESLint/Pylint auto-fix on save

### JetBrains (IntelliJ / WebStorm / PyCharm)
- Import code style from `.editorconfig` or project settings
- Enable [relevant plugins]
- Configure run configurations for dev server and tests

### Vim / Neovim
- LSP config for [project language]
- Formatter integration
- Test runner keybinds

6. Useful Commands Reference

## Daily Commands

| Task | Command |
|------|---------|
| Start dev server | `npm run dev` |
| Run tests | `npm test` |
| Run single test | `npm test -- --grep "test name"` |
| Lint code | `npm run lint` |
| Format code | `npm run format` |
| Start infrastructure | `docker compose up -d` |
| Stop infrastructure | `docker compose down` |
| View logs | `docker compose logs -f [service]` |
| Create migration | `npm run db:migrate:create -- --name=add_users_table` |
| Run migrations | `npm run db:migrate` |
| Reset database | `npm run db:reset` |
| Open DB shell | `docker compose exec db psql -U postgres` |
| Open Redis CLI | `docker compose exec redis redis-cli` |
| Build for production | `npm run build` |
| Check bundle size | `npm run analyze` |

7. Access & Credentials

## Development Accounts & Access

### Local Development
| Service | URL | Credentials |
|---------|-----|-------------|
| App | http://localhost:3000 | — |
| API | http://localhost:3000/api | — |
| DB Admin (pgAdmin/Adminer) | http://localhost:5050 | admin@local.dev / admin |
| Redis Commander | http://localhost:8081 | — |
| Mailhog (email testing) | http://localhost:8025 | — |
| Swagger/API Docs | http://localhost:3000/api/docs | — |

### Seed User Accounts (if applicable)
| Role | Email | Password |
|------|-------|----------|
| Admin | admin@example.com | password123 |
| User | user@example.com | password123 |

### External Service Credentials
Obtain these from your team lead or the shared vault:
- [ ] Stripe test API key
- [ ] AWS credentials (for S3 local testing)
- [ ] OAuth client ID/secret (Google, GitHub, etc.)

Note: Never use production credentials locally.

8. Next Steps After Setup

## You're Set Up! Now What?

### Get Familiar
1. **Read** `docs/architecture.md` or run `/explain-codebase` for an overview
2. **Explore** the codebase starting from `src/api/routes/` (follow a request through the system)
3. **Run** the test suite to see how the code is tested
4. **Check** the project board for "good first issue" tickets

### Your First Task
Pick a small, well-defined task to build familiarity:
- Fix a typo in the UI
- Add a missing unit test
- Update an outdated dependency
- Improve an error message

### Key People
| Area | Contact |
|------|---------|
| Architecture questions | @[tech-lead] |
| Deployment issues | @[devops-lead] |
| Product questions | @[product-manager] |
| General help | #[team-channel] on Slack |

Output Format

Structure the setup guide as:

1. Prerequisites table — tools needed with version check results
2. Install missing tools — commands for anything not found
3. Step-by-step setup — numbered steps from clone to running
4. Verification checklist — confirm everything works
5. Troubleshooting — common issues and fixes
6. Useful commands — daily reference table
7. Next steps — what to do after setup is complete

Adaptation Rules

• Auto-detect everything — don't ask the user what stack they're using, scan the project
• Verify each step — actually run commands to check if things work
• OS-aware — detect the user's OS and provide correct commands (macOS/Linux/Windows)
• Skip what's done — if a tool is already installed and correct version, say ✅ and move on
• Flag blockers — if something critical is missing (Docker not installed, wrong Node version), highlight it immediately before continuing
• Include timings — estimate how long the full setup takes ("~15 minutes on a fast connection")

Summary

End every setup guide with:

1. Setup status — ✅ Ready / ⚠️ Needs attention / ❌ Blocked
2. What's working — services confirmed running
3. What needs manual action — credentials to obtain, accounts to create
4. Estimated time — how long the remaining setup should take
5. First command to run — the one command to start developing