Agent Skills: Validate Git Hygiene

Validate Git Hygiene

Purpose

Validate git repository hygiene including commit message format, branch naming conventions, and sensitive file detection.

When to Use

• Conductor Phase 2 (Implementation) - Branch validation
• Conductor Phase 4 (PR Creation) - Commit validation
• Pre-commit hooks validation
• Security audits (sensitive file detection)
• Git workflow compliance checks

Validation Checks

1. Commit Messages: Conventional Commits format
2. Branch Naming: Standard patterns (feat/, fix/, etc.)
3. Sensitive Files: Detection of credentials, keys, etc.

Instructions

Step 1: Validate Branch Name

echo "→ Validating branch name..."

# Get current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Check against standard patterns
VALID_PATTERNS=(
  "^feat/.*"
  "^fix/.*"
  "^docs/.*"
  "^chore/.*"
  "^refactor/.*"
  "^test/.*"
  "^hotfix/.*"
  "^release/.*"
  "^main$"
  "^master$"
  "^develop$"
  "^development$"
  "^claude/.*"
)

BRANCH_VALID="false"
for pattern in "${VALID_PATTERNS[@]}"; do
  if echo "$CURRENT_BRANCH" | grep -qE "$pattern"; then
    BRANCH_VALID="true"
    break
  fi
done

if [ "$BRANCH_VALID" = "true" ]; then
  echo "✅ Branch name valid: $CURRENT_BRANCH"
  BRANCH_STATUS="valid"
else
  echo "❌ Branch name invalid: $CURRENT_BRANCH"
  echo "   Expected: feat/*, fix/*, docs/*, chore/*, etc."
  BRANCH_STATUS="invalid"
fi

Step 2: Validate Recent Commits

echo ""
echo "→ Validating recent commit messages..."

# Get last 10 commits (or since main/develop)
COMMITS=$(git log --oneline --no-merges -10 --format="%H %s")

# Conventional commit pattern
COMMIT_PATTERN="^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?!?: .+"

INVALID_COMMITS=()
VALID_COMMITS=0

while IFS= read -r commit; do
  HASH=$(echo "$commit" | cut -d' ' -f1)
  MSG=$(echo "$commit" | cut -d' ' -f2-)

  if echo "$MSG" | grep -qE "$COMMIT_PATTERN"; then
    ((VALID_COMMITS++))
  else
    INVALID_COMMITS+=("$HASH:$MSG")
  fi
done <<< "$COMMITS"

