diff --git a/.claude/agent-manager/config/gadugi.yaml b/.claude/agent-manager/config/gadugi.yaml new file mode 100644 index 00000000..f3410846 --- /dev/null +++ b/.claude/agent-manager/config/gadugi.yaml @@ -0,0 +1,35 @@ +# Agent Manager Configuration for Gadugi Repository + +repositories: + - name: "gadugi" + url: "https://github.com/rysweet/gadugi" + type: "github" + branch: "main" + auth: + type: "public" + priority: 1 + auto_update: true + description: "Community-driven collection of reusable Claude Code agents" + +settings: + # Update behavior + auto_update: true + check_interval: "24h" + update_on_startup: true + + # Cache settings + cache_ttl: "7d" + max_cache_size: "50MB" + offline_mode: false + + # Security settings + verify_checksums: true + allow_unsigned: false + scan_agents: true + + # Agent selection + install_all_on_init: false + auto_install_categories: + - "workflow" + - "quality" + - "infrastructure" \ No newline at end of file diff --git a/.claude/agents/agent-manager.md b/.claude/agents/agent-manager.md index 6d8f5917..94d70968 100644 --- a/.claude/agents/agent-manager.md +++ b/.claude/agents/agent-manager.md @@ -517,32 +517,138 @@ check_and_update_agents() { setup_startup_hooks() { echo "🔗 Setting up Agent Manager startup hooks..." - # Create or update Claude Code hooks configuration - local hooks_config=".claude/hooks.json" + local settings_file=".claude/settings.json" + local backup_file=".claude/settings.json.backup.$(date +%s)" - cat > "$hooks_config" << 'EOF' + # Create backup if settings.json exists + if [ -f "$settings_file" ]; then + echo "💾 Creating backup of existing settings.json..." + cp "$settings_file" "$backup_file" + fi + + # Create default settings if file doesn't exist + if [ ! -f "$settings_file" ]; then + echo "📄 Creating new settings.json file..." + mkdir -p ".claude" + echo "{}" > "$settings_file" + fi + + # Read existing settings + local existing_settings + if ! existing_settings=$(cat "$settings_file" 2>/dev/null); then + echo "⚠️ Failed to read existing settings, creating new file..." + echo "{}" > "$settings_file" + existing_settings="{}" + fi + + # Validate JSON syntax + if ! echo "$existing_settings" | python3 -m json.tool >/dev/null 2>&1; then + echo "⚠️ Invalid JSON in settings.json, creating backup and recreating..." + cp "$settings_file" "$backup_file.invalid" + existing_settings="{}" + fi + + # Create agent-manager hook configuration + local agent_manager_hook=$(cat << 'EOH' { - "on_session_start": [ + "matchers": { + "sessionType": ["startup", "resume"] + }, + "hooks": [ { - "name": "agent-manager-check", - "command": "/agent:agent-manager", - "args": "check-and-update-agents", - "async": true, - "timeout": "60s" - } - ], - "on_session_end": [ - { - "name": "agent-manager-cleanup", - "command": "/agent:agent-manager", - "args": "cleanup-cache", - "async": true + "type": "command", + "command": "echo 'Checking for agent updates...' && /agent:agent-manager check-and-update-agents" } ] } -EOF +EOH +) + + # Use Python to merge JSON preserving existing settings + python3 << PYTHON_SCRIPT +import json +import sys + +try: + # Read existing settings + with open('$settings_file', 'r') as f: + settings = json.load(f) + + # Ensure hooks section exists + if 'hooks' not in settings: + settings['hooks'] = {} + + # Ensure SessionStart section exists + if 'SessionStart' not in settings['hooks']: + settings['hooks']['SessionStart'] = [] + + # Create agent-manager hook + agent_manager_hook = $agent_manager_hook + + # Check if agent-manager hook already exists and remove it + settings['hooks']['SessionStart'] = [ + hook for hook in settings['hooks']['SessionStart'] + if not (isinstance(hook.get('hooks'), list) and + any('agent-manager check-and-update-agents' in h.get('command', '') + for h in hook.get('hooks', []))) + ] + + # Add the new agent-manager hook + settings['hooks']['SessionStart'].append(agent_manager_hook) + + # Write updated settings + with open('$settings_file', 'w') as f: + json.dump(settings, f, indent=2) + + print("✅ Successfully updated settings.json with agent-manager hooks") + +except Exception as e: + print(f"❌ Error updating settings.json: {e}") + sys.exit(1) +PYTHON_SCRIPT + + local python_exit_code=$? + + if [ $python_exit_code -ne 0 ]; then + echo "❌ Failed to update settings.json with Python" + + # Fallback: restore backup if it exists + if [ -f "$backup_file" ]; then + echo "🔄 Restoring backup..." + cp "$backup_file" "$settings_file" + fi + + return 1 + fi + + # Validate the final JSON + if ! python3 -m json.tool "$settings_file" >/dev/null 2>&1; then + echo "❌ Generated invalid JSON, restoring backup..." + if [ -f "$backup_file" ]; then + cp "$backup_file" "$settings_file" + fi + return 1 + fi - echo "✅ Startup hooks configured" + echo "✅ Startup hooks configured in $settings_file" + echo "💡 Backup created at: $backup_file" + + # Show the hooks section for verification + echo "📋 Current SessionStart hooks:" + python3 -c " +import json +try: + with open('$settings_file', 'r') as f: + settings = json.load(f) + hooks = settings.get('hooks', {}).get('SessionStart', []) + if hooks: + for i, hook in enumerate(hooks): + print(f' {i+1}. {hook}') + else: + print(' No SessionStart hooks found') +except Exception as e: + print(f' Error reading hooks: {e}') +" } ``` diff --git a/.claude/settings.json b/.claude/settings.json index 4d1c3ed8..527cb80e 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,8 @@ { "permissions": { + "additionalDirectories": [ + "/tmp" + ], "allow": [ "Bash(awk:*)", "Bash(cat:*)", @@ -86,5 +89,23 @@ "WebFetch(domain:github.com)" ], "deny": [] + }, + "hooks": { + "SessionStart": [ + { + "matchers": { + "sessionType": [ + "startup", + "resume" + ] + }, + "hooks": [ + { + "type": "command", + "command": "echo 'Checking for agent updates...' && /agent:agent-manager check-and-update-agents" + } + ] + } + ] } } \ No newline at end of file diff --git a/.claude/settings.json.backup.1754053101 b/.claude/settings.json.backup.1754053101 new file mode 100644 index 00000000..9f72458c --- /dev/null +++ b/.claude/settings.json.backup.1754053101 @@ -0,0 +1,91 @@ +{ + "permissions": { + "additionalDirectories": ["/tmp"], + "allow": [ + "Bash(awk:*)", + "Bash(cat:*)", + "Bash(chmod:*)", + "Bash(cp:*)", + "Bash(curl:*)", + "Bash(diff:*)", + "Bash(echo:*)", + "Bash(find:*)", + "Bash(gh api:*)", + "Bash(gh issue create:*)", + "Bash(gh issue edit:*)", + "Bash(gh issue list:*)", + "Bash(gh issue status:*)", + "Bash(gh issue view:*)", + "Bash(gh pr checkout:*)", + "Bash(gh pr checks:*)", + "Bash(gh pr close:*)", + "Bash(gh pr comment:*)", + "Bash(gh pr create:*)", + "Bash(gh pr diff:*)", + "Bash(gh pr edit:*)", + "Bash(gh pr list:*)", + "Bash(gh pr merge:*)", + "Bash(gh pr review:*)", + "Bash(gh pr view:*)", + "Bash(gh run list:*)", + "Bash(gh run view:*)", + "Bash(gh run watch:*)", + "Bash(gh workflow run:*)", + "Bash(git add:*)", + "Bash(git branch:*)", + "Bash(git checkout:*)", + "Bash(git cherry-pick:*)", + "Bash(git commit:*)", + "Bash(git config:*)", + "Bash(git diff:*)", + "Bash(git fetch:*)", + "Bash(git log:*)", + "Bash(git ls-tree:*)", + "Bash(git merge:*)", + "Bash(git mv:*)", + "Bash(git pull:*)", + "Bash(git push:*)", + "Bash(git rebase:*)", + "Bash(git remote remove:*)", + "Bash(git reset:*)", + "Bash(git restore:*)", + "Bash(git revert:*)", + "Bash(git rm:*)", + "Bash(git status:*)", + "Bash(grep:*)", + "Bash(head:*)", + "Bash(ls:*)", + "Bash(mkdir:*)", + "Bash(mv:*)", + "Bash(node:*)", + "Bash(npm:*)", + "Bash(npx:*)", + "Bash(patch:*)", + "Bash(pip install:*)", + "Bash(pip3 install:*)", + "Bash(pipenv:*)", + "Bash(poetry install:*)", + "Bash(poetry lock:*)", + "Bash(poetry run pytest:*)", + "Bash(poetry run python3:*)", + "Bash(poetry:*)", + "Bash(pytest:*)", + "Bash(python3:*)", + "Bash(python:*)", + "Bash(sed:*)", + "Bash(sort:*)", + "Bash(tail:*)", + "Bash(tar:*)", + "Bash(touch:*)", + "Bash(uniq:*)", + "Bash(unset:*)", + "Bash(unzip:*)", + "Bash(wget:*)", + "Bash(yarn:*)", + "Bash(zip:*)", + "WebFetch(domain:docs.anthropic.com)", + "WebFetch(domain:github.com)" + ], + "deny": [] + } +} \ No newline at end of file diff --git a/.github/Memory.md b/.github/Memory.md index 999366d3..cfd09a64 100644 --- a/.github/Memory.md +++ b/.github/Memory.md @@ -1,5 +1,5 @@ # AI Assistant Memory -Last Updated: 2025-08-01T14:00:00Z +Last Updated: 2025-08-01T20:30:00Z ## Current Goals - ✅ Improve test coverage for Blarify codebase to >80% (ACHIEVED 3x improvement: 20.76% → 63.76%) @@ -43,7 +43,28 @@ Last Updated: 2025-08-01T14:00:00Z - [ ] Improve tests for concept_extractor.py (currently 53.33%) - [ ] Improve tests for documentation_graph_generator.py (currently 62.50%) -## Recent Accomplishments +## Recent Accomplishments + +### Agent Manager Gadugi Sync Update (2025-08-01 20:30) +- **Successfully updated agent-manager from gadugi repository** - Agent Manager PR #39 has been merged with significant improvements +- **Enhanced agent-manager features** include: + - Improved startup hooks with robust JSON merging + - Better error handling and state persistence + - Enhanced Memory.md integration with atomic updates + - Comprehensive session integration system +- **Updated all agents** from gadugi with latest versions and enhancements +- **Registry metadata updated** to reflect latest sync timestamp (2025-08-01T20:30:00Z) +- **All workflow agents now at latest versions** ensuring optimal compatibility and features +- **Agent ecosystem fully synchronized** with centralized gadugi repository + +### Agent Manager Gadugi Sync Completed (2025-08-01 16:30) +- **Successfully synced all agents from gadugi repository** +- **Cloned gadugi repository** to `.claude/agent-manager/cache/repositories/gadugi/` +- **Updated agent registry** with 8 agents from gadugi (workflow-master, orchestrator-agent, code-reviewer, code-review-response, prompt-writer, task-analyzer, worktree-manager, execution-monitor) +- **Installed all gadugi agents** to local `.claude/agents/` directory +- **Preserved local agent-manager** to maintain synchronization capabilities +- **Agent ecosystem now complete** with all workflow, quality, and productivity agents available +- **Registry tracks versions and sources** for proper dependency management ### Agent Manager PR #39 Code Review Response (2025-08-01 16:00) - **Processed positive review feedback** for comprehensive Agent Manager implementation diff --git a/.gitignore b/.gitignore index 306f96f4..cba6377c 100644 --- a/.gitignore +++ b/.gitignore @@ -29,3 +29,7 @@ easy/ # Important workflow checkpoints (committed for recovery) !.github/workflow-checkpoints/ +# Agent Manager cache +.claude/agent-manager/cache/repositories/ +.claude/agent-manager/cache/downloaded/ + diff --git a/AGENT_HIERARCHY.md b/AGENT_HIERARCHY.md deleted file mode 100644 index c9a1e4bc..00000000 --- a/AGENT_HIERARCHY.md +++ /dev/null @@ -1,102 +0,0 @@ -# Agent Hierarchy for Development Workflows - -## Overview - -This document explains the proper agent hierarchy for executing development workflows in the Blarify project. - -## Agent Hierarchy Diagram - -``` -┌─────────────────────────┐ -│ OrchestratorAgent │ ← Start here for multiple tasks -│ (Parallel Coordinator) │ -└───────────┬─────────────┘ - │ - ├─── Invokes → TaskAnalyzer (dependency analysis) - ├─── Invokes → WorktreeManager (git isolation) - ├─── Invokes → ExecutionMonitor (parallel tracking) - │ - └─── Spawns multiple ↓ - -┌─────────────────────────┐ -│ WorkflowMaster │ ← Or start here for single tasks -│ (Workflow Executor) │ -└───────────┬─────────────┘ - │ - ├─── Phase 1: Setup - ├─── Phase 2: Issue Creation - ├─── Phase 3: Branch Management - ├─── Phase 4: Research - ├─── Phase 5: Implementation - ├─── Phase 6: Testing - ├─── Phase 7: Documentation - ├─── Phase 8: PR Creation - │ - └─── Phase 9: Invokes → CodeReviewer - │ - └─── May invoke → CodeReviewResponse -``` - -## When to Use Each Agent - -### Use OrchestratorAgent when: -- You have multiple independent tasks to execute -- Tasks can be parallelized (no file conflicts) -- You want 3-5x speed improvement -- Example: Writing tests for 5 different modules - -### Use WorkflowMaster when: -- You have a single complex task -- The task requires sequential phases -- No parallelization opportunity -- Example: Implementing a single new feature - -### Never manually execute: -- ❌ `gh issue create` -- ❌ `git checkout -b` -- ❌ `gh pr create` -- ❌ Individual workflow phases - -## Correct Usage Examples - -### Multiple Tasks (Use OrchestratorAgent) -``` -/agent:orchestrator-agent - -Execute these specific prompts in parallel: -- test-definition-node.md -- test-relationship-creator.md -- fix-documentation-linker.md -``` - -### Single Task (Use WorkflowMaster) -``` -/agent:workflow-master - -Task: Execute workflow for /prompts/implement-new-feature.md -``` - -### Quick Fix (Manual allowed) -``` -# For a typo fix or single-line change -git add README.md -git commit -m "fix: typo in README" -git push -``` - -## Benefits of Using Agents - -1. **Automation**: All phases execute automatically -2. **Consistency**: Same workflow every time -3. **State Tracking**: Progress saved and resumable -4. **Code Reviews**: Phase 9 never skipped -5. **Parallelization**: 3-5x faster for multiple tasks -6. **Error Handling**: Graceful recovery from failures - -## Common Mistakes - -1. **Wrong**: Manually creating issues, branches, and PRs -2. **Wrong**: Using WorkflowMaster for multiple independent tasks -3. **Wrong**: Skipping OrchestratorAgent when parallelization is possible -4. **Right**: Let agents handle the entire workflow -5. **Right**: Use OrchestratorAgent first, it will spawn WorkflowMasters \ No newline at end of file diff --git a/claude-generic-instructions.md b/claude-generic-instructions.md deleted file mode 100644 index 727da859..00000000 --- a/claude-generic-instructions.md +++ /dev/null @@ -1,258 +0,0 @@ -# Claude Code Generic Instructions - -## Required Context - -**CRITICAL - MUST DO AT START OF EVERY SESSION**: -1. **READ** `.github/Memory.md` for current context -2. **UPDATE** `.github/Memory.md` after completing any significant task -3. **COMMIT** Memory.md changes regularly to preserve context - -**Memory.md is your persistent brain across sessions - USE IT!** - -**WHEN WORKING ON CLAUDE AGENTS OR INSTRUCTIONS**: -- **READ** https://docs.anthropic.com/en/docs/claude-code/memory for proper import syntax -- **READ** https://docs.anthropic.com/en/docs/claude-code/sub-agents for agent patterns -- **USE** `@` syntax for imports, not manual includes - -## Using GitHub CLI for Issue and PR Management - -**IMPORTANT**: When creating issues, PRs, or comments using `gh` CLI, always include a note that the action was performed by an AI agent on behalf of the repository owner. Add "*Note: This [issue/PR/comment] was created by an AI agent on behalf of the repository owner.*" to the body. - -### Issues -```bash -# Create a new issue -gh issue create --title "Issue title" --body "Issue description" - -# List open issues -gh issue list - -# View issue details -gh issue view - -# Update issue -gh issue edit - -# Close issue -gh issue close -``` - -### Pull Requests -```bash -# Create a PR -gh pr create --base main --head feature-branch --title "PR title" --body "PR description" - -# List PRs -gh pr list - -# View PR details -gh pr view - -# Check PR status -gh pr checks - -# Merge PR -gh pr merge -``` - -### Workflows -```bash -# List workflow runs -gh workflow run list - -# View workflow run details -gh run view - -# Watch workflow run in real-time -gh run watch -``` - -## Best Practices for AI-Enhanced Development - -### 1. Clear Documentation -- Maintain documentation files with up-to-date instructions and context -- Document all major decisions and architectural choices -- Include examples and edge cases in documentation - -### 2. Structured Task Management -- Break down complex features into smaller, manageable tasks -- Use GitHub issues to track all work items -- Create detailed implementation plans before coding - -### 3. Iterative Improvement -- Start with a working prototype and iterate -- Use test-driven development when possible -- Course-correct early based on test results - -### 4. Context Management -- Use `/clear` command to reset context when switching tasks -- Keep focused on one feature at a time -- Reference specific files when discussing code changes - -### 5. Subagents -- Subagents are documented at https://docs.anthropic.com/en/docs/claude-code/sub-agents -- Utilize specialized agents for repetitive tasks -- Create new agents for common patterns or issues -- Document agent capabilities and usage patterns -- Subagents can be used to pass scoped or limited context to specialized agents for focused tasks - -## Memory Storage Instructions - -### Regular Memory Updates -You should regularly update the memory file at `.github/Memory.md` with: -- Current date and time -- Consolidated summary of completed tasks -- Current todo list with priorities -- Important context and decisions made -- Any blockers or issues encountered - -### Memory File Format -```markdown -# AI Assistant Memory -Last Updated: [ISO 8601 timestamp] - -## Current Goals -[List of active goals] - -## Todo List -[Current tasks with status] - -## Recent Accomplishments -[What was completed recently] - -## Important Context -[Key decisions, patterns, or information to remember] - -## Reflections -[Insights and improvements] -``` - -### When to Update Memory -**MANDATORY UPDATE TRIGGERS:** -- ✅ After completing ANY task from todo list -- ✅ When creating or merging a PR -- ✅ When discovering important technical details -- ✅ After fixing any bugs -- ✅ Every 30 minutes during long sessions -- ✅ BEFORE ending any conversation - -**Set a mental reminder: "Did I update Memory.md in the last 30 minutes?"** - -### Memory Pruning -Keep the memory file concise by: -- Removing completed tasks older than 7 days -- Consolidating similar context items -- Archiving detailed reflections after incorporating improvements -- Keeping only the most recent 5-10 accomplishments - -## Task Completion Reflection - -After completing each task, reflect on: - -### What Worked Well -- Successful approaches and techniques -- Effective tool usage -- Good architectural decisions - -### Areas for Improvement -- What could have been done more efficiently -- Any confusion or missteps -- Missing documentation or context - -### User Feedback Integration -If the user expressed frustration or provided feedback: -- Document the specific issue -- Propose improvements to documentation -- Update relevant sections to prevent recurrence -- Add new best practices based on learnings - -### Continuous Improvement -- Update documentation with new patterns discovered -- Add commonly used commands -- Document project-specific conventions -- Include solutions to recurring problems - -## Git Workflow Best Practices - -### General Git Workflow -1. **Always fetch latest before creating branches**: `git fetch origin && git reset --hard origin/main` -2. Create feature branches from main: `feature--description` -3. Make atomic commits with clear messages -4. Always create PRs for code review -5. Ensure CI/CD passes before merging - -### Git Safety Instructions (CRITICAL) -**ALWAYS follow these steps to prevent accidental file deletion:** - -1. **Check git status before ANY branch operations**: - ```bash - git status # ALWAYS run this first - ``` - -2. **Preserve uncommitted files when switching branches**: - ```bash - # If uncommitted files exist: - git stash push -m "Preserving work before branch switch" - git checkout -b new-branch - git stash pop - ``` - -3. **Verify repository context**: - ```bash - git remote -v # Ensure working with correct repository - ``` - -4. **Before creating new branches**: - - Run `git status` to check for uncommitted changes - - Commit or stash any important files - - Verify the base branch contains all expected files - -5. **If files go missing**: - ```bash - # Find when files existed - git log --all --full-history -- - # Restore from specific commit - git checkout -- - ``` - -## Using and Creating Reusable Agents - -### CRITICAL: Use Agents for Workflows - -**If a task involves creating issues, branches, code changes, and PRs, you MUST use an orchestration agent (like WorkflowMaster) rather than executing steps manually.** - -### Using Agents -To invoke a reusable agent, use the following pattern: -``` -/agent:[agent-name] - -Context: [Provide specific context about the problem] -Requirements: [What needs to be achieved] -``` - -### Common Workflow Agents (in hierarchical order) -- **orchestrator-agent**: Top-level coordinator for parallel task execution (use FIRST for multiple tasks) -- **workflow-master**: Orchestrates individual development workflows from issue to PR -- **code-reviewer**: Reviews pull requests (invoked by WorkflowMaster in Phase 9) -- **prompt-writer**: Creates structured prompts -- **task-analyzer**: Analyzes dependencies (invoked by OrchestratorAgent) -- **worktree-manager**: Manages git worktrees (invoked by OrchestratorAgent) -- **execution-monitor**: Monitors parallel execution (invoked by OrchestratorAgent) - -### Creating New Agents -New specialized agents can be added to `.github/agents/` or `.claude/agents/` following the existing template structure. Each agent should have: -- Clear specialization and purpose -- Documented approaches and methods -- Success metrics and validation criteria -- Required tools listed in frontmatter - -## Git Guidelines - -### Git Workflow Rules -- **Never commit directly to main** -- **Use meaningful commit messages** -- **Include co-authorship for AI-generated commits**: - ``` - 🤖 Generated with [Claude Code](https://claude.ai/code) - - Co-Authored-By: Claude - ``` \ No newline at end of file diff --git a/claude.md b/claude.md index d0d60dfb..27619599 100644 --- a/claude.md +++ b/claude.md @@ -58,8 +58,29 @@ This file combines generic Claude Code best practices with project-specific inst ## Generic Claude Code Instructions -@claude-generic-instructions.md +See gadugi repository for generic Claude Code best practices and instructions. ## Project-Specific Instructions @claude-project-specific.md + +## Agent Management + +Most agents are now managed via the gadugi repository. The agent-manager itself must remain local to manage synchronization. + +To update agents from gadugi: +1. Run `/agent:agent-manager check-and-update-agents` +2. Or manually sync: `/agent:agent-manager sync gadugi` + +Available agents from gadugi: +- workflow-master +- orchestrator-agent +- code-reviewer +- code-review-response +- prompt-writer +- task-analyzer +- worktree-manager +- execution-monitor + +Local agents: +- agent-manager (required for synchronization) diff --git a/prompts/fix-blarify-tree-sitter-ruby-error.md b/prompts/fix-blarify-tree-sitter-ruby-error.md new file mode 100644 index 00000000..75a71de1 --- /dev/null +++ b/prompts/fix-blarify-tree-sitter-ruby-error.md @@ -0,0 +1,43 @@ +# Fix Blarify tree_sitter_ruby ModuleNotFoundError + +## Objective +Fix the ModuleNotFoundError for tree_sitter_ruby that prevents Blarify from analyzing any codebase, even non-Ruby projects. + +## Context +- Issue #45 tracks this bug +- Blarify is failing on startup due to unconditional import of Ruby language definitions +- The error occurs in the VS Code extension's bundled Blarify installation +- This blocks all code analysis functionality, not just Ruby analysis + +## Error Details +``` +ModuleNotFoundError: No module named 'tree_sitter_ruby' +``` + +The error trace shows that `ruby_definitions.py` is imported unconditionally in the languages `__init__.py` file, causing failure even for non-Ruby projects. + +## Requirements +1. Make language-specific imports conditional or lazy-loaded +2. Ensure Blarify can analyze codebases without requiring all language parsers installed +3. Maintain backward compatibility +4. Add appropriate error handling for missing language modules +5. Test the fix with both Ruby and non-Ruby projects + +## Technical Approach +1. Modify `blarify/code_hierarchy/languages/__init__.py` to use conditional imports +2. Implement lazy loading for language-specific parsers +3. Add try-except blocks around language imports with informative warnings +4. Consider using importlib for dynamic imports based on detected languages +5. Ensure GoDefinitions and other language parsers are similarly handled + +## Testing Requirements +1. Verify Blarify starts successfully without tree_sitter_ruby installed +2. Test analysis on Python, JavaScript, and Go projects +3. Ensure Ruby analysis works when tree_sitter_ruby IS installed +4. Verify error messages are helpful when language support is missing + +## Success Criteria +- Blarify analyzes non-Ruby codebases without errors +- Missing language parsers generate warnings, not failures +- All existing functionality remains intact +- Code is clean, maintainable, and follows project conventions \ No newline at end of file diff --git a/prompts/migrate-to-gadugi-repository.md b/prompts/migrate-to-gadugi-repository.md new file mode 100644 index 00000000..22427186 --- /dev/null +++ b/prompts/migrate-to-gadugi-repository.md @@ -0,0 +1,636 @@ +# Migrate to Gadugi Repository - Agent Community Ecosystem + +## Title and Overview + +This prompt guides the creation of "gadugi" - a centralized repository for reusable Claude Code agents and instructions, implementing the Cherokee concept of communal work and collective wisdom. Gadugi will serve as the foundation for a distributed ecosystem of AI-powered development tools that can be shared across projects. + +The migration will establish gadugi as the canonical source for generic agents while preserving project-specific customizations in individual repositories. This creates a sustainable model for agent development, maintenance, and distribution across the Claude Code community. + +## Problem Statement + +### Current Limitations +- **Fragmented Agent Ecosystem**: Each project maintains its own copies of common agents (workflow-master, code-reviewer, prompt-writer), leading to duplication and version drift +- **No Centralized Updates**: Bug fixes and improvements to agents require manual propagation across projects +- **Discovery Challenges**: Developers cannot easily find and leverage existing agents created by the community +- **Version Management**: No systematic way to track agent versions, updates, or rollback capabilities +- **Maintenance Overhead**: Each project maintainer must independently update and maintain common agents + +### Cherokee Concept of Gadugi +Gadugi (pronounced gah-DOO-gee) is a Cherokee concept representing: +- **Communal Work**: Community members coming together to accomplish tasks that benefit everyone +- **Collective Wisdom**: Sharing knowledge and expertise for the greater good +- **Mutual Support**: Helping others with the understanding that the community thrives together +- **Shared Resources**: Pooling tools and knowledge for more efficient outcomes + +This philosophy aligns perfectly with a shared agent repository where the community contributes, maintains, and benefits from collective AI-powered development tools. + +### Impact on Development Workflow +- Faster project setup with proven, battle-tested agents +- Consistent quality and behavior across projects +- Reduced maintenance burden for individual developers +- Community-driven improvements and innovations +- Scalable model for agent ecosystem growth + +## Feature Requirements + +### 1. Repository Creation and Structure +- **GitHub Repository**: Create "gadugi" repository with comprehensive README explaining Cherokee concept +- **MIT License**: Use permissive licensing to encourage adoption and contribution +- **Directory Structure**: Organized layout for agents, instructions, templates, and examples +- **Comprehensive Documentation**: Usage guides, contribution guidelines, integration patterns + +### 2. Agent Migration Strategy +- **Generic Agent Identification**: Migrate universally applicable agents to gadugi +- **Project-Specific Preservation**: Keep project-specific agents in original repositories +- **Version Management**: Implement semantic versioning for agents and instructions +- **Dependency Mapping**: Document agent dependencies and compatibility requirements + +### 3. Integration Architecture +- **Agent Manager Integration**: Leverage existing agent-manager for repository synchronization +- **Import Pattern**: Use Claude Code @ syntax for seamless integration +- **Auto-Update Mechanism**: Optional automatic updates with configurable policies +- **Fallback Support**: Graceful degradation when gadugi is unavailable + +### 4. Community Ecosystem Features +- **Contribution Workflow**: Standard process for community contributions +- **Quality Assurance**: Testing and validation framework for submitted agents +- **Documentation Standards**: Consistent format for agent documentation +- **Example Integration**: Templates showing how to integrate gadugi with projects + +## Technical Analysis + +### Current Implementation Review + +The current project contains several mature, reusable agents: + +**Generic Agents (Ready for Migration)**: +- `workflow-master.md`: Complete workflow orchestration (1000+ lines) +- `orchestrator-agent.md`: Parallel execution coordination (800+ lines) +- `code-reviewer.md`: Comprehensive code review process (600+ lines) +- `code-review-response.md`: Systematic feedback processing (500+ lines) +- `prompt-writer.md`: Structured prompt creation (700+ lines) +- `agent-manager.md`: External repository management (1000+ lines) + +**Supporting Files**: +- `claude-generic-instructions.md`: Universal Claude Code best practices +- Workflow templates and usage documentation + +**Project-Specific (Remain in Project)**: +- `claude-project-specific.md`: Blarify-specific context and guidelines +- Test-specific agents and project-specific customizations + +### Proposed Repository Structure + +``` +gadugi/ +├── README.md # Cherokee concept, usage, community guidelines +├── LICENSE # MIT license +├── CONTRIBUTING.md # Contribution guidelines and standards +├── CHANGELOG.md # Version history and updates +├── instructions/ +│ ├── claude-generic-instructions.md # Universal Claude Code best practices +│ ├── claude-memory-management.md # Memory.md patterns and guidelines +│ └── templates/ +│ ├── project-integration.md # Template for integrating gadugi +│ └── agent-template.md # Standard agent creation template +├── agents/ +│ ├── workflow-master.md # Complete workflow orchestration +│ ├── orchestrator-agent.md # Parallel execution coordination +│ ├── code-reviewer.md # Comprehensive code review +│ ├── code-review-response.md # Systematic feedback processing +│ ├── prompt-writer.md # Structured prompt creation +│ ├── agent-manager.md # External repository management +│ └── specialized/ +│ ├── task-analyzer.md # Task dependency analysis +│ ├── worktree-manager.md # Git worktree management +│ └── execution-monitor.md # Parallel execution monitoring +├── prompts/ +│ └── templates/ +│ ├── feature-development.md # Standard feature development template +│ ├── bug-fix.md # Bug fix workflow template +│ └── performance-optimization.md # Performance improvement template +├── examples/ +│ ├── integration-examples.md # How to integrate gadugi +│ ├── custom-agent-development.md # Creating project-specific agents +│ └── migration-guide.md # Migrating from standalone agents +├── tests/ +│ ├── agent-validation.md # Agent testing guidelines +│ └── integration-tests.md # Community testing standards +└── docs/ + ├── architecture.md # Repository design and philosophy + ├── versioning.md # Version management strategy + └── community-governance.md # Community guidelines and governance +``` + +### Integration Architecture + +**Agent Manager Configuration**: +```yaml +# .claude/agent-manager/config.yaml +repositories: + gadugi: + url: "https://github.com/community/gadugi.git" + type: "github" + branch: "main" + auto_update: true + update_frequency: "weekly" + agents: + - workflow-master + - orchestrator-agent + - code-reviewer + - code-review-response + - prompt-writer +``` + +**Project Integration Pattern**: +```markdown +# CLAUDE.md +@https://github.com/community/gadugi/instructions/claude-generic-instructions.md +@claude-project-specific.md +``` + +### Dependency Analysis + +**Agent Dependencies**: +- All agents depend on `claude-generic-instructions.md` +- `orchestrator-agent` depends on `workflow-master`, `task-analyzer`, `worktree-manager` +- `workflow-master` depends on `code-reviewer` +- `code-reviewer` integrates with `code-review-response` + +**Tool Requirements**: +- Read, Write, Edit, Bash, Grep, LS, TodoWrite (universal) +- WebSearch, WebFetch (for agent-manager and documentation agents) +- GitHub CLI integration for all workflow agents + +## Implementation Plan + +### Phase 1: Repository Foundation (Days 1-2) +**Deliverables**: +- Create gadugi GitHub repository with comprehensive README +- Implement directory structure and initial documentation +- Set up MIT license and contribution guidelines +- Create templates for agent integration and development + +**Success Criteria**: +- Repository accessible and well-documented +- Clear explanation of Cherokee gadugi concept +- Contribution workflow defined +- Integration examples provided + +### Phase 2: Agent Migration (Days 3-4) +**Deliverables**: +- Migrate generic agents from current project to gadugi +- Update agent documentation for generic use +- Remove project-specific references from migrated agents +- Create agent compatibility matrix + +**Success Criteria**: +- All generic agents successfully migrated +- Agent documentation updated for universal applicability +- No project-specific references remain in migrated agents +- Clear versioning scheme established + +### Phase 3: Integration System (Days 5-6) +**Deliverables**: +- Configure agent-manager to use gadugi repository +- Update current project to import from gadugi +- Test integration and fallback mechanisms +- Document integration patterns for other projects + +**Success Criteria**: +- Agent-manager successfully syncs from gadugi +- Current project imports work correctly +- Fallback to local agents when gadugi unavailable +- Integration documented for community use + +### Phase 4: Community Ecosystem (Days 7-8) +**Deliverables**: +- Create contribution workflow and quality standards +- Develop agent testing and validation framework +- Write community governance guidelines +- Prepare launch announcement and documentation + +**Success Criteria**: +- Clear contribution process established +- Quality assurance mechanisms in place +- Community governance framework defined +- Ready for public announcement and adoption + +### Risk Assessment and Mitigation + +**Technical Risks**: +- **Agent Import Failures**: Implement robust fallback to local agents +- **Version Conflicts**: Use semantic versioning and compatibility matrices +- **Network Dependencies**: Cache agents locally with agent-manager + +**Community Risks**: +- **Low Adoption**: Provide clear value proposition and migration assistance +- **Quality Control**: Establish review process for community contributions +- **Maintenance Burden**: Distribute maintenance across community contributors + +**Mitigation Strategies**: +- Comprehensive testing before migration +- Gradual rollout with current project as test case +- Community engagement and clear communication +- Automated testing and validation systems + +## Testing Requirements + +### Agent Validation Testing +- **Functional Tests**: Verify each agent works in isolation +- **Integration Tests**: Test agent interactions and dependencies +- **Performance Tests**: Ensure agents perform efficiently at scale +- **Compatibility Tests**: Verify agents work across different project types + +### Migration Testing +- **Import Validation**: Test @ syntax imports work correctly +- **Agent Manager Integration**: Verify repository synchronization +- **Fallback Testing**: Ensure graceful degradation when gadugi unavailable +- **Version Management**: Test update and rollback mechanisms + +### Community Testing Framework +- **Contribution Validation**: Automated testing for community submissions +- **Documentation Testing**: Verify examples and integration guides work +- **Cross-Project Testing**: Validate agents work across different project types +- **Security Testing**: Ensure no malicious code in community contributions + +## Success Criteria + +### Quantitative Metrics +- **Migration Completeness**: 100% of identified generic agents migrated successfully +- **Integration Success**: Current project imports and uses gadugi agents without issues +- **Community Adoption**: At least 5 projects integrate gadugi within 30 days of launch +- **Agent Coverage**: 90%+ test coverage for all migrated agents + +### Qualitative Metrics +- **Developer Experience**: Seamless integration with existing workflows +- **Documentation Quality**: Clear, comprehensive documentation for all components +- **Community Engagement**: Active contributions and positive feedback from community +- **Ecosystem Health**: Sustainable model for ongoing development and maintenance + +### Performance Benchmarks +- **Sync Performance**: Agent-manager syncs gadugi repository in <10 seconds +- **Import Speed**: Agent imports add <2 seconds to Claude Code startup +- **Update Efficiency**: Automatic updates complete in background without disruption +- **Fallback Response**: Local fallback activates in <1 second when gadugi unavailable + +## Implementation Steps + +### Step 1: Create GitHub Repository +```bash +# Create new repository on GitHub +gh repo create community/gadugi --public --description "Cherokee concept of communal work - shared Claude Code agents and instructions" + +# Clone and set up initial structure +git clone https://github.com/community/gadugi.git +cd gadugi + +# Create directory structure +mkdir -p {instructions,agents/specialized,prompts/templates,examples,tests,docs} + +# Create initial README with Cherokee concept explanation +``` + +### Step 2: Migrate Generic Agents +```bash +# Copy agents from current project +cp /path/to/current/.claude/agents/workflow-master.md agents/ +cp /path/to/current/.claude/agents/orchestrator-agent.md agents/ +cp /path/to/current/.claude/agents/code-reviewer.md agents/ +cp /path/to/current/.claude/agents/code-review-response.md agents/ +cp /path/to/current/.claude/agents/prompt-writer.md agents/ +cp /path/to/current/.claude/agents/agent-manager.md agents/ + +# Copy generic instructions +cp /path/to/current/claude-generic-instructions.md instructions/ + +# Remove project-specific references from agents +# Update documentation for generic use +``` + +### Step 3: Configure Integration +```bash +# Update agent-manager configuration +cat >> .claude/agent-manager/config.yaml << EOF +repositories: + gadugi: + url: "https://github.com/community/gadugi.git" + type: "github" + branch: "main" + auto_update: true + agents: + - workflow-master + - orchestrator-agent + - code-reviewer + - code-review-response + - prompt-writer + - agent-manager +EOF + +# Test agent manager sync +/agent:agent-manager + +Repository: Add gadugi repository +URL: https://github.com/community/gadugi.git +``` + +### Step 4: Update Current Project +```bash +# Modify CLAUDE.md to import from gadugi +sed -i 's/@claude-generic-instructions.md/@https:\/\/github.com\/community\/gadugi\/instructions\/claude-generic-instructions.md/' CLAUDE.md + +# Remove migrated agents from local .claude/agents/ +mv .claude/agents/workflow-master.md .claude/agents/workflow-master.md.backup +mv .claude/agents/orchestrator-agent.md .claude/agents/orchestrator-agent.md.backup +# ... repeat for other migrated agents + +# Test integration +claude-code --version +/agent:workflow-master +# Verify agent loads from gadugi +``` + +### Step 5: Create Community Documentation +```bash +# Create comprehensive README +cat > README.md << 'EOF' +# Gadugi - Community Agent Ecosystem + +Gadugi (gah-DOO-gee) embodies the Cherokee concept of communal work and collective wisdom, where community members come together to accomplish tasks that benefit everyone. This repository serves as the foundation for a distributed ecosystem of Claude Code agents and instructions. + +## Philosophy + +Gadugi represents: +- **Communal Work**: Sharing development tools for collective benefit +- **Collective Wisdom**: Accumulating community knowledge in reusable agents +- **Mutual Support**: Contributing to tools that help the entire community +- **Shared Resources**: Pooling expertise for more efficient development + +## Quick Start + +1. Configure agent-manager to use gadugi: + ```bash + /agent:agent-manager + Repository: Add gadugi repository + URL: https://github.com/community/gadugi.git + ``` + +2. Import generic instructions in your CLAUDE.md: + ```markdown + @https://github.com/community/gadugi/instructions/claude-generic-instructions.md + @your-project-specific-instructions.md + ``` + +3. Use community agents: + ```bash + /agent:workflow-master + /agent:orchestrator-agent + /agent:code-reviewer + ``` + +## Available Agents + +- **workflow-master**: Complete development workflow orchestration +- **orchestrator-agent**: Parallel execution coordination +- **code-reviewer**: Comprehensive code review process +- **code-review-response**: Systematic feedback processing +- **prompt-writer**: Structured prompt creation +- **agent-manager**: Repository and version management + +## Contributing + +We welcome contributions that embody the gadugi spirit! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. + +## License + +MIT License - fostering open collaboration and community growth +EOF + +# Create contribution guidelines +cat > CONTRIBUTING.md << 'EOF' +# Contributing to Gadugi + +Thank you for embodying the gadugi spirit of communal work and collective wisdom! + +## Contribution Types + +1. **Agent Development**: Create new agents for common development tasks +2. **Agent Improvements**: Enhance existing agents with new features or bug fixes +3. **Documentation**: Improve guides, examples, and explanations +4. **Testing**: Add validation tests and quality assurance measures + +## Submission Process + +1. Fork gadugi repository +2. Create feature branch: `git checkout -b feature/agent-name` +3. Follow agent template structure in `instructions/templates/` +4. Add comprehensive documentation and examples +5. Include tests in `tests/` directory +6. Submit pull request with detailed description + +## Quality Standards + +- Clear, actionable agent descriptions +- Comprehensive error handling +- Extensive documentation with examples +- Test coverage for core functionality +- Community benefit over specific project needs + +## Community Governance + +Decisions are made through consensus, honoring diverse perspectives while maintaining quality standards. Core maintainers facilitate discussion and ensure contributions align with gadugi principles. +EOF +``` + +### Step 6: Version Management System +```bash +# Create versioning documentation +cat > docs/versioning.md << 'EOF' +# Gadugi Version Management + +## Semantic Versioning + +Agents follow semantic versioning (MAJOR.MINOR.PATCH): +- **MAJOR**: Breaking changes requiring user updates +- **MINOR**: New features, backward compatible +- **PATCH**: Bug fixes, backward compatible + +## Version Tags + +```bash +git tag -a v1.0.0 -m "Initial gadugi release with core agents" +git push origin v1.0.0 +``` + +## Compatibility Matrix + +| Agent Version | Claude Code | Dependencies | +|---------------|-------------|--------------| +| workflow-master v1.0 | >=2024.1 | code-reviewer v1.0+ | +| orchestrator-agent v1.0 | >=2024.1 | workflow-master v1.0+ | + +## Update Notifications + +Agent-manager automatically checks for updates weekly and notifies users of available improvements. +EOF +``` + +### Step 7: Testing and Validation +```bash +# Create agent validation tests +cat > tests/agent-validation.md << 'EOF' +# Agent Validation Testing + +## Test Categories + +1. **Syntax Validation**: Ensure proper YAML frontmatter and markdown structure +2. **Tool Requirements**: Verify all required tools are listed and available +3. **Documentation Quality**: Check for comprehensive descriptions and examples +4. **Integration Testing**: Validate agent interactions and dependencies + +## Automated Testing + +```bash +# Validate agent syntax +./scripts/validate-agents.sh + +# Test integration points +./scripts/test-integrations.sh + +# Check documentation completeness +./scripts/check-docs.sh +``` + +## Community Testing + +Before merging contributions: +1. Manual testing by core maintainers +2. Community review period (72 hours minimum) +3. Integration testing with sample projects +4. Performance impact assessment +EOF + +# Create validation script +cat > scripts/validate-agents.sh << 'EOF' +#!/bin/bash +set -e + +echo "Validating gadugi agents..." + +for agent in agents/*.md; do + echo "Validating $agent..." + + # Check YAML frontmatter + if ! head -n 10 "$agent" | grep -q "^---$"; then + echo "ERROR: $agent missing YAML frontmatter" + exit 1 + fi + + # Check required fields + if ! grep -q "^name:" "$agent"; then + echo "ERROR: $agent missing name field" + exit 1 + fi + + if ! grep -q "^description:" "$agent"; then + echo "ERROR: $agent missing description field" + exit 1 + fi + + echo "✅ $agent valid" +done + +echo "All agents validated successfully!" +EOF + +chmod +x scripts/validate-agents.sh +``` + +### Step 8: Launch and Community Engagement +```bash +# Create launch announcement +cat > ANNOUNCEMENT.md << 'EOF' +# Introducing Gadugi - Community Agent Ecosystem + +We're excited to announce gadugi, a shared repository embodying the Cherokee concept of communal work and collective wisdom for Claude Code agents and instructions. + +## What is Gadugi? + +Gadugi (gah-DOO-gee) represents the Cherokee tradition of community members coming together to accomplish tasks that benefit everyone. Our gadugi repository brings this philosophy to AI-powered development tools. + +## Benefits + +- **Faster Setup**: Proven agents ready for immediate use +- **Consistent Quality**: Battle-tested tools with community validation +- **Automatic Updates**: Stay current with latest improvements +- **Community Support**: Learn from and contribute to collective wisdom + +## Getting Started + +1. Add gadugi to your agent-manager configuration +2. Import generic instructions: `@https://github.com/community/gadugi/instructions/claude-generic-instructions.md` +3. Start using community agents: `/agent:workflow-master` + +## Community Contribution + +Join the gadugi community! Contribute agents, improvements, and documentation to help everyone build better software together. + +Repository: https://github.com/community/gadugi +Documentation: https://github.com/community/gadugi/docs +Contributing: https://github.com/community/gadugi/CONTRIBUTING.md + +Together, we embody the spirit of gadugi - collective wisdom for collective benefit. +EOF + +# Commit initial structure +git add . +git commit -m "Initial gadugi repository structure with Cherokee philosophy + +- Implement community agent ecosystem foundation +- Migrate core agents: workflow-master, orchestrator-agent, code-reviewer +- Establish contribution guidelines and quality standards +- Create comprehensive documentation and examples +- Enable agent-manager integration for automatic updates + +Embodies Cherokee gadugi concept of communal work and collective wisdom" + +git push origin main + +# Create initial release +git tag -a v1.0.0 -m "Gadugi v1.0.0 - Community Agent Ecosystem Launch + +Core agents included: +- workflow-master v1.0: Complete development workflow orchestration +- orchestrator-agent v1.0: Parallel execution coordination +- code-reviewer v1.0: Comprehensive code review process +- code-review-response v1.0: Systematic feedback processing +- prompt-writer v1.0: Structured prompt creation +- agent-manager v1.0: Repository and version management + +Ready for community adoption and contribution" + +git push origin v1.0.0 +``` + +## Final Integration and Testing + +### Update Current Project +1. **Modify CLAUDE.md**: Replace local imports with gadugi imports +2. **Configure Agent Manager**: Add gadugi repository to configuration +3. **Test Integration**: Verify all agents work correctly from gadugi +4. **Remove Local Copies**: Clean up migrated agents from local directories +5. **Document Changes**: Update project documentation to reference gadugi + +### Community Launch +1. **Announce on GitHub**: Create discussion thread about gadugi ecosystem +2. **Share with Community**: Reach out to other Claude Code users +3. **Gather Feedback**: Listen to community needs and suggestions +4. **Iterate and Improve**: Refine based on real-world usage + +### Long-term Sustainability +1. **Community Governance**: Establish maintainer rotation and decision processes +2. **Quality Assurance**: Implement automated testing and validation +3. **Performance Monitoring**: Track adoption metrics and performance impact +4. **Continuous Improvement**: Regular agent updates and new feature development + +This migration establishes gadugi as the foundation for a thriving community ecosystem of Claude Code agents, embodying the Cherokee values of collective wisdom and mutual support while providing practical benefits for all developers. \ No newline at end of file