forge-server 0.1.0

package/plugin/skills/agent-development/references/triggering-examples.md

@@ -0,0 +1,491 @@
+# Agent Triggering Examples: Best Practices
+
+Complete guide to writing effective `<example>` blocks in agent descriptions for reliable triggering.
+
+## Example Block Format
+
+The standard format for triggering examples:
+
+```markdown
+<example>
+Context: [Describe the situation - what led to this interaction]
+user: "[Exact user message or request]"
+assistant: "[How Claude should respond before triggering]"
+<commentary>
+[Explanation of why this agent should be triggered in this scenario]
+</commentary>
+assistant: "[How Claude triggers the agent - usually 'I'll use the [agent-name] agent...']"
+</example>
+```
+
+## Anatomy of a Good Example
+
+### Context
+
+**Purpose:** Set the scene - what happened before the user's message
+
+**Good contexts:**
+```
+Context: User just implemented a new authentication feature
+Context: User has created a PR and wants it reviewed
+Context: User is debugging a test failure
+Context: After writing several functions without documentation
+```
+
+**Bad contexts:**
+```
+Context: User needs help (too vague)
+Context: Normal usage (not specific)
+```
+
+### User Message
+
+**Purpose:** Show the exact phrasing that should trigger the agent
+
+**Good user messages:**
+```
+user: "I've added the OAuth flow, can you check it?"
+user: "Review PR #123"
+user: "Why is this test failing?"
+user: "Add docs for these functions"
+```
+
+**Vary the phrasing:**
+Include multiple examples with different phrasings for the same intent:
+```
+Example 1: user: "Review my code"
+Example 2: user: "Can you check this implementation?"
+Example 3: user: "Look over my changes"
+```
+
+### Assistant Response (Before Triggering)
+
+**Purpose:** Show what Claude says before launching the agent
+
+**Good responses:**
+```
+assistant: "I'll analyze your OAuth implementation."
+assistant: "Let me review that PR for you."
+assistant: "I'll investigate the test failure."
+```
+
+**Proactive example:**
+```
+assistant: "Great! Now let me review the code quality."
+<commentary>
+Code was just written, proactively trigger review agent.
+</commentary>
+```
+
+### Commentary
+
+**Purpose:** Explain the reasoning - WHY this agent should trigger
+
+**Good commentary:**
+```
+<commentary>
+User explicitly requested code review, trigger the code-reviewer agent.
+</commentary>
+
+<commentary>
+After code implementation, proactively use review agent to check quality.
+</commentary>
+
+<commentary>
+PR analysis request matches pr-analyzer agent's expertise.
+</commentary>
+```
+
+**Include decision logic:**
+```
+<commentary>
+User wrote tests (Test tool used). The test-analyzer agent should check
+test quality and coverage before continuing.
+</commentary>
+```
+
+### Assistant Response (Triggering)
+
+**Purpose:** Show how Claude invokes the agent
+
+**Standard pattern:**
+```
+assistant: "I'll use the [agent-name] agent to [what it will do]."
+```
+
+**Examples:**
+```
+assistant: "I'll use the code-reviewer agent to analyze the changes."
+assistant: "Let me use the test-generator agent to create comprehensive tests."
+assistant: "I'll use the security-analyzer agent to check for vulnerabilities."
+```
+
+## Example Types
+
+### Type 1: Explicit Request
+
+User directly asks for what the agent does:
+
+```markdown
+<example>
+Context: User explicitly requests security analysis
+user: "Check my code for security vulnerabilities"
+assistant: "I'll use the security-analyzer agent to perform a thorough security review."
+<commentary>
+Direct security analysis request triggers the security-analyzer agent.
+</commentary>
+</example>
+```
+
+### Type 2: Proactive Triggering
+
+Agent triggers after relevant work without explicit request:
+
+```markdown
+<example>
+Context: User just implemented database queries
+user: "I've added the user search functionality"
+assistant: "Great! Let me review it for security."
+<commentary>
+Database code written. Proactively trigger security-analyzer to check
+for SQL injection and other database security issues.
+</commentary>
+assistant: "I'll use the security-analyzer agent to check the database code."
+</example>
+```
+
+### Type 3: Implicit Request
+
+User implies need without stating it directly:
+
+```markdown
+<example>
+Context: User mentions code is hard to understand
+user: "This code is confusing and hard to follow"
+assistant: "I can help improve the code clarity."
+<commentary>
+User indicates complexity issues. Trigger code-simplifier agent to refactor
+for better readability.
+</commentary>
+assistant: "I'll use the code-simplifier agent to suggest improvements."
+</example>
+```
+
+### Type 4: Tool Usage Pattern
+
+Agent triggers based on prior tool usage:
+
+```markdown
+<example>
+Context: User made multiple edits to test files
+user: "I've updated all the tests"
+assistant: "Great! Let me verify test quality."
+<commentary>
+Multiple Edit tools used on test files. Proactively trigger test-quality-analyzer
+to ensure tests follow best practices.
+</commentary>
+assistant: "I'll use the test-quality-analyzer agent to review the tests."
+</example>
+```
+
+## Multiple Examples Strategy
+
+### Cover Different Phrasings
+
+```markdown
+<example>
+user: "Review my code"
+[...]
+</example>
+
+<example>
+user: "Can you check my implementation?"
+[...]
+</example>
+
+<example>
+user: "Look over these changes"
+[...]
+</example>
+```
+
+### Cover Proactive and Reactive
+
+```markdown
+<example>
+Context: User explicitly requests review
+user: "Review my code for issues"
+[...]
+</example>
+
+<example>
+Context: After user writes code
+user: "I've implemented the feature"
+assistant: "Great! Now let me review it."
+<commentary>
+Code written, proactively review.
+</commentary>
+[...]
+</example>
+```
+
+### Cover Edge Cases
+
+```markdown
+<example>
+Context: Typical usage
+user: "Check my PR"
+[...]
+</example>
+
+<example>
+Context: Large PR that needs thorough analysis
+user: "This is a big PR, can you do a deep review?"
+[...]
+<commentary>
+Large PR mentioned, use thorough analysis mode.
+</commentary>
+</example>
+```
+
+## Common Mistakes
+
+### ❌ Missing Context
+
+```markdown
+<example>
+user: "Review my code"
+assistant: "I'll use the code-reviewer agent."
+</example>
+```
+
+**Why bad:** No context about what led to this request.
+
+### ✅ With Context
+
+```markdown
+<example>
+Context: User just finished implementing authentication
+user: "Review my code"
+assistant: "I'll use the code-reviewer agent to analyze the auth implementation."
+<commentary>
+Auth code written, review for security and best practices.
+</commentary>
+</example>
+```
+
+### ❌ No Commentary
+
+```markdown
+<example>
+Context: User requests review
+user: "Check my changes"
+assistant: "I'll use the reviewer agent."
+</example>
+```
+
+**Why bad:** Doesn't explain WHY agent triggers.
+
+### ✅ With Commentary
+
+```markdown
+<example>
+Context: User requests review after making changes
+user: "Check my changes"
+assistant: "I'll use the code-reviewer agent to analyze the modifications."
+<commentary>
+Code review request triggers agent to check quality, security, and adherence to standards.
+</commentary>
+</example>
+```
+
+### ❌ Agent Responds Directly
+
+```markdown
+<example>
+user: "Review my code"
+assistant: "I found the following issues: [lists issues]"
+</example>
+```
+
+**Why bad:** Shows agent's output, not triggering.
+
+### ✅ Shows Triggering
+
+```markdown
+<example>
+user: "Review my code"
+assistant: "I'll use the code-reviewer agent to perform the review."
+<commentary>
+Review request triggers the agent.
+</commentary>
+</example>
+```
+
+## How Many Examples?
+
+### Minimum: 2 Examples
+
+Cover at least:
+1. Explicit request
+2. One variation or proactive trigger
+
+### Recommended: 3-4 Examples
+
+Cover:
+1. Explicit request (direct ask)
+2. Implicit request (user implies need)
+3. Proactive trigger (after relevant work)
+4. Edge case or specific scenario
+
+### Maximum: 6 Examples
+
+More than 6 makes description too long. Focus on most important scenarios.
+
+## Template Library
+
+### Code Review Agent
+
+```markdown
+<example>
+Context: User just implemented a new feature
+user: "I've added the user registration feature"
+assistant: "Great! Let me review the code quality."
+<commentary>
+Code written, proactively trigger code-reviewer agent.
+</commentary>
+assistant: "I'll use the code-reviewer agent to analyze the implementation."
+</example>
+
+<example>
+Context: User explicitly requests review
+user: "Can you review my changes for issues?"
+assistant: "I'll use the code-reviewer agent to perform a thorough review."
+<commentary>
+Explicit review request triggers the agent.
+</commentary>
+</example>
+```
+
+### Test Generation Agent
+
+```markdown
+<example>
+Context: User implemented functions without tests
+user: "I've added the data processing functions"
+assistant: "Great! Let me generate tests for these."
+<commentary>
+New code without tests, proactively trigger test-generator agent.
+</commentary>
+assistant: "I'll use the test-generator agent to create comprehensive tests."
+</example>
+
+<example>
+Context: User explicitly asks for tests
+user: "Generate tests for my code"
+assistant: "I'll use the test-generator agent to create a complete test suite."
+<commentary>
+Direct test generation request triggers the agent.
+</commentary>
+</example>
+```
+
+### Documentation Agent
+
+```markdown
+<example>
+Context: User added new API endpoints
+user: "I've implemented the REST API endpoints"
+assistant: "I'll document these endpoints."
+<commentary>
+New API code, proactively generate documentation.
+</commentary>
+assistant: "I'll use the api-docs-writer agent to create comprehensive documentation."
+</example>
+
+<example>
+Context: User requests documentation
+user: "Write docs for this API"
+assistant: "I'll use the api-docs-writer agent to generate clear documentation."
+<commentary>
+Documentation request triggers the agent.
+</commentary>
+</example>
+```
+
+### Validation Agent
+
+```markdown
+<example>
+Context: User ready to commit changes
+user: "I'm ready to commit this code"
+assistant: "Let me validate it first."
+<commentary>
+Before commit, proactively validate with validation-agent.
+</commentary>
+assistant: "I'll use the code-validator agent to check for issues."
+</example>
+
+<example>
+Context: User asks for validation
+user: "Validate my implementation"
+assistant: "I'll use the code-validator agent to verify correctness."
+<commentary>
+Explicit validation request triggers the agent.
+</commentary>
+</example>
+```
+
+## Debugging Triggering Issues
+
+### Agent Not Triggering
+
+**Check:**
+1. Examples include relevant keywords from user message
+2. Context matches actual usage scenarios
+3. Commentary explains triggering logic clearly
+4. Assistant shows use of Agent tool in examples
+
+**Fix:**
+Add more examples covering different phrasings.
+
+### Agent Triggers Too Often
+
+**Check:**
+1. Examples are too broad or generic
+2. Triggering conditions overlap with other agents
+3. Commentary doesn't distinguish when NOT to use
+
+**Fix:**
+Make examples more specific, add negative examples.
+
+### Agent Triggers in Wrong Scenarios
+
+**Check:**
+1. Examples don't match actual intended use
+2. Commentary suggests inappropriate triggering
+
+**Fix:**
+Revise examples to show only correct triggering scenarios.
+
+## Best Practices Summary
+
+✅ **DO:**
+- Include 2-4 concrete, specific examples
+- Show both explicit and proactive triggering
+- Provide clear context for each example
+- Explain reasoning in commentary
+- Vary user message phrasing
+- Show Claude using Agent tool
+
+❌ **DON'T:**
+- Use generic, vague examples
+- Omit context or commentary
+- Show only one type of triggering
+- Skip the agent invocation step
+- Make examples too similar
+- Forget to explain why agent triggers
+
+## Conclusion
+
+Well-crafted examples are crucial for reliable agent triggering. Invest time in creating diverse, specific examples that clearly demonstrate when and why the agent should be used.

