feat: Add Docker Compose deployment support with AgentManager abstraction

.env.example

@@ -1,6 +1,28 @@
 # Claude Code Slack Application Configuration
 # Copy this file to .env and fill in your values
 
+# ===========================================
+# INFRASTRUCTURE CONFIGURATION (Required)
+# ===========================================
+
+# Infrastructure mode: "kubernetes" for production, "docker" for local development
+INFRASTRUCTURE_MODE=docker
+
+# Docker-specific configuration (when INFRASTRUCTURE_MODE=docker)
+DOCKER_SOCKET_PATH=/var/run/docker.sock
+WORKSPACE_HOST_DIR=/tmp/claude-workspaces
+DOCKER_NETWORK=claude-network
+DOCKER_REMOVE_CONTAINERS=true
+
+# Kubernetes-specific configuration (when INFRASTRUCTURE_MODE=kubernetes)
+KUBERNETES_NAMESPACE=default
+
+# Worker configuration (applies to both modes)
+WORKER_IMAGE=claude-worker:latest
+WORKER_CPU=1000m
+WORKER_MEMORY=2Gi
+WORKER_TIMEOUT_SECONDS=300
+
 # ===========================================
 # SLACK CONFIGURATION (Required)
 # ===========================================
@@ -120,9 +142,28 @@ INCLUDE_GITHUB_FILE_OPS=false
 # GITHUB INTEGRATION (Optional)
 # ===========================================
 
-# GitHub token for file operations (if INCLUDE_GITHUB_FILE_OPS=true)
+# GitHub token for file operations and repository management
 GITHUB_TOKEN=ghp_your-github-token-here
 
+# GitHub organization where repositories will be created
+GITHUB_ORGANIZATION=your-organization-name
+
+# ===========================================
+# STORAGE CONFIGURATION (Optional)
+# ===========================================
+
+# Google Cloud Storage bucket for conversation logs and artifacts
+GCS_BUCKET_NAME=your-bucket-name
+
+# Path to GCS service account key file
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+
+# Google Cloud project ID
+GOOGLE_CLOUD_PROJECT=your-project-id
+
+# Session timeout (in minutes)
+SESSION_TIMEOUT_MINUTES=5
+
 # ===========================================
 # ENVIRONMENT AND LOGGING
 # ===========================================

README.md

