claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-devops/rules/docker-first-development.md

@@ -0,0 +1,404 @@
+# Docker-First Development Rule
+
+> **STATUS**: Can be enabled/disabled via `.claude/config.json` → `features.docker_first_development`
+
+## WHEN ENABLED
+
+### 1. MANDATORY DOCKER USAGE
+
+**ALL development MUST happen inside Docker containers:**
+
+```bash
+# ❌ FORBIDDEN - Local execution
+npm install
+npm test
+python app.py
+pytest
+
+# ✅ REQUIRED - Docker execution
+docker compose run app npm install
+docker compose run app npm test
+docker compose run app python app.py
+docker compose run test pytest
+```
+
+### 2. PROJECT STRUCTURE REQUIREMENTS
+
+Every project MUST have:
+
+```
+project/
+├── Dockerfile                 # Production image
+├── Dockerfile.dev            # Development image with dev tools
+├── docker compose.yml        # Production-like setup
+├── docker compose.dev.yml    # Development overrides
+├── docker compose.test.yml   # Test environment
+└── .dockerignore            # Exclude unnecessary files
+```
+
+### 3. DEVELOPMENT WORKFLOW
+
+#### Initial Setup
+
+```bash
+# 1. Check if Docker files exist
+if [ ! -f "Dockerfile" ]; then
+  Use docker-containerization-expert agent to create Dockerfile
+fi
+
+# 2. Build development image
+docker compose -f docker compose.yml -f docker compose.dev.yml build
+
+# 3. Start development environment
+docker compose -f docker compose.yml -f docker compose.dev.yml up
+```
+
+#### Code Changes
+
+```yaml
+# docker compose.dev.yml
+services:
+  app:
+    volumes:
+      - .:/app                    # Mount source code
+      - /app/node_modules         # Preserve container node_modules
+      - /app/.venv               # Preserve Python venv
+    command: npm run dev          # Hot reload
+```
+
+#### Running Tests
+
+```bash
+# Always in container
+docker compose run --rm test pytest
+docker compose run --rm test npm test
+
+# CI/CD uses same image
+docker build -t app:test .
+docker run app:test pytest
+```
+
+### 4. ENFORCEMENT PIPELINE
+
+When docker_first_development is **enabled**:
+
+```
+1. Hook intercepts local commands (npm, pip, python, etc.)
+2. Checks if Docker alternative exists
+3. Blocks execution with Docker alternative suggestion
+4. Auto-creates Docker files if missing
+```
+
+### 5. DOCKERFILE STANDARDS
+
+#### Python Projects
+
+```dockerfile
+# Dockerfile.dev
+FROM python:3.11-slim AS development
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+CMD ["python", "-m", "flask", "run", "--host=0.0.0.0", "--reload"]
+
+# Dockerfile (production)
+FROM python:3.11-slim AS production
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+CMD ["gunicorn", "app:app"]
+```
+
+#### Node.js Projects
+
+```dockerfile
+# Dockerfile.dev
+FROM node:20-alpine AS development
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+CMD ["npm", "run", "dev"]
+
+# Dockerfile (production)
+FROM node:20-alpine AS production
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+CMD ["node", "server.js"]
+```
+
+### 6. docker compose TEMPLATES
+
+#### Base docker compose.yml
+
+```yaml
+version: '3.9'
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    networks:
+      - app-network
+
+networks:
+  app-network:
+    driver: bridge
+```
+
+#### Development Override (docker compose.dev.yml)
+
+```yaml
+version: '3.9'
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - .:/app
+      - /app/node_modules  # Preserve dependencies
+    environment:
+      - NODE_ENV=development
+      - DEBUG=true
+    ports:
+      - "3000:3000"
+      - "9229:9229"  # Debug port
+```
+
+#### Test Override (docker compose.test.yml)
+
+```yaml
+version: '3.9'
+services:
+  test:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    command: npm test
+    environment:
+      - NODE_ENV=test
+      - CI=true
+```
+
+### 7. GITHUB ACTIONS INTEGRATION
+
+```yaml
+# .github/workflows/test.yml
+name: Test
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Build Test Image
+        run: docker build -f Dockerfile.dev -t app:test .
+      
+      - name: Run Tests in Container
+        run: docker run --rm app:test npm test
+      
+      - name: Run Linting in Container
+        run: docker run --rm app:test npm run lint
+```
+
+### 8. VOLUME MOUNTING STRATEGY
+
+```yaml
+# Development volumes for hot reload
+volumes:
+  # Source code - always mounted
+  - ./src:/app/src
+  - ./tests:/app/tests
+  
+  # Config files - mounted read-only
+  - ./package.json:/app/package.json:ro
+  - ./tsconfig.json:/app/tsconfig.json:ro
+  
+  # Dependencies - NOT mounted (use container's)
+  # - ./node_modules:/app/node_modules  ❌
+  # - ./.venv:/app/.venv                ❌
+```
+
+### 9. DATABASE IN DOCKER
+
+```yaml
+# docker compose.dev.yml
+services:
+  app:
+    depends_on:
+      - db
+      - redis
+  
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_DB: appdb
+      POSTGRES_USER: appuser
+      POSTGRES_PASSWORD: devpassword
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
+  
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  postgres_data:
+```
+
+### 10. HELPER COMMANDS
+
+Create a Makefile for common operations:
+
+```makefile
+# Makefile
+.PHONY: dev test build clean
+
+# Development
+dev:
+ docker compose -f docker compose.yml -f docker compose.dev.yml up
+
+dev-build:
+ docker compose -f docker compose.yml -f docker compose.dev.yml build
+
+# Testing
+test:
+ docker compose -f docker compose.yml -f docker compose.test.yml run --rm test
+
+test-watch:
+ docker compose -f docker compose.yml -f docker compose.test.yml run --rm test npm run test:watch
+
+# Production
+build:
+ docker build -t app:latest .
+
+run:
+ docker run -p 3000:3000 app:latest
+
+# Utilities
+shell:
+ docker compose -f docker compose.yml -f docker compose.dev.yml exec app sh
+
+logs:
+ docker compose logs -f app
+
+clean:
+ docker compose down -v
+ docker system prune -f
+```
+
+## WHEN DISABLED
+
+When `docker_first_development: false` in config:
+
+- Local development is allowed
+- Docker files are optional
+- No enforcement of container usage
+- Traditional development workflow permitted
+
+## PR VALIDATION REQUIREMENTS
+
+When `docker_first_development` is enabled, ALL PRs MUST:
+
+### 1. PASS DOCKER TESTS BEFORE PUSH
+
+```bash
+# Manual validation before creating PR
+./.claude/scripts/pr-validation.sh
+
+# Install Git hooks for automatic validation
+./.claude/scripts/install-hooks.sh
+```
+
+### 2. GITHUB ACTIONS VALIDATION
+
+PR will automatically run:
+
+- Multi-platform Docker builds (linux/amd64, linux/arm64)  
+- Tests in Docker containers using same images as local dev
+- Security scanning with Trivy
+- Docker-first compliance validation
+- Startup testing
+
+### 3. REQUIRED FILES FOR PR
+
+- `Dockerfile` - Production image
+- `Dockerfile.dev` - Development image  
+- `docker compose.yml` - Base configuration
+- `docker compose.test.yml` - Test configuration
+- `.dockerignore` - Build optimization
+
+### 4. AUTOMATED BLOCKING
+
+**Pre-push hook blocks push if:**
+
+- Docker tests fail
+- Docker images don't build
+- Required Docker files missing
+- Docker daemon not running
+
+**GitHub Actions blocks PR if:**
+
+- Any Docker tests fail
+- Security vulnerabilities found (HIGH/CRITICAL)
+- Multi-platform builds fail
+- Container startup fails
+
+### 5. PR VALIDATION WORKFLOW
+
+```bash
+# Full validation (recommended)
+./.claude/scripts/pr-validation.sh
+
+# Quick validation (skip some tests)
+./.claude/scripts/pr-validation.sh --force
+
+# Skip tests entirely (not recommended)  
+./.claude/scripts/pr-validation.sh --skip-tests
+```
+
+### 6. CI/CD REQUIREMENTS
+
+GitHub Actions workflow (`.github/workflows/docker-tests.yml`) runs:
+
+1. **Change Detection** - Only runs Docker tests when needed
+2. **Multi-Environment Testing** - Tests dev and production configs
+3. **Security Scanning** - Trivy vulnerability scan
+4. **Multi-Platform Builds** - AMD64 and ARM64 architectures
+5. **Compliance Validation** - Checks Docker-first requirements
+
+## BYPASS PROCEDURES (EMERGENCY ONLY)
+
+```bash
+# Bypass git hooks temporarily
+git push --no-verify
+
+# Disable Docker-first for urgent fixes
+./.claude/scripts/docker-toggle.sh disable
+# Don't forget to re-enable after fix!
+```
+
+## CHECKING STATUS
+
+```bash
+# Check Docker-first status with detailed info
+./.claude/scripts/docker-toggle.sh status
+
+# Quick check
+cat .claude/config.json | jq '.features.docker_first_development'
+
+# Manual toggle
+./.claude/scripts/docker-toggle.sh enable   # or disable
+```

