setup-guide

What this skill does

# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# OS
uname -a
cat /etc/os-release 2>/dev/null | head -5

# Shell
echo $SHELL
```

### Required Tools Check
```bash
# 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
```markdown
# [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
```markdown
## 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
```markdown
## 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
```markdown
## 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
```markdown
## 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
```markdown
## 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
```markdown
## 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 Sai