aiox-core 5.0.2 → 5.0.3

package/pro/squads/squad-creator-pro/scripts/modernization-score.sh

@@ -0,0 +1,308 @@
+#!/bin/bash
+# modernization-score.sh - Deterministic modernization scoring (no LLM needed)
+# Usage: ./modernization-score.sh <workflow-file> [--json]
+#
+# Applies 12-point checklist to evaluate if workflow follows modern AIOS patterns
+# Based on pv-workflow-validation.yaml criteria
+
+set -e
+
+WORKFLOW_FILE="$1"
+OUTPUT_FORMAT="yaml"
+
+if [[ "$2" == "--json" ]]; then
+    OUTPUT_FORMAT="json"
+fi
+
+if [[ -z "$WORKFLOW_FILE" ]]; then
+    echo "Usage: $0 <workflow-file> [--json]"
+    echo ""
+    echo "Evaluates a workflow/skill file against 12 modern AIOS patterns."
+    echo "Returns score X/12 with per-pattern evidence."
+    exit 1
+fi
+
+if [[ ! -f "$WORKFLOW_FILE" ]]; then
+    echo "Error: File not found: $WORKFLOW_FILE"
+    exit 1
+fi
+
+WORKFLOW_NAME=$(basename "$WORKFLOW_FILE" | sed 's/\.[^.]*$//')
+DATE=$(date -Iseconds)
+TOTAL=0
+RESULTS=()
+
+# ============================================================================
+# P1: Teams Architecture (TeamCreate, TaskCreate)
+# ============================================================================
+if grep -qiE "(TeamCreate|TaskCreate)" "$WORKFLOW_FILE"; then
+    P1="PASS"
+    P1_EVIDENCE=$(grep -n -m1 -iE "(TeamCreate|TaskCreate)" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P1="FAIL"
+    P1_EVIDENCE="No TeamCreate/TaskCreate found"
+fi
+
+# ============================================================================
+# P2: SKILL.md Frontmatter (name: + description:)
+# ============================================================================
+if grep -qiE "^name:" "$WORKFLOW_FILE" && grep -qiE "^description:" "$WORKFLOW_FILE"; then
+    P2="PASS"
+    P2_EVIDENCE="Both name: and description: frontmatter found"
+    TOTAL=$((TOTAL + 1))
+elif grep -qiE "^name:|^description:" "$WORKFLOW_FILE"; then
+    P2="FAIL"
+    P2_EVIDENCE="Partial frontmatter (missing name: or description:)"
+else
+    P2="FAIL"
+    P2_EVIDENCE="No SKILL.md frontmatter found"
+fi
+
+# ============================================================================
+# P3: Blocking Execution (Task with subagent without run_in_background)
+# ============================================================================
+if grep -qiE "Task.*subagent" "$WORKFLOW_FILE" || grep -qiE "subagent_type" "$WORKFLOW_FILE"; then
+    P3="PASS"
+    P3_EVIDENCE=$(grep -n -m1 -iE "(Task.*subagent|subagent_type)" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P3="FAIL"
+    P3_EVIDENCE="No Task subagent invocations found"
+fi
+
+# ============================================================================
+# P4: Parallel Execution (run_in_background)
+# ============================================================================
+if grep -qiE "run_in_background" "$WORKFLOW_FILE"; then
+    P4="PASS"
+    P4_EVIDENCE=$(grep -n -m1 -iE "run_in_background" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P4="FAIL"
+    P4_EVIDENCE="No run_in_background usage found"
+fi
+
+# ============================================================================
+# P5: Context Preamble (git status, gotchas, context loading)
+# ============================================================================
+if grep -qiE "(git status|gotchas|context.*preamble|context.*load)" "$WORKFLOW_FILE"; then
+    P5="PASS"
+    P5_EVIDENCE=$(grep -n -m1 -iE "(git status|gotchas|context.*preamble|context.*load)" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P5="FAIL"
+    P5_EVIDENCE="No context preamble found"
+fi
+
+# ============================================================================
+# P6: File-Based Communication (outputs/ directory)
+# ============================================================================
+if grep -qiE "outputs/" "$WORKFLOW_FILE"; then
+    P6="PASS"
+    P6_EVIDENCE=$(grep -n -m1 -iE "outputs/" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P6="FAIL"
+    P6_EVIDENCE="No outputs/ directory references found"
+fi
+
+# ============================================================================
+# P7: Agent File References (Read agent file, .claude/agents)
+# ============================================================================
+if grep -qiE "(Read.*agent|\.claude/agents|squads/.*/agents)" "$WORKFLOW_FILE"; then
+    P7="PASS"
+    P7_EVIDENCE=$(grep -n -m1 -iE "(Read.*agent|\.claude/agents|squads/.*/agents)" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P7="FAIL"
+    P7_EVIDENCE="No agent file references found"
+fi
+
+# ============================================================================
+# P8: Task Dependencies (blockedBy)
+# ============================================================================
+if grep -qiE "blockedBy" "$WORKFLOW_FILE"; then
+    P8="PASS"
+    P8_EVIDENCE=$(grep -n -m1 -iE "blockedBy" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P8="FAIL"
+    P8_EVIDENCE="No blockedBy task dependencies found"
+fi
+
+# ============================================================================
+# P9: Permission Mode (bypassPermissions or explicit mode)
+# ============================================================================
+if grep -qiE "(bypassPermissions|permissionMode|acceptEdits)" "$WORKFLOW_FILE"; then
+    P9="PASS"
+    P9_EVIDENCE=$(grep -n -m1 -iE "(bypassPermissions|permissionMode|acceptEdits)" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P9="FAIL"
+    P9_EVIDENCE="No explicit permission mode found"
+fi
+
+# ============================================================================
+# P10: Proper Finalization (shutdown + TeamDelete)
+# ============================================================================
+if grep -qiE "(shutdown|TeamDelete)" "$WORKFLOW_FILE"; then
+    P10="PASS"
+    P10_EVIDENCE=$(grep -n -m1 -iE "(shutdown|TeamDelete)" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P10="FAIL"
+    P10_EVIDENCE="No shutdown/TeamDelete finalization found"
+fi
+
+# ============================================================================
+# P11: Anti-Pattern Documentation (NEVER, anti-pattern, DO NOT)
+# ============================================================================
+if grep -qiE "(NEVER|anti.pattern|DO NOT)" "$WORKFLOW_FILE"; then
+    P11="PASS"
+    COUNT=$(grep -ciE "(NEVER|anti.pattern|DO NOT)" "$WORKFLOW_FILE" 2>/dev/null || echo 0)
+    P11_EVIDENCE="Found $COUNT anti-pattern references"
+    TOTAL=$((TOTAL + 1))
+else
+    P11="FAIL"
+    P11_EVIDENCE="No anti-pattern documentation found"
+fi
+
+# ============================================================================
+# P12: Artifact Directory (outputs/{slug}/ structured)
+# ============================================================================
+if grep -qiE "outputs/.*/" "$WORKFLOW_FILE"; then
+    P12="PASS"
+    P12_EVIDENCE=$(grep -n -m1 -iE "outputs/.*/" "$WORKFLOW_FILE" | head -1 | sed 's/"/\\"/g')
+    TOTAL=$((TOTAL + 1))
+else
+    P12="FAIL"
+    P12_EVIDENCE="No structured artifact directory (outputs/{slug}/) found"
+fi
+
+# ============================================================================
+# INTERPRETATION
+# ============================================================================
+if [[ $TOTAL -eq 12 ]]; then
+    INTERPRETATION="Totalmente moderno"
+    ACTION="Pronto para producao"
+elif [[ $TOTAL -ge 9 ]]; then
+    INTERPRETATION="Quase moderno"
+    ACTION="Ajustes menores"
+elif [[ $TOTAL -ge 5 ]]; then
+    INTERPRETATION="Parcialmente moderno"
+    ACTION="Refactor significativo"
+elif [[ $TOTAL -ge 1 ]]; then
+    INTERPRETATION="Majoritariamente legado"
+    ACTION="Rewrite necessario"
+else
+    INTERPRETATION="Completamente legado"
+    ACTION="Rewrite total"
+fi
+
+# ============================================================================
+# OUTPUT
+# ============================================================================
+if [[ "$OUTPUT_FORMAT" == "json" ]]; then
+    cat <<ENDJSON
+{
+  "modernization_score": {
+    "workflow": "$WORKFLOW_NAME",
+    "file": "$WORKFLOW_FILE",
+    "date": "$DATE",
+    "score": "$TOTAL/12",
+    "interpretation": "$INTERPRETATION",
+    "action": "$ACTION",
+    "patterns": [
+      {"id": 1, "name": "Teams Architecture", "status": "$P1", "evidence": "$P1_EVIDENCE"},
+      {"id": 2, "name": "SKILL.md Frontmatter", "status": "$P2", "evidence": "$P2_EVIDENCE"},
+      {"id": 3, "name": "Blocking Execution", "status": "$P3", "evidence": "$P3_EVIDENCE"},
+      {"id": 4, "name": "Parallel Execution", "status": "$P4", "evidence": "$P4_EVIDENCE"},
+      {"id": 5, "name": "Context Preamble", "status": "$P5", "evidence": "$P5_EVIDENCE"},
+      {"id": 6, "name": "File-Based Communication", "status": "$P6", "evidence": "$P6_EVIDENCE"},
+      {"id": 7, "name": "Agent File References", "status": "$P7", "evidence": "$P7_EVIDENCE"},
+      {"id": 8, "name": "Task Dependencies", "status": "$P8", "evidence": "$P8_EVIDENCE"},
+      {"id": 9, "name": "Permission Mode", "status": "$P9", "evidence": "$P9_EVIDENCE"},
+      {"id": 10, "name": "Proper Finalization", "status": "$P10", "evidence": "$P10_EVIDENCE"},
+      {"id": 11, "name": "Anti-Pattern Docs", "status": "$P11", "evidence": "$P11_EVIDENCE"},
+      {"id": 12, "name": "Artifact Directory", "status": "$P12", "evidence": "$P12_EVIDENCE"}
+    ],
+    "recommendations": [
+ENDJSON
+
+    # Build recommendations for FAIL patterns
+    RECS=()
+    [[ "$P1" == "FAIL" ]] && RECS+=('      {"priority": "high", "pattern": "Teams Architecture", "action": "Add TeamCreate/TaskCreate for multi-agent coordination"}')
+    [[ "$P2" == "FAIL" ]] && RECS+=('      {"priority": "medium", "pattern": "SKILL.md Frontmatter", "action": "Add name: and description: frontmatter"}')
+    [[ "$P3" == "FAIL" ]] && RECS+=('      {"priority": "high", "pattern": "Blocking Execution", "action": "Use Task tool with subagent_type for agent delegation"}')
+    [[ "$P4" == "FAIL" ]] && RECS+=('      {"priority": "medium", "pattern": "Parallel Execution", "action": "Add run_in_background for independent tasks"}')
+    [[ "$P5" == "FAIL" ]] && RECS+=('      {"priority": "low", "pattern": "Context Preamble", "action": "Add git status/gotchas context loading"}')
+    [[ "$P6" == "FAIL" ]] && RECS+=('      {"priority": "high", "pattern": "File-Based Communication", "action": "Use outputs/ directory for inter-agent communication"}')
+    [[ "$P7" == "FAIL" ]] && RECS+=('      {"priority": "medium", "pattern": "Agent File References", "action": "Reference .claude/agents/ files instead of hardcoded personas"}')
+    [[ "$P8" == "FAIL" ]] && RECS+=('      {"priority": "medium", "pattern": "Task Dependencies", "action": "Use blockedBy for task ordering"}')
+    [[ "$P9" == "FAIL" ]] && RECS+=('      {"priority": "low", "pattern": "Permission Mode", "action": "Set explicit bypassPermissions or acceptEdits"}')
+    [[ "$P10" == "FAIL" ]] && RECS+=('      {"priority": "high", "pattern": "Proper Finalization", "action": "Add shutdown_request + TeamDelete cleanup"}')
+    [[ "$P11" == "FAIL" ]] && RECS+=('      {"priority": "low", "pattern": "Anti-Pattern Docs", "action": "Document NEVER/DO NOT patterns"}')
+    [[ "$P12" == "FAIL" ]] && RECS+=('      {"priority": "medium", "pattern": "Artifact Directory", "action": "Use outputs/{slug}/ structured artifact paths"}')
+
+    # Join with commas
+    for i in "${!RECS[@]}"; do
+        if [[ $i -lt $((${#RECS[@]} - 1)) ]]; then
+            echo "${RECS[$i]},"
+        else
+            echo "${RECS[$i]}"
+        fi
+    done
+
+    cat <<ENDJSON
+    ]
+  }
+}
+ENDJSON
+else
+    # YAML output (default)
+    echo "# Modernization Score Report"
+    echo "# Generated: $DATE"
+    echo "# File: $WORKFLOW_FILE"
+    echo ""
+    echo "modernization_score:"
+    echo "  workflow: \"$WORKFLOW_NAME\""
+    echo "  file: \"$WORKFLOW_FILE\""
+    echo "  date: \"$DATE\""
+    echo "  score: \"$TOTAL/12\""
+    echo "  interpretation: \"$INTERPRETATION\""
+    echo "  action: \"$ACTION\""
+    echo ""
+    echo "  patterns:"
+    echo "    - { id: 1, name: 'Teams Architecture', status: '$P1', evidence: '$P1_EVIDENCE' }"
+    echo "    - { id: 2, name: 'SKILL.md Frontmatter', status: '$P2', evidence: '$P2_EVIDENCE' }"
+    echo "    - { id: 3, name: 'Blocking Execution', status: '$P3', evidence: '$P3_EVIDENCE' }"
+    echo "    - { id: 4, name: 'Parallel Execution', status: '$P4', evidence: '$P4_EVIDENCE' }"
+    echo "    - { id: 5, name: 'Context Preamble', status: '$P5', evidence: '$P5_EVIDENCE' }"
+    echo "    - { id: 6, name: 'File-Based Communication', status: '$P6', evidence: '$P6_EVIDENCE' }"
+    echo "    - { id: 7, name: 'Agent File References', status: '$P7', evidence: '$P7_EVIDENCE' }"
+    echo "    - { id: 8, name: 'Task Dependencies', status: '$P8', evidence: '$P8_EVIDENCE' }"
+    echo "    - { id: 9, name: 'Permission Mode', status: '$P9', evidence: '$P9_EVIDENCE' }"
+    echo "    - { id: 10, name: 'Proper Finalization', status: '$P10', evidence: '$P10_EVIDENCE' }"
+    echo "    - { id: 11, name: 'Anti-Pattern Docs', status: '$P11', evidence: '$P11_EVIDENCE' }"
+    echo "    - { id: 12, name: 'Artifact Directory', status: '$P12', evidence: '$P12_EVIDENCE' }"
+    echo ""
+    echo "  recommendations:"
+
+    [[ "$P1" == "FAIL" ]] && echo "    - { priority: 'high', pattern: 'Teams Architecture', action: 'Add TeamCreate/TaskCreate for multi-agent coordination' }"
+    [[ "$P2" == "FAIL" ]] && echo "    - { priority: 'medium', pattern: 'SKILL.md Frontmatter', action: 'Add name: and description: frontmatter' }"
+    [[ "$P3" == "FAIL" ]] && echo "    - { priority: 'high', pattern: 'Blocking Execution', action: 'Use Task tool with subagent_type for agent delegation' }"
+    [[ "$P4" == "FAIL" ]] && echo "    - { priority: 'medium', pattern: 'Parallel Execution', action: 'Add run_in_background for independent tasks' }"
+    [[ "$P5" == "FAIL" ]] && echo "    - { priority: 'low', pattern: 'Context Preamble', action: 'Add git status/gotchas context loading' }"
+    [[ "$P6" == "FAIL" ]] && echo "    - { priority: 'high', pattern: 'File-Based Communication', action: 'Use outputs/ directory for inter-agent communication' }"
+    [[ "$P7" == "FAIL" ]] && echo "    - { priority: 'medium', pattern: 'Agent File References', action: 'Reference .claude/agents/ files instead of hardcoded personas' }"
+    [[ "$P8" == "FAIL" ]] && echo "    - { priority: 'medium', pattern: 'Task Dependencies', action: 'Use blockedBy for task ordering' }"
+    [[ "$P9" == "FAIL" ]] && echo "    - { priority: 'low', pattern: 'Permission Mode', action: 'Set explicit bypassPermissions or acceptEdits' }"
+    [[ "$P10" == "FAIL" ]] && echo "    - { priority: 'high', pattern: 'Proper Finalization', action: 'Add shutdown_request + TeamDelete cleanup' }"
+    [[ "$P11" == "FAIL" ]] && echo "    - { priority: 'low', pattern: 'Anti-Pattern Docs', action: 'Document NEVER/DO NOT patterns' }"
+    [[ "$P12" == "FAIL" ]] && echo "    - { priority: 'medium', pattern: 'Artifact Directory', action: 'Use outputs/{slug}/ structured artifact paths' }"
+
+    echo ""
+    echo "# Cost: \$0 (zero tokens)"
+    echo "# Time: <1 second"
+fi

package/pro/squads/squad-creator-pro/scripts/naming_validator.py

@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""
+Script: naming_validator.py
+Purpose: Validate naming conventions across squad files
+Operations: 8+ deterministic checks
+
+Conventions:
+- File names: kebab-case (e.g., gary-halbert.md)
+- Directory names: kebab-case (e.g., squad-creator)
+- YAML keys: snake_case (e.g., voice_dna)
+- slashPrefix: camelCase (e.g., squadCreator)
+- Agent IDs: kebab-case (e.g., gary-halbert)
+
+Usage:
+    python scripts/naming_validator.py squads/{squad-name}/
+    python scripts/naming_validator.py squads/{squad-name}/ --output json
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Any
+
+
+def is_kebab_case(s: str) -> bool:
+    """Check if string is kebab-case."""
+    # Remove extension if present
+    name = s.rsplit('.', 1)[0] if '.' in s else s
+    return bool(re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', name))
+
+
+def is_snake_case(s: str) -> bool:
+    """Check if string is snake_case."""
+    return bool(re.match(r'^[a-z0-9]+(_[a-z0-9]+)*$', s))
+
+
+def is_camel_case(s: str) -> bool:
+    """Check if string is camelCase."""
+    return bool(re.match(r'^[a-z][a-zA-Z0-9]*$', s))
+
+
+def is_pascal_case(s: str) -> bool:
+    """Check if string is PascalCase."""
+    return bool(re.match(r'^[A-Z][a-zA-Z0-9]*$', s))
+
+
+def validate_file_names(squad_path: str) -> List[Dict]:
+    """Validate file naming conventions."""
+    issues = []
+
+    dirs_to_check = ["agents", "tasks", "templates", "checklists", "workflows", "data"]
+
+    for dir_name in dirs_to_check:
+        dir_path = os.path.join(squad_path, dir_name)
+        if not os.path.exists(dir_path):
+            continue
+
+        for file in os.listdir(dir_path):
+            if file.startswith('.'):
+                continue
+
+            # Skip certain patterns
+            if file in ['__init__.py', 'README.md', 'CHANGELOG.md']:
+                continue
+
+            name = file.rsplit('.', 1)[0]
+
+            if not is_kebab_case(name):
+                issues.append({
+                    "type": "NAMING",
+                    "code": "NAM-FILE-001",
+                    "severity": "warning",
+                    "file": os.path.join(dir_name, file),
+                    "expected": "kebab-case",
+                    "actual": name,
+                    "suggestion": name.lower().replace('_', '-').replace(' ', '-'),
+                    "message": f"File name should be kebab-case: {file}"
+                })
+
+    return issues
+
+
+def validate_directory_name(squad_path: str) -> List[Dict]:
+    """Validate squad directory name."""
+    issues = []
+    squad_name = os.path.basename(squad_path.rstrip('/'))
+
+    if not is_kebab_case(squad_name):
+        issues.append({
+            "type": "NAMING",
+            "code": "NAM-DIR-001",
+            "severity": "error",
+            "file": squad_name,
+            "expected": "kebab-case",
+            "actual": squad_name,
+            "suggestion": squad_name.lower().replace('_', '-').replace(' ', '-'),
+            "message": f"Squad directory should be kebab-case: {squad_name}"
+        })
+
+    return issues
+
+
+def validate_config_naming(squad_path: str) -> List[Dict]:
+    """Validate naming in config.yaml."""
+    issues = []
+    config_path = os.path.join(squad_path, "config.yaml")
+
+    if not os.path.exists(config_path):
+        return issues
+
+    try:
+        import yaml
+        with open(config_path, 'r') as f:
+            content = f.read()
+            config = yaml.safe_load(content)
+    except Exception:
+        return issues
+
+    if config is None:
+        return issues
+
+    # Check slashPrefix (should be camelCase)
+    slash_prefix = None
+    if isinstance(config, dict):
+        slash_prefix = config.get('slashPrefix') or config.get('slash_prefix')
+        if 'pack' in config and isinstance(config['pack'], dict):
+            slash_prefix = slash_prefix or config['pack'].get('slash_prefix')
+
+    if slash_prefix:
+        if not is_camel_case(slash_prefix) and not is_pascal_case(slash_prefix):
+            issues.append({
+                "type": "NAMING",
+                "code": "NAM-CONFIG-001",
+                "severity": "warning",
+                "file": "config.yaml",
+                "key": "slashPrefix",
+                "expected": "camelCase or PascalCase",
+                "actual": slash_prefix,
+                "message": f"slashPrefix should be camelCase: {slash_prefix}"
+            })
+
+    # Check name matches directory
+    squad_name = os.path.basename(squad_path.rstrip('/'))
+    config_name = None
+    if isinstance(config, dict):
+        config_name = config.get('name')
+        if 'pack' in config and isinstance(config['pack'], dict):
+            config_name = config_name or config['pack'].get('name')
+
+    if config_name and config_name != squad_name:
+        issues.append({
+            "type": "NAMING",
+            "code": "NAM-CONFIG-002",
+            "severity": "error",
+            "file": "config.yaml",
+            "key": "name",
+            "expected": squad_name,
+            "actual": config_name,
+            "message": f"config.yaml name '{config_name}' doesn't match directory '{squad_name}'"
+        })
+
+    return issues
+
+
+def validate_agent_ids(squad_path: str) -> List[Dict]:
+    """Validate agent IDs are kebab-case."""
+    issues = []
+    agents_dir = os.path.join(squad_path, "agents")
+
+    if not os.path.exists(agents_dir):
+        return issues
+
+    try:
+        import yaml
+    except ImportError:
+        return issues
+
+    for file in os.listdir(agents_dir):
+        if not file.endswith('.md'):
+            continue
+
+        file_path = os.path.join(agents_dir, file)
+        try:
+            with open(file_path, 'r') as f:
+                content = f.read()
+
+            # Try to extract YAML frontmatter
+            if content.startswith('---'):
+                yaml_match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+                if yaml_match:
+                    frontmatter = yaml.safe_load(yaml_match.group(1))
+                    if frontmatter and 'id' in frontmatter:
+                        agent_id = frontmatter['id']
+                        if not is_kebab_case(agent_id):
+                            issues.append({
+                                "type": "NAMING",
+                                "code": "NAM-AGENT-001",
+                                "severity": "warning",
+                                "file": f"agents/{file}",
+                                "key": "id",
+                                "expected": "kebab-case",
+                                "actual": agent_id,
+                                "message": f"Agent ID should be kebab-case: {agent_id}"
+                            })
+        except Exception:
+            continue
+
+    return issues
+
+
+def scan_squad(squad_path: str) -> Dict[str, Any]:
+    """Run all naming validations."""
+    squad_path = squad_path.rstrip('/')
+    squad_name = os.path.basename(squad_path)
+
+    if not os.path.exists(squad_path):
+        return {
+            "squad_name": squad_name,
+            "exists": False,
+            "error": f"Squad path not found: {squad_path}"
+        }
+
+    all_issues = []
+
+    # Run all validators
+    all_issues.extend(validate_directory_name(squad_path))
+    all_issues.extend(validate_file_names(squad_path))
+    all_issues.extend(validate_config_naming(squad_path))
+    all_issues.extend(validate_agent_ids(squad_path))
+
+    # Categorize issues
+    errors = [i for i in all_issues if i["severity"] == "error"]
+    warnings = [i for i in all_issues if i["severity"] == "warning"]
+
+    return {
+        "squad_name": squad_name,
+        "squad_path": squad_path,
+        "exists": True,
+        "status": "PASS" if len(errors) == 0 else "FAIL",
+        "total_issues": len(all_issues),
+        "errors": len(errors),
+        "warnings": len(warnings),
+        "issues": all_issues,
+        "conventions": {
+            "files": "kebab-case (e.g., gary-halbert.md)",
+            "directories": "kebab-case (e.g., squad-creator)",
+            "yaml_keys": "snake_case (e.g., voice_dna)",
+            "slashPrefix": "camelCase (e.g., squadCreator)",
+            "agent_ids": "kebab-case (e.g., gary-halbert)"
+        }
+    }
+
+
+def print_report(results: Dict[str, Any]) -> None:
+    """Print human-readable report."""
+    print(f"\nNaming Validation: {results['squad_name']}")
+    print("=" * 50)
+
+    if not results.get("exists"):
+        print(f"ERROR: {results.get('error', 'Squad not found')}")
+        return
+
+    print(f"Status: {'✓ PASSED' if results['status'] == 'PASS' else '✗ FAILED'}")
+    print(f"Errors: {results['errors']}")
+    print(f"Warnings: {results['warnings']}")
+
+    if results["issues"]:
+        print("\nIssues:")
+        for issue in results["issues"]:
+            icon = "✗" if issue["severity"] == "error" else "⚠️"
+            print(f"  {icon} [{issue['code']}] {issue['message']}")
+            if "suggestion" in issue:
+                print(f"    Suggestion: {issue['suggestion']}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate squad naming conventions")
+    parser.add_argument("squad_path", help="Path to squad directory")
+    parser.add_argument("--output", choices=["text", "json"], default="text",
+                        help="Output format")
+
+    args = parser.parse_args()
+
+    results = scan_squad(args.squad_path)
+
+    if args.output == "json":
+        print(json.dumps(results, indent=2))
+    else:
+        print_report(results)
+
+    # Exit with error code if blocking errors found
+    sys.exit(0 if results.get("status") == "PASS" else 1)
+
+
+if __name__ == "__main__":
+    main()