package/packages/plugin-devops/rules/github-operations.md

@@ -0,0 +1,92 @@
+# GitHub Operations Rule
+
+Standard patterns for GitHub CLI operations across all commands.
+
+## CRITICAL: Repository Protection
+
+**Before ANY GitHub operation that creates/modifies issues or PRs:**
+
+```bash
+# Check if remote origin is the AutoPM template repository
+remote_url=$(git remote get-url origin 2>/dev/null || echo "")
+if [[ "$remote_url" == *"rlagowski/autopm"* ]] || [[ "$remote_url" == *"rlagowski/autopm.git"* ]]; then
+  echo "❌ ERROR: You're trying to sync with the AutoPM template repository!"
+  echo ""
+  echo "This repository (rlagowski/autopm) is a template for others to use."
+  echo "You should NOT create issues or PRs here."
+  echo ""
+  echo "To fix this:"
+  echo "1. Fork this repository to your own GitHub account"
+  echo "2. Update your remote origin:"
+  echo "   git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO.git"
+  echo ""
+  echo "Or if this is a new project:"
+  echo "1. Create a new repository on GitHub"
+  echo "2. Update your remote origin:"
+  echo "   git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO.git"
+  echo ""
+  echo "Current remote: $remote_url"
+  exit 1
+fi
+```
+
+This check MUST be performed in ALL commands that:
+
+- Create issues (`gh issue create`)
+- Edit issues (`gh issue edit`)
+- Comment on issues (`gh issue comment`)
+- Create PRs (`gh pr create`)
+- Any other operation that modifies the GitHub repository
+
+## Authentication
+
+**Don't pre-check authentication.** Just run the command and handle failure:
+
+```bash
+gh {command} || echo "❌ GitHub CLI failed. Run: gh auth login"
+```
+
+## Common Operations
+
+### Get Issue Details
+
+```bash
+gh issue view {number} --json state,title,labels,body
+```
+
+### Create Issue
+
+```bash
+# ALWAYS check remote origin first!
+gh issue create --title "{title}" --body-file {file} --label "{labels}"
+```
+
+### Update Issue
+
+```bash
+# ALWAYS check remote origin first!
+gh issue edit {number} --add-label "{label}" --add-assignee @me
+```
+
+### Add Comment
+
+```bash
+# ALWAYS check remote origin first!
+gh issue comment {number} --body-file {file}
+```
+
+## Error Handling
+
+If any gh command fails:
+
+1. Show clear error: "❌ GitHub operation failed: {command}"
+2. Suggest fix: "Run: gh auth login" or check issue number
+3. Don't retry automatically
+
+## Important Notes
+
+- **ALWAYS** check remote origin before ANY write operation to GitHub
+- Trust that gh CLI is installed and authenticated
+- Use --json for structured output when parsing
+- Keep operations atomic - one gh command per action
+- Don't check rate limits preemptively

