Skip to content
environment-bootstrap logo

Environment Bootstrap

environment-bootstrap

Use for development environment setup - create and maintain init scripts, run smoke tests, ensure consistent environment across sessions

SKILL.md

Full skill instructions

Environment Bootstrap

Overview

Set up and maintain consistent development environments.

Core principle: Every session should start with a known-good environment.

Announce at start: "I'm using environment-bootstrap to set up the development environment."

When to Use

SituationAction
First clone of repositoryCreate init script
Starting new sessionRun init script
After pulling changesRe-run init if deps changed
Environment seems brokenRun init to reset

The Init Script

Location

project/
├── scripts/
│   └── init.sh    ← Standard location
├── package.json
└── ...

Template

#!/​usr/​bin/​env bash
set -euo pipefail

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

echo "=== Development Environment Bootstrap ==="
echo ""

# Step 1: Check prerequisites
echo "Checking prerequisites..."

check_command() {
    if ! command -v "$1" &> /​dev/​null; then
        echo -e "${RED}ERROR: $1 is required but not installed${NC}"
        exit 1
    fi
    echo -e "  ${GREEN}✓${NC} $1 found"
}

check_command node
check_command pnpm
check_command git
check_command gh

# Check Node version
REQUIRED_NODE="18"
CURRENT_NODE=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$CURRENT_NODE" -lt "$REQUIRED_NODE" ]; then
    echo -e "${RED}ERROR: Node $REQUIRED_NODE+ required, found $CURRENT_NODE${NC}"
    exit 1
fi
echo -e "  ${GREEN}✓${NC} Node version OK ($CURRENT_NODE)"

# Check gh authentication
if ! gh auth status &> /​dev/​null; then
    echo -e "${RED}ERROR: gh CLI not authenticated. Run 'gh auth login'${NC}"
    exit 1
fi
echo -e "  ${GREEN}✓${NC} GitHub CLI authenticated"

echo ""

# Step 2: Install dependencies
echo "Installing dependencies..."
pnpm install --frozen-lockfile --silent
echo -e "${GREEN}✓${NC} Dependencies installed"
echo ""

# Step 3: Environment setup
echo "Setting up environment..."
if [ ! -f .env ]; then
    if [ -f .env.example ]; then
        cp .env.example .env
        echo -e "${YELLOW}!${NC} Created .env from .env.example - review and update values"
    else
        echo -e "${YELLOW}!${NC} No .env file and no .env.example found"
    fi
else
    echo -e "  ${GREEN}✓${NC} .env exists"
fi
echo ""

# Step 4: Build
echo "Building project..."
pnpm build --silent
echo -e "${GREEN}✓${NC} Build successful"
echo ""

# Step 5: Run tests
echo "Running tests..."
if pnpm test --silent; then
    echo -e "${GREEN}✓${NC} Tests passed"
else
    echo -e "${RED}✗${NC} Tests failed - environment may have issues"
    exit 1
fi
echo ""

# Step 6: Start development services (if docker-compose exists)
if [ -f "docker-compose.yml" ] || [ -f "docker-compose.yaml" ]; then
    echo "Starting development services..."
    docker-compose up -d

    echo "Waiting for services to be ready..."
    sleep 5

    # Verify postgres (if defined)
    if docker-compose config --services 2>/​dev/​null | grep -q "postgres"; then
        if docker-compose ps postgres 2>/​dev/​null | grep -q "Up"; then
            echo -e "${GREEN}✓${NC} postgres ready"
        else
            echo -e "${RED}✗${NC} postgres failed to start"
        fi
    fi

    # Verify redis (if defined)
    if docker-compose config --services 2>/​dev/​null | grep -q "redis"; then
        if docker-compose ps redis 2>/​dev/​null | grep -q "Up"; then
            echo -e "${GREEN}✓${NC} redis ready"
        else
            echo -e "${RED}✗${NC} redis failed to start"
        fi
    fi

    echo ""
fi

