Skill: generate-tilt-dev-environment

Version: 0.3.0-alpha Purpose: Generate complete local development environments using Tilt, Docker Compose, and containerization Author: The Forge Last Updated: 2026-02-06

Title

Generate Tilt Development Environment - Construct local development realms with Tilt orchestration

File Structure

forge-plugin/skills/generate-tilt-dev-environment/
├── SKILL.md                  # This file - mandatory workflow
├── examples.md               # Usage scenarios and examples
├── scripts/
│   └── environment_generator.py  # Helper script for environment generation
└── templates/
    ├── tiltfile_template.txt           # Tiltfile template
    ├── docker_compose_template.txt     # Docker Compose template
    ├── dockerfile_template.txt         # Dockerfile template
    ├── env_template.txt                # .env template
    └── makefile_template.txt           # Makefile template

Required Reading

Before executing this skill, load context and memory via interfaces:

Context: Use contextProvider.getDomainIndex("azure") for Azure/container context. Use contextProvider.detectProjectType() for framework detection. See ContextProvider Interface.
Skill memory: Use memoryStore.getSkillMemory("generate-tilt-dev-environment", "{project-name}") for previous configurations. See MemoryStore Interface.

Interface References

Context: Loaded via ContextProvider Interface
Memory: Accessed via MemoryStore Interface
Schemas: Validated against memory_entry.schema.json

Design Requirements

Core Functionality

This skill must:

Analyze existing project structure to understand services and dependencies
Ask user about service requirements (services to containerize, dependencies)
Generate Tiltfile with live reload and service orchestration
Create Docker Compose configuration for service dependencies
Generate Dockerfiles for each service
Create development scripts (Makefile, startup scripts)
Configure environment variables (.env files, settings)
Store project configuration in memory for future reference

Output Requirements

Generate a complete, working Tilt development environment with:

Tiltfile with live reload configured
docker-compose.yml with all services and dependencies
Dockerfiles for each application service
Environment configuration (.env, .env.local, .env.example)
Makefile with common commands (up, down, logs, clean)
Development scripts (initialization, seed data, cleanup)
README with setup instructions
All necessary ignore files (.dockerignore, .gitignore)

Quality Requirements

Generated environments must:

Work immediately with tilt up (no manual fixes needed)
Support live reload (code changes reflected without rebuild)
Include proper health checks (services wait for dependencies)
Follow best practices (layer caching, ignore patterns, pinned versions)
Be well-documented (README, inline comments)
Support multiple environments (development, testing, staging)

Prompting Guidelines

User Questions Framework

After analyzing project structure, ask user about:

1. Project Type

Question: "What type of project are you developing?"
- Web application (frontend + backend)
- Microservices architecture
- API service
- Full-stack application
- Data pipeline
- Mobile app backend
Why ask: Determines service structure and dependencies
Follow-up: "What is the primary programming language/framework?"

2. Services to Containerize

Question: "Which services need to be containerized?"
- Backend API
- Frontend application
- Database (PostgreSQL, MySQL, MongoDB)
- Cache (Redis, Memcached)
- Message queue (RabbitMQ, Kafka)
- Search (Elasticsearch, OpenSearch)
- Storage (MinIO, Azurite)
Why ask: Determines number of containers and dependencies
Follow-up: "Are there any existing Dockerfiles we should use as a base?"

3. Programming Languages & Runtimes

Question: "What programming languages/runtimes are you using?"
- Python (specify version: 3.9, 3.10, 3.11, 3.12)
- Node.js (specify version: 16, 18, 20, 22)
- .NET (specify version: 6, 7, 8)
- Go (specify version)
- Java (specify version: 11, 17, 21)
- Ruby (specify version)
- PHP (specify version)
Why ask: Determines base Docker images and build processes

4. Database & Storage

Question: "What databases or storage systems do you need?"
- PostgreSQL (specify version)
- MySQL/MariaDB (specify version)
- MongoDB (specify version)
- Redis (specify version)
- File storage (MinIO, local volumes)
Why ask: Determines service dependencies and data persistence
Follow-up: "Do you need seed data or initialization scripts?"

5. Development Dependencies

Question: "What development dependencies do you need?"
- Package managers (pip, npm, yarn, poetry, cargo)
- Build tools (make, gradle, maven, webpack)
- Testing tools (pytest, jest, mocha)
- Linters (eslint, pylint, golangci-lint)
- Debugging tools
Why ask: Determines development container configuration

6. Port Configuration