@@ -49,7 +49,31 @@ A powerful [Claude Code](https://claude.ai/code) Slack application that brings A
 
 Choose your deployment approach:
 
-### 🎯 **Option 1: Kubernetes (Recommended)**
+### 🐳 **Option 1: Local Development (Docker Compose)**
+Perfect for development, testing, and small teams
+
+**Benefits:**
+- ✅ Quick setup with one command
+- ✅ Hot reload for development
+- ✅ Full Docker isolation
+- ✅ No Kubernetes required
+- ✅ Easy debugging and testing
+- ❌ Single-node scaling only
+
+**Prerequisites:**
+- Docker and Docker Compose
+- Slack app tokens
+- GitHub personal access token
+
+**Quick Start:**
+```bash
+npm run setup:local    # Setup environment
+npm run dev:local      # Start development server
+```
+
+📖 **[→ Local Development Guide](./docs/local-development.md)**
+
+### 🎯 **Option 2: Kubernetes (Production)**
 Full-featured deployment with per-user isolation and persistence
 
 **Benefits:**
@@ -58,6 +82,7 @@ Full-featured deployment with per-user isolation and persistence
 - ✅ Horizontal scaling for large teams
 - ✅ Enterprise security and monitoring
 - ✅ GCS backup and recovery
+- ✅ Cost optimization and auto-scaling
 
 **Prerequisites:**
 - Google Kubernetes Engine (GKE) cluster
@@ -66,7 +91,7 @@ Full-featured deployment with per-user isolation and persistence
 
 📖 **[→ Kubernetes Deployment Guide](./docs/kubernetes-deployment.md)**
 
-### 🔧 **Option 2: Single Container (Legacy)**
+### 🔧 **Option 3: Single Container (Legacy)**
 Simple deployment for small teams and development
 
 **Benefits:**
@@ -80,6 +105,26 @@ Simple deployment for small teams and development
 
 ---
 
+## 🚀 Quick Start Comparison
+
+| Feature | Local Docker | Kubernetes | Single Container |
+|---------|-------------|------------|------------------|
+| **Setup Time** | 5 minutes | 30+ minutes | 2 minutes |
+| **Prerequisites** | Docker | K8s cluster | Node.js |
+| **User Isolation** | ✅ | ✅ | ❌ |
+| **Persistence** | ✅ | ✅ | ❌ |
+| **Scalability** | Single node | Unlimited | Single process |
+| **Hot Reload** | ✅ | ❌ | ✅ |
+| **Production Ready** | ❌ | ✅ | ❌ |
+| **Cost** | Free | Variable | Free |
+
+**Recommendation:**
+- **Development**: Use Local Docker
+- **Production**: Use Kubernetes  
+- **Quick Testing**: Use Single Container
+
+---
+
 ## 🐳 Kubernetes Quick Start
 
 ### Prerequisites

docker-compose.override.yml

@@ -0,0 +1,37 @@
+version: '3.8'
+
+# Docker Compose override file for development
+# This file is automatically loaded when running `docker compose up`
+# and provides development-specific configurations
+
+services:
+  dispatcher:
+    # Override build context for development
+    build:
+      context: .
+      dockerfile: docker/dispatcher.Dockerfile
+      target: development  # Use development stage if available
+
+    # Development environment variables
+    environment:
+      - NODE_ENV=development
+      - LOG_LEVEL=DEBUG
+
+    # Mount source code for hot reload
+    volumes:
+      # Docker socket (required for container management)
+      - /var/run/docker.sock:/var/run/docker.sock
+      # Source code mounting for hot reload
+      - ./packages:/app/packages:ro
+      - ./scripts:/app/scripts:ro
+      # Workspace directory for development
+      - ./tmp/workspaces:/tmp/claude-workspaces
+      # Optional: mount your local .env file
+      - ./.env:/app/.env:ro
+
+    # Override command for development (if needed)
+    # command: ["bun", "run", "dev"]
+
+    # Enable file watching and auto-restart (if supported by the image)
+    stdin_open: true
+    tty: true

docker-compose.yml

@@ -0,0 +1,75 @@
+version: '3.8'
+
+services:
+  dispatcher:
+    build:
+      context: .
+      dockerfile: docker/dispatcher.Dockerfile
+    container_name: claude-dispatcher
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    volumes:
+      # Mount Docker socket for container management
+      # WARNING: This gives containers full Docker daemon access. Consider using
+      # Docker-in-Docker or rootless Docker for better security in production.
+      - /var/run/docker.sock:/var/run/docker.sock
+      # Mount workspace directory for development
+      # Use dedicated directory instead of /tmp for better security
+      - ./workspaces:/tmp/claude-workspaces
+    environment:
+      # Infrastructure configuration
+      - INFRASTRUCTURE_MODE=docker
+      - DOCKER_SOCKET_PATH=/var/run/docker.sock
+      - WORKSPACE_HOST_DIR=./workspaces
+      - DOCKER_NETWORK=claude-network
+
+      # Slack configuration (socket mode by default)
+      - SLACK_HTTP_MODE=false
+      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
+      - SLACK_APP_TOKEN=${SLACK_APP_TOKEN}
+      - SLACK_SIGNING_SECRET=${SLACK_SIGNING_SECRET}
+      - SLACK_TRIGGER_PHRASE=${SLACK_TRIGGER_PHRASE:-@claude}
+
+      # GitHub configuration
+      - GITHUB_TOKEN=${GITHUB_TOKEN}
+      - GITHUB_ORGANIZATION=${GITHUB_ORGANIZATION:-peerbot-community}
+
+      # Claude configuration
+      - MODEL=${MODEL:-claude-3-5-sonnet-20241022}
+      - TIMEOUT_MINUTES=${TIMEOUT_MINUTES:-5}
+      - ALLOWED_TOOLS=${ALLOWED_TOOLS}
+
+      # Worker configuration
+      - WORKER_IMAGE=${WORKER_IMAGE:-claude-worker:latest}
+      - WORKER_CPU=${WORKER_CPU:-1000m}
+      - WORKER_MEMORY=${WORKER_MEMORY:-2Gi}
+      - WORKER_TIMEOUT_SECONDS=${WORKER_TIMEOUT_SECONDS:-300}
+
+      # Storage configuration
+      - GCS_BUCKET_NAME=${GCS_BUCKET_NAME}
+      - GOOGLE_APPLICATION_CREDENTIALS=${GOOGLE_APPLICATION_CREDENTIALS}
+      - GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
+
+      # Session configuration
+      - SESSION_TIMEOUT_MINUTES=${SESSION_TIMEOUT_MINUTES:-5}
+
+      # Development configuration
+      - NODE_ENV=${NODE_ENV:-production}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+    networks:
+      - claude-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+networks:
+  claude-network:
+    driver: bridge
+
+volumes:
+  claude-workspaces:
+    driver: local