cue-ai 0.3.0 → 0.4.1

package/resources/claude-plugins-official/plugins/plugin-dev/skills/plugin-settings/references/real-world-examples.md

@@ -1,395 +0,0 @@
-# Real-World Plugin Settings Examples
-
-Detailed analysis of how production plugins use the `.claude/plugin-name.local.md` pattern.
-
-## multi-agent-swarm Plugin
-
-### Settings File Structure
-
-**.claude/multi-agent-swarm.local.md:**
-
-```markdown
----
-agent_name: auth-implementation
-task_number: 3.5
-pr_number: 1234
-coordinator_session: team-leader
-enabled: true
-dependencies: ["Task 3.4"]
-additional_instructions: "Use JWT tokens, not sessions"
----
-
-# Task: Implement Authentication
-
-Build JWT-based authentication for the REST API.
-
-## Requirements
-- JWT token generation and validation
-- Refresh token flow
-- Secure password hashing
-
-## Success Criteria
-- Auth endpoints implemented
-- Tests passing (100% coverage)
-- PR created and CI green
-- Documentation updated
-
-## Coordination
-Depends on Task 3.4 (user model).
-Report status to 'team-leader' session.
-```
-
-### How It's Used
-
-**File:** `hooks/agent-stop-notification.sh`
-
-**Purpose:** Send notifications to coordinator when agent becomes idle
-
-**Implementation:**
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-SWARM_STATE_FILE=".claude/multi-agent-swarm.local.md"
-
-# Quick exit if no swarm active
-if [[ ! -f "$SWARM_STATE_FILE" ]]; then
-  exit 0
-fi
-
-# Parse frontmatter
-FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$SWARM_STATE_FILE")
-
-# Extract configuration
-COORDINATOR_SESSION=$(echo "$FRONTMATTER" | grep '^coordinator_session:' | sed 's/coordinator_session: *//' | sed 's/^"\(.*\)"$/\1/')
-AGENT_NAME=$(echo "$FRONTMATTER" | grep '^agent_name:' | sed 's/agent_name: *//' | sed 's/^"\(.*\)"$/\1/')
-TASK_NUMBER=$(echo "$FRONTMATTER" | grep '^task_number:' | sed 's/task_number: *//' | sed 's/^"\(.*\)"$/\1/')
-PR_NUMBER=$(echo "$FRONTMATTER" | grep '^pr_number:' | sed 's/pr_number: *//' | sed 's/^"\(.*\)"$/\1/')
-ENABLED=$(echo "$FRONTMATTER" | grep '^enabled:' | sed 's/enabled: *//')
-
-# Check if enabled
-if [[ "$ENABLED" != "true" ]]; then
-  exit 0
-fi
-
-# Send notification to coordinator
-NOTIFICATION="🤖 Agent ${AGENT_NAME} (Task ${TASK_NUMBER}, PR #${PR_NUMBER}) is idle."
-
-if tmux has-session -t "$COORDINATOR_SESSION" 2>/dev/null; then
-  tmux send-keys -t "$COORDINATOR_SESSION" "$NOTIFICATION" Enter
-  sleep 0.5
-  tmux send-keys -t "$COORDINATOR_SESSION" Enter
-fi
-
-exit 0
-```
-
-**Key patterns:**
-1. **Quick exit** (line 7-9): Returns immediately if file doesn't exist
-2. **Field extraction** (lines 11-17): Parses each frontmatter field
-3. **Enabled check** (lines 19-21): Respects enabled flag
-4. **Action based on settings** (lines 23-29): Uses coordinator_session to send notification
-
-### Creation
-
-**File:** `commands/launch-swarm.md`
-
-Settings files are created during swarm launch with:
-
-```bash
-cat > "$WORKTREE_PATH/.claude/multi-agent-swarm.local.md" <<EOF
----
-agent_name: $AGENT_NAME
-task_number: $TASK_ID
-pr_number: TBD
-coordinator_session: $COORDINATOR_SESSION
-enabled: true
-dependencies: [$DEPENDENCIES]
-additional_instructions: "$EXTRA_INSTRUCTIONS"
----
-
-# Task: $TASK_DESCRIPTION
-
-$TASK_DETAILS
-EOF
-```
-
-### Updates
-
-PR number updated after PR creation:
-
-```bash
-# Update pr_number field
-sed "s/^pr_number: .*/pr_number: $PR_NUM/" \
-  ".claude/multi-agent-swarm.local.md" > temp.md
-mv temp.md ".claude/multi-agent-swarm.local.md"
-```
-
-## ralph-loop Plugin
-
-### Settings File Structure
-
-**.claude/ralph-loop.local.md:**
-
-```markdown
----
-iteration: 1
-max_iterations: 10
-completion_promise: "All tests passing and build successful"
-started_at: "2025-01-15T14:30:00Z"
----
-
-Fix all the linting errors in the project.
-Make sure tests pass after each fix.
-Document any changes needed in CLAUDE.md.
-```
-
-### How It's Used
-
-**File:** `hooks/stop-hook.sh`
-
-**Purpose:** Prevent session exit and loop Claude's output back as input
-
-**Implementation:**
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-RALPH_STATE_FILE=".claude/ralph-loop.local.md"
-
-# Quick exit if no active loop
-if [[ ! -f "$RALPH_STATE_FILE" ]]; then
-  exit 0
-fi
-
-# Parse frontmatter
-FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
-
-# Extract configuration
-ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
-MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
-COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
-
-# Check max iterations
-if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
-  echo "🛑 Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
-  rm "$RALPH_STATE_FILE"
-  exit 0
-fi
-
-# Get transcript and check for completion promise
-TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
-LAST_OUTPUT=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1 | jq -r '.message.content | map(select(.type == "text")) | map(.text) | join("\n")')
-
-# Check for completion
-if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
-  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g')
-
-  if [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
-    echo "✅ Ralph loop: Detected completion"
-    rm "$RALPH_STATE_FILE"
-    exit 0
-  fi
-fi
-
-# Continue loop - increment iteration
-NEXT_ITERATION=$((ITERATION + 1))
-
-# Extract prompt from markdown body
-PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
-
-# Update iteration counter
-TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
-sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
-mv "$TEMP_FILE" "$RALPH_STATE_FILE"
-
-# Block exit and feed prompt back
-jq -n \
-  --arg prompt "$PROMPT_TEXT" \
-  --arg msg "🔄 Ralph iteration $NEXT_ITERATION" \
-  '{
-    "decision": "block",
-    "reason": $prompt,
-    "systemMessage": $msg
-  }'
-
-exit 0
-```
-
-**Key patterns:**
-1. **Quick exit** (line 7-9): Skip if not active
-2. **Iteration tracking** (lines 11-20): Count and enforce max iterations
-3. **Promise detection** (lines 25-33): Check for completion signal in output
-4. **Prompt extraction** (line 38): Read markdown body as next prompt
-5. **State update** (lines 40-43): Increment iteration atomically
-6. **Loop continuation** (lines 45-53): Block exit and feed prompt back
-
-### Creation
-
-**File:** `scripts/setup-ralph-loop.sh`
-
-```bash
-#!/bin/bash
-PROMPT="$1"
-MAX_ITERATIONS="${2:-0}"
-COMPLETION_PROMISE="${3:-}"
-
-# Create state file
-cat > ".claude/ralph-loop.local.md" <<EOF
----
-iteration: 1
-max_iterations: $MAX_ITERATIONS
-completion_promise: "$COMPLETION_PROMISE"
-started_at: "$(date -Iseconds)"
----
-
-$PROMPT
-EOF
-
-echo "Ralph loop initialized: .claude/ralph-loop.local.md"
-```
-
-## Pattern Comparison
-
-| Feature | multi-agent-swarm | ralph-loop |
-|---------|-------------------|--------------|
-| **File** | `.claude/multi-agent-swarm.local.md` | `.claude/ralph-loop.local.md` |
-| **Purpose** | Agent coordination state | Loop iteration state |
-| **Frontmatter** | Agent metadata | Loop configuration |
-| **Body** | Task assignment | Prompt to loop |
-| **Updates** | PR number, status | Iteration counter |
-| **Deletion** | Manual or on completion | On loop exit |
-| **Hook** | Stop (notifications) | Stop (loop control) |
-
-## Best Practices from Real Plugins
-
-### 1. Quick Exit Pattern
-
-Both plugins check file existence first:
-
-```bash
-if [[ ! -f "$STATE_FILE" ]]; then
-  exit 0  # Not active
-fi
-```
-
-**Why:** Avoids errors when plugin isn't configured and performs fast.
-
-### 2. Enabled Flag
-
-Both use an `enabled` field for explicit control:
-
-```yaml
-enabled: true
-```
-
-**Why:** Allows temporary deactivation without deleting file.
-
-### 3. Atomic Updates
-
-Both use temp file + atomic move:
-
-```bash
-TEMP_FILE="${FILE}.tmp.$$"
-sed "s/^field: .*/field: $NEW_VALUE/" "$FILE" > "$TEMP_FILE"
-mv "$TEMP_FILE" "$FILE"
-```
-
-**Why:** Prevents corruption if process is interrupted.
-
-### 4. Quote Handling
-
-Both strip surrounding quotes from YAML values:
-
-```bash
-sed 's/^"\(.*\)"$/\1/'
-```
-
-**Why:** YAML allows both `field: value` and `field: "value"`.
-
-### 5. Error Handling
-
-Both handle missing/corrupt files gracefully:
-
-```bash
-if [[ ! -f "$FILE" ]]; then
-  exit 0  # No error, just not configured
-fi
-
-if [[ -z "$CRITICAL_FIELD" ]]; then
-  echo "Settings file corrupt" >&2
-  rm "$FILE"  # Clean up
-  exit 0
-fi
-```
-
-**Why:** Fails gracefully instead of crashing.
-
-## Anti-Patterns to Avoid
-
-### ❌ Hardcoded Paths
-
-```bash
-# BAD
-FILE="/Users/alice/.claude/my-plugin.local.md"
-
-# GOOD
-FILE=".claude/my-plugin.local.md"
-```
-
-### ❌ Unquoted Variables
-
-```bash
-# BAD
-echo $VALUE
-
-# GOOD
-echo "$VALUE"
-```
-
-### ❌ Non-Atomic Updates
-
-```bash
-# BAD: Can corrupt file if interrupted
-sed -i "s/field: .*/field: $VALUE/" "$FILE"
-
-# GOOD: Atomic
-TEMP_FILE="${FILE}.tmp.$$"
-sed "s/field: .*/field: $VALUE/" "$FILE" > "$TEMP_FILE"
-mv "$TEMP_FILE" "$FILE"
-```
-
-### ❌ No Default Values
-
-```bash
-# BAD: Fails if field missing
-if [[ $MAX -gt 100 ]]; then
-  # MAX might be empty!
-fi
-
-# GOOD: Provide default
-MAX=${MAX:-10}
-```
-
-### ❌ Ignoring Edge Cases
-
-```bash
-# BAD: Assumes exactly 2 --- markers
-sed -n '/^---$/,/^---$/{ /^---$/d; p; }'
-
-# GOOD: Handles --- in body
-awk '/^---$/{i++; next} i>=2'  # For body
-```
-
-## Conclusion
-
-The `.claude/plugin-name.local.md` pattern provides:
-- Simple, human-readable configuration
-- Version-control friendly (gitignored)
-- Per-project settings
-- Easy parsing with standard bash tools
-- Supports both structured config (YAML) and freeform content (markdown)
-
-Use this pattern for any plugin that needs user-configurable behavior or state persistence.