package/packages/plugin-devops/scripts/examples/docker-build-multistage.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Docker multi-stage build example with optimization
+# Usage: ./docker-build-multistage.sh [image-name] [tag]
+
+set -euo pipefail
+
+IMAGE_NAME="${1:-myapp}"
+TAG="${2:-latest}"
+DOCKERFILE="${DOCKERFILE:-Dockerfile}"
+
+echo "🐳 Building multi-stage Docker image: ${IMAGE_NAME}:${TAG}..."
+
+# Check Docker is installed
+if ! command -v docker &> /dev/null; then
+    echo "❌ Docker not found. Please install it first."
+    exit 1
+fi
+
+# Build with BuildKit for better caching and performance
+export DOCKER_BUILDKIT=1
+
+echo "📦 Building image with BuildKit optimization..."
+docker build \
+    --build-arg BUILDKIT_INLINE_CACHE=1 \
+    --tag "${IMAGE_NAME}:${TAG}" \
+    --file "${DOCKERFILE}" \
+    .
+
+# Get image size
+IMAGE_SIZE=$(docker images "${IMAGE_NAME}:${TAG}" --format "{{.Size}}")
+echo "✅ Image built successfully: ${IMAGE_NAME}:${TAG} (Size: ${IMAGE_SIZE})"
+
+# Optional: Security scan with Trivy if available
+if command -v trivy &> /dev/null; then
+    echo "🔒 Running security scan with Trivy..."
+    trivy image --severity HIGH,CRITICAL "${IMAGE_NAME}:${TAG}"
+fi
+
+# Optional: Show image layers
+echo "📊 Image layers:"
+docker history "${IMAGE_NAME}:${TAG}" --no-trunc --human
+
+echo "✅ Build complete: ${IMAGE_NAME}:${TAG}"

