claude-flow-novice 2.15.4 → 2.15.6

package/.claude/cfn-extras/skills/google-sheets-api-coordinator/validate.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+set -eu
+
+# google-sheets-api-coordinator/validate.sh
+# Validates dependencies and configuration
+# Version: 1.0.0
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VALIDATION_ERRORS=0
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+validate_command() {
+  local cmd="$1"
+  local message="${2:-Command '$cmd' not found}"
+
+  if command -v "$cmd" &>/dev/null; then
+    echo -e "${GREEN}✓${NC} $cmd available"
+    return 0
+  else
+    echo -e "${RED}✗${NC} $message"
+    ((VALIDATION_ERRORS++))
+    return 1
+  fi
+}
+
+validate_file() {
+  local file="$1"
+  local message="${2:-File '$file' not found}"
+
+  if [ -f "$file" ]; then
+    echo -e "${GREEN}✓${NC} $file exists"
+    return 0
+  else
+    echo -e "${RED}✗${NC} $message"
+    ((VALIDATION_ERRORS++))
+    return 1
+  fi
+}
+
+validate_executable() {
+  local file="$1"
+  local message="${2:-File '$file' is not executable}"
+
+  if [ -x "$file" ]; then
+    echo -e "${GREEN}✓${NC} $file is executable"
+    return 0
+  else
+    echo -e "${RED}✗${NC} $message"
+    ((VALIDATION_ERRORS++))
+    return 1
+  fi
+}
+
+main() {
+  echo "========================================"
+  echo "Validating google-sheets-api-coordinator"
+  echo "========================================"
+  echo ""
+
+  echo "Checking dependencies..."
+  validate_command "bash" "Bash shell required"
+  validate_command "jq" "jq (JSON processor) required"
+  validate_command "curl" "curl required for API calls"
+
+  echo ""
+  echo "Checking skill files..."
+  validate_file "$SCRIPT_DIR/SKILL.md" "SKILL.md documentation required"
+  validate_executable "$SCRIPT_DIR/api-call.sh" "api-call.sh must be executable"
+  validate_executable "$SCRIPT_DIR/test.sh" "test.sh must be executable"
+
+  echo ""
+  echo "Testing basic functionality..."
+  if "$SCRIPT_DIR/api-call.sh" --help >/dev/null 2>&1; then
+    echo -e "${GREEN}✓${NC} api-call.sh responds to --help"
+  else
+    echo -e "${RED}✗${NC} api-call.sh help command failed"
+    ((VALIDATION_ERRORS++))
+  fi
+
+  echo ""
+  echo "========================================"
+  echo "Validation Results"
+  echo "========================================"
+
+  if [ $VALIDATION_ERRORS -eq 0 ]; then
+    echo -e "${GREEN}✓ All validations passed${NC}"
+    exit 0
+  else
+    echo -e "${RED}✗ ${VALIDATION_ERRORS} validation errors found${NC}"
+    exit 1
+  fi
+}
+
+main "$@"

package/.claude/cfn-extras/skills/google-sheets-decomposition/SKILL.md

