gh-rknall-claude-skills-stack-validator/SKILL.md

---
name: "GitLab Stack Validator"
description: "Validates GitLab stack projects before deployment, ensuring proper architecture patterns, directory structure, secrets management, .env configuration, and Docker best practices. Use when users ask to validate a stack, check stack configuration, verify stack architecture, audit stack setup, or ensure stack deployment readiness."
---

# GitLab Stack Validator

This skill validates GitLab stack projects to ensure they follow proper architecture patterns and are ready for deployment. It focuses on **detection and reporting** of issues, working alongside companion skills (stack-creator, secrets-manager) for remediation.

## When to Use This Skill

Activate this skill when the user requests:
- Validate a GitLab stack project
- Check stack configuration before deployment
- Verify stack architecture and structure
- Audit stack for best practices compliance
- Ensure stack follows proper patterns
- Pre-deployment validation checks
- Stack health check or readiness verification

## Core Validation Principles

This skill validates stacks that follow these architecture principles:

1. **Configuration Management**: All configuration through docker-compose.yml and ./config directory
2. **Secrets Management**: Secrets stored in ./secrets and referenced via Docker secrets
3. **Environment Variables**: .env file with matching .env.example template
4. **Minimal Custom Scripts**: docker-entrypoint.sh only when containers don't support native secrets
5. **Proper Ownership**: No root-owned files (all files owned by Docker user)
6. **Temporary Files**: _temporary directory for transient files that are cleaned up after use
7. **Docker Best Practices**: Leverage docker-validation skill for Docker-specific checks

## Validation Workflow

When a user requests stack validation, follow this comprehensive workflow:

### Phase 1: Pre-flight Checks

**Step 1: Verify Stack Project**
1. Check if current directory appears to be a stack project
2. Look for key indicators:
   - docker-compose.yml exists
   - Presence of ./config, ./secrets, or ./_temporary directories
   - .env file exists
3. If not a stack project, report findings and ask if user wants to initialize one

**Step 2: Gather Context**
1. Ask user for validation scope (if needed):
   - Full validation or targeted checks?
   - Strict mode or permissive mode?
   - Output format preference (text report vs JSON)?
2. Check if .stack-validator.yml exists for custom rules
3. Note the working directory for reporting

### Phase 2: Directory Structure Validation

**Step 1: Required Directories**
1. Check for required directories:
   - `./config` - Configuration files directory
   - `./secrets` - Secrets storage directory
   - `./_temporary` - Temporary files directory
2. For each missing directory, record:
   - Directory name
   - Purpose and why it's required
   - Impact on stack functionality

**Step 2: Directory Permissions**
1. Check ./secrets has restricted permissions (700 or 600)
2. Verify other directories have appropriate permissions
3. Report any permission issues with security implications

**Step 3: Directory Ownership**
1. Scan all project directories for ownership
2. Flag any root-owned directories:
   - Directory path
   - Current owner
   - Expected owner (current user or docker user)
3. Flag any files with unexpected ownership

**Step 4: .gitignore Validation**
1. Check if .gitignore exists
2. Verify it excludes:
   - `./secrets` or `./secrets/*`
   - `./_temporary` or `./_temporary/*`
   - `.env` (should not be in git)
3. Report missing exclusions with security implications

### Phase 3: Environment Variables Validation

**Step 1: .env File Validation**
1. Check if .env file exists
2. Parse .env file for:
   - Syntax errors
   - Duplicate variable definitions
   - Empty values that might be required
3. Record all environment variable names found

**Step 2: .env.example Validation**
1. Check if .env.example exists
2. If missing, this is a **critical issue** - document why it's needed
3. Parse .env.example for variable names

**Step 3: .env Synchronization Check**
1. Compare variables in .env with .env.example:
   - Variables in .env but NOT in .env.example
   - Variables in .env.example but NOT in .env
2. This is a **critical validation point** - they must match
3. Report any mismatches with specific variable names

