cortexhawk 3.1.0

package/scripts/validate.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# validate.sh — Check CortexHawk components for quality standards
+# Run: bash scripts/validate.sh
+
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+ERRORS=0
+WARNINGS=0
+
+red() { echo -e "\033[31m$1\033[0m"; }
+yellow() { echo -e "\033[33m$1\033[0m"; }
+green() { echo -e "\033[32m$1\033[0m"; }
+
+error() { red "  ERROR: $1"; ERRORS=$((ERRORS + 1)); }
+warn() { yellow "  WARN:  $1"; WARNINGS=$((WARNINGS + 1)); }
+ok() { green "  OK:    $1"; }
+
+echo "================================"
+echo "CortexHawk Validator"
+echo "================================"
+echo ""
+
+# --- Agents ---
+echo "Checking agents..."
+for file in "$REPO_DIR"/agents/*.md; do
+    name=$(basename "$file")
+    lines=$(wc -l < "$file")
+
+    # Frontmatter check
+    if ! head -1 "$file" | grep -q '^---$'; then
+        error "$name — missing YAML frontmatter"
+    else
+        ok "$name — frontmatter present"
+    fi
+
+    # Line limit
+    if [ "$lines" -gt 100 ]; then
+        error "$name — $lines lines (max 100)"
+    fi
+
+    # Required sections
+    for section in "## Process" "## Output" "## Rules"; do
+        if ! grep -q "$section" "$file"; then
+            warn "$name — missing '$section' section"
+        fi
+    done
+done
+echo ""
+
+# --- Commands ---
+echo "Checking commands..."
+for file in "$REPO_DIR"/commands/*.md; do
+    name=$(basename "$file")
+    lines=$(wc -l < "$file")
+
+    # Frontmatter check
+    if ! head -1 "$file" | grep -q '^---$'; then
+        error "$name — missing YAML frontmatter"
+    else
+        ok "$name — frontmatter present"
+    fi
+
+    # Line limit
+    if [ "$lines" -gt 50 ]; then
+        error "$name — $lines lines (max 50)"
+    fi
+
+    # Must reference an agent
+    if ! grep -qi 'agent' "$file"; then
+        warn "$name — no agent reference found"
+    fi
+done
+echo ""
+
+# --- Skills ---
+echo "Checking skills..."
+while IFS= read -r file; do
+    rel=$(echo "$file" | sed "s|$REPO_DIR/||")
+    lines=$(wc -l < "$file")
+
+    # Frontmatter check
+    if ! head -1 "$file" | grep -q '^---$'; then
+        error "$rel — missing YAML frontmatter"
+    else
+        ok "$rel — frontmatter present"
+    fi
+
+    # Line limit
+    if [ "$lines" -gt 150 ]; then
+        error "$rel — $lines lines (max 150)"
+    fi
+
+    # Should have code examples
+    if ! grep -q '```' "$file"; then
+        warn "$rel — no code examples found"
+    fi
+done < <(find "$REPO_DIR/skills" -name "SKILL.md" -type f)
+
+# detect: syntax validation
+echo "Checking detect: metadata..."
+BASE_COUNT=0
+while IFS= read -r file; do
+    rel=$(echo "$file" | sed "s|$REPO_DIR/||")
+    detect=$(head -10 "$file" | sed -n '/^---$/,/^---$/{ /^detect:/{ s/^detect: //; p; } }')
+    [ -z "$detect" ] && continue
+    for marker in $detect; do
+        case "$marker" in
+            base|dir:*) ;;
+            *:*) file_part="${marker%%:*}"
+                 case "$file_part" in
+                     package.json|requirements.txt|pyproject.toml|Dockerfile|docker-compose.yml|docker-compose.yaml) ;;
+                     *) warn "$rel — unknown detect file: $file_part" ;;
+                 esac ;;
+            *) ;;
+        esac
+    done
+    case " $detect " in *" base "*) BASE_COUNT=$((BASE_COUNT + 1)) ;; esac
+done < <(find "$REPO_DIR/skills" -name "SKILL.md" -type f)
+if [ "$BASE_COUNT" -ge 8 ]; then
+    ok "detect: $BASE_COUNT base skills found (>= 8)"
+else
+    error "detect: only $BASE_COUNT base skills (expected >= 8)"
+fi
+
+# requires: dependency validation
+echo "Checking requires: dependencies..."
+REQ_COUNT=0
+while IFS= read -r file; do
+    rel=$(echo "$file" | sed "s|$REPO_DIR/||")
+    requires=$(head -10 "$file" | sed -n '/^---$/,/^---$/{ /^requires:/{ s/^requires: //; p; } }')
+    [ -z "$requires" ] && continue
+    REQ_COUNT=$((REQ_COUNT + 1))
+    for dep in $requires; do
+        if [ ! -f "$REPO_DIR/skills/$dep/SKILL.md" ]; then
+            error "$rel — requires '$dep' but skill not found"
+        fi
+    done
+done < <(find "$REPO_DIR/skills" -name "SKILL.md" -type f)
+ok "requires: $REQ_COUNT skill(s) with dependencies"
+echo ""
+
+# --- Hooks ---
+echo "Checking hooks..."
+for file in "$REPO_DIR"/hooks/*.sh; do
+    name=$(basename "$file")
+
+    # Shebang
+    if ! head -1 "$file" | grep -q '^#!/bin/bash'; then
+        error "$name — missing shebang (#!/bin/bash)"
+    else
+        ok "$name — shebang present"
+    fi
+
+    # Syntax check
+    if ! bash -n "$file" 2>/dev/null; then
+        error "$name — syntax error"
+    fi
+
+    # Executable
+    if [ ! -x "$file" ]; then
+        warn "$name — not executable (run chmod +x)"
+    fi
+done
+echo ""
+
+# --- Modes ---
+echo "Checking modes..."
+for file in "$REPO_DIR"/modes/*.md; do
+    name=$(basename "$file")
+    lines=$(wc -l < "$file")
+
+    if [ "$lines" -gt 10 ]; then
+        warn "$name — $lines lines (recommended max 10)"
+    else
+        ok "$name — $lines lines"
+    fi
+done
+echo ""
+
+# --- Required root files ---
+echo "Checking root files..."
+for required in CLAUDE.md README.md CONTRIBUTING.md CHANGELOG.md LICENSE settings.json install.sh; do
+    if [ -f "$REPO_DIR/$required" ]; then
+        ok "$required exists"
+    else
+        error "$required missing"
+    fi
+done
+echo ""
+
+# --- Secret scan ---
+echo "Checking for secrets..."
+SECRET_HITS=$(grep -rEil '(api[_-]?key|api[_-]?secret|password|token)\s*[=:]\s*["\x27][A-Za-z0-9]{16,}' \
+    "$REPO_DIR"/{agents,commands,skills,hooks,modes,templates} 2>/dev/null || true)
+if [ -n "$SECRET_HITS" ]; then
+    error "Potential secrets found in: $SECRET_HITS"
+else
+    ok "No hardcoded secrets detected"
+fi
+echo ""
+
+# --- Summary ---
+echo "================================"
+if [ "$ERRORS" -gt 0 ]; then
+    red "FAILED: $ERRORS error(s), $WARNINGS warning(s)"
+    exit 1
+elif [ "$WARNINGS" -gt 0 ]; then
+    yellow "PASSED with $WARNINGS warning(s)"
+    exit 0
+else
+    green "PASSED: all checks clean"
+    exit 0
+fi

package/settings.json

@@ -0,0 +1,90 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(pnpm:*)",
+      "Bash(pip:*)",
+      "Bash(python:*)",
+      "Bash(node:*)",
+      "Bash(pytest:*)",
+      "Bash(gh:*)",
+      "Read(*)",
+      "Write(*)",
+      "Edit(*)"
+    ],
+    "deny": []
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/file-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/branch-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/commit-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/self-review.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/dependency-check.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/test-reminder.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/agent-analytics.sh"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .claude/hooks/session-telemetry.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/setup.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# setup.sh — Install the `cortexhawk` CLI wrapper into PATH
+# Run once after cloning the repo.
+
+set -e
+
+green() { printf "\033[32m%s\033[0m\n" "$1"; }
+yellow() { printf "\033[33m%s\033[0m\n" "$1"; }
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+INSTALL_DIR="${1:-$HOME/.local/bin}"
+
+mkdir -p "$INSTALL_DIR"
+
+# Copy wrapper to PATH
+cp "$SCRIPT_DIR/cortexhawk" "$INSTALL_DIR/cortexhawk"
+chmod +x "$INSTALL_DIR/cortexhawk"
+
+# Set CORTEXHAWK_HOME to this repo
+export CORTEXHAWK_HOME="$SCRIPT_DIR"
+
+green "Installed: $INSTALL_DIR/cortexhawk"
+echo "  Source:  $SCRIPT_DIR"
+echo ""
+
+# Check if INSTALL_DIR is in PATH
+if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
+    yellow "Add to your shell profile:"
+    echo "  export PATH=\"$INSTALL_DIR:\$PATH\""
+    echo "  export CORTEXHAWK_HOME=\"$SCRIPT_DIR\""
+    echo ""
+fi
+
+# Detect shell rc file and offer to add
+SHELL_RC=""
+if [ -n "$ZSH_VERSION" ] || [ "$(basename "$SHELL")" = "zsh" ]; then
+    SHELL_RC="$HOME/.zshrc"
+elif [ "$(basename "$SHELL")" = "bash" ]; then
+    SHELL_RC="$HOME/.bashrc"
+fi
+
+if [ -n "$SHELL_RC" ] && [ -f "$SHELL_RC" ]; then
+    if ! grep -q "CORTEXHAWK_HOME" "$SHELL_RC" 2>/dev/null; then
+        printf "Add to %s automatically? [Y/n] " "$SHELL_RC"
+        read -r confirm </dev/tty 2>/dev/null || confirm="y"
+        case "$confirm" in
+            [nN]*)
+                yellow "Skipped. Add manually when ready."
+                ;;
+            *)
+                {
+                    echo ""
+                    echo "# CortexHawk CLI"
+                    echo "export CORTEXHAWK_HOME=\"$SCRIPT_DIR\""
+                    echo "export PATH=\"$INSTALL_DIR:\$PATH\""
+                } >> "$SHELL_RC"
+                green "Added to $SHELL_RC"
+                echo "  Run: source $SHELL_RC"
+                ;;
+        esac
+    else
+        green "CORTEXHAWK_HOME already in $SHELL_RC"
+    fi
+fi
+
+echo ""
+green "Ready! Run: cortexhawk help"

package/skills/databases/schema-designer/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: schema-designer
+description: Database schema design — normalization, relationships, migrations, naming conventions.
+detect: package.json:prisma package.json:sequelize package.json:knex package.json:pg package.json:mysql package.json:sqlite requirements.txt:sqlalchemy requirements.txt:psycopg requirements.txt:pymysql requirements.txt:sqlite pyproject.toml:sqlalchemy pyproject.toml:psycopg pyproject.toml:pymysql pyproject.toml:sqlite
+---
+
+# Schema Designer
+
+## Naming Conventions
+- Tables: plural, snake_case (`users`, `order_items`)
+- Columns: snake_case (`created_at`, `user_id`)
+- Primary key: `id`
+- Foreign key: `{referenced_table_singular}_id`
+- Timestamps: `created_at`, `updated_at`, `deleted_at`
+- Booleans: `is_` or `has_` prefix (`is_active`, `has_verified`)
+
+## Essential Patterns
+- Every table gets `id`, `created_at`, `updated_at`
+- Soft delete (`deleted_at`) over hard delete for audit trail
+- UUID for public-facing IDs, auto-increment for internal
+- Enum values in code, not DB constraints (easier to migrate)
+- JSON columns only for truly unstructured data
+
+## Example Schema
+```sql
+CREATE TABLE users (
+    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    email       VARCHAR(255) NOT NULL UNIQUE,
+    name        VARCHAR(100) NOT NULL,
+    is_active   BOOLEAN NOT NULL DEFAULT true,
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    deleted_at  TIMESTAMPTZ
+);
+
+CREATE TABLE orders (
+    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    user_id     BIGINT NOT NULL REFERENCES users(id),
+    total       DECIMAL(10,2) NOT NULL CHECK (total >= 0),
+    status      VARCHAR(20) NOT NULL DEFAULT 'pending',
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_status ON orders(status) WHERE deleted_at IS NULL;
+```
+
+## Migration Rules
+- Always reversible (up + down)
+- Never modify production data in migration — use separate scripts
+- Add columns as nullable first, backfill, then add NOT NULL
+- Index creation: `CONCURRENTLY` on large tables (PostgreSQL)
+- Test migration on production-size data before deploying

package/skills/databases/sql-optimizer/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: sql-optimizer
+description: Optimize SQL queries — indexing, query plans, N+1 detection, performance tuning.
+detect: package.json:prisma package.json:sequelize package.json:knex package.json:pg package.json:mysql package.json:sqlite requirements.txt:sqlalchemy requirements.txt:psycopg requirements.txt:pymysql requirements.txt:sqlite pyproject.toml:sqlalchemy pyproject.toml:psycopg pyproject.toml:pymysql pyproject.toml:sqlite
+requires: databases/schema-designer
+---
+
+# SQL Optimizer
+
+## Common Performance Issues
+1. **N+1 queries** — Use JOINs or batch loading instead of loop queries
+2. **Missing indexes** — Add indexes on WHERE, JOIN, ORDER BY columns
+3. **SELECT *** — Select only needed columns
+4. **No LIMIT** — Always paginate large result sets
+5. **Unoptimized JOINs** — Smaller table first, join on indexed columns
+
+## Index Strategy
+- Primary key: automatic index
+- Foreign keys: always index
+- Frequently filtered columns: index
+- Composite index: most selective column first
+- Don't over-index: each index slows writes
+
+## EXPLAIN Analysis
+```sql
+EXPLAIN ANALYZE SELECT ...;
+```
+Look for: Seq Scan (missing index), Nested Loop (N+1), Sort (missing index on ORDER BY)
+
+## Pagination
+```sql
+-- ❌ Slow on large tables
+SELECT * FROM items LIMIT 10 OFFSET 10000;
+
+-- ✅ Cursor-based (fast)
+SELECT * FROM items WHERE id > :last_id ORDER BY id LIMIT 10;
+```

package/skills/devops/ci-cd/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ci-cd
+description: CI/CD pipeline configuration — GitHub Actions, testing, deployment automation.
+detect: dir:.github/workflows
+---
+
+# CI/CD Pipelines
+
+## GitHub Actions Pipeline Order
+```
+lint → typecheck → test → security scan → build → deploy
+```
+
+## Standard Workflow Template
+```yaml
+name: CI/CD
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup
+        uses: actions/setup-node@v4  # or setup-python
+        with: { node-version: '20' }
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test -- --coverage
+      - run: npm audit --audit-level=high
+
+  build:
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: docker build -t app:${{ github.sha }} .
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        run: echo "Deploy to production"
+```
+
+## Rules
+- Cache dependencies (`actions/cache`) to speed up builds
+- Run security scan on every PR, not just main
+- Fail fast — lint before test, test before build
+- Pin action versions to SHA, not tags
+- Secrets via GitHub Secrets, never in workflow files
+- Matrix builds for multi-version/multi-OS testing

package/skills/devops/deployment/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: deployment
+description: Deployment strategies and production readiness checks.
+---
+
+# Deployment
+
+## Pre-Deploy Checklist
+- [ ] All tests pass
+- [ ] Security scan clean (no critical/high)
+- [ ] Environment variables documented and set
+- [ ] Database migrations tested
+- [ ] Health check endpoint responds
+- [ ] Rollback procedure documented
+- [ ] Monitoring/alerting configured
+- [ ] Rate limiting enabled
+- [ ] HTTPS enforced
+- [ ] Logs structured and forwarded
+
+## Strategies
+| Strategy | Downtime | Risk | Rollback |
+|---|---|---|---|
+| Rolling | Zero | Medium | Automatic |
+| Blue-Green | Zero | Low | Instant switch |
+| Canary | Zero | Lowest | Route back |
+| Recreate | Yes | High | Redeploy old |
+
+## Recommended: Blue-Green for SaaS
+1. Deploy new version to "green" environment
+2. Run smoke tests against green
+3. Switch traffic from blue → green
+4. Keep blue alive for instant rollback
+5. Tear down blue after confidence period (24h)
+
+## Example: Health Check Endpoint
+```python
+@app.get("/healthz")
+async def health():
+    checks = {
+        "database": await check_db(),
+        "redis": await check_redis(),
+        "version": os.getenv("APP_VERSION", "unknown"),
+    }
+    healthy = all(v is True for v in checks.values() if isinstance(v, bool))
+    return JSONResponse(
+        content=checks,
+        status_code=200 if healthy else 503
+    )
+```

package/skills/devops/docker/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: docker
+description: Docker best practices — multi-stage builds, security hardening, compose patterns, optimization.
+detect: Dockerfile docker-compose.yml docker-compose.yaml
+---
+
+# Docker
+
+## Dockerfile Best Practices
+- Multi-stage builds: separate build and runtime stages
+- Use specific base image tags (never `latest`)
+- Order layers by change frequency (least changed first)
+- Combine RUN commands to reduce layers
+- Use `.dockerignore` to exclude `node_modules`, `.git`, `__pycache__`
+- Run as non-root user: `USER 1001`
+- No secrets in build args or env — use runtime secrets
+- Health check on every service: `HEALTHCHECK CMD curl -f http://localhost:8080/health`
+
+## Python Template
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /install /usr/local
+COPY . .
+USER 1001
+EXPOSE 8000
+HEALTHCHECK CMD curl -f http://localhost:8000/health || exit 1
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+## Node.js Template
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json .
+RUN npm ci --only=production
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+USER 1001
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+## Compose Patterns
+- Use `depends_on` with health checks for startup order
+- Named volumes for persistent data
+- Networks to isolate services
+- `.env` file for configuration, never hardcoded values
+- Resource limits: `deploy.resources.limits`