claude-flow-novice 2.15.3 → 2.15.4

package/claude-assets/skills/bootstrap/skill-loader.md

@@ -0,0 +1,616 @@
+---
+name: skill-loader
+category: foundation
+team: foundation
+approval_level: auto
+approval_criteria:
+  max_commands: 3
+  test_coverage: 0.95
+  no_external_calls: true
+tags: [skill-loading, cache, foundation]
+version: 1.0.0
+owner: cfn-core
+---
+
+# Skill Loader - Bootstrap Skill
+
+## Overview
+Dynamic skill loading from database, skill cache management, and hash validation patterns. Enables runtime skill injection and adaptive specialization.
+
+**⚠️ SECURITY NOTE:** This skill uses SQL queries with bash variable interpolation. While basic escaping (`${var//\'/\'\'}`) is applied, this pattern has limitations and should only be used with trusted inputs in controlled bootstrap environments. See database-connection.md for full security documentation.
+
+## SQL Injection Protection
+
+### Identifier Validation
+```bash
+# SQL INJECTION PROTECTION: Validate identifier before interpolation
+validate_sql_identifier() {
+    local identifier="$1"
+    local identifier_type="${2:-identifier}"
+
+    # Strict validation: only allow safe SQL identifiers
+    # Pattern: starts with letter/underscore, contains only alphanumeric/underscore
+    if [[ ! "$identifier" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]]; then
+        echo "ERROR: Invalid $identifier_type '$identifier' - must match ^[a-zA-Z_][a-zA-Z0-9_]*$" >&2
+        return 1
+    fi
+
+    return 0
+}
+```
+
+## Database-Driven Skill Loading
+
+### Load Skill from Database
+```bash
+#!/bin/bash
+set -euo pipefail
+
+load_skill_from_db() {
+    local db_path="$1"
+    local skill_name="$2"
+    local cache_dir="${3:-./.skill-cache}"
+
+    # Validate database exists
+    if [[ ! -f "$db_path" ]]; then
+        echo "ERROR: Database not found: $db_path" >&2
+        return 1
+    fi
+
+    # SQL INJECTION PREVENTION: Validate skill name before query
+    validate_sql_identifier "$skill_name" "skill name" || return 1
+
+    # Query skill content (validated identifier - safe to interpolate)
+    local skill_content
+    skill_content=$(sqlite3 "$db_path" <<EOF
+SELECT content FROM skills WHERE name = '${skill_name//\'/\'\'}' LIMIT 1;
+EOF
+)
+
+    if [[ -z "$skill_content" ]]; then
+        echo "ERROR: Skill not found: $skill_name" >&2
+        return 1
+    fi
+
+    # Create cache directory
+    mkdir -p "$cache_dir"
+
+    # Write to cache file
+    local cache_file="${cache_dir}/${skill_name}.md"
+    echo "$skill_content" > "$cache_file"
+
+    echo "$cache_file"
+}
+
+# Usage
+SKILL_FILE=$(load_skill_from_db "./data/skills.db" "database-connection")
+echo "Loaded skill: $SKILL_FILE"
+```
+
+### Load Multiple Skills
+```bash
+load_skills_batch() {
+    local db_path="$1"
+    local cache_dir="${2:-./.skill-cache}"
+    shift 2
+    local skill_names=("$@")
+
+    local -a loaded_skills=()
+    local -a failed_skills=()
+
+    for skill_name in "${skill_names[@]}"; do
+        if skill_file=$(load_skill_from_db "$db_path" "$skill_name" "$cache_dir" 2>/dev/null); then
+            loaded_skills+=("$skill_file")
+            echo "Loaded: $skill_name"
+        else
+            failed_skills+=("$skill_name")
+            echo "Failed: $skill_name" >&2
+        fi
+    done
+
+    if [[ ${#failed_skills[@]} -gt 0 ]]; then
+        echo "ERROR: Failed to load ${#failed_skills[@]} skills: ${failed_skills[*]}" >&2
+        return 1
+    fi
+
+    printf '%s\n' "${loaded_skills[@]}"
+}
+
+# Usage
+SKILLS=("database-connection" "error-handling" "bash-fundamentals")
+load_skills_batch "./data/skills.db" "./.skill-cache" "${SKILLS[@]}"
+```
+
+### Query Skills by Category
+```bash
+load_skills_by_category() {
+    local db_path="$1"
+    local category="$2"
+    local cache_dir="${3:-./.skill-cache}"
+
+    # SQL INJECTION PREVENTION: Validate category name before query
+    validate_sql_identifier "$category" "category name" || return 1
+
+    # Get skill names in category (validated identifier - safe to interpolate)
+    local skill_names
+    skill_names=$(sqlite3 "$db_path" <<EOF
+SELECT name FROM skills WHERE category = '${category//\'/\'\'}' ORDER BY name;
+EOF
+)
+
+    if [[ -z "$skill_names" ]]; then
+        echo "WARNING: No skills found in category: $category" >&2
+        return 0
+    fi
+
+    # Load each skill
+    local -a loaded_skills=()
+    while IFS= read -r skill_name; do
+        if skill_file=$(load_skill_from_db "$db_path" "$skill_name" "$cache_dir"); then
+            loaded_skills+=("$skill_file")
+        fi
+    done <<< "$skill_names"
+
+    printf '%s\n' "${loaded_skills[@]}"
+}
+
+# Usage
+load_skills_by_category "./data/skills.db" "foundation" "./.skill-cache"
+```
+
+## Skill Cache Management
+
+### Cache Initialization
+```bash
+initialize_skill_cache() {
+    local cache_dir="${1:-./.skill-cache}"
+    local max_age_seconds="${2:-86400}"  # Default 24 hours
+
+    # Create cache directory
+    mkdir -p "$cache_dir"
+
+    # Create cache metadata file
+    local metadata_file="${cache_dir}/.cache-metadata"
+    cat > "$metadata_file" <<EOF
+{
+  "initialized_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "max_age_seconds": $max_age_seconds,
+  "version": "1.0.0"
+}
+EOF
+
+    echo "Cache initialized: $cache_dir"
+}
+```
+
+### Cache Invalidation
+```bash
+invalidate_skill_cache() {
+    local cache_dir="${1:-./.skill-cache}"
+    local skill_name="${2:-}"
+
+    if [[ -z "$skill_name" ]]; then
+        # Invalidate entire cache
+        echo "Invalidating entire cache: $cache_dir"
+        rm -rf "$cache_dir"
+        mkdir -p "$cache_dir"
+    else
+        # Invalidate specific skill
+        local cache_file="${cache_dir}/${skill_name}.md"
+        if [[ -f "$cache_file" ]]; then
+            echo "Invalidating cached skill: $skill_name"
+            rm -f "$cache_file"
+        fi
+    fi
+}
+```
+
+### Cache Cleanup (Age-Based)
+```bash
+cleanup_skill_cache() {
+    local cache_dir="${1:-./.skill-cache}"
+    local max_age_seconds="${2:-86400}"  # Default 24 hours
+
+    if [[ ! -d "$cache_dir" ]]; then
+        echo "Cache directory does not exist: $cache_dir"
+        return 0
+    fi
+
+    local current_time=$(date +%s)
+    local removed_count=0
+
+    # Find and remove old cache files
+    while IFS= read -r -d '' file; do
+        local file_time=$(stat -f%m "$file" 2>/dev/null || stat -c%Y "$file")
+        local age=$((current_time - file_time))
+
+        if [[ $age -gt $max_age_seconds ]]; then
+            echo "Removing stale cache file: $(basename "$file") (age: ${age}s)"
+            rm -f "$file"
+            ((removed_count++))
+        fi
+    done < <(find "$cache_dir" -type f -name "*.md" -print0)
+
+    echo "Removed $removed_count stale cache files"
+}
+```
+
+### Cache Statistics
+```bash
+get_cache_stats() {
+    local cache_dir="${1:-./.skill-cache}"
+
+    if [[ ! -d "$cache_dir" ]]; then
+        echo "Cache directory does not exist: $cache_dir"
+        return 1
+    fi
+
+    local total_files=$(find "$cache_dir" -type f -name "*.md" | wc -l)
+    local total_size=$(du -sb "$cache_dir" 2>/dev/null | cut -f1)
+    local cache_age=0
+
+    local metadata_file="${cache_dir}/.cache-metadata"
+    if [[ -f "$metadata_file" ]]; then
+        local init_time=$(jq -r '.initialized_at' "$metadata_file" 2>/dev/null || echo "unknown")
+        echo "Cache Statistics:"
+        echo "  Directory: $cache_dir"
+        echo "  Initialized: $init_time"
+        echo "  Total files: $total_files"
+        echo "  Total size: $total_size bytes"
+    fi
+}
+```
+
+## Hash Validation
+
+### Compute Content Hash
+```bash
+compute_content_hash() {
+    local content="$1"
+    local algorithm="${2:-sha256}"
+
+    case "$algorithm" in
+        md5)
+            echo -n "$content" | md5sum | cut -d' ' -f1
+            ;;
+        sha256)
+            echo -n "$content" | sha256sum | cut -d' ' -f1
+            ;;
+        *)
+            echo "ERROR: Unsupported hash algorithm: $algorithm" >&2
+            return 1
+            ;;
+    esac
+}
+
+compute_file_content_hash() {
+    local file_path="$1"
+    local algorithm="${2:-sha256}"
+
+    if [[ ! -f "$file_path" ]]; then
+        echo "ERROR: File not found: $file_path" >&2
+        return 1
+    fi
+
+    case "$algorithm" in
+        md5)
+            md5sum "$file_path" | cut -d' ' -f1
+            ;;
+        sha256)
+            sha256sum "$file_path" | cut -d' ' -f1
+            ;;
+        *)
+            echo "ERROR: Unsupported hash algorithm: $algorithm" >&2
+            return 1
+            ;;
+    esac
+}
+```
+
+### Validate Skill Hash
+```bash
+validate_skill_hash() {
+    local db_path="$1"
+    local skill_name="$2"
+    local cache_file="$3"
+
+    # SQL INJECTION PREVENTION: Validate skill name before query
+    validate_sql_identifier "$skill_name" "skill name" || return 1
+
+    # Get stored hash from database (validated identifier - safe to interpolate)
+    local stored_hash
+    stored_hash=$(sqlite3 "$db_path" <<EOF
+SELECT hash FROM skills WHERE name = '${skill_name//\'/\'\'}' LIMIT 1;
+EOF
+)
+
+    if [[ -z "$stored_hash" ]]; then
+        echo "WARNING: No hash found for skill: $skill_name" >&2
+        return 0  # No hash to validate
+    fi
+
+    # Compute hash of cached file
+    local actual_hash
+    actual_hash=$(compute_file_content_hash "$cache_file" "sha256")
+
+    if [[ "$actual_hash" != "$stored_hash" ]]; then
+        echo "ERROR: Hash mismatch for skill: $skill_name" >&2
+        echo "  Expected: $stored_hash" >&2
+        echo "  Actual: $actual_hash" >&2
+        return 1
+    fi
+
+    echo "Hash validated: $skill_name"
+    return 0
+}
+```
+
+### Update Skill Hash in Database
+```bash
+update_skill_hash() {
+    local db_path="$1"
+    local skill_name="$2"
+    local skill_content="$3"
+
+    # SQL INJECTION PREVENTION: Validate skill name before query
+    validate_sql_identifier "$skill_name" "skill name" || return 1
+
+    # Compute hash of new content
+    local new_hash
+    new_hash=$(compute_content_hash "$skill_content" "sha256")
+
+    # Update hash in database (validated identifier - safe to interpolate)
+    sqlite3 "$db_path" <<EOF
+UPDATE skills SET hash = '$new_hash' WHERE name = '${skill_name//\'/\'\'}';
+EOF
+
+    echo "Updated hash for skill: $skill_name ($new_hash)"
+}
+```
+
+## Skill Loading with Validation
+
+### Load and Validate Skill
+```bash
+load_and_validate_skill() {
+    local db_path="$1"
+    local skill_name="$2"
+    local cache_dir="${3:-./.skill-cache}"
+    local validate_hash="${4:-true}"
+
+    # Load skill from database
+    local cache_file
+    cache_file=$(load_skill_from_db "$db_path" "$skill_name" "$cache_dir") || return 1
+
+    # Validate hash if requested
+    if [[ "$validate_hash" == "true" ]]; then
+        if ! validate_skill_hash "$db_path" "$skill_name" "$cache_file"; then
+            echo "ERROR: Hash validation failed, removing cached file" >&2
+            rm -f "$cache_file"
+            return 1
+        fi
+    fi
+
+    echo "$cache_file"
+}
+```
+
+### Load Skills with Dependency Resolution
+```bash
+load_skills_with_dependencies() {
+    local db_path="$1"
+    local skill_name="$2"
+    local cache_dir="${3:-./.skill-cache}"
+
+    local -a loaded_skills=()
+    local -a skill_queue=("$skill_name")
+    local -A processed_skills=()
+
+    while [[ ${#skill_queue[@]} -gt 0 ]]; do
+        local current_skill="${skill_queue[0]}"
+        skill_queue=("${skill_queue[@]:1}")  # Remove first element
+
+        # Skip if already processed
+        [[ -n "${processed_skills[$current_skill]:-}" ]] && continue
+        processed_skills[$current_skill]=1
+
+        # Load skill
+        local cache_file
+        cache_file=$(load_and_validate_skill "$db_path" "$current_skill" "$cache_dir") || {
+            echo "ERROR: Failed to load skill: $current_skill" >&2
+            return 1
+        }
+
+        loaded_skills+=("$cache_file")
+
+        # Get dependencies (if any)
+        local dependencies
+        dependencies=$(sqlite3 "$db_path" <<EOF
+SELECT depends_on FROM skill_dependencies WHERE skill_name = '${current_skill//\'/\'\'}';
+EOF
+)
+
+        # Add dependencies to queue
+        while IFS= read -r dep; do
+            [[ -z "$dep" ]] && continue
+            skill_queue+=("$dep")
+        done <<< "$dependencies"
+    done
+
+    printf '%s\n' "${loaded_skills[@]}"
+}
+```
+
+## Agent Context Injection
+
+### Build Skill Context for Agent
+```bash
+build_agent_skill_context() {
+    local db_path="$1"
+    local agent_type="$2"
+    local cache_dir="${3:-./.skill-cache}"
+
+    # SQL INJECTION PREVENTION: Validate agent type before query
+    validate_sql_identifier "$agent_type" "agent type" || return 1
+
+    # Get required skills for agent type (validated identifier - safe to interpolate)
+    local skill_names
+    skill_names=$(sqlite3 "$db_path" <<EOF
+SELECT s.name
+FROM skills s
+JOIN agent_skills a ON s.id = a.skill_id
+JOIN agents ag ON a.agent_id = ag.id
+WHERE ag.type = '${agent_type//\'/\'\'}'
+ORDER BY a.priority;
+EOF
+)
+
+    if [[ -z "$skill_names" ]]; then
+        echo "WARNING: No skills configured for agent type: $agent_type" >&2
+        return 0
+    fi
+
+    local skill_context=""
+
+    # Load each skill and concatenate
+    while IFS= read -r skill_name; do
+        local cache_file
+        if cache_file=$(load_and_validate_skill "$db_path" "$skill_name" "$cache_dir"); then
+            skill_context+=$'\n\n'
+            skill_context+="# Skill: $skill_name"
+            skill_context+=$'\n\n'
+            skill_context+=$(cat "$cache_file")
+        fi
+    done <<< "$skill_names"
+
+    echo "$skill_context"
+}
+
+# Usage
+AGENT_CONTEXT=$(build_agent_skill_context "./data/skills.db" "backend-developer")
+echo "Agent context built (${#AGENT_CONTEXT} chars)"
+```
+
+### Inject Skills into Agent Prompt
+```bash
+inject_skills_into_prompt() {
+    local base_prompt="$1"
+    local skill_context="$2"
+
+    # Create enhanced prompt
+    cat <<EOF
+$base_prompt
+
+## Specialized Skills
+
+The following skills are available for this agent:
+
+$skill_context
+
+---
+
+Use these skills to guide your work and ensure best practices.
+EOF
+}
+
+# Usage
+BASE_PROMPT=$(cat agent-base-prompt.txt)
+SKILL_CONTEXT=$(build_agent_skill_context "./data/skills.db" "backend-developer")
+ENHANCED_PROMPT=$(inject_skills_into_prompt "$BASE_PROMPT" "$SKILL_CONTEXT")
+```
+
+## Performance Optimization
+
+### Preload Bootstrap Skills
+```bash
+preload_bootstrap_skills() {
+    local db_path="$1"
+    local cache_dir="${2:-./.skill-cache}"
+
+    # Bootstrap skills that should always be loaded
+    local -a bootstrap_skills=(
+        "database-connection"
+        "error-handling"
+        "bash-fundamentals"
+        "file-operations"
+        "skill-loader"
+    )
+
+    echo "Preloading ${#bootstrap_skills[@]} bootstrap skills..."
+
+    local start_time=$(date +%s)
+
+    if load_skills_batch "$db_path" "$cache_dir" "${bootstrap_skills[@]}"; then
+        local end_time=$(date +%s)
+        local duration=$((end_time - start_time))
+        echo "Bootstrap skills loaded in ${duration}s"
+        return 0
+    else
+        echo "ERROR: Failed to preload bootstrap skills" >&2
+        return 1
+    fi
+}
+```
+
+### Parallel Skill Loading
+```bash
+load_skills_parallel() {
+    local db_path="$1"
+    local cache_dir="${2:-./.skill-cache}"
+    shift 2
+    local skill_names=("$@")
+
+    local load_timeout="${SKILL_LOAD_TIMEOUT:-30}"  # Default 30 seconds
+
+    local -a pids=()
+
+    # Load skills in parallel with timeout protection
+    for skill_name in "${skill_names[@]}"; do
+        (
+            timeout "$load_timeout" load_and_validate_skill "$db_path" "$skill_name" "$cache_dir" &>/dev/null
+            local exit_code=$?
+            if [[ $exit_code -eq 124 ]]; then
+                echo "ERROR: Skill load timeout after ${load_timeout}s: $skill_name" >&2
+                exit 124
+            fi
+            exit $exit_code
+        ) &
+        pids+=($!)
+    done
+
+    # Wait for all loads to complete
+    local failed=0
+    local timeout_failures=0
+    for pid in "${pids[@]}"; do
+        wait "$pid"
+        local exit_code=$?
+        if [[ $exit_code -ne 0 ]]; then
+            ((failed++))
+            if [[ $exit_code -eq 124 ]]; then
+                ((timeout_failures++))
+            fi
+        fi
+    done
+
+    if [[ $failed -gt 0 ]]; then
+        echo "ERROR: $failed skills failed to load (${timeout_failures} timeouts)" >&2
+        return 1
+    fi
+
+    echo "All ${#skill_names[@]} skills loaded successfully"
+}
+```
+
+## Success Criteria
+
+- ✅ Dynamic skill loading from SQLite database
+- ✅ Skill cache initialization and management
+- ✅ Age-based cache cleanup and invalidation
+- ✅ SHA-256 hash validation for content integrity
+- ✅ Dependency resolution for skill loading
+- ✅ Agent-specific skill context building
+- ✅ Skill injection into agent prompts
+- ✅ Bootstrap skill preloading
+- ✅ Parallel skill loading for performance
+- ✅ Cache statistics and monitoring
+- ✅ Error handling for missing or invalid skills