GitLab Stack Creator

What this skill does

# GitLab Stack Creator

Expert assistance for creating new GitLab stack projects with proper structure, git configuration, validation scripts, and comprehensive documentation.

## When to Use This Skill

This skill should be triggered when:
- Creating a new GitLab stack project
- Initializing a Docker stack with proper structure
- Setting up a project with ./config, ./secrets, ./_temporary directories
- Configuring git repository for stack projects
- Setting up validation hooks and scripts
- Bootstrapping a stack project with best practices

## Core Principles

This skill follows the GitLab Stack Management patterns:

1. **Everything configured through docker-compose.yml and ./config**
2. **Secrets stored in ./secrets and Docker secrets**
3. **docker-entrypoint.sh scripts only when containers don't support native secrets**
4. **All container files owned by the user running docker (no root-owned files)**
5. **./_temporary directory for transient setup files (cleaned up after use)**
6. **Complete validation before considering stack creation complete**

## Stack Creation is Complete When

A stack creation is considered COMPLETE only when:

1. ✅ **stack-validator** skill reports NO issues
2. ✅ **secrets-manager** skill is satisfied with NO open issues
3. ✅ **docker-validation** skill is satisfied with NO issues
4. ✅ All validation scripts execute successfully
5. ✅ Git repository is properly initialized and configured
6. ✅ Documentation is complete in ./docs

**IMPORTANT**: NEVER use workarounds. If the direct approach is not working, STOP and ask the user what to do instead.

## Stack Creation Workflow

### Phase 1: Project Initialization

#### 1.1 Gather Requirements

Ask the user:
- Project name
- Primary services needed (nginx, PostgreSQL, Redis, etc.)
- Remote git repository URL (if any)
- Environment (development, staging, production)
- Special requirements

**NEVER assume** - always ask if information is missing.

#### 1.2 Check Existing Setup

Before creating anything:
- Check if directory already exists
- Check if git repository exists
- Ask user how to proceed if conflicts exist
- NEVER overwrite without explicit permission

### Phase 2: Directory Structure Creation

Create the standard directory structure:

```
project-name/
├── .git/                       # Git repository
│   ├── hooks/                  # Git hooks (validation scripts)
│   └── config                  # Git configuration
├── config/                     # Service configurations
│   ├── nginx/                  # Nginx configs (if needed)
│   ├── postgres/               # PostgreSQL configs (if needed)
│   └── redis/                  # Redis configs (if needed)
├── secrets/                    # Docker secrets files
│   └── .gitkeep               # Keep directory in git
├── _temporary/                 # Temporary files (gitignored)
├── scripts/                    # Validation and utility scripts
│   ├── pre-commit              # Pre-commit validation hook
│   ├── validate-stack.sh       # Full stack validation
│   └── setup-hooks.sh          # Hook installation script
├── docs/                       # Project documentation
│   ├── decisions/              # Architecture decision records
│   ├── setup.md                # Setup instructions
│   └── services.md             # Service documentation
├── docker-compose.yml          # Main compose file
├── .env.example                # Environment template
├── .gitignore                  # Git exclusions
├── .dockerignore               # Docker exclusions
├── CLAUDE.md                   # Claude Code instructions
└── README.md                   # Project overview
```

**Actions**:
1. Create directories: `mkdir -p config secrets _temporary scripts docs/decisions`
2. Create placeholder files: `touch secrets/.gitkeep`
3. Set proper permissions: `chmod 700 secrets`

### Phase 3: Git Repository Setup

#### 3.1 Initialize or Connect Repository

**If NO git repository exists**:
- Strongly suggest creating a local repository
- Ask if remote repository should be added
- Initialize with `git init`
- Set main as default branch: `git config init.defaultBranch main`

**If remote repository URL provided**:
- Clone repository: `git clone <url> <project-name>`
- Or add remote: `git remote add origin <url>`
- Verify remote connection: `git remote -v`

**If setup fails**: STOP and ask user for guidance. NEVER attempt workarounds.