Question: "What ports should each service expose?"
- Frontend (default: 3000, 8080)
- Backend API (default: 8000, 5000)
- Database (default: 5432, 3306, 27017)
- Custom ports for specific services
Why ask: Prevents port conflicts and ensures proper routing
Follow-up: "Do you have any existing services running on these ports?"

7. Environment Variables

Question: "What environment variables does your application need?"
- Database connection strings
- API keys (development only)
- Feature flags
- Service URLs
- Configuration values
Why ask: Determines .env file content
Follow-up: "Which values should be different between environments?"

8. Live Reload Requirements

Question: "Which services need live reload during development?"
- Hot reload for frontend (React, Vue, Angular)
- Auto-restart for backend (nodemon, uvicorn --reload)
- File watching for specific directories
Why ask: Determines Tiltfile live_update configuration

Instructions

MANDATORY STEPS (Must Execute in Order)

Step 1: Initial Analysis

Purpose: Understand project context and existing structure

Actions:

Identify working directory and project name
Check if Tilt is installed (tilt version)
Check if Docker is installed (docker --version)
Scan project directory for:
- Existing Dockerfiles or docker-compose.yml
- Language-specific files (package.json, requirements.txt, go.mod, pom.xml)
- Framework indicators (Angular, React, Django, Flask, Express)
- Configuration files
Identify services that need to be containerized
Note any existing development setup

Output: Clear understanding of project structure and services

Step 2: Load Index Files

Purpose: Understand available context and memory

Actions:

Use contextProvider.getDomainIndex("azure") for relevant context files. See ContextProvider Interface.
Use memoryStore.getSkillMemory("generate-tilt-dev-environment", "{project-name}") to check for existing memory. See MemoryStore Interface.
Identify which context domains are relevant based on project type

Output: Knowledge of available guidance and memory structure

Step 3: Load Project Memory (if exists)

Purpose: Understand previous configurations for this project

Actions:

Use memoryStore.getSkillMemory("generate-tilt-dev-environment", "{project-name}") to load project memory. See MemoryStore Interface.
If memory exists, review:
- environment_config.md - Previous configuration decisions
- generated_files.md - What was generated before
- customizations.md - User-specific modifications
- setup_notes.md - Important setup information
If not exists, note this is first-time generation

Output: Understanding of project history or recognition of new project

Step 4: Load Context

Purpose: Load relevant development environment knowledge

Actions:

Use contextProvider.getConditionalContext() to load context based on project stack. See ContextProvider Interface:
- For Python projects: contextProvider.getDomainIndex("python")
- For Azure services: contextProvider.getDomainIndex("azure")
- For framework-specific context: contextProvider.detectProjectType() + contextProvider.getConditionalContext()
Note any best practices or patterns relevant to the project

Output: Comprehensive understanding of development environment patterns

Step 5: Gather Requirements

Purpose: Understand user's needs through conversation

Actions:

Ask user about project type
Ask about services to containerize
Ask about programming languages and runtimes
Ask about database and storage requirements
Ask about development dependencies
Ask about port configuration
Ask about environment variables
Ask about live reload requirements
Confirm all requirements with user before proceeding

Output: Complete specification of environment to generate

Step 6: Generate Environment Configuration

Purpose: Create Tilt development environment files

Actions:

Generate Tiltfile:
- Use templates/tiltfile_template.txt as base
- Configure docker_build() for each service
- Set up k8s_resource() or docker_compose() orchestration
- Configure live_update for services that need it:
```
# Example live_update for Python
live_update=[
    sync('./src', '/app/src'),
    run('pip install -r requirements.txt', trigger='requirements.txt'),
    restart_container()
]
```
- Add local_resource() for build tasks
- Configure resource dependencies
- Add custom commands and buttons
Generate docker-compose.yml:
- Use templates/docker_compose_template.txt
- Add service for each containerized component
- Configure networks and volumes
- Set environment variables
- Map ports correctly
- Add health checks where appropriate
- Configure service dependencies (depends_on)
Generate Dockerfiles for each service:
- Use templates/dockerfile_template.txt
- Customize for each runtime (Python/Node/.NET/Go/Java)
- Configure multi-stage builds if appropriate
- Add development tools and dependencies
- Set up working directory
- Configure proper layer caching
- Add .dockerignore support
Generate environment files:
- .env.example - Template with all required variables
- .env - Local development values (add to .gitignore)
- .env.local - Optional override file
- Document each variable purpose
Generate Makefile:
- Use templates/makefile_template.txt
- Add common commands:
  - make up - Start Tilt
  - make down - Stop services
  - make logs - View logs
  - make clean - Clean up containers/volumes
  - make rebuild - Force rebuild
  - make shell-<service> - Access service shell
