agentic-flow 1.6.5 → 1.7.2

package/.claude/skills/skill-builder/scripts/generate-skill.sh

@@ -0,0 +1,334 @@
+#!/bin/bash
+# Skill Builder - Generate New Skill Script
+# Usage: ./scripts/generate-skill.sh <skill-name> <location>
+# Location: personal | project | both (default: personal)
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Parse arguments
+SKILL_NAME="${1:-my-new-skill}"
+LOCATION="${2:-personal}"
+
+# Paths
+PERSONAL_SKILLS="$HOME/.claude/skills"
+PROJECT_SKILLS="$(git rev-parse --show-toplevel 2>/dev/null)/.claude/skills" || PROJECT_SKILLS="$(pwd)/.claude/skills"
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}🎨 Skill Builder - Generate New Skill${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+
+# Prompt for skill details
+read -p "Skill name (display name, max 64 chars): " DISPLAY_NAME
+DISPLAY_NAME="${DISPLAY_NAME:-$SKILL_NAME}"
+
+read -p "Skill description (what it does and when to use, max 1024 chars): " DESCRIPTION
+DESCRIPTION="${DESCRIPTION:-Describe what this skill does and when to use it.}"
+
+read -p "Category/Namespace (e.g., 'my-skills', 'dev-tools'): " NAMESPACE
+NAMESPACE="${NAMESPACE:-my-skills}"
+
+read -p "Include scripts directory? (y/n): " INCLUDE_SCRIPTS
+read -p "Include resources directory? (y/n): " INCLUDE_RESOURCES
+read -p "Include docs directory? (y/n): " INCLUDE_DOCS
+
+# Function to create skill
+create_skill() {
+    local base_dir="$1"
+    local skill_path="$base_dir/$NAMESPACE/$SKILL_NAME"
+
+    echo ""
+    echo -e "${GREEN}Creating skill at: ${BLUE}$skill_path${NC}"
+
+    # Create directories
+    mkdir -p "$skill_path"
+
+    if [[ "$INCLUDE_SCRIPTS" == "y" ]]; then
+        mkdir -p "$skill_path/scripts"
+        echo -e "${GREEN}✓${NC} Created scripts/ directory"
+    fi
+
+    if [[ "$INCLUDE_RESOURCES" == "y" ]]; then
+        mkdir -p "$skill_path/resources/templates"
+        mkdir -p "$skill_path/resources/examples"
+        mkdir -p "$skill_path/resources/schemas"
+        echo -e "${GREEN}✓${NC} Created resources/ directory structure"
+    fi
+
+    if [[ "$INCLUDE_DOCS" == "y" ]]; then
+        mkdir -p "$skill_path/docs"
+        echo -e "${GREEN}✓${NC} Created docs/ directory"
+    fi
+
+    # Create SKILL.md
+    cat > "$skill_path/SKILL.md" << EOF
+---
+name: "$DISPLAY_NAME"
+description: "$DESCRIPTION"
+---
+
+# $DISPLAY_NAME
+
+## What This Skill Does
+
+$DESCRIPTION
+
+## Prerequisites
+
+- Prerequisite 1
+- Prerequisite 2
+
+## Quick Start
+
+\`\`\`bash
+# Basic usage command
+command --option value
+\`\`\`
+
+## Step-by-Step Guide
+
+### Step 1: Initial Setup
+
+\`\`\`bash
+# Setup commands
+\`\`\`
+
+Expected output:
+\`\`\`
+✓ Setup complete
+\`\`\`
+
+### Step 2: Main Operation
+
+1. Action 1
+2. Action 2
+3. Action 3
+
+### Step 3: Verification
+
+\`\`\`bash
+# Verify installation/setup
+\`\`\`
+
+## Advanced Options
+
+### Option 1: Custom Configuration
+
+\`\`\`bash
+# Advanced usage
+\`\`\`
+
+### Option 2: Integration
+
+\`\`\`bash
+# Integration steps
+\`\`\`
+
+## Troubleshooting
+
+### Issue: Common Problem
+
+**Symptoms**: What you might see
+**Cause**: Why it happens
+**Solution**: How to fix it
+
+\`\`\`bash
+# Fix command
+\`\`\`
+
+## Learn More
+
+- [Related Documentation](#)
+- [Examples](#)
+- [API Reference](#)
+
+---
+
+**Created**: $(date +%Y-%m-%d)
+**Category**: $NAMESPACE
+**Status**: Draft
+EOF
+
+    echo -e "${GREEN}✓${NC} Created SKILL.md"
+
+    # Create README.md
+    cat > "$skill_path/README.md" << EOF
+# $DISPLAY_NAME
+
+$DESCRIPTION
+
+## Directory Structure
+
+\`\`\`
+$SKILL_NAME/
+├── SKILL.md           # Main skill file (Claude reads this)
+├── README.md          # This file (human-readable documentation)
+EOF
+
+    if [[ "$INCLUDE_SCRIPTS" == "y" ]]; then
+        cat >> "$skill_path/README.md" << EOF
+├── scripts/           # Executable scripts
+EOF
+    fi
+
+    if [[ "$INCLUDE_RESOURCES" == "y" ]]; then
+        cat >> "$skill_path/README.md" << EOF
+├── resources/         # Templates, examples, schemas
+│   ├── templates/
+│   ├── examples/
+│   └── schemas/
+EOF
+    fi
+
+    if [[ "$INCLUDE_DOCS" == "y" ]]; then
+        cat >> "$skill_path/README.md" << EOF
+└── docs/              # Additional documentation
+EOF
+    fi
+
+    cat >> "$skill_path/README.md" << EOF
+\`\`\`
+
+## Usage
+
+This skill is automatically discovered by Claude Code when placed in:
+- Personal: \`~/.claude/skills/\`
+- Project: \`<project>/.claude/skills/\`
+
+## Development
+
+1. Edit \`SKILL.md\` to add instructions
+2. Add scripts to \`scripts/\` directory (if needed)
+3. Add resources to \`resources/\` directory (if needed)
+4. Test with Claude Code
+
+## Testing
+
+1. Restart Claude Code (or refresh Claude.ai)
+2. Verify skill appears in skills list
+3. Test skill by asking Claude to use it
+
+---
+
+**Created**: $(date +%Y-%m-%d)
+EOF
+
+    echo -e "${GREEN}✓${NC} Created README.md"
+
+    # Create example script if scripts directory
+    if [[ "$INCLUDE_SCRIPTS" == "y" ]]; then
+        cat > "$skill_path/scripts/example.sh" << 'EOF'
+#!/bin/bash
+# Example script for skill
+
+echo "Example script executed successfully!"
+echo "Skill: $DISPLAY_NAME"
+EOF
+        chmod +x "$skill_path/scripts/example.sh"
+        echo -e "${GREEN}✓${NC} Created example script"
+    fi
+
+    # Create example template if resources directory
+    if [[ "$INCLUDE_RESOURCES" == "y" ]]; then
+        cat > "$skill_path/resources/templates/example.template" << EOF
+# Example Template
+# Replace placeholders with actual values
+
+Name: {{NAME}}
+Description: {{DESCRIPTION}}
+Created: {{DATE}}
+EOF
+        echo -e "${GREEN}✓${NC} Created example template"
+
+        # Create example schema
+        cat > "$skill_path/resources/schemas/config.schema.json" << 'EOF'
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Configuration name"
+    },
+    "enabled": {
+      "type": "boolean",
+      "default": true
+    }
+  },
+  "required": ["name"]
+}
+EOF
+        echo -e "${GREEN}✓${NC} Created example schema"
+    fi
+
+    # Create docs if docs directory
+    if [[ "$INCLUDE_DOCS" == "y" ]]; then
+        cat > "$skill_path/docs/ADVANCED.md" << EOF
+# Advanced Usage - $DISPLAY_NAME
+
+## Complex Scenarios
+
+### Scenario 1
+
+[Description and instructions]
+
+### Scenario 2
+
+[Description and instructions]
+
+## Best Practices
+
+1. Best practice 1
+2. Best practice 2
+3. Best practice 3
+
+## Performance Optimization
+
+[Optimization tips]
+EOF
+        echo -e "${GREEN}✓${NC} Created advanced documentation"
+    fi
+
+    echo ""
+    echo -e "${GREEN}✨ Skill created successfully!${NC}"
+    echo ""
+    echo -e "${BLUE}Location:${NC} $skill_path"
+    echo -e "${BLUE}Name:${NC} $DISPLAY_NAME"
+    echo -e "${BLUE}Namespace:${NC} $NAMESPACE"
+    echo ""
+    echo -e "${YELLOW}Next steps:${NC}"
+    echo -e "  1. Edit ${BLUE}$skill_path/SKILL.md${NC} with your instructions"
+    echo -e "  2. Add scripts to ${BLUE}$skill_path/scripts/${NC} (optional)"
+    echo -e "  3. Add resources to ${BLUE}$skill_path/resources/${NC} (optional)"
+    echo -e "  4. Restart Claude Code or refresh Claude.ai to test"
+    echo ""
+}
+
+# Create skill based on location
+case "$LOCATION" in
+    personal)
+        create_skill "$PERSONAL_SKILLS"
+        ;;
+    project)
+        create_skill "$PROJECT_SKILLS"
+        ;;
+    both)
+        echo -e "${BLUE}Creating in both locations...${NC}"
+        create_skill "$PERSONAL_SKILLS"
+        create_skill "$PROJECT_SKILLS"
+        ;;
+    *)
+        echo -e "${YELLOW}Unknown location: $LOCATION${NC}"
+        echo "Usage: $0 <skill-name> [personal|project|both]"
+        exit 1
+        ;;
+esac
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""

package/.claude/skills/skill-builder/scripts/validate-skill.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+# Skill Builder - Validate Skill Script
+# Usage: ./scripts/validate-skill.sh <path-to-skill-directory>
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+SKILL_DIR="${1:-.}"
+ERRORS=0
+WARNINGS=0
+
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}🔍 Skill Builder - Validate Skill${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+echo -e "Validating: ${BLUE}$SKILL_DIR${NC}"
+echo ""
+
+# Check if SKILL.md exists
+echo -e "${BLUE}[1/10]${NC} Checking SKILL.md exists..."
+if [[ ! -f "$SKILL_DIR/SKILL.md" ]]; then
+    echo -e "${RED}✗ SKILL.md not found${NC}"
+    ((ERRORS++))
+else
+    echo -e "${GREEN}✓ SKILL.md found${NC}"
+fi
+
+# Check YAML frontmatter exists
+echo -e "${BLUE}[2/10]${NC} Checking YAML frontmatter..."
+if ! grep -q "^---$" "$SKILL_DIR/SKILL.md" 2>/dev/null; then
+    echo -e "${RED}✗ YAML frontmatter not found (missing --- delimiters)${NC}"
+    ((ERRORS++))
+else
+    # Extract frontmatter
+    FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$SKILL_DIR/SKILL.md" | head -n -1 | tail -n +2)
+    echo -e "${GREEN}✓ YAML frontmatter found${NC}"
+fi
+
+# Check name field
+echo -e "${BLUE}[3/10]${NC} Checking 'name' field..."
+if ! echo "$FRONTMATTER" | grep -q "^name:"; then
+    echo -e "${RED}✗ 'name' field missing in YAML frontmatter${NC}"
+    ((ERRORS++))
+else
+    NAME=$(echo "$FRONTMATTER" | grep "^name:" | sed 's/name: *//; s/"//g; s/'"'"'//g')
+    NAME_LENGTH=${#NAME}
+
+    if [[ $NAME_LENGTH -gt 64 ]]; then
+        echo -e "${RED}✗ name too long: $NAME_LENGTH chars (max 64)${NC}"
+        ((ERRORS++))
+    elif [[ $NAME_LENGTH -eq 0 ]]; then
+        echo -e "${RED}✗ name is empty${NC}"
+        ((ERRORS++))
+    else
+        echo -e "${GREEN}✓ name valid: $NAME_LENGTH chars${NC}"
+    fi
+fi
+
+# Check description field
+echo -e "${BLUE}[4/10]${NC} Checking 'description' field..."
+if ! echo "$FRONTMATTER" | grep -q "^description:"; then
+    echo -e "${RED}✗ 'description' field missing in YAML frontmatter${NC}"
+    ((ERRORS++))
+else
+    DESCRIPTION=$(echo "$FRONTMATTER" | grep "^description:" | sed 's/description: *//; s/"//g; s/'"'"'//g')
+    DESC_LENGTH=${#DESCRIPTION}
+
+    if [[ $DESC_LENGTH -gt 1024 ]]; then
+        echo -e "${RED}✗ description too long: $DESC_LENGTH chars (max 1024)${NC}"
+        ((ERRORS++))
+    elif [[ $DESC_LENGTH -eq 0 ]]; then
+        echo -e "${RED}✗ description is empty${NC}"
+        ((ERRORS++))
+    elif [[ $DESC_LENGTH -lt 50 ]]; then
+        echo -e "${YELLOW}⚠ description short: $DESC_LENGTH chars (recommended 50+ for better matching)${NC}"
+        ((WARNINGS++))
+    else
+        echo -e "${GREEN}✓ description valid: $DESC_LENGTH chars${NC}"
+    fi
+
+    # Check if description includes "when" clause
+    if ! echo "$DESCRIPTION" | grep -qi "use when\|when to use\|use it when\|when you need"; then
+        echo -e "${YELLOW}⚠ description should include 'when to use' clause for better matching${NC}"
+        ((WARNINGS++))
+    fi
+fi
+
+# Check YAML syntax
+echo -e "${BLUE}[5/10]${NC} Checking YAML syntax..."
+if command -v python3 &> /dev/null; then
+    YAML_CHECK=$(echo "$FRONTMATTER" | python3 -c "import sys, yaml; yaml.safe_load(sys.stdin)" 2>&1)
+    if [[ $? -ne 0 ]]; then
+        echo -e "${RED}✗ YAML syntax error:${NC}"
+        echo "$YAML_CHECK"
+        ((ERRORS++))
+    else
+        echo -e "${GREEN}✓ YAML syntax valid${NC}"
+    fi
+else
+    echo -e "${YELLOW}⚠ python3 not available, skipping YAML syntax check${NC}"
+    ((WARNINGS++))
+fi
+
+# Check content structure
+echo -e "${BLUE}[6/10]${NC} Checking content structure..."
+REQUIRED_SECTIONS=("What This Skill Does" "Quick Start" "Step-by-Step")
+for section in "${REQUIRED_SECTIONS[@]}"; do
+    if ! grep -qi "$section" "$SKILL_DIR/SKILL.md"; then
+        echo -e "${YELLOW}⚠ Recommended section missing: $section${NC}"
+        ((WARNINGS++))
+    fi
+done
+
+if grep -qi "What This Skill Does\|Quick Start\|Step-by-Step"; then
+    echo -e "${GREEN}✓ Content structure looks good${NC}"
+fi
+
+# Check file size
+echo -e "${BLUE}[7/10]${NC} Checking file size..."
+FILE_SIZE=$(wc -c < "$SKILL_DIR/SKILL.md")
+FILE_SIZE_KB=$((FILE_SIZE / 1024))
+
+if [[ $FILE_SIZE_KB -gt 50 ]]; then
+    echo -e "${YELLOW}⚠ SKILL.md is large: ${FILE_SIZE_KB}KB (consider moving content to separate files)${NC}"
+    ((WARNINGS++))
+elif [[ $FILE_SIZE_KB -gt 100 ]]; then
+    echo -e "${RED}✗ SKILL.md too large: ${FILE_SIZE_KB}KB (should be < 50KB for optimal performance)${NC}"
+    ((ERRORS++))
+else
+    echo -e "${GREEN}✓ File size appropriate: ${FILE_SIZE_KB}KB${NC}"
+fi
+
+# Check for executable scripts
+echo -e "${BLUE}[8/10]${NC} Checking scripts..."
+if [[ -d "$SKILL_DIR/scripts" ]]; then
+    SCRIPT_COUNT=$(find "$SKILL_DIR/scripts" -type f | wc -l)
+    echo -e "${GREEN}✓ Found $SCRIPT_COUNT script(s)${NC}"
+
+    # Check if scripts are executable
+    NON_EXECUTABLE=$(find "$SKILL_DIR/scripts" -type f ! -executable | wc -l)
+    if [[ $NON_EXECUTABLE -gt 0 ]]; then
+        echo -e "${YELLOW}⚠ $NON_EXECUTABLE script(s) not executable (run: chmod +x scripts/*.sh)${NC}"
+        ((WARNINGS++))
+    fi
+else
+    echo -e "${BLUE}ℹ No scripts directory${NC}"
+fi
+
+# Check for resources
+echo -e "${BLUE}[9/10]${NC} Checking resources..."
+if [[ -d "$SKILL_DIR/resources" ]]; then
+    RESOURCE_COUNT=$(find "$SKILL_DIR/resources" -type f | wc -l)
+    echo -e "${GREEN}✓ Found $RESOURCE_COUNT resource file(s)${NC}"
+else
+    echo -e "${BLUE}ℹ No resources directory${NC}"
+fi
+
+# Check for documentation
+echo -e "${BLUE}[10/10]${NC} Checking documentation..."
+if [[ -f "$SKILL_DIR/README.md" ]]; then
+    echo -e "${GREEN}✓ README.md found${NC}"
+else
+    echo -e "${YELLOW}⚠ README.md not found (recommended for human-readable docs)${NC}"
+    ((WARNINGS++))
+fi
+
+# Summary
+echo ""
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo -e "${BLUE}Validation Summary${NC}"
+echo -e "${BLUE}═══════════════════════════════════════════════════════════════${NC}"
+echo ""
+
+if [[ $ERRORS -eq 0 && $WARNINGS -eq 0 ]]; then
+    echo -e "${GREEN}✅ Skill validation passed!${NC}"
+    echo -e "${GREEN}No errors or warnings found.${NC}"
+    exit 0
+elif [[ $ERRORS -eq 0 ]]; then
+    echo -e "${YELLOW}⚠ Skill validation passed with warnings${NC}"
+    echo -e "${YELLOW}Errors: 0${NC}"
+    echo -e "${YELLOW}Warnings: $WARNINGS${NC}"
+    echo ""
+    echo "The skill will work, but consider addressing the warnings above."
+    exit 0
+else
+    echo -e "${RED}❌ Skill validation failed${NC}"
+    echo -e "${RED}Errors: $ERRORS${NC}"
+    echo -e "${YELLOW}Warnings: $WARNINGS${NC}"
+    echo ""
+    echo "Please fix the errors above before using this skill."
+    exit 1
+fi

package/.claude/skills/swarm-orchestration/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: "Swarm Orchestration"
+description: "Orchestrate multi-agent swarms with agentic-flow for parallel task execution, dynamic topology, and intelligent coordination. Use when scaling beyond single agents, implementing complex workflows, or building distributed AI systems."
+---
+
+# Swarm Orchestration
+
+## What This Skill Does
+
+Orchestrates multi-agent swarms using agentic-flow's advanced coordination system. Supports mesh, hierarchical, and adaptive topologies with automatic task distribution, load balancing, and fault tolerance.
+
+## Prerequisites
+
+- agentic-flow v1.5.11+
+- Node.js 18+
+- Understanding of distributed systems (helpful)
+
+## Quick Start
+
+```bash
+# Initialize swarm
+npx agentic-flow hooks swarm-init --topology mesh --max-agents 5
+
+# Spawn agents
+npx agentic-flow hooks agent-spawn --type coder
+npx agentic-flow hooks agent-spawn --type tester
+npx agentic-flow hooks agent-spawn --type reviewer
+
+# Orchestrate task
+npx agentic-flow hooks task-orchestrate \
+  --task "Build REST API with tests" \
+  --mode parallel
+```
+
+## Topology Patterns
+
+### 1. Mesh (Peer-to-Peer)
+```typescript
+// Equal peers, distributed decision-making
+await swarm.init({
+  topology: 'mesh',
+  agents: ['coder', 'tester', 'reviewer'],
+  communication: 'broadcast'
+});
+```
+
+### 2. Hierarchical (Queen-Worker)
+```typescript
+// Centralized coordination, specialized workers
+await swarm.init({
+  topology: 'hierarchical',
+  queen: 'architect',
+  workers: ['backend-dev', 'frontend-dev', 'db-designer']
+});
+```
+
+### 3. Adaptive (Dynamic)
+```typescript
+// Automatically switches topology based on task
+await swarm.init({
+  topology: 'adaptive',
+  optimization: 'task-complexity'
+});
+```
+
+## Task Orchestration
+
+### Parallel Execution
+```typescript
+// Execute tasks concurrently
+const results = await swarm.execute({
+  tasks: [
+    { agent: 'coder', task: 'Implement API endpoints' },
+    { agent: 'frontend', task: 'Build UI components' },
+    { agent: 'tester', task: 'Write test suite' }
+  ],
+  mode: 'parallel',
+  timeout: 300000 // 5 minutes
+});
+```
+
+### Pipeline Execution
+```typescript
+// Sequential pipeline with dependencies
+await swarm.pipeline([
+  { stage: 'design', agent: 'architect' },
+  { stage: 'implement', agent: 'coder', after: 'design' },
+  { stage: 'test', agent: 'tester', after: 'implement' },
+  { stage: 'review', agent: 'reviewer', after: 'test' }
+]);
+```
+
+### Adaptive Execution
+```typescript
+// Let swarm decide execution strategy
+await swarm.autoOrchestrate({
+  goal: 'Build production-ready API',
+  constraints: {
+    maxTime: 3600,
+    maxAgents: 8,
+    quality: 'high'
+  }
+});
+```
+
+## Memory Coordination
+
+```typescript
+// Share state across swarm
+await swarm.memory.store('api-schema', {
+  endpoints: [...],
+  models: [...]
+});
+
+// Agents read shared memory
+const schema = await swarm.memory.retrieve('api-schema');
+```
+
+## Advanced Features
+
+### Load Balancing
+```typescript
+// Automatic work distribution
+await swarm.enableLoadBalancing({
+  strategy: 'dynamic',
+  metrics: ['cpu', 'memory', 'task-queue']
+});
+```
+
+### Fault Tolerance
+```typescript
+// Handle agent failures
+await swarm.setResiliency({
+  retry: { maxAttempts: 3, backoff: 'exponential' },
+  fallback: 'reassign-task'
+});
+```
+
+### Performance Monitoring
+```typescript
+// Track swarm metrics
+const metrics = await swarm.getMetrics();
+// { throughput, latency, success_rate, agent_utilization }
+```
+
+## Integration with Hooks
+
+```bash
+# Pre-task coordination
+npx agentic-flow hooks pre-task --description "Build API"
+
+# Post-task synchronization
+npx agentic-flow hooks post-task --task-id "task-123"
+
+# Session restore
+npx agentic-flow hooks session-restore --session-id "swarm-001"
+```
+
+## Best Practices
+
+1. **Start small**: Begin with 2-3 agents, scale up
+2. **Use memory**: Share context through swarm memory
+3. **Monitor metrics**: Track performance and bottlenecks
+4. **Enable hooks**: Automatic coordination and sync
+5. **Set timeouts**: Prevent hung tasks
+
+## Troubleshooting
+
+### Issue: Agents not coordinating
+**Solution**: Verify memory access and enable hooks
+
+### Issue: Poor performance
+**Solution**: Check topology (use adaptive) and enable load balancing
+
+## Learn More
+
+- Swarm Guide: docs/swarm/orchestration.md
+- Topology Patterns: docs/swarm/topologies.md
+- Hooks Integration: docs/hooks/coordination.md