#### 3.2 Configure Git

Set required git configuration:
```bash
# Set main as branch name
git config init.defaultBranch main

# Set ff-only merge strategy
git config pull.ff only
git config merge.ff only

# Ensure no rebase by default
git config pull.rebase false

# Set user info if not set globally
git config user.name "User Name"
git config user.email "[email protected]"
```

**If configuration fails**: Ask user to set configuration manually or provide correct values.

#### 3.3 Create .gitignore

Generate comprehensive .gitignore:
```gitignore
# Secrets - NEVER commit
secrets/*
!secrets/.gitkeep
*.key
*.pem
*.crt
*.p12
*.pfx

# Environment files
.env
.env.local
.env.*.local

# Temporary files
_temporary/
*.tmp
*.temp
.cache/

# Docker
.docker/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db
*.log

# Backup files
*.bak
*.backup
```

#### 3.4 Create .dockerignore

Generate .dockerignore:
```dockerignore
.git
.gitignore
README.md
docs/
_temporary/
*.md
.env
.env.example
secrets/
.vscode/
.idea/
```

### Phase 4: Validation Scripts Setup

#### 4.1 Create scripts/validate-stack.sh

Generate comprehensive validation script that:
- Calls stack-validator skill
- Calls secrets-manager skill validation
- Calls docker-validation skill
- Reports all issues
- Returns exit code 0 only if all pass

**Template**:
```bash
#!/usr/bin/env bash
set -euo pipefail

echo "=== GitLab Stack Validation ==="
echo

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

ERRORS=0

echo "1. Validating stack structure..."
if ! claude-code-cli run stack-validator; then
    echo -e "${RED}✗ Stack validation failed${NC}"
    ((ERRORS++))
else
    echo -e "${GREEN}✓ Stack validation passed${NC}"
fi
echo

echo "2. Validating secrets configuration..."
if ! claude-code-cli run secrets-manager --validate; then
    echo -e "${RED}✗ Secrets validation failed${NC}"
    ((ERRORS++))
else
    echo -e "${GREEN}✓ Secrets validation passed${NC}"
fi
echo

echo "3. Validating Docker configuration..."
if ! claude-code-cli run docker-validation; then
    echo -e "${RED}✗ Docker validation failed${NC}"
    ((ERRORS++))
else
    echo -e "${GREEN}✓ Docker validation passed${NC}"
fi
echo

if [ $ERRORS -gt 0 ]; then
    echo -e "${RED}Validation failed with $ERRORS error(s)${NC}"
    exit 1
fi

echo -e "${GREEN}All validations passed!${NC}"
exit 0
```

Make executable: `chmod +x scripts/validate-stack.sh`

#### 4.2 Create scripts/pre-commit

Generate pre-commit hook:
```bash
#!/usr/bin/env bash
set -euo pipefail

echo "Running pre-commit validation..."

# Check for secrets in staged files
if git diff --cached --name-only | grep -qE "secrets/.*[^.gitkeep]|\.env$"; then
    echo "ERROR: Attempting to commit secrets or .env file!"
    echo "Secrets should never be committed to git."
    exit 1
fi

# Check for root-owned files
if find . -user root -not -path "./.git/*" 2>/dev/null | grep -q .; then
    echo "ERROR: Root-owned files detected!"
    echo "All files should be owned by the user running Docker."
    exit 1
fi

# Run quick validation (if available)
if [ -x "./scripts/validate-stack.sh" ]; then
    echo "Running stack validation..."
    if ! ./scripts/validate-stack.sh; then
        echo "ERROR: Stack validation failed!"
        echo "Fix issues before committing, or use 'git commit --no-verify' to skip."
        exit 1
    fi
fi

echo "Pre-commit validation passed!"
exit 0
```

Make executable: `chmod +x scripts/pre-commit`

#### 4.3 Create scripts/setup-hooks.sh

Generate hook installation script:
```bash
#!/usr/bin