package/resources/claude-plugins-official/plugins/plugin-dev/skills/plugin-settings/scripts/parse-frontmatter.sh

@@ -1,59 +0,0 @@
-#!/bin/bash
-# Frontmatter Parser Utility
-# Extracts YAML frontmatter from .local.md files
-
-set -euo pipefail
-
-# Usage
-show_usage() {
-  echo "Usage: $0 <settings-file.md> [field-name]"
-  echo ""
-  echo "Examples:"
-  echo "  # Show all frontmatter"
-  echo "  $0 .claude/my-plugin.local.md"
-  echo ""
-  echo "  # Extract specific field"
-  echo "  $0 .claude/my-plugin.local.md enabled"
-  echo ""
-  echo "  # Extract and use in script"
-  echo "  ENABLED=\$($0 .claude/my-plugin.local.md enabled)"
-  exit 0
-}
-
-if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
-  show_usage
-fi
-
-FILE="$1"
-FIELD="${2:-}"
-
-# Validate file
-if [ ! -f "$FILE" ]; then
-  echo "Error: File not found: $FILE" >&2
-  exit 1
-fi
-
-# Extract frontmatter
-FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$FILE")
-
-if [ -z "$FRONTMATTER" ]; then
-  echo "Error: No frontmatter found in $FILE" >&2
-  exit 1
-fi
-
-# If no field specified, output all frontmatter
-if [ -z "$FIELD" ]; then
-  echo "$FRONTMATTER"
-  exit 0
-fi
-
-# Extract specific field
-VALUE=$(echo "$FRONTMATTER" | grep "^${FIELD}:" | sed "s/${FIELD}: *//" | sed 's/^"\(.*\)"$/\1/' | sed "s/^'\\(.*\\)'$/\\1/")
-
-if [ -z "$VALUE" ]; then
-  echo "Error: Field '$FIELD' not found in frontmatter" >&2
-  exit 1
-fi
-
-echo "$VALUE"
-exit 0