**Step 4: Environment Variable Security**
1. Scan .env for potential secrets:
   - Variables with names containing: password, secret, key, token, api
   - Base64-encoded looking values
   - Long random strings
2. If secrets detected in .env, flag as security issue
3. Suggest moving to ./secrets and Docker secrets instead

### Phase 4: Docker Configuration Validation

**Step 1: Invoke docker-validation Skill**
1. Use the docker-validation skill to validate:
   - docker-compose.yml syntax and best practices
   - Dockerfile(s) if present
   - Multi-stage builds
   - Security configurations
2. Collect all findings from docker-validation
3. Integrate into overall stack validation report

**Step 2: Stack-Specific Docker Checks**
1. Review docker-compose.yml for stack patterns:
   - Secrets are defined in top-level `secrets:` section
   - Services reference secrets via `secrets:` key (not environment variables)
   - Volume mounts follow patterns (./config, ./secrets, ./_temporary)
   - Networks are properly defined if multi-service
   - Service dependencies use `depends_on` correctly

**Step 3: Version Check**
1. Ensure docker-compose.yml does NOT have version field at top
2. This follows modern Docker Compose specification
3. If version field present, flag for removal

### Phase 5: Secrets Management Validation

**Step 1: Secrets Directory Check**
1. Verify ./secrets directory exists
2. Check permissions are restrictive (700)
3. Verify it's excluded from git

**Step 2: Docker Secrets Validation**
1. Parse docker-compose.yml for secrets definitions
2. For each secret definition:
   - Verify the secret file exists in ./secrets
   - Check file permissions (600 or 400)
   - Verify not tracked by git
3. Report missing secret files

**Step 3: Secret References Validation**
1. Check each service's `secrets:` section
2. Verify referenced secrets are defined in top-level secrets
3. Flag any undefined secret references

**Step 4: Environment Variables vs Secrets**
1. Scan service environment variables for potential secrets
2. Look for patterns like:
   - *_PASSWORD
   - *_SECRET
   - *_KEY
   - *_TOKEN
   - API_*
3. If sensitive data in environment, suggest using secrets instead

**Step 5: Secret Exposure Check**
1. Check for secrets in:
   - docker-compose.yml (hardcoded values)
   - .env file (should be in ./secrets instead)
   - Configuration files in ./config
   - Any shell scripts
2. Report any exposed secrets as **critical security issues**

### Phase 6: Configuration Files Validation

**Step 1: Config Directory Structure**
1. List all files in ./config directory
2. Organize by service (if applicable)
3. Check for proper organization

**Step 2: Config File Validation**
1. For common config file types, validate syntax:
   - YAML files (.yml, .yaml)
   - JSON files (.json)
   - INI files (.ini, .conf)
   - TOML files (.toml)
2. Report any syntax errors

**Step 3: Config vs Secrets Separation**
1. Scan config files for potential secrets
2. Look for hardcoded passwords, tokens, keys
3. Flag any secrets that should be in ./secrets instead

**Step 4: Config Ownership**
1. Check all config files for ownership
2. Flag any root-owned config files
3. Report expected ownership (current user)

### Phase 7: Script Validation

**Step 1: docker-entrypoint.sh Detection**
1. Search for docker-entrypoint.sh files
2. For each found:
   - Document location
   - Check if truly necessary
3. Validate it's only used when container doesn't support native secrets

**Step 2: Script Permissions**
1. Check docker-entrypoint.sh is executable (chmod +x)
2. Verify ownership (should not be root)
3. Report permission issues

**Step 3: Script Content Validation**
1. Scan script for:
   - Hardcoded secrets (critical issue)
   - Proper secret handling from /run/secrets/
   - Error handling
   - Syntax errors (if bash/sh)
2. Report any issues found

**Step 4: Necessity Check**
1. Review if docker-entrypoint.sh is truly needed
2. Check if service supports native Docker secrets
3. Suggest removal if unnecessary

