claude-flow-novice 2.18.6 → 2.18.8

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

@@ -1,287 +0,0 @@
----
-name: google-sheets-progress
-version: 1.0.0
-category: coordination
-tags: [google-sheets, progress-tracking, micro-sprint, state-management]
-status: approved
-author: CFN Team
-description: Tracks micro-sprint completion state and progress for Google Sheets operations
-dependencies: [jq, bash]
-created: 2025-11-18
-updated: 2025-11-18
-complexity: Low
-keywords: [google-sheets, sprint-tracking, state-persistence, json]
-triggers: [cfn-loop-micro-sprint, progress-monitoring]
-performance_targets:
-  execution_time_ms: 500
-  success_rate: 0.99
----
-
-# Google Sheets Progress Tracking Skill
-
-## Purpose
-
-Tracks and manages micro-sprint completion state for Google Sheets operations within CFN Loop iterations. Provides persistent state management enabling agents to resume operations after interruptions and coordinate work across multiple sprint phases.
-
-## Problem Solved
-
-Google Sheets operations often require multiple sequential steps (schema creation, data population, formula application). Without persistent progress tracking, agents cannot resume after failures or coordinate work between sprints. This skill enables micro-sprint checkpointing with recovery capabilities.
-
-## When to Use
-
-- After completing each micro-sprint phase (schema, data, formulas)
-- When resuming interrupted work across CFN Loop iterations
-- For progress reporting in Loop 2 validators
-- When coordinating multi-phase operations across agents
-- For audit trails showing which sprints completed successfully
-
-## Interface
-
-### Primary Script: `track-progress.sh`
-
-**Required Parameters:**
-- `--action`: `read`, `write`, `update`, `reset` (default: read)
-- `--state-file`: Path to progress state file (default: `.claude/cfn-extras/.gs-progress-state.json`)
-
-**Optional Parameters (for write/update):**
-- `--completed`: JSON array of completed sprints, e.g., `["schema_001","data_001"]`
-- `--current`: Current active sprint identifier, e.g., `formula_001`
-- `--remaining`: JSON array of remaining sprints, e.g., `["formula_002"]`
-- `--status`: State status (in_progress, completed, blocked, paused)
-- `--metadata`: Additional JSON metadata to track
-- `--task-id`: Task ID for coordination context
-
-**Usage:**
-
-```bash
-# Read current progress state
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action read
-
-# Initialize new sprint tracking
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action write \
-  --completed '[]' \
-  --current schema_001 \
-  --remaining '["data_001","formula_001"]' \
-  --status in_progress
-
-# Update after completing a sprint
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action update \
-  --completed '["schema_001"]' \
-  --current data_001 \
-  --remaining '["formula_001"]'
-
-# Reset state for retry
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action reset
-```
-
-## Progress State Format
-
-JSON structure managed by skill:
-
-```json
-{
-  "task_id": "cfn-task-20251118-001",
-  "sprint_sequence": [
-    "schema_001",
-    "data_001",
-    "formula_001"
-  ],
-  "completed": ["schema_001"],
-  "current": "data_001",
-  "remaining": ["formula_001"],
-  "status": "in_progress",
-  "timestamps": {
-    "created": "2025-11-18T10:30:00Z",
-    "last_updated": "2025-11-18T10:45:30Z",
-    "started": "2025-11-18T10:30:00Z",
-    "completed": null
-  },
-  "metrics": {
-    "total_sprints": 3,
-    "completed_count": 1,
-    "remaining_count": 1,
-    "progress_percentage": 33.33,
-    "estimated_completion": "2025-11-18T11:15:00Z"
-  },
-  "metadata": {
-    "spreadsheet_id": "abc123def456",
-    "sheet_name": "Operations",
-    "retry_count": 0,
-    "last_error": null
-  }
-}
-```
-
-## Validation Rules
-
-The skill enforces:
-
-1. **Valid JSON structure** - All state files are valid JSON
-2. **Sprint identifier format** - Matches pattern: `[a-z]+_[0-9]{3}`
-3. **Status enum validation** - Must be: `in_progress`, `completed`, `blocked`, `paused`
-4. **Array consistency** - No duplicates between completed/current/remaining
-5. **Chronological order** - Timestamps are monotonically increasing
-6. **Atomic writes** - State files written atomically with backup
-
-## Integration with CFN Loop
-
-### Loop 3 Agents (Implementers)
-
-After each micro-sprint completes:
-
-```bash
-# Initialize progress for 3-phase operation
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action write \
-  --completed '[]' \
-  --current schema_001 \
-  --remaining '["data_001","formula_001"]' \
-  --status in_progress \
-  --task-id "$TASK_ID" \
-  --metadata "{\"spreadsheet_id\": \"$SHEET_ID\", \"source\": \"loop3_agent\"}"
-
-# After schema phase completes
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action update \
-  --completed '["schema_001"]' \
-  --current data_001 \
-  --remaining '["formula_001"]'
-
-# After data phase completes
-./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh \
-  --action update \
-  --completed '["schema_001","data_001"]' \
-  --current formula_001 \
-  --remaining '[]'
-```
-
-### Loop 2 Validators
-
-Read progress for validation context:
-
-```bash
-# Check what phases are complete
-PROGRESS=$(./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh --action read)
-
-COMPLETED=$(echo "$PROGRESS" | jq -r '.completed | length')
-TOTAL=$(echo "$PROGRESS" | jq -r '.metrics.total_sprints')
-
-echo "Validator inspecting: $COMPLETED of $TOTAL sprints completed"
-```
-
-### Coordinator Context
-
-Use progress to determine which Loop 3 agents to spawn:
-
-```bash
-# Get current progress
-PROGRESS=$(./.claude/cfn-extras/skills/google-sheets-progress/track-progress.sh --action read)
-CURRENT_SPRINT=$(echo "$PROGRESS" | jq -r '.current')
-REMAINING=$(echo "$PROGRESS" | jq -r '.remaining | length')
-
-# Only spawn agents if there's remaining work
-if [ "$REMAINING" -gt 0 ]; then
-  echo "Spawning agents for remaining $REMAINING sprints"
-  # Coordinator logic
-fi
-```
-
-## Output Format
-
-The script outputs structured JSON:
-
-```json
-{
-  "success": true,
-  "action": "read",
-  "confidence": 0.98,
-  "state": {
-    "completed": ["schema_001"],
-    "current": "data_001",
-    "remaining": ["formula_001"],
-    "status": "in_progress"
-  },
-  "metrics": {
-    "progress_percentage": 33.33,
-    "execution_time_ms": 45
-  },
-  "deliverables": [".claude/cfn-extras/.gs-progress-state.json"],
-  "errors": []
-}
-```
-
-## Error Handling
-
-Skill handles these error scenarios:
-
-1. **Invalid JSON in state file** - Backs up corrupted file, returns error with rollback option
-2. **Missing state file** - Creates new state file with initialization defaults
-3. **Lock contention** - Implements exponential backoff (100ms, 200ms, 400ms)
-4. **Atomic write failures** - Uses temp file + mv pattern for safety
-5. **Validation failures** - Returns detailed validation errors with suggestions
-
-## State File Locations
-
-State files are stored in:
-
-- **Default**: `.claude/cfn-extras/.gs-progress-state.json`
-- **Task-scoped**: `.claude/cfn-extras/.gs-progress-${TASK_ID}.json`
-- **Backup location**: `.backups/gs-progress/[timestamp]_[hash].json`
-
-## Best Practices
-
-1. **Initialize on loop start**: Write initial state before spawning agents
-2. **Atomic updates**: Use `--action update` for multi-field changes
-3. **Regular reads**: Loop 2 validators should read at least once per iteration
-4. **Task isolation**: Use `--task-id` to scope state to specific tasks
-5. **Cleanup**: Call `--action reset` at completion to prepare for next task
-
-## Anti-Patterns
-
-❌ **Partial state updates**: Updating only some fields manually
-❌ **File direct manipulation**: Editing JSON file directly instead of using script
-❌ **Stale state assumptions**: Not reading current state before updating
-❌ **Missing task context**: Not including task-id for multi-task scenarios
-❌ **No validation**: Assuming state is always well-formed
-
-## Testing
-
-The skill includes comprehensive test coverage:
-
-```bash
-# Run all tests
-./.claude/cfn-extras/skills/google-sheets-progress/test.sh
-
-# Run specific test
-./.claude/cfn-extras/skills/google-sheets-progress/test.sh --test write_action
-
-# Validate dependencies
-./.claude/cfn-extras/skills/google-sheets-progress/validate.sh
-```
-
-### Test Categories
-
-1. **Initialization tests** - Create, read, verify state
-2. **Update tests** - Modify state atomically
-3. **Edge cases** - Missing file, corrupted JSON, concurrent access
-4. **Validation tests** - Invalid enums, malformed arrays
-5. **Performance tests** - Execution time within targets
-
-## Success Criteria
-
-- **Pass rate**: ≥0.95 (standard mode)
-- **State consistency**: 0 consistency errors in concurrent access patterns
-- **Recovery capability**: Failed operations recoverable via reset
-- **Performance**: All operations complete within 500ms
-- **Backward compatibility**: State files from v1.0.0 remain compatible
-
-## References
-
-- **CFN Loop Documentation**: `.claude/commands/CFN_LOOP_TASK_MODE.md`
-- **State Management Pattern**: `.claude/skills/cfn-automatic-memory-persistence/SKILL.md`
-- **Coordination Protocols**: `.claude/skills/cfn-coordination/SKILL.md`
-- **Agent Output Standards**: `docs/AGENT_OUTPUT_STANDARDS.md`