package/plugin/skills/agent-development/scripts/validate-agent.sh

@@ -0,0 +1,217 @@
+#!/bin/bash
+# Agent File Validator
+# Validates agent markdown files for correct structure and content
+
+set -euo pipefail
+
+# Usage
+if [ $# -eq 0 ]; then
+  echo "Usage: $0 <path/to/agent.md>"
+  echo ""
+  echo "Validates agent file for:"
+  echo "  - YAML frontmatter structure"
+  echo "  - Required fields (name, description, model, color)"
+  echo "  - Field formats and constraints"
+  echo "  - System prompt presence and length"
+  echo "  - Example blocks in description"
+  exit 1
+fi
+
+AGENT_FILE="$1"
+
+echo "🔍 Validating agent file: $AGENT_FILE"
+echo ""
+
+# Check 1: File exists
+if [ ! -f "$AGENT_FILE" ]; then
+  echo "❌ File not found: $AGENT_FILE"
+  exit 1
+fi
+echo "✅ File exists"
+
+# Check 2: Starts with ---
+FIRST_LINE=$(head -1 "$AGENT_FILE")
+if [ "$FIRST_LINE" != "---" ]; then
+  echo "❌ File must start with YAML frontmatter (---)"
+  exit 1
+fi
+echo "✅ Starts with frontmatter"
+
+# Check 3: Has closing ---
+if ! tail -n +2 "$AGENT_FILE" | grep -q '^---$'; then
+  echo "❌ Frontmatter not closed (missing second ---)"
+  exit 1
+fi
+echo "✅ Frontmatter properly closed"
+
+# Extract frontmatter and system prompt
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$AGENT_FILE")
+SYSTEM_PROMPT=$(awk '/^---$/{i++; next} i>=2' "$AGENT_FILE")
+
+# Check 4: Required fields
+echo ""
+echo "Checking required fields..."
+
+error_count=0
+warning_count=0
+
+# Check name field
+NAME=$(echo "$FRONTMATTER" | grep '^name:' | sed 's/name: *//' | sed 's/^"\(.*\)"$/\1/')
+
+if [ -z "$NAME" ]; then
+  echo "❌ Missing required field: name"
+  ((error_count++))
+else
+  echo "✅ name: $NAME"
+
+  # Validate name format
+  if ! [[ "$NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$ ]]; then
+    echo "❌ name must start/end with alphanumeric and contain only letters, numbers, hyphens"
+    ((error_count++))
+  fi
+
+  # Validate name length
+  name_length=${#NAME}
+  if [ $name_length -lt 3 ]; then
+    echo "❌ name too short (minimum 3 characters)"
+    ((error_count++))
+  elif [ $name_length -gt 50 ]; then
+    echo "❌ name too long (maximum 50 characters)"
+    ((error_count++))
+  fi
+
+  # Check for generic names
+  if [[ "$NAME" =~ ^(helper|assistant|agent|tool)$ ]]; then
+    echo "⚠️  name is too generic: $NAME"
+    ((warning_count++))
+  fi
+fi
+
+# Check description field
+DESCRIPTION=$(echo "$FRONTMATTER" | grep '^description:' | sed 's/description: *//')
+
+if [ -z "$DESCRIPTION" ]; then
+  echo "❌ Missing required field: description"
+  ((error_count++))
+else
+  desc_length=${#DESCRIPTION}
+  echo "✅ description: ${desc_length} characters"
+
+  if [ $desc_length -lt 10 ]; then
+    echo "⚠️  description too short (minimum 10 characters recommended)"
+    ((warning_count++))
+  elif [ $desc_length -gt 5000 ]; then
+    echo "⚠️  description very long (over 5000 characters)"
+    ((warning_count++))
+  fi
+
+  # Check for example blocks
+  if ! echo "$DESCRIPTION" | grep -q '<example>'; then
+    echo "⚠️  description should include <example> blocks for triggering"
+    ((warning_count++))
+  fi
+
+  # Check for "Use this agent when" pattern
+  if ! echo "$DESCRIPTION" | grep -qi 'use this agent when'; then
+    echo "⚠️  description should start with 'Use this agent when...'"
+    ((warning_count++))
+  fi
+fi
+
+# Check model field
+MODEL=$(echo "$FRONTMATTER" | grep '^model:' | sed 's/model: *//')
+
+if [ -z "$MODEL" ]; then
+  echo "❌ Missing required field: model"
+  ((error_count++))
+else
+  echo "✅ model: $MODEL"
+
+  case "$MODEL" in
+    inherit|sonnet|opus|haiku)
+      # Valid model
+      ;;
+    *)
+      echo "⚠️  Unknown model: $MODEL (valid: inherit, sonnet, opus, haiku)"
+      ((warning_count++))
+      ;;
+  esac
+fi
+
+# Check color field
+COLOR=$(echo "$FRONTMATTER" | grep '^color:' | sed 's/color: *//')
+
+if [ -z "$COLOR" ]; then
+  echo "❌ Missing required field: color"
+  ((error_count++))
+else
+  echo "✅ color: $COLOR"
+
+  case "$COLOR" in
+    blue|cyan|green|yellow|magenta|red)
+      # Valid color
+      ;;
+    *)
+      echo "⚠️  Unknown color: $COLOR (valid: blue, cyan, green, yellow, magenta, red)"
+      ((warning_count++))
+      ;;
+  esac
+fi
+
+# Check tools field (optional)
+TOOLS=$(echo "$FRONTMATTER" | grep '^tools:' | sed 's/tools: *//')
+
+if [ -n "$TOOLS" ]; then
+  echo "✅ tools: $TOOLS"
+else
+  echo "💡 tools: not specified (agent has access to all tools)"
+fi
+
+# Check 5: System prompt
+echo ""
+echo "Checking system prompt..."
+
+if [ -z "$SYSTEM_PROMPT" ]; then
+  echo "❌ System prompt is empty"
+  ((error_count++))
+else
+  prompt_length=${#SYSTEM_PROMPT}
+  echo "✅ System prompt: $prompt_length characters"
+
+  if [ $prompt_length -lt 20 ]; then
+    echo "❌ System prompt too short (minimum 20 characters)"
+    ((error_count++))
+  elif [ $prompt_length -gt 10000 ]; then
+    echo "⚠️  System prompt very long (over 10,000 characters)"
+    ((warning_count++))
+  fi
+
+  # Check for second person
+  if ! echo "$SYSTEM_PROMPT" | grep -q "You are\|You will\|Your"; then
+    echo "⚠️  System prompt should use second person (You are..., You will...)"
+    ((warning_count++))
+  fi
+
+  # Check for structure
+  if ! echo "$SYSTEM_PROMPT" | grep -qi "responsibilities\|process\|steps"; then
+    echo "💡 Consider adding clear responsibilities or process steps"
+  fi
+
+  if ! echo "$SYSTEM_PROMPT" | grep -qi "output"; then
+    echo "💡 Consider defining output format expectations"
+  fi
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ $error_count -eq 0 ] && [ $warning_count -eq 0 ]; then
+  echo "✅ All checks passed!"
+  exit 0
+elif [ $error_count -eq 0 ]; then
+  echo "⚠️  Validation passed with $warning_count warning(s)"
+  exit 0
+else
+  echo "❌ Validation failed with $error_count error(s) and $warning_count warning(s)"
+  exit 1
+fi