### Phase 8: Temporary Directory Validation

**Step 1: Directory Check**
1. Verify ./_temporary exists
2. Check it's in .gitignore
3. Verify permissions

**Step 2: Content Check**
1. List contents of ./_temporary
2. Check for:
   - Leftover files that should be cleaned
   - Large files consuming space
   - Old files (> 7 days old)
3. Report if not empty with details

**Step 3: Usage Validation**
1. Check if ./_temporary is properly mounted in docker-compose.yml
2. Verify services use it for temporary files
3. Flag if not being utilized

### Phase 9: File Ownership Audit

**Step 1: Comprehensive Ownership Scan**
1. Use `find . -type f -user root 2>/dev/null` to find root-owned files
2. Exclude expected directories (.git, node_modules, vendor)
3. List all root-owned files found

**Step 2: Categorize Issues**
1. Group by directory:
   - ./config files owned by root
   - ./secrets files owned by root
   - Application files owned by root
2. Report with specific paths

**Step 3: Impact Assessment**
1. For each root-owned file:
   - Explain why this is problematic
   - Impact on stack operations
   - Potential errors that may occur

### Phase 10: Report Generation

**Step 1: Compile All Findings**
1. Organize findings by category:
   - Directory Structure
   - Environment Variables (.env sync)
   - Docker Configuration
   - Secrets Management
   - Configuration Files
   - Scripts (docker-entrypoint.sh)
   - Temporary Directory
   - File Ownership
2. Assign severity levels:
   - ❌ **CRITICAL**: Security issues, missing required components, .env mismatch
   - ⚠️ **WARNING**: Best practice violations, potential issues
   - ✅ **PASS**: No issues found

**Step 2: Generate Validation Report**

Create a comprehensive report with this structure:

```
🔍 GitLab Stack Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stack: [directory name]
Date: [timestamp]
Mode: [strict/permissive]

📊 SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Passed: [count]
⚠️  Warnings: [count]
❌ Critical: [count]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 DETAILED FINDINGS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[For each validation category]

[Category Icon] [Category Name]: [STATUS]
[If issues found:]
   ❌ [Issue description]
      Location: [file/directory path]
      Impact: [what this affects]
      Details: [specific information]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 OVERALL STATUS: [PASSED/FAILED/WARNINGS]

[If failures or warnings:]
🔧 RECOMMENDED ACTIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Prioritized list of actions needed]
1. [Most critical action]
2. [Next action]
...

💡 NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Use stack-creator skill to fix structural issues
- Use secrets-manager skill to properly configure secrets
- Re-run validation after fixes
```

**Step 3: Provide Actionable Guidance**
1. For each issue, provide:
   - Clear description of the problem
   - Why it matters
   - Which companion skill can help fix it
   - General guidance (but not actual fix commands)
2. Prioritize issues by severity
3. Group related issues together

**Step 4: Export Options**
1. If user requested JSON output, export as:
   ```json
   {
     "stack": "directory-name",
     "timestamp": "ISO-8601",
     "summary": {
       "passed": 5,
       "warnings": 2,
       "critical": 1,
       "status": "failed"
     },
     "findings": [
       {
         "category": "environment-variables",
         "status": "critical",
         "issues": [...]
       }
     ]
   }
   ```

## Validation Categories Reference

### 1. Directory Structure
- Required directories exist
- Proper permissions
- .gitignore coverage
- Ownership correctness

### 2. Environment Variables
- .env file exists and valid
- .env.example exists
- **CRITICAL**: .env and .env.example are synchronized
- No secrets in .env

### 3. Docker Configuration
- docker-compose.yml valid (via docker-validation skill)
- No version field
- Secrets properly defined
- Volumes follow patterns
- Service dependencies correct

### 4. Secrets Management
- ./secrets directory secure
- All referenced secrets exist
- Proper permissions
- No exposed secrets
- Environment variables don't contain secrets