package/claude-assets/cfn-extras/skills/google-sheets-progress/test.sh

@@ -1,385 +0,0 @@
-#!/bin/bash
-set -eu
-
-# google-sheets-progress/test.sh
-# Comprehensive test suite for progress tracking
-# Version: 1.0.0
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TEST_STATE_FILE=$(mktemp)
-TESTS_PASSED=0
-TESTS_FAILED=0
-TESTS_TOTAL=0
-
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m'
-
-# Cleanup
-cleanup() {
-  rm -f "$TEST_STATE_FILE" "$TEST_STATE_FILE.lock" 2>/dev/null || true
-}
-trap cleanup EXIT
-
-# Test helpers
-assert_success() {
-  local result="$1"
-  local message="${2:-Command should succeed}"
-
-  ((TESTS_TOTAL++))
-
-  if echo "$result" | jq -e '.success == true' >/dev/null 2>&1; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} $message"
-    return 0
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} $message"
-    echo "  Result: $result"
-    return 1
-  fi
-}
-
-assert_field_equals() {
-  local result="$1"
-  local field="$2"
-  local expected="$3"
-  local message="${4:-Field $field should equal $expected}"
-
-  ((TESTS_TOTAL++))
-
-  local actual
-  actual=$(echo "$result" | jq -r "$field" 2>/dev/null || echo "PARSE_ERROR")
-
-  if [ "$actual" = "$expected" ]; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} $message"
-    return 0
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} $message"
-    echo "  Expected: $expected"
-    echo "  Actual:   $actual"
-    return 1
-  fi
-}
-
-assert_file_exists() {
-  local file="$1"
-  local message="${2:-File should exist}"
-
-  ((TESTS_TOTAL++))
-
-  if [ -f "$file" ]; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} $message"
-    return 0
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} $message"
-    echo "  File not found: $file"
-    return 1
-  fi
-}
-
-# Test: Read from non-existent file initializes default state
-test_read_initializes_default() {
-  echo ""
-  echo "Testing read action initialization..."
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" --action read --state-file "$TEST_STATE_FILE")
-
-  assert_success "$result" "Read should initialize default state"
-  assert_field_equals "$result" ".state.completed | length" "0" "Default completed array should be empty"
-  assert_field_equals "$result" ".state.status" "pending" "Default status should be pending"
-}
-
-# Test: Write action creates valid state
-test_write_creates_state() {
-  echo ""
-  echo "Testing write action..."
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '["data_001","formula_001"]' \
-    --status in_progress)
-
-  assert_success "$result" "Write should succeed"
-  assert_field_equals "$result" ".state.current" "schema_001" "Current should be schema_001"
-  assert_field_equals "$result" ".state.status" "in_progress" "Status should be in_progress"
-  assert_file_exists "$TEST_STATE_FILE" "State file should be created"
-}
-
-# Test: Update action modifies state
-test_update_modifies_state() {
-  echo ""
-  echo "Testing update action..."
-
-  # Initialize state first
-  "$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '["data_001","formula_001"]' \
-    --status in_progress >/dev/null
-
-  # Update state
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action update \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '["schema_001"]' \
-    --current data_001 \
-    --remaining '["formula_001"]')
-
-  assert_success "$result" "Update should succeed"
-  assert_field_equals "$result" ".state.current" "data_001" "Current should be updated to data_001"
-  assert_field_equals "$result" ".state.completed | length" "1" "Completed array length should be 1"
-}
-
-# Test: Reset action clears state
-test_reset_clears_state() {
-  echo ""
-  echo "Testing reset action..."
-
-  # Initialize state first
-  "$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '["data_001"]' \
-    --status in_progress >/dev/null
-
-  # Reset state
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action reset \
-    --state-file "$TEST_STATE_FILE")
-
-  assert_success "$result" "Reset should succeed"
-  # Verify state file is removed
-  if [ -f "$TEST_STATE_FILE" ]; then
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} State file should be removed after reset"
-    ((TESTS_TOTAL++))
-  else
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} State file should be removed after reset"
-    ((TESTS_TOTAL++))
-  fi
-}
-
-# Test: Metrics calculation
-test_metrics_calculation() {
-  echo ""
-  echo "Testing metrics calculation..."
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '["data_001","formula_001"]' \
-    --status in_progress)
-
-  assert_success "$result" "Metrics calculation should succeed"
-
-  # Check metrics
-  local total_sprints
-  total_sprints=$(echo "$result" | jq '.state.metrics.total_sprints')
-  assert_field_equals "$result" ".state.metrics.total_sprints" "3" "Total sprints should be 3"
-
-  local progress
-  progress=$(echo "$result" | jq '.state.metrics.progress_percentage')
-  if [ "$progress" = "0" ] || [ "$progress" = "0.0" ]; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} Progress percentage should be 0 initially"
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} Progress percentage should be 0 initially (got $progress)"
-  fi
-  ((TESTS_TOTAL++))
-}
-
-# Test: Timestamp tracking
-test_timestamp_tracking() {
-  echo ""
-  echo "Testing timestamp tracking..."
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '["data_001"]' \
-    --status in_progress)
-
-  assert_success "$result" "Timestamp tracking should succeed"
-
-  # Check that timestamps are set
-  local created
-  created=$(echo "$result" | jq -r '.state.timestamps.created')
-
-  if [ -n "$created" ] && [ "$created" != "null" ]; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} Timestamp 'created' should be set"
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} Timestamp 'created' should be set"
-  fi
-  ((TESTS_TOTAL++))
-}
-
-# Test: Invalid sprint identifier rejected
-test_invalid_sprint_id() {
-  echo ""
-  echo "Testing sprint ID validation..."
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current invalid_sprint \
-    --remaining '[]' \
-    --status in_progress 2>&1 || true)
-
-  if echo "$result" | grep -q "Invalid sprint identifier"; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} Invalid sprint ID should be rejected"
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} Invalid sprint ID should be rejected"
-  fi
-  ((TESTS_TOTAL++))
-}
-
-# Test: Invalid status rejected
-test_invalid_status() {
-  echo ""
-  echo "Testing status validation..."
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '[]' \
-    --status invalid_status 2>&1 || true)
-
-  if echo "$result" | grep -q "Invalid status"; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} Invalid status should be rejected"
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} Invalid status should be rejected"
-  fi
-  ((TESTS_TOTAL++))
-}
-
-# Test: Metadata persistence
-test_metadata_persistence() {
-  echo ""
-  echo "Testing metadata persistence..."
-
-  local metadata='{"spreadsheet_id":"abc123","sheet_name":"Operations"}'
-
-  local result
-  result=$("$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '[]' \
-    --status in_progress \
-    --metadata "$metadata")
-
-  assert_success "$result" "Metadata should be persisted"
-
-  local sheet_name
-  sheet_name=$(echo "$result" | jq -r '.state.metadata.sheet_name')
-  assert_field_equals "$result" ".state.metadata.sheet_name" "Operations" "Metadata should be preserved"
-}
-
-# Test: Concurrent access handling
-test_concurrent_access() {
-  echo ""
-  echo "Testing concurrent access handling..."
-
-  # Initialize state
-  "$SCRIPT_DIR/track-progress.sh" \
-    --action write \
-    --state-file "$TEST_STATE_FILE" \
-    --completed '[]' \
-    --current schema_001 \
-    --remaining '[]' \
-    --status in_progress >/dev/null
-
-  # Simulate concurrent updates
-  local result1
-  result1=$("$SCRIPT_DIR/track-progress.sh" \
-    --action update \
-    --state-file "$TEST_STATE_FILE" \
-    --status blocked 2>&1 || true)
-
-  if echo "$result1" | jq -e '.success' >/dev/null 2>&1; then
-    ((TESTS_PASSED++))
-    echo -e "${GREEN}✓${NC} Concurrent access should be handled gracefully"
-  else
-    ((TESTS_FAILED++))
-    echo -e "${RED}✗${NC} Concurrent access should be handled gracefully"
-  fi
-  ((TESTS_TOTAL++))
-}
-
-# Run all tests
-run_tests() {
-  echo "========================================"
-  echo "Running tests for google-sheets-progress"
-  echo "========================================"
-
-  test_read_initializes_default
-  test_write_creates_state
-  test_update_modifies_state
-  test_reset_clears_state
-  test_metrics_calculation
-  test_timestamp_tracking
-  test_invalid_sprint_id
-  test_invalid_status
-  test_metadata_persistence
-  test_concurrent_access
-
-  echo ""
-  echo "========================================"
-  echo "Test Results"
-  echo "========================================"
-  echo "Total:  ${TESTS_TOTAL}"
-  echo -e "Passed: ${GREEN}${TESTS_PASSED}${NC}"
-
-  if [ $TESTS_FAILED -gt 0 ]; then
-    echo -e "Failed: ${RED}${TESTS_FAILED}${NC}"
-    local pass_rate
-    pass_rate=$(echo "scale=3; $TESTS_PASSED / $TESTS_TOTAL" | bc)
-    echo "Pass Rate: $pass_rate"
-    exit 1
-  else
-    echo -e "Failed: ${TESTS_FAILED}"
-    echo ""
-    echo -e "${GREEN}All tests passed! Pass rate: 1.000${NC}"
-    exit 0
-  fi
-}
-
-run_tests