pyeye-mcp 1.0.1__tar.gz

pyeye_mcp-1.0.1/.claude/README.md

@@ -0,0 +1,60 @@
+# ⚠️ This Directory is for Claude Code, Not Humans
+
+## Humans: You're in the Wrong Place
+
+This directory contains behavioral instructions for Claude Code (AI assistant). These files control how Claude behaves when working on this project.
+
+### Looking for Documentation?
+
+- **Project Overview**: See [`/README.md`](../README.md)
+- **Contributing Guide**: See [`/CONTRIBUTING.md`](../CONTRIBUTING.md)
+- **Documentation**: See [`/docs`](../docs/)
+- **API Reference**: See [`/docs/api`](../docs/api/)
+
+### For Maintainers Only
+
+If you need to modify Claude's behavior:
+
+#### Directory Structure
+
+```text
+.claude/
+├── instructions/     # Modular behavior rules
+│   ├── 00-*.md      # Core understanding
+│   ├── 01-*.md      # Fundamental rules
+│   ├── 02-*.md      # Startup/context
+│   └── ...          # Other behaviors
+├── agents/          # Agent definitions
+├── feedback/        # Learning/logs
+└── settings.json    # Configuration
+```
+
+#### Key Files
+
+- `instructions/00-documentation-system.md` - Teaches Claude about documentation
+- `instructions/01-core-rules.md` - Critical behavior rules
+- `instructions/04-agent-triggers.md` - When to use specific agents
+
+#### Making Changes
+
+1. Changes here immediately affect Claude's behavior
+2. Use IMPERATIVE language (MUST, NEVER, ALWAYS)
+3. Keep instructions concise and enforceable
+4. Don't put human explanations here - use `/docs` instead
+
+#### Understanding the System
+
+The instruction files use a numbered prefix system:
+
+- `00-*` Foundational understanding
+- `01-*` Core rules and enforcement
+- `02-*` Startup and context detection
+- `03-*` Required practices
+- `04-*` Behavioral triggers
+- `05-07-*` Workflows
+- `08-*` Project-specific
+- `09-10-*` Tools and utilities
+
+### Warning
+
+Modifying these files changes how Claude behaves across ALL sessions on this project. Be careful and test changes thoroughly.

pyeye_mcp-1.0.1/.claude/agents/INTEGRATION-EXAMPLE.md