### 5. Configuration Files
- Proper organization
- Valid syntax
- No embedded secrets
- Correct ownership

### 6. Scripts
- docker-entrypoint.sh only when necessary
- Executable permissions
- No hardcoded secrets
- Proper secret handling

### 7. Temporary Directory
- Exists and in .gitignore
- Empty or contains only expected transient files
- Properly utilized in compose file

### 8. File Ownership
- No root-owned files
- Consistent ownership
- Proper user/group

## Integration with Companion Skills

### stack-creator
- Recommend for: Creating missing directories, initializing structure
- Handles: Setting up new stacks, fixing structural issues

### secrets-manager
- Recommend for: Secrets configuration, secret file management
- Handles: Creating/updating secrets, proper secret setup

### docker-validation
- **Used directly during validation** for Docker-specific checks
- Provides: Docker Compose and Dockerfile validation
- Integrated into stack validation report

## Validation Modes

### Standard Mode (Default)
- Report all issues as warnings or errors
- Provide comprehensive findings
- Suggest improvements

### Strict Mode
- Fail on warnings
- Require all best practices
- Zero tolerance for deviations

### Permissive Mode
- Only fail on critical issues
- Allow warnings
- More lenient on best practices

## Configuration Support

If `.stack-validator.yml` exists in project root, respect these settings:

```yaml
# Validation mode
strict_mode: false

# Whether warnings should fail validation
fail_on_warnings: false

# Paths to exclude from validation
exclude_paths:
  - ./vendor
  - ./node_modules
  - ./_temporary/cache

# Custom validation scripts to run
custom_checks:
  - ./scripts/custom-validation.sh

# Specific checks to skip
skip_checks:
  - temporary-directory-empty
```

## Communication Style

When reporting validation results:

1. **Be Clear and Direct**: State issues plainly without hedging
2. **Be Specific**: Include exact file paths, line numbers, variable names
3. **Be Actionable**: Explain what needs to be done (without doing it)
4. **Be Helpful**: Point to companion skills that can fix issues
5. **Be Organized**: Group related issues, prioritize by severity
6. **Be Educational**: Explain why something is an issue
7. **Be Concise**: Don't overwhelm with details, but be thorough

## Critical Validation Points

These are **must-pass** criteria for production stacks:

1. ✅ .env and .env.example are fully synchronized
2. ✅ No secrets in docker-compose.yml environment variables
3. ✅ ./secrets directory exists and has restrictive permissions
4. ✅ All referenced secrets exist
5. ✅ ./secrets and ./_temporary are in .gitignore
6. ✅ No root-owned files
7. ✅ docker-compose.yml passes docker-validation
8. ✅ No secrets exposed in git
9. ✅ .env file is not tracked by git

## Important Notes

- **Read-Only**: This skill NEVER modifies files - validation only
- **Detection-Focused**: Report issues, don't fix them
- **Comprehensive**: Check all aspects systematically
- **Fast**: Complete validation in seconds
- **Integrative**: Use docker-validation skill for Docker checks
- **Companion-Aware**: Direct users to appropriate skills for fixes

## Example Validation Flow

```
User: "Validate my stack"

1. Check if docker-compose.yml exists ✅
2. Verify directory structure
   - ./config ✅
   - ./secrets ✅
   - ./_temporary ⚠️ (not in .gitignore)
3. Validate .env configuration
   - .env exists ✅
   - .env.example exists ❌ CRITICAL
4. Run docker-validation skill
   - docker-compose.yml syntax ✅
   - Secrets configuration ⚠️ (using environment vars)
5. Check secrets management
   - ./secrets permissions ✅
   - Secret files exist ✅
6. Scan for ownership issues
   - Found 3 root-owned files in ./config ❌
7. Generate report with findings
8. Suggest: Use stack-creator to add .env.example and fix .gitignore
```

---

*This skill ensures stack quality, security, and deployment readiness through comprehensive validation.*