Efficient Setup Handler

Handle complete project setup operations including environment configuration, dependency installation, service initialization, and development tooling in a single efficient execution.

When to Use This Command

Run this command when...

• You are onboarding to a new project and need to configure the local development environment from scratch
• A new team member needs to get the project running with all dependencies, services, and configurations
• You need to set up environment variables, database connections, and external service integrations
• The project requires multiple services (database, cache, message queue) to be configured and verified
• You want to automate the repetitive setup steps documented in a project README

Quick Start

Copy
# .claude/commands/efficient-setup-handler.md
---
name: Efficient Setup Handler
description: Complete project setup with dependencies, services, and configuration
command: true
---
Set up: $ARGUMENTS

1. Detect project type and required dependencies
2. Install packages and configure tooling
3. Set up environment variables and config files
4. Initialize databases and external services
5. Verify the setup by running health checks

Copy
# Invoke the command
claude "/efficient-setup-handler full local development environment"

# Expected output
# > Detecting project requirements...
# >   Runtime: Node.js 20 | Package manager: pnpm
# >   Services: PostgreSQL, Redis, S3 (localstack)
# > Installing dependencies...
# >   pnpm install (487 packages, 12s)
# > Configuring environment...
# >   Created .env from .env.example (12 variables)
# >   Missing: DATABASE_URL, REDIS_URL (prompting...)
# > Initializing services...
# >   PostgreSQL: connected, running migrations (14 migrations)
# >   Redis: connected, ping successful
# >   LocalStack S3: bucket created
# > Verification:
# >   API health check: OK (localhost:3000/health)
# >   All 14 migrations applied
# >   Test suite: 142/142 passing
# > Setup complete. Ready for development.

Core Concepts

Concept	Description
Project Detection	Identifies runtime, package manager, framework, and required services automatically
Dependency Resolution	Installs all packages and resolves version conflicts or peer dependency issues
Environment Templating	Creates .env files from templates, prompting for missing secrets
Service Initialization	Starts and configures databases, caches, and other backend services
Verification Suite	Runs health checks, migrations, and test suites to confirm successful setup

Setup Handler Flow
===================

  Detect Project --> Install Deps --> Configure Env
       |                 |                |
  Read configs     npm/pnpm/pip      .env template
  Find services    Resolve peers     Prompt secrets
  Map requirements Lock versions     Set defaults
                                          |
                   Verify <-- Init Services
                     |              |
                Health checks  Run migrations
                Run tests      Start databases
                Report status  Connect caches

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Scope of setup to perform	full setup	"dependencies only"	No
env_template	Path to environment variable template	.env.example	.env.template	No
skip_services	Skip external service initialization	false	true	No
run_migrations	Execute database migrations during setup	true	false	No
verify	Run verification checks after setup	true	false	No

Best Practices

1. Maintain up-to-date .env.example files -- The setup handler uses these templates to create local configurations. Missing variables in the template mean missing variables in the setup.

2. Document required external services -- List all required services (databases, caches, queues) in your project README or a services.yml file so the handler knows what to initialize.

3. Use Docker for service dependencies -- When the handler needs PostgreSQL or Redis, Docker Compose provides reproducible service setup. Maintain a docker-compose.yml for development services.

4. Run verification after every setup -- Keep verify: true to catch configuration issues immediately. A passing test suite confirms the environment is correctly configured.

5. Version-lock your dependencies -- Use lock files (package-lock.json, pnpm-lock.yaml) to ensure the setup handler installs the exact same versions every time, preventing "works on my machine" issues.

Common Issues

Missing system dependencies: The project may require system-level tools (e.g., libpq-dev, ImageMagick) that the handler cannot install. Document these in a Prerequisites section and check for them early.

Port conflicts with existing services: If PostgreSQL or Redis is already running on default ports, the setup may fail or connect to the wrong instance. Use non-default ports in development configurations.

Environment variable secrets not available: The handler cannot generate API keys or passwords. Have new team members obtain secrets from a password manager or secrets vault before running setup.