package/resources/claude-plugins-official/plugins/plugin-dev/skills/plugin-settings/scripts/validate-settings.sh

@@ -1,101 +0,0 @@
-#!/bin/bash
-# Settings File Validator
-# Validates .claude/plugin-name.local.md structure
-
-set -euo pipefail
-
-# Usage
-if [ $# -eq 0 ]; then
-  echo "Usage: $0 <path/to/settings.local.md>"
-  echo ""
-  echo "Validates plugin settings file for:"
-  echo "  - File existence and readability"
-  echo "  - YAML frontmatter structure"
-  echo "  - Required --- markers"
-  echo "  - Field format"
-  echo ""
-  echo "Example: $0 .claude/my-plugin.local.md"
-  exit 1
-fi
-
-SETTINGS_FILE="$1"
-
-echo "🔍 Validating settings file: $SETTINGS_FILE"
-echo ""
-
-# Check 1: File exists
-if [ ! -f "$SETTINGS_FILE" ]; then
-  echo "❌ File not found: $SETTINGS_FILE"
-  exit 1
-fi
-echo "✅ File exists"
-
-# Check 2: File is readable
-if [ ! -r "$SETTINGS_FILE" ]; then
-  echo "❌ File is not readable"
-  exit 1
-fi
-echo "✅ File is readable"
-
-# Check 3: Has frontmatter markers
-MARKER_COUNT=$(grep -c '^---$' "$SETTINGS_FILE" 2>/dev/null || echo "0")
-
-if [ "$MARKER_COUNT" -lt 2 ]; then
-  echo "❌ Invalid frontmatter: found $MARKER_COUNT '---' markers (need at least 2)"
-  echo "   Expected format:"
-  echo "   ---"
-  echo "   field: value"
-  echo "   ---"
-  echo "   Content..."
-  exit 1
-fi
-echo "✅ Frontmatter markers present"
-
-# Check 4: Extract and validate frontmatter
-FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$SETTINGS_FILE")
-
-if [ -z "$FRONTMATTER" ]; then
-  echo "❌ Empty frontmatter (nothing between --- markers)"
-  exit 1
-fi
-echo "✅ Frontmatter not empty"
-
-# Check 5: Frontmatter has valid YAML-like structure
-if ! echo "$FRONTMATTER" | grep -q ':'; then
-  echo "⚠️  Warning: Frontmatter has no key:value pairs"
-fi
-
-# Check 6: Look for common fields
-echo ""
-echo "Detected fields:"
-echo "$FRONTMATTER" | grep '^[a-z_][a-z0-9_]*:' | while IFS=':' read -r key value; do
-  echo "  - $key: ${value:0:50}"
-done
-
-# Check 7: Validate common boolean fields
-for field in enabled strict_mode; do
-  VALUE=$(echo "$FRONTMATTER" | grep "^${field}:" | sed "s/${field}: *//" || true)
-  if [ -n "$VALUE" ]; then
-    if [ "$VALUE" != "true" ] && [ "$VALUE" != "false" ]; then
-      echo "⚠️  Field '$field' should be boolean (true/false), got: $VALUE"
-    fi
-  fi
-done
-
-# Check 8: Check body exists
-BODY=$(awk '/^---$/{i++; next} i>=2' "$SETTINGS_FILE")
-
-echo ""
-if [ -n "$BODY" ]; then
-  BODY_LINES=$(echo "$BODY" | wc -l | tr -d ' ')
-  echo "✅ Markdown body present ($BODY_LINES lines)"
-else
-  echo "⚠️  No markdown body (frontmatter only)"
-fi
-
-echo ""
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "✅ Settings file structure is valid"
-echo ""
-echo "Reminder: Changes to this file require restarting Claude Code"
-exit 0

package/resources/claude-plugins-official/plugins/plugin-dev/skills/plugin-structure/README.md

@@ -1,109 +0,0 @@
-# Plugin Structure Skill
-
-Comprehensive guidance on Claude Code plugin architecture, directory layout, and best practices.
-
-## Overview
-
-This skill provides detailed knowledge about:
-- Plugin directory structure and organization
-- `plugin.json` manifest configuration
-- Component organization (commands, agents, skills, hooks)
-- Auto-discovery mechanisms
-- Portable path references with `${CLAUDE_PLUGIN_ROOT}`
-- File naming conventions
-
-## Skill Structure
-
-### SKILL.md (1,619 words)
-
-Core skill content covering:
-- Directory structure overview
-- Plugin manifest (plugin.json) fields
-- Component organization patterns
-- ${CLAUDE_PLUGIN_ROOT} usage
-- File naming conventions
-- Auto-discovery mechanism
-- Best practices
-- Common patterns
-- Troubleshooting
-
-### References
-
-Detailed documentation for deep dives:
-
-- **manifest-reference.md**: Complete `plugin.json` field reference
-  - All field descriptions and examples
-  - Path resolution rules
-  - Validation guidelines
-  - Minimal vs. complete manifest examples
-
-- **component-patterns.md**: Advanced organization patterns
-  - Component lifecycle (discovery, activation)
-  - Command organization patterns
-  - Agent organization patterns
-  - Skill organization patterns
-  - Hook organization patterns
-  - Script organization patterns
-  - Cross-component patterns
-  - Best practices for scalability
-
-### Examples
-
-Three complete plugin examples:
-
-- **minimal-plugin.md**: Simplest possible plugin
-  - Single command
-  - Minimal manifest
-  - When to use this pattern
-
-- **standard-plugin.md**: Well-structured production plugin
-  - Multiple components (commands, agents, skills, hooks)
-  - Complete manifest with metadata
-  - Rich skill structure
-  - Integration between components
-
-- **advanced-plugin.md**: Enterprise-grade plugin
-  - Multi-level organization
-  - MCP server integration
-  - Shared libraries
-  - Configuration management
-  - Security automation
-  - Monitoring integration
-
-## When This Skill Triggers
-
-Claude Code activates this skill when users:
-- Ask to "create a plugin" or "scaffold a plugin"
-- Need to "understand plugin structure"
-- Want to "organize plugin components"
-- Need to "set up plugin.json"
-- Ask about "${CLAUDE_PLUGIN_ROOT}" usage
-- Want to "add commands/agents/skills/hooks"
-- Need "configure auto-discovery" help
-- Ask about plugin architecture or best practices
-
-## Progressive Disclosure
-
-The skill uses progressive disclosure to manage context:
-
-1. **SKILL.md** (~1600 words): Core concepts and workflows
-2. **References** (~6000 words): Detailed field references and patterns
-3. **Examples** (~8000 words): Complete working examples
-
-Claude loads references and examples only as needed based on the task.
-
-## Related Skills
-
-This skill works well with:
-- **hook-development**: For creating plugin hooks
-- **mcp-integration**: For integrating MCP servers (when available)
-- **marketplace-publishing**: For publishing plugins (when available)
-
-## Maintenance
-
-To update this skill:
-1. Keep SKILL.md lean and focused on core concepts
-2. Move detailed information to references/
-3. Add new examples/ for common patterns
-4. Update version in SKILL.md frontmatter
-5. Ensure all documentation uses imperative/infinitive form