package/packages/plugin-devops/scripts/examples/docker-compose-validate.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Docker Compose validation and health check
+# Usage: ./docker-compose-validate.sh [compose-file]
+
+set -euo pipefail
+
+COMPOSE_FILE="${1:-docker-compose.yml}"
+
+echo "🐳 Validating Docker Compose configuration: ${COMPOSE_FILE}..."
+
+# Check docker-compose is installed
+if ! command -v docker-compose &> /dev/null && ! docker compose version &> /dev/null; then
+    echo "❌ docker-compose not found. Please install it first."
+    exit 1
+fi
+
+# Use 'docker compose' or 'docker-compose' based on availability
+if docker compose version &> /dev/null 2>&1; then
+    COMPOSE_CMD="docker compose"
+else
+    COMPOSE_CMD="docker-compose"
+fi
+
+# Validate compose file syntax
+echo "📋 Validating Compose file syntax..."
+if $COMPOSE_CMD -f "${COMPOSE_FILE}" config > /dev/null; then
+    echo "  ✓ Compose file syntax is valid"
+else
+    echo "  ❌ Compose file has syntax errors"
+    exit 1
+fi
+
+# Show parsed configuration
+echo ""
+echo "📊 Parsed configuration:"
+$COMPOSE_CMD -f "${COMPOSE_FILE}" config --services
+
+# Check for common issues
+echo ""
+echo "🔍 Checking for common issues..."
+
+# Check for missing environment variables
+if grep -q '\${[A-Z_]*}' "${COMPOSE_FILE}"; then
+    echo "  ⚠️  Warning: Compose file contains environment variable references"
+    echo "     Make sure all required variables are set in .env file"
+fi
+
+# Check for volume definitions
+VOLUMES=$($COMPOSE_CMD -f "${COMPOSE_FILE}" config --volumes 2>/dev/null | wc -l)
+if [ "$VOLUMES" -gt 0 ]; then
+    echo "  ✓ Volumes defined: ${VOLUMES}"
+    $COMPOSE_CMD -f "${COMPOSE_FILE}" config --volumes
+fi
+
+# Check for network definitions
+NETWORKS=$($COMPOSE_CMD -f "${COMPOSE_FILE}" config --networks 2>/dev/null | wc -l)
+if [ "$NETWORKS" -gt 0 ]; then
+    echo "  ✓ Networks defined: ${NETWORKS}"
+fi
+
+# If compose stack is running, check health
+if $COMPOSE_CMD -f "${COMPOSE_FILE}" ps | grep -q "Up"; then
+    echo ""
+    echo "📊 Running services status:"
+    $COMPOSE_CMD -f "${COMPOSE_FILE}" ps
+
+    # Check logs for errors (last 50 lines)
+    echo ""
+    echo "📋 Recent logs (last 50 lines):"
+    $COMPOSE_CMD -f "${COMPOSE_FILE}" logs --tail=50
+fi
+
+echo ""
+echo "✅ Docker Compose validation complete"

package/packages/plugin-devops/scripts/examples/github-workflow-validate.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# GitHub Actions workflow validation
+# Usage: ./github-workflow-validate.sh [workflow-file]
+
+set -euo pipefail
+
+WORKFLOW_FILE="${1:-.github/workflows/*.yml}"
+
+echo "🔍 Validating GitHub Actions workflows..."
+
+# Check GitHub CLI is installed
+if ! command -v gh &> /dev/null; then
+    echo "❌ GitHub CLI not found. Please install it first."
+    echo "   Visit: https://cli.github.com/"
+    exit 1
+fi
+
+# Check if logged in
+if ! gh auth status &> /dev/null; then
+    echo "❌ Not logged into GitHub CLI. Please run: gh auth login"
+    exit 1
+fi
+
+# Validate workflow syntax
+echo "📋 Checking workflow syntax..."
+for workflow in .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null; do
+    if [ -f "$workflow" ]; then
+        echo "  ✓ Validating: $workflow"
+        # Check YAML syntax
+        if command -v yamllint &> /dev/null; then
+            yamllint "$workflow" || echo "    ⚠️  YAML lint warnings found"
+        fi
+
+        # Validate with GitHub Actions
+        if gh workflow view "$(basename "$workflow")" &> /dev/null; then
+            echo "    ✓ Workflow exists on GitHub"
+        else
+            echo "    ⚠️  Workflow not found on GitHub (may not be pushed yet)"
+        fi
+    fi
+done
+
+# List all workflows
+echo ""
+echo "📊 Available workflows:"
+gh workflow list
+
+echo "✅ Workflow validation complete"