@@ -0,0 +1,269 @@
+# Google Sheets Request Decomposition
+
+## Overview
+Analyzes complex Google Sheets requests and decomposes them into atomic micro-sprints with clear dependencies and success criteria.
+
+## Purpose
+Prevents "doing too much at once" by breaking complex spreadsheet operations into progressive, testable units that build toward the end goal.
+
+## Sprint Types
+
+### 1. Schema Sprint
+**Purpose:** Establish spreadsheet structure
+**Operations:**
+- Create/rename sheets
+- Add/remove columns
+- Define data types
+- Set up named ranges
+
+**Dependencies:** None (foundation sprint)
+**Max Operations:** 5 per sprint
+**Success Criteria:**
+- All sheets exist with expected names
+- Column headers match specification
+- Named ranges defined correctly
+
+### 2. Data Sprint
+**Purpose:** Populate or transform spreadsheet data
+**Operations:**
+- Import data from external sources
+- Transform existing data
+- Merge/split columns
+- Clean/normalize values
+
+**Dependencies:** Schema Sprint
+**Max Operations:** 5 per sprint
+**Success Criteria:**
+- Data imported without errors
+- Transformations produce expected output
+- No data loss or corruption
+- Row counts match expectations
+
+### 3. Formula Sprint
+**Purpose:** Add calculated columns and validation rules
+**Operations:**
+- Create formulas (simple to complex)
+- Add data validation rules
+- Implement conditional logic
+- Set up array formulas
+
+**Dependencies:** Schema Sprint, Data Sprint
+**Max Operations:** 5 per sprint
+**Success Criteria:**
+- All formulas return expected types
+- No #REF!, #VALUE!, #N/A errors
+- Validation rules enforce constraints
+- Array formulas expand correctly
+
+### 4. Formatting Sprint
+**Purpose:** Apply visual formatting and conditional styles
+**Operations:**
+- Conditional formatting rules
+- Number/date formats
+- Cell styling (colors, fonts, borders)
+- Column widths/row heights
+
+**Dependencies:** Data Sprint
+**Max Operations:** 5 per sprint
+**Success Criteria:**
+- Formatting rules apply to correct ranges
+- Conditional formatting triggers properly
+- Visual consistency maintained
+
+### 5. Integration Sprint
+**Purpose:** Connect external data sources or services
+**Operations:**
+- Import from databases
+- Connect APIs
+- Link other spreadsheets
+- Set up IMPORTRANGE functions
+
+**Dependencies:** Schema Sprint
+**Max Operations:** 3 per sprint (API quota considerations)
+**Success Criteria:**
+- External connections established
+- Data syncs without errors
+- API quota not exceeded
+- Refresh triggers work correctly
+
+### 6. Automation Sprint
+**Purpose:** Add scripts, triggers, and automations
+**Operations:**
+- Google Apps Script functions
+- Time-based triggers
+- Event-driven triggers
+- Custom functions
+
+**Dependencies:** All previous sprint types
+**Max Operations:** 3 per sprint (complexity considerations)
+**Success Criteria:**
+- Scripts execute without errors
+- Triggers fire on expected events
+- Custom functions return correct values
+- No infinite loop conditions
+
+## Decomposition Algorithm
+
+### Input
+- User request (natural language or structured)
+- Current spreadsheet state (optional)
+- Business requirements
+
+### Process
+1. **Parse Request:** Extract operations and goals
+2. **Classify Operations:** Map to sprint types
+3. **Determine Dependencies:** Build directed acyclic graph (DAG)
+4. **Group Operations:** Batch into sprints (max 5 ops/sprint)
+5. **Order Sprints:** Topological sort based on dependencies
+6. **Generate Success Criteria:** Define testable conditions for each sprint
+
+### Output
+JSON structure:
+```json
+{
+  "request_summary": "...",
+  "total_sprints": 5,
+  "sprints": [
+    {
+      "sprint_id": "schema_001",
+      "sprint_type": "schema",
+      "operations": [
+        "Create sheet 'Sales Data'",
+        "Add columns: Date, Product, Quantity, Revenue",
+        "Define named range 'SalesTable'"
+      ],
+      "dependencies": [],
+      "success_criteria": [
+        "Sheet 'Sales Data' exists",
+        "Columns match: Date, Product, Quantity, Revenue",
+        "Named range 'SalesTable' covers A1:D1000"
+      ],
+      "estimated_api_calls": 3
+    },
+    {
+      "sprint_id": "data_001",
+      "sprint_type": "data",
+      "operations": [
+        "Import CSV from Google Drive",
+        "Parse dates to standard format",
+        "Validate quantity > 0"
+      ],
+      "dependencies": ["schema_001"],
+      "success_criteria": [
+        "All rows imported (expect ~500 rows)",
+        "Date column format: YYYY-MM-DD",
+        "No negative quantities",
+        "No import errors"
+      ],
+      "estimated_api_calls": 2
+    }
+  ]
+}
+```
+
+## Usage
+
+### CLI
+```bash
+./.claude/cfn-extras/skills/google-sheets-decomposition/decompose.sh \
+  --request "Create sales dashboard with pivot tables" \
+  --mode standard \
+  --output /tmp/google-sheets-sprints.json
+```
+
+### From Agent
+```bash
+# Generate decomposition
+DECOMPOSITION=$(bash ./.claude/cfn-extras/skills/google-sheets-decomposition/decompose.sh \
+  --request "$USER_REQUEST" \
+  --mode standard)
+
+# Parse output
+TOTAL_SPRINTS=$(echo "$DECOMPOSITION" | jq -r '.total_sprints')
+```
+
+## Validation Rules
+
+### Per Sprint
+- Maximum 5 operations (3 for Integration/Automation)
+- Clear success criteria (2-5 testable conditions)
+- Explicit dependencies declared
+- Estimated API calls < 10 per sprint
+
+### Across All Sprints
+- No circular dependencies
+- Schema sprints before Data sprints
+- Formula sprints after Data sprints
+- Automation sprints last
+- Total estimated API calls < 100 (quota management)
+
+## Error Handling
+
+### Invalid Request
+```json
+{
+  "error": "INVALID_REQUEST",
+  "message": "Request too vague: 'make it better'",
+  "suggestion": "Specify concrete operations (e.g., 'add revenue column', 'create pivot table')"
+}
+```
+
+### Too Complex
+```json
+{
+  "error": "EXCEEDS_COMPLEXITY_LIMIT",
+  "message": "Request requires 25 sprints, maximum is 15",
+  "suggestion": "Break into multiple user requests or simplify scope"
+}
+```
+
+### Missing Dependencies
+```json
+{
+  "error": "CIRCULAR_DEPENDENCY",
+  "message": "Formula sprint depends on Automation sprint which depends on Formula sprint",
+  "sprints_affected": ["formula_003", "automation_001"]
+}
+```
+
+## Integration with CFN Loop
+
+### Coordinator Usage
+```bash
+# 1. Decompose request
+SPRINTS_JSON=$(decompose.sh --request "$USER_REQUEST" --mode standard)
+
+# 2. Extract sprint count
+TOTAL_SPRINTS=$(echo "$SPRINTS_JSON" | jq -r '.total_sprints')
+
+# 3. Execute sprints sequentially
+for i in $(seq 0 $((TOTAL_SPRINTS - 1))); do
+  SPRINT=$(echo "$SPRINTS_JSON" | jq -r ".sprints[$i]")
+  SPRINT_ID=$(echo "$SPRINT" | jq -r '.sprint_id')
+
+  # Execute CFN Loop for this micro-sprint
+  ./.claude/skills/cfn-loop-orchestration/orchestrate.sh \
+    --task-id "$TASK_ID" \
+    --sprint "$SPRINT" \
+    --mode standard
+done
+```
+
+## Testing
+
+Test script: `./.claude/cfn-extras/skills/google-sheets-decomposition/test-decomposition.sh`
+
+**Test Cases:**
+1. Simple request (1 sprint)
+2. Multi-sprint with dependencies
+3. Complex request (10+ sprints)
+4. Invalid request handling
+5. Circular dependency detection
+6. API quota estimation
+
+**Expected Pass Rate:** ≥0.95 (Standard mode)
+
+## References
+- Google Sheets API Quotas: https://developers.google.com/sheets/api/limits
+- Sprint Types Documentation: `./.claude/cfn-extras/docs/GOOGLE_SHEETS_SPRINTS.md`
+- CFN Loop Integration: `CLAUDE.md` Section 4

