cue-ai 0.3.0

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

@@ -0,0 +1,395 @@
+# 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

@@ -0,0 +1,59 @@
+#!/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

@@ -0,0 +1,101 @@
+#!/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

@@ -0,0 +1,109 @@
+# 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