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:
-
Everything configured through docker-compose.yml and ./config
-
Secrets stored in ./secrets and Docker secrets
-
docker-entrypoint.sh scripts only when containers don't support native secrets
-
All container files owned by the user running docker (no root-owned files)
-
./_temporary directory for transient setup files (cleaned up after use)
-
Complete validation before considering stack creation complete
Stack Creation is Complete When
A stack creation is considered COMPLETE only when:
-
✅ stack-validator skill reports NO issues
-
✅ secrets-manager skill is satisfied with NO open issues
-
✅ docker-validation skill is satisfied with NO issues
-
✅ All validation scripts execute successfully
-
✅ Git repository is properly initialized and configured
-
✅ 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:
-
Create directories:
mkdir -p config secrets _temporary scripts docs/decisions -
Create placeholder files:
touch secrets/.gitkeep -
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:
# 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 "user@example.com"
If configuration fails: Ask user to set configuration manually or provide correct values.
3.3 Create .gitignore
Generate comprehensive .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:
.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:
#!/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:
#!/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:
#!/usr/bin/env bash
set -euo pipefail
echo "Installing git hooks..."
# Check if .git directory exists
if [ ! -d ".git" ]; then
echo "ERROR: Not a git repository!"
exit 1
fi
# Install pre-commit hook
if [ -f "scripts/pre-commit" ]; then
cp scripts/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
echo "✓ Installed pre-commit hook"
else
echo "✗ scripts/pre-commit not found"
exit 1
fi
echo "Git hooks installed successfully!"
Make executable: chmod +x scripts/setup-hooks.sh
After creating scripts: Run ./scripts/setup-hooks.sh to install hooks.
Phase 5: Docker Configuration
5.1 Create docker-compose.yml Template
Generate initial docker-compose.yml based on user requirements:
IMPORTANT: Use the docker-validation skill to ensure the docker-compose.yml follows all best practices.
Basic template structure:
services:
# Services will be added based on requirements
# Example: nginx service
nginx:
image: nginx:alpine
container_name: ${PROJECT_NAME:-project}_nginx
restart: unless-stopped
ports:
- "${NGINX_PORT:-80}:80"
volumes:
- ./config/nginx:/etc/nginx/conf.d:ro
networks:
- app-network
networks:
app-network:
driver: bridge
# Secrets will be defined here when needed
secrets: {}
# Volumes for persistent data
volumes: {}
Actions:
-
Generate docker-compose.yml with selected services
-
Use docker-validation skill to validate
-
Fix any issues reported
-
NEVER proceed if validation fails - ask user for guidance
5.2 Create .env.example
Generate environment template:
# Project Configuration
PROJECT_NAME=myproject
# Service Ports
NGINX_PORT=80
# Add more as needed
# Database Configuration (if applicable)
# POSTGRES_PORT=5432
# REDIS_PORT=6379
# IMPORTANT: Copy this file to .env and configure for your environment
# .env is gitignored and should contain actual secrets
Phase 6: Configuration Files
Use the config-generator skill to create service-specific configuration files:
Actions:
-
For each service (nginx, PostgreSQL, Redis), invoke config-generator
-
Generate configs in ./config//
-
Validate generated configs with config-generator validation
-
NEVER proceed with invalid configs - ask user for guidance
Example invocation:
-
"Generate nginx production configuration for this stack"
-
"Create PostgreSQL development configuration"
-
"Generate Redis configuration with persistence"
Phase 7: Secrets Management
Use the secrets-manager skill to set up secrets:
Actions:
-
Identify services that require secrets
-
Use secrets-manager to create secure secrets
-
Configure docker-compose.yml with secret references
-
Generate docker-entrypoint.sh scripts ONLY if containers don't support native Docker secrets
-
Validate with secrets-manager that NO secrets are in .env or docker-compose.yml environment
-
NEVER proceed if secrets-manager reports issues - ask user for guidance
Example invocation:
-
"Set up database password secret for PostgreSQL"
-
"Create Redis password secret"
-
"Generate secure random secret for JWT_SECRET"
Phase 8: Documentation Generation
8.1 Create docs/setup.md
Generate setup documentation:
# Setup Instructions
## Prerequisites
- Docker Engine 20.10+
- Docker Compose V2
- Git
## Initial Setup
1. Clone the repository:
```bash
git clone <repository-url>
cd <project-name>
- Copy environment template:
cp .env.example .env
- Configure environment:
Edit .env with your settings
-
NEVER commit .env to git
-
Set up secrets:
Follow secrets/README.md for secret creation
-
Use
docker secret createfor each secret -
Install git hooks:
./scripts/setup-hooks.sh
- Validate stack:
./scripts/validate-stack.sh
- Start services:
docker compose up -d
Validation
Always run validation before deploying:
./scripts/validate-stack.sh
This checks:
-
Stack structure
-
Secrets configuration
-
Docker configuration
-
File ownership
-
Git exclusions
#### 8.2 Create docs/services.md
Document all services:
```markdown
# Services Documentation
## Service Overview
| Service | Port | Purpose | Configuration |
|---------|------|---------|---------------|
| nginx | 80 | Web server | ./config/nginx |
| ... | ... | ... | ... |
## Service Details
### Nginx
**Image**: nginx:alpine
**Purpose**: Web server and reverse proxy
**Configuration**: ./config/nginx/
**Secrets**: None
**Volumes**:
- ./config/nginx:/etc/nginx/conf.d:ro
### [Other Services]
Document each service similarly...
8.3 Create docs/decisions/0001-stack-architecture.md
Create architecture decision record:
# 1. Stack Architecture
**Date**: YYYY-MM-DD
## Status
Accepted
## Context
This project uses GitLab Stack Management patterns to ensure:
- Consistent configuration management
- Secure secrets handling
- Proper file ownership
- Validated deployments
## Decision
We will follow these principles:
1. All configuration in docker-compose.yml and ./config
2. All secrets in ./secrets and Docker secrets
3. docker-entrypoint.sh only when necessary
4. No root-owned files
5. ./_temporary for transient files
6. Complete validation before deployment
## Consequences
**Positive**:
- Consistent structure across all stacks
- Automated validation prevents issues
- Secure by default
- Easy to maintain and update
**Negative**:
- Initial setup requires more steps
- Must follow strict patterns
- Validation gates can slow rapid iteration
## Compliance
- stack-validator: Ensures structure compliance
- secrets-manager: Ensures secure secrets
- docker-validation: Ensures Docker best practices
8.4 Create CLAUDE.md
Generate Claude Code instructions for the project:
# CLAUDE.md
This file provides guidance to Claude Code when working with this stack project.
## Project Structure
This is a GitLab Stack project following strict patterns:
- Configuration: docker-compose.yml and ./config/
- Secrets: ./secrets/ and Docker secrets
- Temporary: ./_temporary/ (gitignored)
- Documentation: ./docs/
- Validation: ./scripts/
## Required Skills
This project uses these Claude Code skills:
- **stack-validator**: Validate entire stack structure
- **secrets-manager**: Manage Docker secrets securely
- **docker-validation**: Validate Docker configurations
- **config-generator**: Generate service configs
## Git Configuration
**Branch**: main
**Merge Strategy**: ff-only (fast-forward only)
**Hooks**: Pre-commit validation enabled
## Validation Requirements
BEFORE any git commit, ALL these must pass:
1. stack-validator reports NO issues
2. secrets-manager is satisfied
3. docker-validation is satisfied
4. No root-owned files exist
5. No secrets in .env or docker-compose.yml environment
## Making Changes
### Adding a Service
1. Update docker-compose.yml
2. Use config-generator to create configs
3. Use secrets-manager to handle secrets
4. Run ./scripts/validate-stack.sh
5. Fix ALL issues before committing
6. NEVER commit if validation fails
### Modifying Configuration
1. Edit configuration files
2. Validate with docker-validation
3. Run ./scripts/validate-stack.sh
4. Fix ALL issues before committing
### Working with Secrets
1. Use secrets-manager for ALL secret operations
2. NEVER put secrets in .env or docker-compose.yml
3. Use Docker secrets or ./secrets/ directory
4. Validate with secrets-manager before committing
## Commit Standards
**Pre-commit Hook**: Automatically validates before commit
**Skip Hook**: `git commit --no-verify` (emergency only)
**Commit Messages**: Use conventional commits format
Example:
feat: add Redis service with persistence fix: correct nginx proxy configuration docs: update setup instructions
## Important Rules
1. NEVER commit secrets to git
2. NEVER create root-owned files
3. NEVER skip validation without asking
4. NEVER use workarounds - ask user instead
5. ALWAYS run validation before committing
6. ALWAYS document decisions in ./docs/decisions/
7. ALWAYS use ff-only merge strategy
8. ALWAYS use main as branch name
## Troubleshooting
### Validation Fails
1. Review validation output
2. Use respective skill to investigate (stack-validator, secrets-manager, docker-validation)
3. Fix reported issues
4. Re-run validation
5. Ask user if stuck - NEVER use workarounds
### Git Conflicts
1. NEVER use rebase without explicit permission
2. Use ff-only merges
3. Ask user how to resolve conflicts
### Permission Issues
1. Check file ownership: `find . -user root`
2. Fix with: `sudo chown -R $USER:$USER .`
3. Validate with stack-validator
## Resources
- Stack Validator Documentation
- Secrets Manager Documentation
- Docker Validation Documentation
- Config Generator Documentation
8.5 Create README.md
Generate project README:
# Project Name
Brief description of the project.
## Quick Start
```bash
# Clone repository
git clone <url>
cd <project-name>
# Copy environment template
cp .env.example .env
# Configure environment (edit .env)
nano .env
# Install git hooks
./scripts/setup-hooks.sh
# Validate stack
./scripts/validate-stack.sh
# Start services
docker compose up -d
Documentation
Project Structure
.
├── config/ # Service configurations
├── secrets/ # Docker secrets (gitignored except .gitkeep)
├── _temporary/ # Temporary files (gitignored)
├── scripts/ # Validation and utility scripts
├── docs/ # Project documentation
└── docker-compose.yml
Validation
This project uses automated validation:
# Full validation
./scripts/validate-stack.sh
# Pre-commit validation (automatic)
git commit -m "message"
Validation checks:
-
✓ Stack structure (stack-validator)
-
✓ Secrets configuration (secrets-manager)
-
✓ Docker configuration (docker-validation)
-
✓ File ownership (no root files)
-
✓ Git exclusions (.gitignore)
Git Workflow
Branch: main Merge Strategy: ff-only (fast-forward only) Pre-commit Hook: Enabled (validates before commit)
Services
| ... | ... | ...
See Services Documentation for details.
Development
Prerequisites
-
Docker Engine 20.10+
-
Docker Compose V2
-
Git
-
Bash (for scripts)
Adding a Service
-
Update docker-compose.yml
-
Generate configs: Use config-generator skill
-
Set up secrets: Use secrets-manager skill
-
Validate:
./scripts/validate-stack.sh -
Commit changes
Making Changes
-
Make your changes
-
Run validation:
./scripts/validate-stack.sh -
Fix any issues reported
-
Commit (pre-commit hook will validate again)
Troubleshooting
Validation Fails
Run individual validators:
-
claude-code-cli run stack-validator -
claude-code-cli run secrets-manager --validate -
claude-code-cli run docker-validation
Permission Issues
Check for root-owned files:
find . -user root -not -path "./.git/*"
Fix ownership:
sudo chown -R $USER:$USER .
License
[Your License]
Contact
[Your Contact Info]
### Phase 9: Final Validation
#### 9.1 Run Complete Validation
Execute full validation workflow:
```bash
# Run validation script
./scripts/validate-stack.sh
This must check:
-
stack-validator: Full structure validation
-
secrets-manager: All secrets properly configured
-
docker-validation: Docker configs valid
-
File ownership: No root-owned files
-
Git setup: Proper .gitignore, hooks installed
9.2 Verification Checklist
Manually verify:
All directories created Git repository initialized Git configured (main branch, ff-only) .gitignore and .dockerignore created Validation scripts created and executable Git hooks installed docker-compose.yml created and valid .env.example created Service configs generated (if applicable) Secrets properly configured (if applicable) All documentation created CLAUDE.md created README.md created stack-validator: ✓ NO issues secrets-manager: ✓ NO issues docker-validation: ✓ NO issues
9.3 Complete Stack Creation
ONLY mark stack creation as complete when:
-
All validation passes with NO errors
-
All documentation is complete
-
Git repository is properly configured
-
User confirms everything is correct
If ANY validation fails:
-
Report the issue clearly
-
Ask user how to proceed
-
NEVER use workarounds
-
Fix the issue properly
-
Re-validate
Phase 10: Initial Commit
Once all validation passes:
# Stage all files
git add .
# Commit (pre-commit hook will validate)
git commit -m "feat: initial stack setup
- Created directory structure
- Configured git with main branch and ff-only
- Set up validation scripts and hooks
- Generated docker-compose.yml
- Created service configurations
- Set up secrets management
- Added comprehensive documentation"
# Push to remote (if configured)
git push -u origin main
If commit fails due to pre-commit hook:
-
Review validation output
-
Fix issues
-
Re-run validation
-
Try commit again
-
Ask user if issues persist
Communication Style
When creating a stack:
-
Ask clarifying questions for missing information
-
Explain each phase before executing
-
Report validation results clearly
-
NEVER proceed if validation fails
-
Ask user for guidance when stuck
-
Confirm important decisions before executing
-
Document all decisions in ./docs/decisions/
-
Provide clear next steps
Integration with Other Skills
stack-validator
-
Call at the end of Phase 9 (Final Validation)
-
Call in validation scripts
-
Call in pre-commit hooks
-
NEVER proceed if validation fails
secrets-manager
-
Call during Phase 7 (Secrets Management)
-
Use for ALL secret operations
-
Validate secrets configuration
-
NEVER proceed if secrets-manager reports issues
docker-validation
-
Call during Phase 5 (Docker Configuration)
-
Validate docker-compose.yml
-
Validate Dockerfiles (if any)
-
Call in validation scripts
-
NEVER proceed if docker-validation fails
config-generator
-
Call during Phase 6 (Configuration Files)
-
Generate service-specific configs
-
Use for nginx, PostgreSQL, Redis, etc.
-
Validate generated configs
Error Handling
Validation Failure
DO NOT:
-
Try workarounds
-
Skip validation
-
Proceed with errors
-
Assume user wants to continue
DO:
-
Stop immediately
-
Report the issue clearly
-
Show validation output
-
Ask user how to proceed
-
Document the decision
Git Issues
DO NOT:
-
Force push
-
Skip hooks without permission
-
Use rebase without permission
-
Modify git history without permission
DO:
-
Ask user for guidance
-
Explain the issue
-
Provide options
-
Document the solution
Permission Issues
DO NOT:
-
Create root-owned files
-
Use sudo without permission
-
Skip permission checks
DO:
-
Report permission issues
-
Ask user to fix ownership
-
Validate after fixing
-
Document proper ownership
Example Workflows
Workflow 1: Creating a Simple Web Stack
User: "Create a new stack for a web application with nginx"
Assistant: "I'll create a new web stack with nginx. Let me gather some information first."
**Questions**:
1. "What's the project name?"
User: "mywebapp"
2. "Do you have a remote git repository URL?"
User: "https://gitlab.com/user/mywebapp.git"
3. "What environment is this for?"
User: "production"
**Actions**:
1. Create directory structure
2. Initialize git and connect to remote
3. Configure git (main branch, ff-only)
4. Create docker-compose.yml with nginx
5. Use docker-validation to validate
6. Use config-generator to create nginx config
7. Create validation scripts
8. Install git hooks
9. Generate all documentation
10. Run full validation
11. Report status
**Completion**:
"Stack creation complete! All validations passed:
✓ stack-validator: NO issues
✓ secrets-manager: NO issues (no secrets needed)
✓ docker-validation: NO issues
Next steps:
1. Review generated files
2. Customize .env from .env.example
3. Run: docker compose up -d"
Workflow 2: Creating a Full Application Stack
User: "Create a stack with nginx, PostgreSQL, and Redis"
Assistant: "I'll create a full application stack. Let me gather information."
**Questions**:
1. "Project name?" → "myapp"
2. "Remote repository?" → "Yes, https://gitlab.com/user/myapp.git"
3. "Environment?" → "production"
**Actions**:
1. Create directory structure with config/{nginx,postgres,redis}
2. Initialize git, connect remote, configure (main, ff-only)
3. Create docker-compose.yml with all three services
4. Validate with docker-validation
5. Use config-generator for each service:
- nginx production config
- PostgreSQL production config
- Redis production config
6. Use secrets-manager for:
- PostgreSQL password
- Redis password
- Create Docker secrets
7. Create validation scripts and install hooks
8. Generate all documentation
9. Run full validation (stack-validator, secrets-manager, docker-validation)
10. Initial commit
**Completion**:
"Stack creation complete! All validations passed:
✓ stack-validator: NO issues
✓ secrets-manager: All secrets properly configured
✓ docker-validation: NO issues
Services configured:
- nginx (port 80)
- PostgreSQL (port 5432, password in Docker secret)
- Redis (port 6379, password in Docker secret)
Next steps:
1. Review secrets in ./secrets/
2. Customize .env from .env.example
3. Run: docker compose up -d"
Summary
The stack-creator skill:
-
Integrates with stack-validator, secrets-manager, docker-validation, config-generator
-
Enforces complete validation before considering creation complete
-
NEVER uses workarounds - always asks user for guidance
-
Configures git properly (main branch, ff-only merges)
-
Installs validation hooks and scripts
-
Documents everything in ./docs/
-
Creates production-ready stacks following GitLab Stack Management patterns
Stack creation is complete ONLY when all three validators pass with NO issues and all documentation is in place.