package/.claude/cfn-extras/skills/google-sheets-decomposition/decompose.sh

@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Google Sheets Request Decomposition Script
+# Breaks complex requests into atomic micro-sprints with dependencies
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+# Configuration
+MAX_SPRINTS=15
+MAX_OPS_PER_SPRINT=5
+MAX_OPS_INTEGRATION=3
+MAX_OPS_AUTOMATION=3
+MAX_API_CALLS_TOTAL=100
+
+# Default values
+REQUEST=""
+MODE="standard"
+OUTPUT_FILE=""
+CURRENT_STATE=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --request)
+      REQUEST="$2"
+      shift 2
+      ;;
+    --mode)
+      MODE="$2"
+      shift 2
+      ;;
+    --output)
+      OUTPUT_FILE="$2"
+      shift 2
+      ;;
+    --current-state)
+      CURRENT_STATE="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [[ -z "$REQUEST" ]]; then
+  echo "Error: --request is required" >&2
+  exit 1
+fi
+
+# Validate request is not too vague
+if [[ ${#REQUEST} -lt 10 ]]; then
+  cat <<EOF
+{
+  "error": "INVALID_REQUEST",
+  "message": "Request too vague: '$REQUEST'",
+  "suggestion": "Specify concrete operations (e.g., 'add revenue column', 'create pivot table')"
+}
+EOF
+  exit 1
+fi
+
+# Function to classify operation into sprint type
+classify_operation() {
+  local operation="$1"
+
+  # Schema operations
+  if echo "$operation" | grep -qiE "create sheet|add column|rename|define range|structure"; then
+    echo "schema"
+    return
+  fi
+
+  # Data operations
+  if echo "$operation" | grep -qiE "import|transform|merge|clean|populate|data"; then
+    echo "data"
+    return
+  fi
+
+  # Formula operations
+  if echo "$operation" | grep -qiE "formula|calculate|sum|average|validation|vlookup"; then
+    echo "formula"
+    return
+  fi
+
+  # Formatting operations
+  if echo "$operation" | grep -qiE "format|style|color|conditional format|width|height"; then
+    echo "formatting"
+    return
+  fi
+
+  # Integration operations
+  if echo "$operation" | grep -qiE "api|import.*from|connect|external|database|importrange"; then
+    echo "integration"
+    return
+  fi
+
+  # Automation operations
+  if echo "$operation" | grep -qiE "script|trigger|automat|custom function|apps script"; then
+    echo "automation"
+    return
+  fi
+
+  # Default to data if unclear
+  echo "data"
+}
+
+# Function to extract operations from request
+extract_operations() {
+  local request="$1"
+
+  # Simple extraction: split by common delimiters
+  # In production, this would use NLP or more sophisticated parsing
+  echo "$request" | sed 's/[,;.]/\n/g' | sed 's/and /\n/g' | sed '/^$/d'
+}
+
+# Function to generate sprint ID
+generate_sprint_id() {
+  local sprint_type="$1"
+  local counter="$2"
+  printf "%s_%03d" "$sprint_type" "$counter"
+}
+
+# Function to estimate API calls for operation
+estimate_api_calls() {
+  local operation="$1"
+  local sprint_type="$2"
+
+  case "$sprint_type" in
+    schema) echo "1" ;;
+    data) echo "2" ;;
+    formula) echo "1" ;;
+    formatting) echo "1" ;;
+    integration) echo "3" ;;
+    automation) echo "2" ;;
+    *) echo "1" ;;
+  esac
+}
+
+# Main decomposition logic
+decompose_request() {
+  local request="$1"
+
+  # Extract operations
+  mapfile -t operations < <(extract_operations "$request")
+
+  if [[ ${#operations[@]} -eq 0 ]]; then
+    cat <<EOF
+{
+  "error": "NO_OPERATIONS_FOUND",
+  "message": "Could not extract operations from request",
+  "request": "$request"
+}
+EOF
+    return 1
+  fi
+
+  # Classify and group operations
+  declare -A sprint_groups
+  declare -A sprint_counters=(
+    [schema]=1
+    [data]=1
+    [formula]=1
+    [formatting]=1
+    [integration]=1
+    [automation]=1
+  )
+
+  for op in "${operations[@]}"; do
+    # Skip empty lines
+    [[ -z "$op" ]] && continue
+
+    # Trim whitespace
+    op="$(echo "$op" | xargs)"
+
+    # Classify operation
+    sprint_type=$(classify_operation "$op")
+
+    # Get current counter
+    counter=${sprint_counters[$sprint_type]}
+    sprint_id=$(generate_sprint_id "$sprint_type" "$counter")
+
+    # Add to group
+    if [[ -z "${sprint_groups[$sprint_id]:-}" ]]; then
+      sprint_groups[$sprint_id]="$op"
+    else
+      sprint_groups[$sprint_id]="${sprint_groups[$sprint_id]}|$op"
+    fi
+
+    # Check if we need to start a new sprint (max operations reached)
+    op_count=$(echo "${sprint_groups[$sprint_id]}" | tr '|' '\n' | wc -l)
+    max_ops=$MAX_OPS_PER_SPRINT
+
+    if [[ "$sprint_type" == "integration" ]]; then
+      max_ops=$MAX_OPS_INTEGRATION
+    elif [[ "$sprint_type" == "automation" ]]; then
+      max_ops=$MAX_OPS_AUTOMATION
+    fi
+
+    if [[ $op_count -ge $max_ops ]]; then
+      sprint_counters[$sprint_type]=$((counter + 1))
+    fi
+  done
+
+  # Check total sprint count
+  total_sprints=${#sprint_groups[@]}
+  if [[ $total_sprints -gt $MAX_SPRINTS ]]; then
+    cat <<EOF
+{
+  "error": "EXCEEDS_COMPLEXITY_LIMIT",
+  "message": "Request requires $total_sprints sprints, maximum is $MAX_SPRINTS",
+  "suggestion": "Break into multiple user requests or simplify scope"
+}
+EOF
+    return 1
+  fi
+
+  # Generate JSON output
+  echo "{"
+  echo "  \"request_summary\": \"$request\","
+  echo "  \"total_sprints\": $total_sprints,"
+  echo "  \"sprints\": ["
+
+  local sprint_index=0
+  local total_api_calls=0
+
+  # Sort sprints by dependency order (schema → data → formula → formatting → integration → automation)
+  local -a ordered_types=(schema data formula formatting integration automation)
+
+  for sprint_type in "${ordered_types[@]}"; do
+    for sprint_id in $(echo "${!sprint_groups[@]}" | tr ' ' '\n' | grep "^${sprint_type}_" | sort); do
+      [[ $sprint_index -gt 0 ]] && echo ","
+
+      # Extract operations for this sprint
+      IFS='|' read -ra ops <<< "${sprint_groups[$sprint_id]}"
+
+      # Determine dependencies
+      local dependencies="[]"
+      case "$sprint_type" in
+        data)
+          dependencies='["schema"]'
+          ;;
+        formula)
+          dependencies='["schema", "data"]'
+          ;;
+        formatting)
+          dependencies='["data"]'
+          ;;
+        integration)
+          dependencies='["schema"]'
+          ;;
+        automation)
+          dependencies='["schema", "data", "formula", "formatting", "integration"]'
+          ;;
+      esac
+
+      # Generate success criteria
+      local success_criteria="["
+      local criteria_index=0
+      for op in "${ops[@]}"; do
+        [[ $criteria_index -gt 0 ]] && success_criteria+=", "
+        success_criteria+="\"Operation completed: $op\""
+        criteria_index=$((criteria_index + 1))
+      done
+      success_criteria+="]"
+
+      # Estimate API calls
+      local api_calls=0
+      for op in "${ops[@]}"; do
+        api_calls=$((api_calls + $(estimate_api_calls "$op" "$sprint_type")))
+      done
+      total_api_calls=$((total_api_calls + api_calls))
+
+      # Output sprint JSON
+      cat <<EOF
+    {
+      "sprint_id": "$sprint_id",
+      "sprint_type": "$sprint_type",
+      "operations": [$(printf '"%s"' "${ops[0]}"; printf ', "%s"' "${ops[@]:1}")],
+      "dependencies": $dependencies,
+      "success_criteria": $success_criteria,
+      "estimated_api_calls": $api_calls
+    }
+EOF
+
+      sprint_index=$((sprint_index + 1))
+    done
+  done
+
+  echo ""
+  echo "  ],"
+  echo "  \"total_estimated_api_calls\": $total_api_calls"
+  echo "}"
+
+  # Check API quota
+  if [[ $total_api_calls -gt $MAX_API_CALLS_TOTAL ]]; then
+    echo "Warning: Estimated API calls ($total_api_calls) exceeds quota limit ($MAX_API_CALLS_TOTAL)" >&2
+  fi
+}
+
+# Execute decomposition
+RESULT=$(decompose_request "$REQUEST")
+
+# Output to file or stdout
+if [[ -n "$OUTPUT_FILE" ]]; then
+  echo "$RESULT" > "$OUTPUT_FILE"
+  echo "Decomposition written to: $OUTPUT_FILE" >&2
+else
+  echo "$RESULT"
+fi