Easy Setup Executor

Run a complete project setup pipeline that chains dependency installation, configuration generation, database setup, and environment verification into a single automated sequence.

When to Use This Command

Run this command when...

• You want to execute a full setup sequence that runs multiple setup steps in the correct dependency order
• You need to chain together dependency installation, database creation, migration, seeding, and service startup
• You are automating the onboarding process so new developers can go from clone to running with one command
• You want to run setup steps selectively, skipping components that are already configured
• You need a setup pipeline that reports progress and surfaces errors clearly for each step

Quick Start

Copy
# .claude/commands/easy-setup-executor.yaml
name: Easy Setup Executor
description: Run complete project setup pipeline in correct order
inputs:
  - name: steps
    description: "all, deps, config, database, services, or verify"
    default: "all"

Copy
# Run complete setup pipeline
claude "easy-setup-executor"

# Run only database setup steps
claude "easy-setup-executor --steps database"

# Run setup skipping already-completed steps
claude "easy-setup-executor --skip-completed"

Output:
  [pipeline] Running 6 setup steps...
  Step 1/6: Install dependencies      [done] 23s
  Step 2/6: Generate config files      [done] 2s
  Step 3/6: Setup database             [done] 5s
  Step 4/6: Run migrations             [done] 3s
  Step 5/6: Seed test data             [done] 4s
  Step 6/6: Verify environment         [done] 1s
  ──────────────────────────────────────────────
  Pipeline complete: 6/6 steps passed (38s total)
  Manual steps: Set STRIPE_KEY in .env

Core Concepts

Concept	Description
Ordered Pipeline	Steps execute in dependency order: deps first, then config, then database, then services
Step Detection	Auto-detects which setup steps are needed based on project structure and configuration files
Skip Completed	Detects already-completed steps (deps installed, DB exists) and skips them for faster re-runs
Error Recovery	When a step fails, reports the error clearly and indicates whether subsequent steps can proceed
Manual Steps	Identifies actions that cannot be automated and lists them at the end with instructions

Setup Pipeline Order:
  ┌──────────┐   ┌──────────┐   ┌──────────┐
  │ 1. Deps  │──>│ 2. Config│──>│ 3. DB    │
  │ npm/pip  │   │ .env etc │   │ create   │
  └──────────┘   └──────────┘   └────┬─────┘
                                     │
  ┌──────────┐   ┌──────────┐   ┌────▼─────┐
  │ 6.Verify │<──│5. Seed   │<──│4.Migrate │
  │ all OK   │   │ test data│   │ schema   │
  └──────────┘   └──────────┘   └──────────┘

Configuration

Parameter	Type	Default	Description
steps	string	"all"	Steps to run: all, deps, config, database, services, or verify
skip_completed	boolean	false	Skip steps that are already done (deps installed, DB exists)
env	string	"development"	Target environment: development, test, or staging
seed	boolean	true	Include test data seeding after migrations
verbose	boolean	false	Show detailed output for each step instead of summary

Best Practices

1. Run the full pipeline for initial setup -- Use --steps all the first time to ensure every component is properly configured. Use selective steps for subsequent runs.
2. Use skip-completed for fast iteration -- When developing setup scripts, --skip-completed avoids re-running slow steps like dependency installation that are already done.
3. Define the pipeline in a config file -- Store the step definitions and order in a setup config so the pipeline is reproducible and version-controlled.
4. Test the full pipeline in CI -- Run the setup executor in your CI pipeline with a clean environment to verify that new developers can set up the project without manual intervention.
5. Keep manual steps minimal -- Every manual step is a friction point for new developers. Automate API key generation, database provisioning, and service registration where possible.

Common Issues

1. Step dependency failure cascades -- When an early step like dependency installation fails, subsequent steps that depend on it will also fail. Fix the root cause rather than retrying later steps.
2. Database already exists error -- Re-running the database creation step on an existing database produces errors. Use --skip-completed or add conditional creation (CREATE IF NOT EXISTS) logic.
3. Environment variables not loaded -- Config generation creates .env but the database step needs it. Ensure the pipeline reloads environment variables between steps.