@@ -0,0 +1,238 @@
+---
+name: example-with-event-learning
+description: Example agent showing how to integrate with event-driven learning
+tools: Bash, Read, Edit
+color: cyan
+---
+
+# Example Agent with Event-Driven Learning Integration
+
+This example shows how agents can integrate with the event-driven learning system.
+
+## Startup: Source the Learning System
+
+```bash
+# At agent startup, source the learning functions
+source "${CLAUDE_FEEDBACK_DIR:-/home/mark/GitHub/pyeye-mcp-work/claude-development/.claude/feedback}/event_driven_learning.sh"
+
+AGENT_NAME="example-with-event-learning"
+
+# Signal execution start (increments counter, checks thresholds)
+handle_agent_event "execution_start" "$AGENT_NAME"
+```
+
+## During Execution: Track Events
+
+```bash
+# Example task function with event tracking
+perform_task() {
+    local task_path="$1"
+
+    # Try the operation
+    if cd "$task_path" 2>/dev/null; then
+        echo "✓ Successfully changed to $task_path"
+    else
+        # Log the issue pattern
+        handle_agent_event "issue_detected" "$AGENT_NAME" "path_error" "Failed to cd to $task_path"
+
+        # Try recovery with absolute path
+        task_path="$(realpath "$task_path" 2>/dev/null || pwd)"
+        if cd "$task_path"; then
+            echo "✓ Recovered using absolute path"
+        else
+            # Track failure
+            handle_agent_event "execution_complete" "$AGENT_NAME" "failure"
+            return 1
+        fi
+    fi
+
+    # Continue with task...
+    echo "Performing task in $(pwd)"
+
+    # Simulate some work
+    if [ -w "." ]; then
+        echo "✓ Have write permissions"
+    else
+        # Another pattern to track
+        handle_agent_event "issue_detected" "$AGENT_NAME" "permission_denied" "No write permission in $(pwd)"
+    fi
+
+    return 0
+}
+```
+
+## Completion: Report Outcome
+
+```bash
+# Main execution flow
+main() {
+    echo "Starting $AGENT_NAME"
+
+    # Track start
+    handle_agent_event "execution_start" "$AGENT_NAME"
+
+    # Perform the actual work
+    if perform_task "$@"; then
+        # Success
+        handle_agent_event "execution_complete" "$AGENT_NAME" "success"
+        echo "✅ Task completed successfully"
+    else
+        # Failure
+        handle_agent_event "execution_complete" "$AGENT_NAME" "failure"
+        echo "❌ Task failed"
+    fi
+
+    # The event system will automatically:
+    # 1. Check if execution threshold reached (triggers learning)
+    # 2. Monitor failure rate (triggers immediate fixes)
+    # 3. Detect repeated patterns (applies known fixes)
+}
+```
+
+## Real-Time Pattern Response
+
+```bash
+# Advanced: Agent can check for patterns in real-time
+check_and_adapt() {
+    local operation=$1
+
+    # Before attempting operation, check if it's been problematic
+    if grep -q "$operation.*failed" "$CLAUDE_FEEDBACK_DIR/.patterns/${AGENT_NAME}.patterns" 2>/dev/null; then
+        echo "⚠️ This operation has failed before - using enhanced approach"
+
+        # Use learned approach
+        case "$operation" in
+            "cd")
+                echo "Using absolute paths (learned from failures)"
+                USE_ABSOLUTE_PATHS=true
+                ;;
+            "git")
+                echo "Adding retry logic (learned from failures)"
+                MAX_RETRIES=5
+                ;;
+        esac
+    fi
+}
+```
+
+## Session End Hook
+
+```bash
+# At session end (or context switch)
+cleanup() {
+    echo "Session ending for $AGENT_NAME"
+
+    # Trigger session-end analysis
+    handle_agent_event "session_end"
+
+    # This will:
+    # - Analyze all agents active this session
+    # - Apply learnings if thresholds met
+    # - Update agent files if patterns detected
+}
+
+# Register cleanup
+trap cleanup EXIT
+```
+
+## How It Works - The Flow
+
+1. **Execution starts** → Counter increments → Checks if threshold reached
+2. **Issues occur** → Patterns logged → Checks if pattern repeated
+3. **Execution ends** → Outcome tracked → Checks failure rate
+4. **Thresholds triggered** → Analysis runs → Fixes applied automatically
+
+## Benefits of Integration
+
+1. **No Manual Tracking** - Events logged automatically
+2. **Real-Time Response** - Fixes applied during execution
+3. **Adaptive Thresholds** - Adjusts based on agent performance
+4. **Known Fix Database** - Common issues fixed immediately
+5. **Session Persistence** - Learning continues across sessions
+
+## Example Trigger Scenarios
+
+### Scenario 1: Execution Threshold
+
+```text
+Agent runs 10 times → Threshold reached → Analysis triggered →
+Patterns found → Agent updated → Next run uses improvements
+```
+
+### Scenario 2: High Failure Rate
+
+```text
+3 failures in last 10 runs → Failure threshold hit →
+Immediate analysis → Critical fixes applied → Agent recovers
+```
+
+### Scenario 3: Pattern Detection
+
+```text
+Same error 3 times → Pattern detected → Known fix exists →
+Fix applied immediately → Error stops occurring
+```
+
+## Testing the Integration
+
+```bash
+# Test execution counter
+for i in {1..10}; do
+    ./example-with-event-learning.sh test_task
+done
+# Should trigger learning after 10 executions
+
+# Test failure tracking
+for i in {1..3}; do
+    ./example-with-event-learning.sh /nonexistent/path
+done
+# Should trigger high failure rate response
+
+# Test pattern detection
+for i in {1..3}; do
+    handle_agent_event "issue_detected" "example-with-event-learning" "timeout"
+done
+# Should detect pattern and suggest/apply timeout fix
+```
+
+## Customizing Thresholds
+
+Create agent-specific profile:
+
+```bash
+cat > $CLAUDE_FEEDBACK_DIR/.profiles/example-with-event-learning.profile << EOF
+EXECUTION_THRESHOLD=5    # Check every 5 runs (not 10)
+FAILURE_THRESHOLD=2      # React after 2 failures (not 3)
+PATTERN_THRESHOLD=2      # Detect pattern after 2 occurrences
+AUTO_FIX_ENABLED=true    # Apply fixes automatically
+EOF
+```
+
+## Monitoring & Metrics
+
+Check agent's learning status:
+
+```bash
+# View current counters
+cat $CLAUDE_FEEDBACK_DIR/.counters/example-with-event-learning.count
+
+# View recent outcomes
+cat $CLAUDE_FEEDBACK_DIR/.outcomes/example-with-event-learning.recent
+
+# View detected patterns
+cat $CLAUDE_FEEDBACK_DIR/.patterns/example-with-event-learning.patterns
+
+# Run manual analysis
+$CLAUDE_FEEDBACK_DIR/event_driven_learning.sh check_agent example-with-event-learning
+```
+
+## The Result
+
+Agents that integrate with event-driven learning:
+
+- **Get smarter automatically** based on usage
+- **Fix themselves** when patterns detected
+- **Adapt thresholds** based on performance
+- **Share knowledge** through the learning system
+
+No cron jobs. No waiting. Just intelligent, event-driven improvement!