# Step 7: Start development server (optional)
if [ "${START_DEV_SERVER:-false}" = "true" ]; then
    echo "Starting development server..."
    pnpm dev &
    DEV_PID=$!

    # Wait for server to be ready
    sleep 5

    # Smoke test (IPv6-first: try [::1] before falling back to 127.0.0.1)
    if curl -sf http://[::1]:3000/​health > /​dev/​null; then
        echo -e "${GREEN}✓${NC} Development server running on IPv6 (PID: $DEV_PID)"
    elif curl -sf http://127.0.0.1:3000/​health > /​dev/​null; then
        echo -e "${YELLOW}!${NC} Development server running on IPv4 legacy (PID: $DEV_PID)"
    else
        echo -e "${RED}✗${NC} Development server not responding"
        kill $DEV_PID 2>/​dev/​null
        exit 1
    fi
fi

echo ""
echo -e "${GREEN}=== Environment Ready ===${NC}"
echo ""
echo "Next steps:"
echo "  pnpm dev    - Start development server"
echo "  pnpm test   - Run tests"
echo "  pnpm build  - Build for production"

Making Executable

chmod +x scripts/​init.sh

Running the Init Script

Standard Run

./​scripts/​init.sh

With Dev Server

START_DEV_SERVER=true ./​scripts/​init.sh

After Pulling Changes

git pull origin main
./​scripts/​init.sh

Smoke Test

After environment setup, verify basic functionality:

What to Test

TestHowPass Criteria
Buildpnpm buildNo errors
Testspnpm testAll pass
Dev serverpnpm devServer starts
Health checkcurl http://[::1]:3000/​health200 OK (IPv6-first)
Basic flowRun E2E testPasses

Smoke Test Script

#!/​usr/​bin/​env bash
# scripts/​smoke-test.sh

set -euo pipefail

echo "Running smoke tests..."

# Start dev server
pnpm dev &
DEV_PID=$!
sleep 10

# Health check (IPv6-first, fallback to IPv4 legacy)
if curl -sf http://[::1]:3000/​health > /​dev/​null; then
    echo "Health check passed (IPv6)"
elif curl -sf http://127.0.0.1:3000/​health > /​dev/​null; then
    echo "Health check passed (IPv4 legacy)"
else
    echo "Health check failed"
    kill $DEV_PID
    exit 1
fi

# Basic E2E (if available)
if [ -f "tests/​smoke.test.ts" ]; then
    pnpm test:e2e tests/​smoke.test.ts
fi

# Clean up
kill $DEV_PID

echo "Smoke tests passed"

Environment Documentation

README Section

## Development Setup

### Prerequisites

- Node.js 18+
- pnpm 8+
- GitHub CLI (`gh`) authenticated

### Quick Start

```bash
# Clone repository
git clone https://github.com/owner/repo.git
cd repo

# Run setup
./​scripts/​init.sh

# Start development
pnpm dev

Environment Variables

Copy .env.example to .env and update:

VariableDescriptionRequired
DATABASE_URLPostgreSQL connection stringYes
JWT_SECRETSecret for signing tokensYes
API_KEYExternal API keyNo

## Maintaining Init Scripts

### When to Update

Update the init script when:

- New prerequisite added
- New environment variable needed
- Build process changes
- New verification step needed

### Version in Commit

When updating init script:

```bash
git add scripts/​init.sh
git commit -m "chore: Update init script for [change]"

Troubleshooting

Common Issues

IssueSolution
"command not found"Install missing prerequisite
"permission denied"chmod +x scripts/​init.sh
"node version"Use nvm: nvm use 18
"pnpm install failed"Delete node_modules, try again
"build failed"Check for type errors, missing deps

Reset Environment

When environment is in unknown state:

# Nuclear option
rm -rf node_modules dist .cache .next
pnpm store prune
./​scripts/​init.sh

Checklist

Init script should:

  • Check all prerequisites
  • Verify correct versions
  • Install dependencies
  • Set up environment files
  • Run build
  • Run tests
  • Start development services (if docker-compose exists)
  • Verify services are ready (postgres, redis, etc.)
  • Optionally start dev server
  • Verify server responds (if started)
  • Print clear success/​failure

Environment documentation should:

  • List prerequisites
  • Explain quick start
  • Document env variables
  • Explain common issues

Integration

This skill is called by:

  • session-start - Beginning of each session
  • error-recovery - Resetting environment

This skill ensures:

  • Consistent development environment
  • Quick session startup
  • Early detection of environment issues

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View