TOTAL_COMMITS=$((VALID_COMMITS + ${#INVALID_COMMITS[@]}))

if [ ${#INVALID_COMMITS[@]} -eq 0 ]; then
  echo "✅ All $VALID_COMMITS commit messages valid"
  COMMITS_STATUS="valid"
else
  echo "❌ ${#INVALID_COMMITS[@]} invalid commit messages found"
  COMMITS_STATUS="invalid"

  # Show first 3 invalid commits
  for i in "${INVALID_COMMITS[@]:0:3}"; do
    HASH=$(echo "$i" | cut -d: -f1)
    MSG=$(echo "$i" | cut -d: -f2-)
    echo "   $HASH: $MSG"
  done
fi

Step 3: Check for Sensitive Files

echo ""
echo "→ Checking for sensitive files..."

# Patterns for sensitive files
SENSITIVE_PATTERNS=(
  "\.env$"
  "\.env\..+"
  "credentials\.json$"
  "\.pem$"
  "\.key$"
  "\.p12$"
  "id_rsa$"
  "\.ssh/"
  "secret"
  "private.*\.key$"
  "\.pfx$"
)

SENSITIVE_FILES=()

# Check tracked files
for pattern in "${SENSITIVE_PATTERNS[@]}"; do
  while IFS= read -r file; do
    if [ -n "$file" ]; then
      SENSITIVE_FILES+=("$file")
    fi
  done < <(git ls-files | grep -E "$pattern")
done

# Check unstaged/untracked
for pattern in "${SENSITIVE_PATTERNS[@]}"; do
  while IFS= read -r file; do
    # Only files not in .gitignore
    if [ -n "$file" ] && ! git check-ignore -q "$file" 2>/dev/null; then
      SENSITIVE_FILES+=("$file (untracked)")
    fi
  done < <(git status --porcelain | awk '{print $2}' | grep -E "$pattern")
done

if [ ${#SENSITIVE_FILES[@]} -eq 0 ]; then
  echo "✅ No sensitive files detected"
  SENSITIVE_STATUS="clean"
else
  echo "⚠️  ${#SENSITIVE_FILES[@]} potential sensitive files found:"
  SENSITIVE_STATUS="found"

  for file in "${SENSITIVE_FILES[@]:0:5}"; do
    echo "   - $file"
  done
fi

Step 4: Determine Overall Status

# Aggregate results
if [ "$BRANCH_STATUS" = "valid" ] && [ "$COMMITS_STATUS" = "valid" ] && [ "$SENSITIVE_STATUS" = "clean" ]; then
  OVERALL_STATUS="passing"
  CAN_PROCEED="true"
  STATUS="success"
elif [ "$SENSITIVE_STATUS" = "found" ]; then
  OVERALL_STATUS="sensitive-files"
  CAN_PROCEED="false"
  STATUS="error"
  DETAILS="Sensitive files detected - must be removed or added to .gitignore"
elif [ "$BRANCH_STATUS" = "invalid" ] || [ "$COMMITS_STATUS" = "invalid" ]; then
  OVERALL_STATUS="format-issues"
  CAN_PROCEED="true"
  STATUS="warning"
  DETAILS="Git hygiene issues detected - should be fixed but not blocking"
else
  OVERALL_STATUS="passing"
  CAN_PROCEED="true"
  STATUS="success"
fi

Step 5: Return Structured Output

{
  "status": "$STATUS",
  "gitHygiene": {
    "status": "$OVERALL_STATUS",
    "branch": {
      "name": "$CURRENT_BRANCH",
      "valid": $([ "$BRANCH_STATUS" = "valid" ] && echo 'true' || echo 'false')
    },
    "commits": {
      "total": $TOTAL_COMMITS,
      "valid": $VALID_COMMITS,
      "invalid": ${#INVALID_COMMITS[@]},
      "invalidExamples": $(printf '%s\n' "${INVALID_COMMITS[@]:0:3}" | jq -R -s -c 'split("\n") | map(select(length > 0))')
    },
    "sensitiveFiles": {
      "count": ${#SENSITIVE_FILES[@]},
      "files": $(printf '%s\n' "${SENSITIVE_FILES[@]}" | jq -R -s -c 'split("\n") | map(select(length > 0))')
    }
  },
  "canProceed": $CAN_PROCEED,
  "details": "$DETAILS"
}

Output Format

All Checks Pass

{
  "status": "success",
  "gitHygiene": {
    "status": "passing",
    "branch": {
      "name": "feat/add-user-profile",
      "valid": true
    },
    "commits": {
      "total": 10,
      "valid": 10,
      "invalid": 0,
      "invalidExamples": []
    },
    "sensitiveFiles": {
      "count": 0,
      "files": []
    }
  },
  "canProceed": true
}

Issues Found

{
  "status": "warning",
  "gitHygiene": {
    "status": "format-issues",
    "branch": {
      "name": "update-settings",
      "valid": false
    },
    "commits": {
      "total": 10,
      "valid": 7,
      "invalid": 3,
      "invalidExamples": [
        "a1b2c3d:updated some stuff",
        "e4f5g6h:WIP",
        "i7j8k9l:fixed bug"
      ]
    },
    "sensitiveFiles": {
      "count": 0,
      "files": []
    }
  },
  "canProceed": true,
  "details": "Git hygiene issues detected - should be fixed but not blocking"
}

Sensitive Files Detected

{
  "status": "error",
  "gitHygiene": {
    "status": "sensitive-files",
    "branch": {
      "name": "feat/api-integration",
      "valid": true
    },
    "commits": {
      "total": 5,
      "valid": 5,
      "invalid": 0,
      "invalidExamples": []
    },
    "sensitiveFiles": {
      "count": 2,
      "files": [
        ".env.production",
        "src/config/credentials.json"
      ]
    }
  },
  "canProceed": false,
  "details": "Sensitive files detected - must be removed or added to .gitignore"
}

Conventional Commit Format

Valid commit message format:

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
Scope: optional (component, feature, etc.)
Description: imperative, lowercase, no period

Examples:
✅ feat(auth): add user login endpoint
✅ fix: resolve null pointer in settings
✅ docs(readme): update installation instructions
❌ Updated some files
❌ WIP
❌ Fixed bug

Branch Naming Conventions

Valid patterns:

feat/*      - New features
fix/*       - Bug fixes
docs/*      - Documentation
chore/*     - Maintenance
refactor/*  - Code refactoring
test/*      - Test additions
hotfix/*    - Critical fixes
release/*   - Release preparation
claude/*    - AI-generated branches

Examples:
✅ feat/user-authentication
✅ fix/settings-crash
✅ claude/implement-validation-011ABC
❌ update-settings
❌ myfeature

Sensitive File Patterns

Detected patterns:

• .env, .env.local, .env.production
• credentials.json, secrets.json
• *.pem, *.key, *.p12, *.pfx
• id_rsa, .ssh/ files
• Files containing "secret", "private"

Integration with Conductor

Phase 2: Branch Validation

Use `validate-git-hygiene` to check branch name:
- Expected: feat/*, fix/*, etc.
- If invalid: Warning but continue

Phase 4: Pre-PR Validation

Use `validate-git-hygiene` to check:
- Commit messages format
- No sensitive files
- If sensitive files: BLOCK - cannot proceed

Fixing Issues

Branch Name

# Rename current branch
git branch -m feat/descriptive-name

Commit Messages

# Amend last commit message
git commit --amend -m "feat: proper commit message"

# Interactive rebase to fix multiple commits
git rebase -i HEAD~5

Sensitive Files

# Remove from git (keep local)
git rm --cached .env

# Add to .gitignore
echo ".env*" >> .gitignore
git add .gitignore
git commit -m "chore: add .env to .gitignore"

Related Skills

• create-feature-branch - Creates properly named branches
• commit-with-validation - Commits with validation
• security-pentest - Uses for sensitive file detection

Best Practices

1. Use conventional commits - Enables auto-changelog, semantic versioning
2. Meaningful branch names - Self-documenting workflow
3. Never commit secrets - Use environment variables
4. Check before push - Validate locally first
5. Use .gitignore - Prevent accidental commits

Notes

• Sensitive files BLOCK (canProceed: false)
• Branch/commit format issues are warnings (canProceed: true)
• Checks last 10 commits or since main/develop
• Respects .gitignore for file detection