pyeye_mcp-1.0.1/.claude/agents/README-SELF-IMPROVEMENT.md

@@ -0,0 +1,326 @@
+# Agent Self-Improvement & Learning System
+
+## Overview
+
+This document describes the self-improvement feedback mechanism for Claude Code agents, enabling them to learn from issues, adapt their behavior, and improve over time.
+
+## 🎯 Core Principles
+
+1. **Capture Issues**: Document problems as they occur
+2. **Analyze Patterns**: Identify recurring issues
+3. **Update Instructions**: Evolve agent behavior based on learnings
+4. **Track Improvements**: Measure success of changes
+5. **Share Knowledge**: Cross-agent learning
+
+## 📁 Feedback Structure
+
+### Directory Layout
+
+```text
+.claude/
+├── agents/
+│   ├── worktree-manager.md
+│   ├── smart-commit.md
+│   ├── pr-workflow.md
+│   └── ...
+├── feedback/
+│   ├── logs/
+│   │   ├── 2025-01-30-worktree-manager.json
+│   │   ├── 2025-01-30-smart-commit.json
+│   │   └── ...
+│   ├── learnings/
+│   │   ├── worktree-manager-learnings.md
+│   │   ├── smart-commit-learnings.md
+│   │   └── ...
+│   └── metrics/
+│       └── agent-performance.json
+```
+
+## 📝 Feedback Log Format
+
+Each agent execution should log feedback in JSON format:
+
+```json
+{
+  "timestamp": "2025-01-30T14:43:40.896644",
+  "agent": "worktree-manager",
+  "session_id": "claude-session-xyz",
+  "task": "Create worktree for issue 115",
+  "outcome": "partial_success",
+  "issues": [
+    {
+      "type": "path_error",
+      "description": "Failed to cd to relative path from wrong directory",
+      "context": "Shell reset to startup directory after git worktree add",
+      "impact": "high"
+    }
+  ],
+  "successes": [
+    {
+      "type": "worktree_created",
+      "description": "Successfully created worktree with correct branch naming"
+    }
+  ],
+  "suggestions": [
+    "Always use absolute paths for directory changes",
+    "Store and restore CLAUDE_WORKING_DIR after shell resets"
+  ],
+  "execution_time_ms": 3500,
+  "tools_used": ["Bash", "TodoWrite"],
+  "error_recovery": true
+}
+```
+
+## 🔄 Learning Loop Process
+
+### 1. Immediate Feedback (During Execution)
+
+When an agent encounters an issue:
+
+```bash
+# Agent should log the issue immediately
+echo '{
+  "timestamp": "'$(date -Iseconds)'",
+  "agent": "worktree-manager",
+  "issue": "cd failed due to shell reset",
+  "recovery": "using absolute path instead"
+}' >> ~/.claude/feedback/logs/$(date +%Y-%m-%d)-worktree-manager.json
+```
+
+### 2. Post-Execution Analysis
+
+After each agent run, analyze what happened:
+
+```python
+# Pseudocode for analysis
+def analyze_agent_execution(agent_name, session_id):
+    # Collect all logs from session
+    logs = load_logs(agent_name, session_id)
+
+    # Identify patterns
+    patterns = {
+        "repeated_errors": find_repeated_errors(logs),
+        "recovery_strategies": extract_successful_recoveries(logs),
+        "performance_issues": identify_slow_operations(logs)
+    }
+
+    # Generate learnings
+    learnings = generate_learnings(patterns)
+
+    # Update agent instructions if needed
+    if should_update_agent(learnings):
+        update_agent_instructions(agent_name, learnings)
+```
+
+### 3. Learning Extraction
+
+Convert feedback into actionable learnings:
+
+```markdown
+## Learnings for worktree-manager
+
+### Issue: Shell Directory Reset (Encountered 5 times)
+
+**Problem**: After `git worktree add`, the shell resets to CLAUDE_STARTUP_DIR
+
+**Root Cause**: Each Bash command runs in isolation, directory context not preserved
+
+**Solution**:
+1. Always use absolute paths
+2. Export and restore CLAUDE_WORKING_DIR
+3. Chain commands with && when context matters
+
+**Updated Instruction**:
+```bash
+# OLD (problematic)
+git worktree add ../work/feat-123 -b feat/123
+cd ../work/feat-123
+
+# NEW (reliable)
+WORK_DIR="/absolute/path/to/work/feat-123"
+git worktree add "$WORK_DIR" -b feat/123
+cd "$WORK_DIR" && export CLAUDE_WORKING_DIR=$(pwd)
+```
+
+### Issue: Permission Errors on Windows (Encountered 3 times)
+
+**Problem**: chmod operations fail silently on Windows
+
+**Solution**: Add platform detection and conditional chmod
+
+**Updated Instruction**: Check OS before chmod operations
+
+```text
+```
+
+## 🚀 Implementation Strategy
+
+### Phase 1: Manual Feedback Collection
+
+1. Create feedback directory structure
+2. Manually log issues during agent execution
+3. Weekly review of feedback logs
+4. Manual updates to agent instructions
+
+### Phase 2: Semi-Automated Collection
+
+1. Add feedback hooks to agent templates
+2. Automatic JSON logging of issues
+3. Simple analysis scripts to find patterns
+4. Suggested updates for human review
+
+### Phase 3: Full Learning Loop
+
+1. Real-time feedback collection
+2. Automatic pattern detection
+3. A/B testing of instruction changes
+4. Continuous improvement metrics
+
+## 📊 Success Metrics
+
+Track these metrics to measure improvement:
+
+```json
+{
+  "agent": "worktree-manager",
+  "period": "2025-01",
+  "metrics": {
+    "success_rate": 0.85,
+    "error_recovery_rate": 0.92,
+    "avg_execution_time_ms": 2500,
+    "unique_errors": 3,
+    "repeated_errors": 1,
+    "instruction_updates": 2,
+    "user_interventions_required": 0.15
+  },
+  "improvements": {
+    "success_rate_change": "+0.10",
+    "execution_time_change": "-500ms",
+    "error_reduction": "-40%"
+  }
+}
+```
+
+## 🔧 Quick Fixes Based on Current Issues
+
+### For worktree-manager
+
+1. **Always use absolute paths**
+
+   ```bash
+   MAIN_REPO="/home/mark/GitHub/pyeye-mcp"
+   WORK_DIR="$MAIN_REPO-work/feat-123"
+   ```
+
+2. **Preserve context across commands**
+
+   ```bash
+   export CLAUDE_WORKING_DIR=$(pwd)
+   # After any directory change:
+   cd "$SOME_DIR" && export CLAUDE_WORKING_DIR=$(pwd)
+   ```
+
+3. **Check before assuming**
+
+   ```bash
+   # Don't assume worktree creation succeeded
+   if git worktree add "$WORK_DIR" -b "$BRANCH"; then
+       cd "$WORK_DIR"
+   else
+       echo "Failed to create worktree"
+       exit 1
+   fi
+   ```
+
+### For all agents
+
+1. **Error handling first**
+   - Check command success before proceeding
+   - Log failures with context
+   - Provide recovery strategies
+
+2. **Platform awareness**
+   - Test for OS-specific behaviors
+   - Use cross-platform alternatives
+   - Document platform limitations
+
+3. **State validation**
+   - Verify assumptions before operations
+   - Check current directory, branch, etc.
+   - Report state clearly to user
+
+## 📚 Knowledge Sharing
+
+### Cross-Agent Learnings
+
+Some learnings apply to multiple agents:
+
+```markdown
+## Universal Agent Learnings
+
+### Shell Context Management
+- Applies to: ALL agents using Bash
+- Learning: Shell resets between commands
+- Solution: Export critical variables, use absolute paths
+
+### Git Operations
+- Applies to: worktree-manager, smart-commit, pr-workflow
+- Learning: Git commands can fail silently
+- Solution: Always check exit codes, parse output
+
+### File System Operations
+- Applies to: ALL agents
+- Learning: Relative paths are unreliable
+- Solution: Resolve to absolute paths early
+```
+
+## 🎯 Next Steps
+
+1. **Immediate**: Update worktree-manager with absolute path usage
+2. **This Week**: Create feedback logging function for all agents
+3. **This Month**: Build analysis tool to find patterns
+4. **This Quarter**: Implement automatic instruction updates
+
+## 📝 Template for Agent Updates
+
+When updating an agent based on learnings:
+
+```markdown
+## Update: [Agent Name] - [Date]
+
+### Issue Addressed
+[Description of the problem]
+
+### Root Cause
+[Why it happened]
+
+### Solution Implemented
+[What was changed]
+
+### Test Case
+[How to verify the fix works]
+
+### Rollback Plan
+[How to revert if issues arise]
+```
+
+## 🔍 Monitoring & Alerts
+
+Set up monitoring for critical agent failures:
+
+1. **Failure threshold**: Alert if success rate < 70%
+2. **Repeated errors**: Alert if same error occurs 3+ times
+3. **Performance degradation**: Alert if execution time increases 50%
+4. **User intervention**: Alert if manual fixes required > 25%
+
+## 🤝 Contributing to Agent Improvement
+
+When you encounter an agent issue:
+
+1. **Document it** in the feedback log
+2. **Attempt recovery** and note what worked
+3. **Suggest improvement** in the feedback
+4. **Update instructions** if you have a fix
+5. **Share learning** in the learnings file
+
+Remember: Every issue is an opportunity for the system to improve!