- Add project-specific commands
Generate initialization scripts:
- Database seed scripts
- Data migration scripts
- Service health check scripts
- Setup/teardown scripts
Generate .dockerignore:
- Exclude common patterns (node_modules, pycache, .git)
- Exclude build artifacts
- Project-specific exclusions
Generate README.md with:
- Project overview
- Prerequisites (Docker, Tilt)
- Quick start guide
- Service descriptions and endpoints
- Environment variable documentation
- Common commands
- Troubleshooting guide

Output: Complete environment configuration with all files generated

Step 7: Validate Generated Configuration

Purpose: Ensure configuration works before presenting to user

Actions:

Verify all required files exist
Check Tiltfile syntax (no obvious errors)
Verify docker-compose.yml is valid YAML
Ensure Dockerfiles have proper structure
Check that ports don't conflict
Verify file paths are correct
Ensure environment variables are documented

Do NOT run tilt up or docker build - just validate file structure and syntax

Output: Confidence that generated environment is correct

Step 8: Present Results to User

Purpose: Show user what was generated and next steps

Actions:

List all generated files with brief description
Highlight key configuration decisions made
Show directory structure

Provide next steps:

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

# Start development environment
tilt up

# Or use Makefile
make up

Point to README.md for detailed instructions
Mention Tilt UI at http://localhost:10350
List service endpoints and ports

Output: User understands what was created and how to use it

Step 9: Update Project Memory

Purpose: Store configuration for future reference

Actions:

Use memoryStore.update(layer="skill-specific", skill="generate-tilt-dev-environment", project="{project-name}", ...) to store the following. Timestamps and staleness tracking are handled automatically by MemoryStore. See MemoryStore Interface.
environment_config.md:
- Project type
- Services configured
- Programming languages and versions
- Ports assigned
- Environment variables
- Live reload configuration
Create generated_files.md:
- List of all generated files
- Timestamp of generation
- Skill version used
Create customizations.md:
- User-specific requirements
- Special configurations
- Deviations from templates
Create setup_notes.md:
- Important setup information
- Known issues or quirks
- Testing recommendations
- Debugging tips

Output: Memory stored for future skill invocations

Best Practices

Tilt Configuration

Use live_update: Essential for fast development iteration
Set resource_deps: Ensure proper service startup order
Add helpful labels: Group related services
Include links: Make endpoints easily accessible in Tilt UI
Configure triggers: Control when rebuilds happen
Add custom buttons: Common operations accessible via UI

Docker Configuration

Multi-stage builds: Keep production images small
Layer caching: Order commands for optimal caching
Use .dockerignore: Reduce build context size
Pin versions: Specify exact versions for reproducibility
Health checks: Ensure services are ready before dependencies start
Named volumes: Persist data across container restarts

Environment Management

Document all variables: Use .env.example as template
Never commit secrets: Keep .env in .gitignore
Use different values per environment: Development vs testing vs production
Validate required variables: Fail fast if missing
Use sensible defaults: Minimize configuration burden

Service Orchestration

Start dependencies first: Database before API
Wait for health: Use health checks, not sleep
Graceful shutdown: Handle SIGTERM properly
Log aggregation: Use Docker logging drivers
Network isolation: Use Docker networks properly

Error Handling

Common Issues

Port conflicts: Check for existing services, use alternative ports
Permission errors: Ensure proper file/volume permissions
Build failures: Check Dockerfile syntax, verify base images exist
Network issues: Verify service names match in docker-compose and Tilt
Environment variables: Check for missing required variables

Debugging

Use tilt logs <service>: View service logs
Check Tilt UI: Visual representation of service status
Use docker-compose ps: Verify services are running
Exec into containers: docker-compose exec <service> /bin/sh
Validate YAML: Use yamllint or online validators

Version History

1.1.0 (2026-02-10): Phase 4 Migration
- Migrated to interface-based patterns (ContextProvider + MemoryStore)
- Added YAML frontmatter with declarative context/memory configuration
- Removed hardcoded filesystem paths
- Added interface references section
1.0.0 (2026-02-06): Initial implementation
- Tiltfile generation with live reload
- Docker Compose orchestration
- Multi-language support (Python, Node.js, .NET, Go, Java)
- Environment variable management
- Makefile with common commands
- Memory system for configuration tracking

Related Skills

generate-azure-functions: For Azure Functions development
generate-mock-service: For creating mock services
test-cli-tools: For validating CLI tools in the environment