Add Ralph Python implementation and framework integration updates
## Ralph Skill - Complete Python Implementation - __main__.py: Main entry point for Ralph autonomous agent - agent_capability_registry.py: Agent capability registry (FIXED syntax error) - dynamic_agent_selector.py: Dynamic agent selection logic - meta_agent_orchestrator.py: Meta-orchestration for multi-agent workflows - worker_agent.py: Worker agent implementation - ralph_agent_integration.py: Integration with Claude Code - superpowers_integration.py: Superpowers framework integration - observability_dashboard.html: Real-time observability UI - observability_server.py: Dashboard server - multi-agent-architecture.md: Architecture documentation - SUPERPOWERS_INTEGRATION.md: Integration guide ## Framework Integration Status - ✅ codebase-indexer (Chippery): Complete implementation with 5 scripts - ✅ ralph (Ralph Orchestrator): Complete Python implementation - ✅ always-use-superpowers: Declarative skill (SKILL.md) - ✅ auto-superpowers: Declarative skill (SKILL.md) - ✅ auto-dispatcher: Declarative skill (Ralph framework) - ✅ autonomous-planning: Declarative skill (Ralph framework) - ✅ mcp-client: Declarative skill (AGIAgent/Agno framework) ## Agent Updates - Updated README.md with latest integration status - Added framework integration agents Token Savings: ~99% via semantic codebase indexing 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
3450
.codebase-index.json
Normal file
3450
.codebase-index.json
Normal file
File diff suppressed because one or more lines are too long
711
agents/README.md
711
agents/README.md
@@ -1,469 +1,298 @@
|
||||
# 🚀 Ultimate Claude Code & GLM Suite
|
||||
# Contains Studio AI Agents
|
||||
|
||||
> **40+ specialized AI agents, 15+ MCP tools, 7 PROACTIVELY auto-triggering coordinators** for Claude Code. Works with Anthropic Claude and Z.AI/GLM models (90% cost savings).
|
||||
A comprehensive collection of specialized AI agents designed to accelerate and enhance every aspect of rapid development. Each agent is an expert in their domain, ready to be invoked when their expertise is needed.
|
||||
|
||||
> 💡 **Tip:** Use invite token `R0K78RJKNW` for **10% OFF** Z.AI GLM Plan subscription: https://z.ai/subscribe?ic=R0K78RJKNW
|
||||
## 📥 Installation
|
||||
|
||||
[](agents/)
|
||||
[](#-proactively-auto-coordination)
|
||||
[](#-mcp-tools)
|
||||
[](LICENSE)
|
||||
1. **Download this repository:**
|
||||
```bash
|
||||
git clone https://github.com/contains-studio/agents.git
|
||||
```
|
||||
|
||||
---
|
||||
2. **Copy to your Claude Code agents directory:**
|
||||
```bash
|
||||
cp -r agents/* ~/.claude/agents/
|
||||
```
|
||||
|
||||
Or manually copy all the agent files to your `~/.claude/agents/` directory.
|
||||
|
||||
## 🎯 What's New (January 2026)
|
||||
|
||||
### ✨ Latest Updates
|
||||
|
||||
- **📊 Agent Coordination System** - 7 PROACTIVELY coordinators automatically orchestrate 31 specialists
|
||||
- **🎨 ui-ux-pro-max Integration** - Professional UI/UX agent with 50+ styles, 97 palettes, WCAG compliance
|
||||
- **📝 MASTER-PROMPT.md Enhanced** - Complete workflow examples, proper markdown formatting
|
||||
- **🔧 All 7 Coordinators Documented** - studio-coach, ui-ux-pro-max, whimsy-injector, test-writer-fixer, experiment-tracker, studio-producer, project-shipper
|
||||
- **📚 Complete Documentation** - Workflow examples, coordination patterns, real-world use cases
|
||||
|
||||
### 🏗️ Architecture Overview
|
||||
|
||||
**38 Total Agents = 7 Coordinators + 31 Specialists**
|
||||
|
||||
The 7 **PROACTIVELY coordinators** auto-trigger based on context and orchestrate specialists automatically:
|
||||
|
||||
| Coordinator | Department | Auto-Triggers On |
|
||||
|-------------|------------|-------------------|
|
||||
| **ui-ux-pro-max** | Design | UI/UX design work, components, pages |
|
||||
| **whimsy-injector** | Design | After UI/UX changes for delightful touches |
|
||||
| **test-writer-fixer** | Engineering | After code modifications for testing |
|
||||
| **experiment-tracker** | Project Management | Feature flags, A/B tests, experiments |
|
||||
| **studio-producer** | Project Management | Cross-team coordination, resource conflicts |
|
||||
| **project-shipper** | Project Management | Launches, releases, go-to-market activities |
|
||||
| **studio-coach** | Bonus | Complex multi-agent tasks, agent confusion |
|
||||
|
||||
**How It Works:**
|
||||
- **Automatic Path:** Coordinators auto-trigger → call specialists → coordinate workflow
|
||||
- **Manual Path:** You directly invoke any specialist for precise control
|
||||
- **Best of Both:** Automation when you want it, control when you need it
|
||||
|
||||
**Real Example:**
|
||||
```
|
||||
You: "I need a viral TikTok app in 2 weeks"
|
||||
↓
|
||||
[studio-coach PROACTIVELY triggers]
|
||||
↓
|
||||
Coordinates: rapid-prototyper + tiktok-strategist + frontend-developer
|
||||
↓
|
||||
[whimsy-injector PROACTIVELY triggers]
|
||||
↓
|
||||
Adds delightful touches
|
||||
↓
|
||||
[project-shipper PROACTIVELY triggers]
|
||||
↓
|
||||
Plans launch strategy
|
||||
↓
|
||||
Result: Complete app, launch-ready ✓
|
||||
```
|
||||
|
||||
---
|
||||
3. **Restart Claude Code** to load the new agents.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.rommark.dev/admin/claude-code-glm-suite.git
|
||||
cd claude-code-glm-suite
|
||||
Agents are automatically available in Claude Code. Simply describe your task and the appropriate agent will be triggered. You can also explicitly request an agent by mentioning their name.
|
||||
|
||||
# Run the interactive installer
|
||||
chmod +x interactive-install-claude.sh
|
||||
./interactive-install-claude.sh
|
||||
📚 **Learn more:** [Claude Code Sub-Agents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
|
||||
|
||||
# Follow the prompts:
|
||||
# ✅ Choose model (Anthropic/Z.AI)
|
||||
# ✅ Select agent categories to install
|
||||
# ✅ Configure MCP tools
|
||||
# ✅ Enter your API key
|
||||
# ✅ Launch Claude Code
|
||||
```
|
||||
### Example Usage
|
||||
- "Create a new app for tracking meditation habits" → `rapid-prototyper`
|
||||
- "What's trending on TikTok that we could build?" → `trend-researcher`
|
||||
- "Our app reviews are dropping, what's wrong?" → `feedback-synthesizer`
|
||||
- "Make this loading screen more fun" → `whimsy-injector`
|
||||
|
||||
---
|
||||
## 📁 Directory Structure
|
||||
|
||||
## ⚠️ IMPORTANT: For Z.AI / GLM Users
|
||||
|
||||
**If using the GLM Coding Plan (90% cheaper), you MUST configure GLM FIRST before using Claude Code!**
|
||||
|
||||
**🎯 EASIEST METHOD - Use Z.AI Coding Helper Wizard:**
|
||||
|
||||
```bash
|
||||
# Install coding helper and run setup wizard
|
||||
npm install -g @z_ai/coding-helper
|
||||
npx @z_ai/coding-helper init
|
||||
|
||||
# The wizard will:
|
||||
# ✅ Ask for your Z.AI API key
|
||||
# ✅ Configure Claude Code for GLM automatically
|
||||
# ✅ Set up model mappings (glm-4.5-air, glm-4.7)
|
||||
# ✅ Verify everything works
|
||||
|
||||
# Start Claude Code with GLM
|
||||
claude
|
||||
```
|
||||
|
||||
**Manual Configuration (if you prefer):**
|
||||
```bash
|
||||
# Get API key: https://z.ai/
|
||||
mkdir -p ~/.claude
|
||||
cat > ~/.claude/settings.json << 'EOF'
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_AUTH_TOKEN": "YOUR_ZAI_API_KEY_HERE",
|
||||
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
|
||||
"API_TIMEOUT_MS": "3000000",
|
||||
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
|
||||
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
|
||||
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
claude
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Installation Options
|
||||
|
||||
### Option 1: Master Prompt (Recommended for First-Time Users)
|
||||
|
||||
**Copy and paste into Claude Code** - it will guide you through the entire installation step-by-step:
|
||||
|
||||
📄 **[MASTER-PROMPT.md](MASTER-PROMPT.md)**
|
||||
|
||||
**⚡ Quick Start:**
|
||||
1. **If using GLM:** Configure GLM first (see above)
|
||||
2. Start Claude Code: `claude`
|
||||
3. Copy the prompt from MASTER-PROMPT.md (clearly marked with ✂️ COPY FROM HERE)
|
||||
4. Paste into Claude Code
|
||||
5. Done!
|
||||
|
||||
**Benefits:**
|
||||
- ✅ See all steps before executing
|
||||
- ✅ Easy to customize and understand
|
||||
- ✅ Works entirely within Claude Code
|
||||
- ✅ Includes all source repository references
|
||||
|
||||
### Option 2: Interactive Installation Script
|
||||
|
||||
```bash
|
||||
git clone https://github.rommark.dev/admin/claude-code-glm-suite.git
|
||||
cd claude-code-glm-suite
|
||||
chmod +x interactive-install-claude.sh
|
||||
./interactive-install-claude.sh
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Automated execution
|
||||
- ✅ Menu-driven configuration
|
||||
- ✅ Backup and verification built-in
|
||||
- ✅ Faster for experienced users
|
||||
|
||||
### Option 3: Manual Installation
|
||||
|
||||
Follow the step-by-step guide below for full control over each component.
|
||||
|
||||
---
|
||||
|
||||
## ✨ What's Included
|
||||
|
||||
- **🤖 38 Custom Agents** across 8 departments
|
||||
- **7 PROACTIVELY coordinators** that auto-trigger and orchestrate specialists
|
||||
- **31 specialist agents** for domain-specific tasks
|
||||
- **🔧 15+ MCP Tools** for vision, search, and GitHub integration
|
||||
- **⚡ Intelligent Coordination** - Coordinators automatically detect context and orchestrate workflows
|
||||
- **🎛️ Interactive Installation** with model selection (Anthropic/Z.AI)
|
||||
- **🛡️ One-Click Setup** with comprehensive verification
|
||||
- **📚 Complete Documentation** with real-world workflow examples
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Agent Departments
|
||||
|
||||
### Engineering (7 agents)
|
||||
- **AI Engineer** - ML & LLM integration, prompt engineering
|
||||
- **Backend Architect** - API design, database architecture, microservices
|
||||
- **DevOps Automator** - CI/CD pipelines, infrastructure as code
|
||||
- **Frontend Developer** - React/Vue/Angular, responsive design
|
||||
- **Mobile Builder** - iOS/Android React Native apps
|
||||
- **Rapid Prototyper** - Quick MVPs in 6-day cycles
|
||||
- **Test Writer/Fixer** - Auto-write and fix tests (PROACTIVELY)
|
||||
|
||||
### Design (6 agents)
|
||||
- **UI/UX Pro Max** - Professional UI/UX design with 50+ styles, 97 palettes, WCAG (PROACTIVELY)
|
||||
- **Whimsy Injector** - Delightful micro-interactions and memorable UX (PROACTIVELY)
|
||||
- **Brand Guardian** - Brand consistency
|
||||
- **UI Designer** - UI design and implementation
|
||||
- **UX Researcher** - User experience research
|
||||
- **Visual Storyteller** - Visual communication
|
||||
|
||||
### Project Management (3 agents)
|
||||
- **Experiment Tracker** - A/B test tracking and metrics (PROACTIVELY)
|
||||
- **Project Shipper** - Launch coordination and go-to-market (PROACTIVELY)
|
||||
- **Studio Producer** - Cross-team coordination and resources (PROACTIVELY)
|
||||
|
||||
### Product (3 agents)
|
||||
- **Feedback Synthesizer** - User feedback analysis
|
||||
- **Sprint Prioritizer** - 6-day sprint planning
|
||||
- **Trend Researcher** - Market trend analysis
|
||||
|
||||
### Marketing (7 agents)
|
||||
- **TikTok Strategist** - Viral TikTok marketing strategies
|
||||
- **Growth Hacker** - Growth strategies and user acquisition
|
||||
- **Content Creator** - Multi-platform content creation
|
||||
- **Instagram Curator** - Instagram strategy and engagement
|
||||
- **Reddit Builder** - Reddit community building
|
||||
- **Twitter Engager** - Twitter strategy and tactics
|
||||
- **App Store Optimizer** - ASO optimization
|
||||
|
||||
### Studio Operations (5 agents)
|
||||
- **Analytics Reporter** - Data analysis and reporting
|
||||
- **Finance Tracker** - Financial tracking
|
||||
- **Infrastructure Maintainer** - Infrastructure management
|
||||
- **Legal Compliance Checker** - Compliance checks
|
||||
- **Support Responder** - Customer support automation
|
||||
|
||||
### Testing (5 agents)
|
||||
- **API Tester** - API testing
|
||||
- **Performance Benchmarker** - Performance testing
|
||||
- **Test Results Analyzer** - Test analysis
|
||||
- **Tool Evaluator** - Tool evaluation
|
||||
- **Workflow Optimizer** - Workflow optimization
|
||||
|
||||
### Bonus (2 agents)
|
||||
- **Studio Coach** - Team coaching and motivation for complex tasks (PROACTIVELY)
|
||||
- **Joker** - Humor and team morale
|
||||
|
||||
---
|
||||
|
||||
## 🎯 PROACTIVELY Auto-Coordination
|
||||
|
||||
### How It Works
|
||||
|
||||
The 7 PROACTIVELY coordinators automatically orchestrate the 31 specialists based on context:
|
||||
|
||||
**Two Pathways:**
|
||||
|
||||
1. **Automatic** (Recommended)
|
||||
- Coordinators auto-trigger based on context
|
||||
- Call appropriate specialists
|
||||
- Coordinate multi-agent workflows
|
||||
- Ensure quality and completeness
|
||||
|
||||
2. **Direct**
|
||||
- Manually invoke any specialist
|
||||
- Precise control over specific tasks
|
||||
- Use when you need specific expertise
|
||||
|
||||
### The 7 PROACTIVELY Coordinators
|
||||
|
||||
#### 1. ui-ux-pro-max (Design)
|
||||
**Triggers on:** UI/UX design work, components, pages, dashboards
|
||||
|
||||
**Provides:**
|
||||
- Professional design patterns
|
||||
- 50+ design styles (glassmorphism, minimalism, brutalism, etc.)
|
||||
- 97 color palettes by industry
|
||||
- 57 font pairings with Google Fonts
|
||||
- WCAG 2.1 AA/AAA accessibility compliance
|
||||
- Tech-stack specific patterns (React, Next.js, Vue, Tailwind, shadcn/ui)
|
||||
|
||||
#### 2. whimsy-injector (Design)
|
||||
**Triggers after:** UI/UX changes, new components, feature completion
|
||||
|
||||
**Provides:**
|
||||
- Delightful micro-interactions
|
||||
- Memorable user moments
|
||||
- Playful animations
|
||||
- Engaging empty states
|
||||
- Celebratory success states
|
||||
|
||||
#### 3. test-writer-fixer (Engineering)
|
||||
**Triggers after:** Code modifications, refactoring, bug fixes
|
||||
|
||||
**Provides:**
|
||||
- Comprehensive test coverage
|
||||
- Unit, integration, and E2E tests
|
||||
- Failure analysis and repair
|
||||
- Test suite health maintenance
|
||||
- Edge case coverage
|
||||
|
||||
#### 4. experiment-tracker (Project Management)
|
||||
**Triggers on:** Feature flags, A/B tests, experiments, product decisions
|
||||
|
||||
**Provides:**
|
||||
- Experiment design and setup
|
||||
- Success metrics definition
|
||||
- A/B test tracking
|
||||
- Statistical significance calculation
|
||||
- Data-driven decision support
|
||||
|
||||
#### 5. studio-producer (Project Management)
|
||||
**Triggers on:** Team collaboration, resource conflicts, workflow issues
|
||||
|
||||
**Provides:**
|
||||
- Cross-team coordination
|
||||
- Resource allocation optimization
|
||||
- Workflow improvement
|
||||
- Dependency management
|
||||
- Sprint planning support
|
||||
|
||||
#### 6. project-shipper (Project Management)
|
||||
**Triggers on:** Releases, launches, go-to-market, shipping milestones
|
||||
|
||||
**Provides:**
|
||||
- Launch planning and coordination
|
||||
- Release calendar management
|
||||
- Go-to-market strategy
|
||||
- Stakeholder communication
|
||||
- Post-launch monitoring
|
||||
|
||||
#### 7. studio-coach (Bonus)
|
||||
**Triggers on:** Complex projects, multi-agent tasks, agent confusion
|
||||
|
||||
**Provides:**
|
||||
- Elite performance coaching
|
||||
- Multi-agent coordination
|
||||
- Motivation and alignment
|
||||
- Problem-solving guidance
|
||||
- Best practices enforcement
|
||||
|
||||
### Real Workflow Example
|
||||
Agents are organized by department for easy discovery:
|
||||
|
||||
```
|
||||
You: "I need a viral TikTok app in 2 weeks"
|
||||
↓
|
||||
[studio-coach PROACTIVELY triggers]
|
||||
↓
|
||||
Analyzes complexity and coordinates:
|
||||
→ rapid-prototyper builds MVP
|
||||
→ tiktok-strategist plans viral features
|
||||
→ frontend-developer builds UI
|
||||
↓
|
||||
[whimsy-injector PROACTIVELY triggers]
|
||||
↓
|
||||
Adds delightful touches and micro-interactions
|
||||
↓
|
||||
[project-shipper PROACTIVELY triggers]
|
||||
↓
|
||||
Plans launch strategy and coordinates release
|
||||
↓
|
||||
Result: Complete viral app, launch-ready, in 2 weeks ✓
|
||||
contains-studio-agents/
|
||||
├── design/
|
||||
│ ├── brand-guardian.md
|
||||
│ ├── ui-designer.md
|
||||
│ ├── ux-researcher.md
|
||||
│ ├── visual-storyteller.md
|
||||
│ └── whimsy-injector.md
|
||||
├── engineering/
|
||||
│ ├── ai-engineer.md
|
||||
│ ├── backend-architect.md
|
||||
│ ├── devops-automator.md
|
||||
│ ├── frontend-developer.md
|
||||
│ ├── mobile-app-builder.md
|
||||
│ ├── rapid-prototyper.md
|
||||
│ └── test-writer-fixer.md
|
||||
├── marketing/
|
||||
│ ├── app-store-optimizer.md
|
||||
│ ├── content-creator.md
|
||||
│ ├── growth-hacker.md
|
||||
│ ├── instagram-curator.md
|
||||
│ ├── reddit-community-builder.md
|
||||
│ ├── tiktok-strategist.md
|
||||
│ └── twitter-engager.md
|
||||
├── product/
|
||||
│ ├── feedback-synthesizer.md
|
||||
│ ├── sprint-prioritizer.md
|
||||
│ └── trend-researcher.md
|
||||
├── project-management/
|
||||
│ ├── experiment-tracker.md
|
||||
│ ├── project-shipper.md
|
||||
│ └── studio-producer.md
|
||||
├── studio-operations/
|
||||
│ ├── analytics-reporter.md
|
||||
│ ├── finance-tracker.md
|
||||
│ ├── infrastructure-maintainer.md
|
||||
│ ├── legal-compliance-checker.md
|
||||
│ └── support-responder.md
|
||||
├── testing/
|
||||
│ ├── api-tester.md
|
||||
│ ├── performance-benchmarker.md
|
||||
│ ├── test-results-analyzer.md
|
||||
│ ├── tool-evaluator.md
|
||||
│ └── workflow-optimizer.md
|
||||
└── bonus/
|
||||
├── joker.md
|
||||
└── studio-coach.md
|
||||
```
|
||||
|
||||
**Key Benefits:**
|
||||
- ✅ No manual orchestration required
|
||||
- ✅ Automatic quality gates (testing, UX, launches)
|
||||
- ✅ Intelligent specialist selection
|
||||
- ✅ Seamless multi-agent workflows
|
||||
- ✅ Consistent delivery quality
|
||||
## 📋 Complete Agent List
|
||||
|
||||
### Engineering Department (`engineering/`)
|
||||
- **ai-engineer** - Integrate AI/ML features that actually ship
|
||||
- **backend-architect** - Design scalable APIs and server systems
|
||||
- **devops-automator** - Deploy continuously without breaking things
|
||||
- **frontend-developer** - Build blazing-fast user interfaces
|
||||
- **mobile-app-builder** - Create native iOS/Android experiences
|
||||
- **rapid-prototyper** - Build MVPs in days, not weeks
|
||||
- **test-writer-fixer** - Write tests that catch real bugs
|
||||
|
||||
### Product Department (`product/`)
|
||||
- **feedback-synthesizer** - Transform complaints into features
|
||||
- **sprint-prioritizer** - Ship maximum value in 6 days
|
||||
- **trend-researcher** - Identify viral opportunities
|
||||
|
||||
### Marketing Department (`marketing/`)
|
||||
- **app-store-optimizer** - Dominate app store search results
|
||||
- **content-creator** - Generate content across all platforms
|
||||
- **growth-hacker** - Find and exploit viral growth loops
|
||||
- **instagram-curator** - Master the visual content game
|
||||
- **reddit-community-builder** - Win Reddit without being banned
|
||||
- **tiktok-strategist** - Create shareable marketing moments
|
||||
- **twitter-engager** - Ride trends to viral engagement
|
||||
|
||||
### Design Department (`design/`)
|
||||
- **brand-guardian** - Keep visual identity consistent everywhere
|
||||
- **ui-designer** - Design interfaces developers can actually build
|
||||
- **ux-researcher** - Turn user insights into product improvements
|
||||
- **visual-storyteller** - Create visuals that convert and share
|
||||
- **whimsy-injector** - Add delight to every interaction
|
||||
|
||||
### Project Management (`project-management/`)
|
||||
- **experiment-tracker** - Data-driven feature validation
|
||||
- **project-shipper** - Launch products that don't crash
|
||||
- **studio-producer** - Keep teams shipping, not meeting
|
||||
|
||||
### Studio Operations (`studio-operations/`)
|
||||
- **analytics-reporter** - Turn data into actionable insights
|
||||
- **finance-tracker** - Keep the studio profitable
|
||||
- **infrastructure-maintainer** - Scale without breaking the bank
|
||||
- **legal-compliance-checker** - Stay legal while moving fast
|
||||
- **support-responder** - Turn angry users into advocates
|
||||
|
||||
### Testing & Benchmarking (`testing/`)
|
||||
- **api-tester** - Ensure APIs work under pressure
|
||||
- **performance-benchmarker** - Make everything faster
|
||||
- **test-results-analyzer** - Find patterns in test failures
|
||||
- **tool-evaluator** - Choose tools that actually help
|
||||
- **workflow-optimizer** - Eliminate workflow bottlenecks
|
||||
|
||||
## 🎁 Bonus Agents
|
||||
- **studio-coach** - Rally the AI troops to excellence
|
||||
- **joker** - Lighten the mood with tech humor
|
||||
|
||||
## 🎯 Proactive Agents
|
||||
|
||||
Some agents trigger automatically in specific contexts:
|
||||
- **studio-coach** - When complex multi-agent tasks begin or agents need guidance
|
||||
- **test-writer-fixer** - After implementing features, fixing bugs, or modifying code
|
||||
- **whimsy-injector** - After UI/UX changes
|
||||
- **experiment-tracker** - When feature flags are added
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
1. **Let agents work together** - Many tasks benefit from multiple agents
|
||||
2. **Be specific** - Clear task descriptions help agents perform better
|
||||
3. **Trust the expertise** - Agents are designed for their specific domains
|
||||
4. **Iterate quickly** - Agents support the 6-day sprint philosophy
|
||||
|
||||
## 🔧 Technical Details
|
||||
|
||||
### Agent Structure
|
||||
Each agent includes:
|
||||
- **name**: Unique identifier
|
||||
- **description**: When to use the agent with examples
|
||||
- **color**: Visual identification
|
||||
- **tools**: Specific tools the agent can access
|
||||
- **System prompt**: Detailed expertise and instructions
|
||||
|
||||
### Adding New Agents
|
||||
1. Create a new `.md` file in the appropriate department folder
|
||||
2. Follow the existing format with YAML frontmatter
|
||||
3. Include 3-4 detailed usage examples
|
||||
4. Write comprehensive system prompt (500+ words)
|
||||
5. Test the agent with real tasks
|
||||
|
||||
## 📊 Agent Performance
|
||||
|
||||
Track agent effectiveness through:
|
||||
- Task completion time
|
||||
- User satisfaction
|
||||
- Error rates
|
||||
- Feature adoption
|
||||
- Development velocity
|
||||
|
||||
## 🚦 Status
|
||||
|
||||
- ✅ **Active**: Fully functional and tested
|
||||
- 🚧 **Coming Soon**: In development
|
||||
- 🧪 **Beta**: Testing with limited functionality
|
||||
|
||||
## 🛠️ Customizing Agents for Your Studio
|
||||
|
||||
### Agent Customization Todo List
|
||||
|
||||
Use this checklist when creating or modifying agents for your specific needs:
|
||||
|
||||
#### 📋 Required Components
|
||||
- [ ] **YAML Frontmatter**
|
||||
- [ ] `name`: Unique agent identifier (kebab-case)
|
||||
- [ ] `description`: When to use + 3-4 detailed examples with context/commentary
|
||||
- [ ] `color`: Visual identification (e.g., blue, green, purple, indigo)
|
||||
- [ ] `tools`: Specific tools the agent can access (Write, Read, MultiEdit, Bash, etc.)
|
||||
|
||||
#### 📝 System Prompt Requirements (500+ words)
|
||||
- [ ] **Agent Identity**: Clear role definition and expertise area
|
||||
- [ ] **Core Responsibilities**: 5-8 specific primary duties
|
||||
- [ ] **Domain Expertise**: Technical skills and knowledge areas
|
||||
- [ ] **Studio Integration**: How agent fits into 6-day sprint workflow
|
||||
- [ ] **Best Practices**: Specific methodologies and approaches
|
||||
- [ ] **Constraints**: What the agent should/shouldn't do
|
||||
- [ ] **Success Metrics**: How to measure agent effectiveness
|
||||
|
||||
#### 🎯 Required Examples by Agent Type
|
||||
|
||||
**Engineering Agents** need examples for:
|
||||
- [ ] Feature implementation requests
|
||||
- [ ] Bug fixing scenarios
|
||||
- [ ] Code refactoring tasks
|
||||
- [ ] Architecture decisions
|
||||
|
||||
**Design Agents** need examples for:
|
||||
- [ ] New UI component creation
|
||||
- [ ] Design system work
|
||||
- [ ] User experience problems
|
||||
- [ ] Visual identity tasks
|
||||
|
||||
**Marketing Agents** need examples for:
|
||||
- [ ] Campaign creation requests
|
||||
- [ ] Platform-specific content needs
|
||||
- [ ] Growth opportunity identification
|
||||
- [ ] Brand positioning tasks
|
||||
|
||||
**Product Agents** need examples for:
|
||||
- [ ] Feature prioritization decisions
|
||||
- [ ] User feedback analysis
|
||||
- [ ] Market research requests
|
||||
- [ ] Strategic planning needs
|
||||
|
||||
**Operations Agents** need examples for:
|
||||
- [ ] Process optimization
|
||||
- [ ] Tool evaluation
|
||||
- [ ] Resource management
|
||||
- [ ] Performance analysis
|
||||
|
||||
#### ✅ Testing & Validation Checklist
|
||||
- [ ] **Trigger Testing**: Agent activates correctly for intended use cases
|
||||
- [ ] **Tool Access**: Agent can use all specified tools properly
|
||||
- [ ] **Output Quality**: Responses are helpful and actionable
|
||||
- [ ] **Edge Cases**: Agent handles unexpected or complex scenarios
|
||||
- [ ] **Integration**: Works well with other agents in multi-agent workflows
|
||||
- [ ] **Performance**: Completes tasks within reasonable timeframes
|
||||
- [ ] **Documentation**: Examples accurately reflect real usage patterns
|
||||
|
||||
#### 🔧 Agent File Structure Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-agent-name
|
||||
description: Use this agent when [scenario]. This agent specializes in [expertise]. Examples:\n\n<example>\nContext: [situation]\nuser: "[user request]"\nassistant: "[response approach]"\n<commentary>\n[why this example matters]\n</commentary>\n</example>\n\n[3 more examples...]
|
||||
color: agent-color
|
||||
tools: Tool1, Tool2, Tool3
|
||||
---
|
||||
|
||||
## 🔧 MCP Tools
|
||||
You are a [role] who [primary function]. Your expertise spans [domains]. You understand that in 6-day sprints, [sprint constraint], so you [approach].
|
||||
|
||||
### Vision Tools (8 tools)
|
||||
| Tool | Function | Input |
|
||||
|------|----------|-------|
|
||||
| `analyze_image` | General image analysis | PNG, JPG, JPEG |
|
||||
| `analyze_video` | Video content analysis | MP4, MOV, M4V |
|
||||
| `ui_to_artifact` | UI screenshot to code | Screenshots |
|
||||
| `extract_text` | OCR text extraction | Any image |
|
||||
| `diagnose_error` | Error screenshot diagnosis | Error screenshots |
|
||||
| `ui_diff_check` | Compare UI screenshots | Before/after |
|
||||
| `analyze_data_viz` | Data visualization insights | Dashboards, charts |
|
||||
| `understand_diagram` | Technical diagram analysis | UML, flowcharts |
|
||||
Your primary responsibilities:
|
||||
1. [Responsibility 1]
|
||||
2. [Responsibility 2]
|
||||
...
|
||||
|
||||
### Web & GitHub Tools
|
||||
| Tool | Function | Source |
|
||||
|------|----------|--------|
|
||||
| `web-search-prime` | AI-optimized web search | Real-time information |
|
||||
| `web-reader` | Web page to markdown conversion | Documentation access |
|
||||
| `zread` | GitHub repository reader | Codebase analysis |
|
||||
| `@z_ai/mcp-server` | Vision and analysis tools | [@z_ai/mcp-server](https://github.com/zai-ai/mcp-server) |
|
||||
| `@z_ai/coding-helper` | Web and GitHub integration | [@z_ai/coding-helper](https://github.com/zai-ai/mcp-server) |
|
||||
[Detailed system prompt content...]
|
||||
|
||||
---
|
||||
Your goal is to [ultimate objective]. You [key behavior traits]. Remember: [key philosophy for 6-day sprints].
|
||||
```
|
||||
|
||||
## 📚 Documentation
|
||||
#### 📂 Department-Specific Guidelines
|
||||
|
||||
- **[MASTER-PROMPT.md](MASTER-PROMPT.md)** - Copy-paste installation prompt with complete workflow examples
|
||||
- **[docs/workflow-example-pro.html](docs/workflow-example-pro.html)** - PRO-level workflow visualization
|
||||
- **[docs/coordination-system-pro.html](docs/coordination-system-pro.html)** - Complete coordination system explanation
|
||||
- **[docs/AUTO-TRIGGER-INTEGRATION-REPORT.md](docs/AUTO-TRIGGER-INTEGRATION-REPORT.md)** - Complete auto-trigger verification report
|
||||
**Engineering** (`engineering/`): Focus on implementation speed, code quality, testing
|
||||
**Design** (`design/`): Emphasize user experience, visual consistency, rapid iteration
|
||||
**Marketing** (`marketing/`): Target viral potential, platform expertise, growth metrics
|
||||
**Product** (`product/`): Prioritize user value, data-driven decisions, market fit
|
||||
**Operations** (`studio-operations/`): Optimize processes, reduce friction, scale systems
|
||||
**Testing** (`testing/`): Ensure quality, find bottlenecks, validate performance
|
||||
**Project Management** (`project-management/`): Coordinate teams, ship on time, manage scope
|
||||
|
||||
---
|
||||
#### 🎨 Customizations
|
||||
|
||||
## 📖 Complete Source Guide
|
||||
Modify these elements for your needs:
|
||||
- [ ] Adjust examples to reflect your product types
|
||||
- [ ] Add specific tools agents have access to
|
||||
- [ ] Modify success metrics for your KPIs
|
||||
- [ ] Update department structure if needed
|
||||
- [ ] Customize agent colors for your brand
|
||||
|
||||
This suite integrates **6 major open-source projects**:
|
||||
## 🤝 Contributing
|
||||
|
||||
### 1. contains-studio/agents 🎭
|
||||
**Source:** https://github.com/contains-studio/agents
|
||||
**Provides:** 37 specialized agents with PROACTIVELY auto-triggering
|
||||
**Key Innovation:** Context-aware agent selection system
|
||||
|
||||
### 2. @z_ai/mcp-server 🖼️
|
||||
**Source:** https://github.com/zai-ai/mcp-server
|
||||
**Provides:** 8 vision tools for images, videos, diagrams
|
||||
**Key Feature:** Understand visual content for debugging and design
|
||||
|
||||
### 3. @z_ai/coding-helper 🌐
|
||||
**Source:** https://github.com/zai-ai/mcp-server
|
||||
**Provides:** Web search, GitHub integration, GLM setup wizard
|
||||
**Key Feature:** Interactive configuration and real-time information
|
||||
|
||||
### 4. llm-tldr 📊
|
||||
**Source:** https://github.com/parcadei/llm-tldr
|
||||
**Provides:** 95% token reduction via 5-layer code analysis
|
||||
**Key Feature:** Semantic search and impact analysis
|
||||
|
||||
### 5. ui-ux-pro-max-skill 🎨
|
||||
**Source:** https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
|
||||
**Provides:** Professional UI/UX design agent with comprehensive patterns
|
||||
**Key Feature:** PROACTIVELY auto-triggering for all design work
|
||||
|
||||
### 6. claude-codex-settings 📋
|
||||
**Source:** https://github.com/fcakyon/claude-codex-settings
|
||||
**Provides:** MCP configuration best practices (reference)
|
||||
**Key Feature:** Proven integration patterns
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Real-Life Impact: Before vs After
|
||||
|
||||
| Scenario | Without Suite | With Suite | Impact |
|
||||
|----------|--------------|-----------|--------|
|
||||
| **Debugging Errors** | Paste text manually, miss context | Upload screenshot → Instant diagnosis | 5x faster |
|
||||
| **Implementing UI** | Describe in words, iterate 10+ times | Upload design → Exact code generated | 10x faster |
|
||||
| **Understanding Code** | Read files manually, hit token limits | TLDR 5-layer analysis, 95% token savings | 20x faster |
|
||||
| **Writing Tests** | Write manually, forget often | Auto-triggered after every code change | Always tested |
|
||||
| **Code Search** | grep for exact names | Semantic search by behavior | Finds by intent |
|
||||
| **Web Research** | Outdated training data | Real-time web search | Always current |
|
||||
| **Refactoring** | Risk breaking changes | Impact analysis, safe refactoring | Zero breaking changes |
|
||||
| **Multi-Agent Tasks** | Manual orchestration | Automatic coordination | Hands-free delivery |
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Community & Contributing
|
||||
|
||||
This suite is **100% open source** and available on [GitHub](https://github.rommark.dev/admin/claude-code-glm-suite).
|
||||
|
||||
- ⭐ Star the repo
|
||||
- 🐛 Report issues
|
||||
- 🔄 Submit pull requests
|
||||
- 💡 Contribute your own agents!
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
MIT License - Feel free to use and modify for your needs.
|
||||
|
||||
---
|
||||
|
||||
**Built for developers who ship.** 🚀
|
||||
To improve existing agents or suggest new ones:
|
||||
1. Use the customization checklist above
|
||||
2. Test thoroughly with real projects
|
||||
3. Document performance improvements
|
||||
4. Share successful patterns with the community
|
||||
|
||||
@@ -56,20 +56,6 @@ You MUST:
|
||||
- Use before: Any design work, HTML/CSS, component creation, layouts
|
||||
- Priority: HIGH for any UI/UX work
|
||||
|
||||
#### 5. design-pattern-learner
|
||||
**When to use:** Studying or implementing designs from external sources
|
||||
- Use before: Learning from gists, repositories, or external websites
|
||||
- Triggers on: "study design from", "learn from", "implement this design", "copy style from"
|
||||
- Priority: HIGH for external design learning
|
||||
- Benefit: Fetches, analyzes, and implements patterns from any design source
|
||||
|
||||
#### 6. codebase-indexer (ALWAYS ACTIVE)
|
||||
**When to use:** EVERY TASK involving code navigation, file searches, codebase understanding
|
||||
- **ALWAYS RUN THIS FIRST** before any code-related task
|
||||
- Use for: Finding files, understanding code structure, semantic search, 40-60% token reduction
|
||||
- Priority: CRITICAL - Runs automatically on ALL code tasks
|
||||
- Benefit: Drastically reduces token usage and provides intelligent code context
|
||||
|
||||
### Auto-Trigger Conditions:
|
||||
|
||||
The `always-use-superpowers` skill should automatically trigger when:
|
||||
@@ -83,12 +69,6 @@ The `always-use-superpowers` skill should automatically trigger when:
|
||||
```
|
||||
User sends message
|
||||
↓
|
||||
Check: Is this code-related work?
|
||||
↓ YES → Invoke codebase-indexer (ALWAYS)
|
||||
↓ NO
|
||||
Check: Is this studying/learning external design?
|
||||
↓ YES → Invoke design-pattern-learner
|
||||
↓ NO
|
||||
Check: Is this UI/UX work?
|
||||
↓ YES → Invoke ui-ux-pro-max
|
||||
↓ NO
|
||||
|
||||
328
skills/ralph/SUPERPOWERS_INTEGRATION.md
Normal file
328
skills/ralph/SUPERPOWERS_INTEGRATION.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Ralph Superpowers Integration
|
||||
|
||||
Complete integration of oh-my-opencode and superpowers features into Ralph for Claude Code CLI.
|
||||
|
||||
## Integrated Features
|
||||
|
||||
### From oh-my-opencode:
|
||||
|
||||
**Agents (10 total):**
|
||||
- **Sisyphus** - Primary orchestrator (Claude Opus 4.5)
|
||||
- **Atlas** - Master orchestrator
|
||||
- **Oracle** - Consultation, debugging (GPT 5.2)
|
||||
- **Librarian** - Docs, GitHub search
|
||||
- **Explore** - Fast codebase grep
|
||||
- **Multimodal-Looker** - PDF/image analysis (Gemini 3 Flash)
|
||||
- **Prometheus** - Strategic planning
|
||||
|
||||
**Lifecycle Hooks (31 total):**
|
||||
- agent-usage-reminder
|
||||
- anthropic-context-window-limit-recovery
|
||||
- atlas (main orchestrator)
|
||||
- auto-slash-command
|
||||
- auto-update-checker
|
||||
- background-notification
|
||||
- claude-code-hooks
|
||||
- comment-checker
|
||||
- compaction-context-injector
|
||||
- delegate-task-retry
|
||||
- directory-agents-injector
|
||||
- directory-readme-injector
|
||||
- edit-error-recovery
|
||||
- empty-task-response-detector
|
||||
- interactive-bash-session
|
||||
- keyword-detector
|
||||
- non-interactive-env
|
||||
- prometheus-md-only
|
||||
- question-label-truncator
|
||||
- ralph-loop
|
||||
- rules-injector
|
||||
- session-recovery
|
||||
- sisyphus-junior-notepad
|
||||
- start-work
|
||||
- task-resume-info
|
||||
- think-mode
|
||||
- thinking-block-validator
|
||||
- todo-continuation-enforcer
|
||||
- tool-output-truncator
|
||||
|
||||
**Built-in MCPs:**
|
||||
- websearch (Exa)
|
||||
- context7 (docs)
|
||||
- grep_app (GitHub)
|
||||
|
||||
**Tools (20+):**
|
||||
- LSP support
|
||||
- AST-Grep
|
||||
- Delegation system
|
||||
- Background task management
|
||||
|
||||
### From superpowers:
|
||||
|
||||
**Skills (14 total):**
|
||||
- brainstorming - Interactive design refinement
|
||||
- writing-plans - Detailed implementation plans
|
||||
- executing-plans - Batch execution with checkpoints
|
||||
- subagent-driven-development - Fast iteration with two-stage review
|
||||
- test-driven-development - RED-GREEN-REFACTOR cycle
|
||||
- systematic-debugging - 4-phase root cause process
|
||||
- verification-before-completion - Ensure it's actually fixed
|
||||
- requesting-code-review - Pre-review checklist
|
||||
- receiving-code-review - Responding to feedback
|
||||
- using-git-worktrees - Parallel development branches
|
||||
- finishing-a-development-branch - Merge/PR decision workflow
|
||||
- dispatching-parallel-agents - Concurrent subagent workflows
|
||||
- using-superpowers - Introduction to the skills system
|
||||
- writing-skills - Create new skills
|
||||
|
||||
**Commands (3):**
|
||||
- /superpowers:brainstorm - Interactive design refinement
|
||||
- /superpowers:write-plan - Create implementation plan
|
||||
- /superpowers:execute-plan - Execute plan in batches
|
||||
|
||||
**Agents (1):**
|
||||
- code-reviewer - Code review specialist
|
||||
|
||||
## Installation
|
||||
|
||||
### For Claude Code CLI
|
||||
|
||||
```bash
|
||||
# Install Ralph with all superpowers
|
||||
cd ~/.claude/skills
|
||||
git clone https://github.com/YOUR-USERNAME/ralph-superpowers.git
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Create `~/.claude/config/ralph.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"superpowers": {
|
||||
"enabled": true,
|
||||
"skills": {
|
||||
"brainstorming": true,
|
||||
"writing-plans": true,
|
||||
"executing-plans": true,
|
||||
"subagent-driven-development": true,
|
||||
"test-driven-development": true,
|
||||
"systematic-debugging": true,
|
||||
"verification-before-completion": true,
|
||||
"requesting-code-review": true,
|
||||
"receiving-code-review": true,
|
||||
"using-git-worktrees": true,
|
||||
"finishing-a-development-branch": true,
|
||||
"dispatching-parallel-agents": true
|
||||
},
|
||||
"hooks": {
|
||||
"atlas": true,
|
||||
"claude-code-hooks": true,
|
||||
"ralph-loop": true,
|
||||
"todo-continuation-enforcer": true
|
||||
},
|
||||
"agents": {
|
||||
"sisyphus": true,
|
||||
"oracle": true,
|
||||
"librarian": true,
|
||||
"explore": true,
|
||||
"prometheus": true
|
||||
},
|
||||
"mcps": {
|
||||
"websearch": true,
|
||||
"context7": true,
|
||||
"grep_app": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
```
|
||||
1. /ralph "Build a new feature"
|
||||
→ Ralph invokes brainstorming skill
|
||||
→ Refines requirements through questions
|
||||
→ Presents design in sections
|
||||
|
||||
2. User approves design
|
||||
→ Ralph invokes writing-plans skill
|
||||
→ Creates detailed implementation plan
|
||||
→ Breaks into 2-5 minute tasks
|
||||
|
||||
3. User approves plan
|
||||
→ Ralph invokes subagent-driven-development
|
||||
→ Executes tasks with two-stage review
|
||||
→ Continues until complete
|
||||
|
||||
4. Throughout process
|
||||
→ test-driven-development enforces TDD
|
||||
→ systematic-debugging handles issues
|
||||
→ requesting-code-review between tasks
|
||||
```
|
||||
|
||||
### With Multi-Agent Mode
|
||||
|
||||
```bash
|
||||
RALPH_MULTI_AGENT=true \
|
||||
RALPH_SUPERPOWERS_ENABLED=true \
|
||||
/ralph "Complex task with multiple components"
|
||||
```
|
||||
|
||||
### Individual Skill Invocation
|
||||
|
||||
```bash
|
||||
# Brainstorm design
|
||||
/ralph:brainstorm "I want to add user authentication"
|
||||
|
||||
# Create plan
|
||||
/ralph:write-plan
|
||||
|
||||
# Execute plan
|
||||
/ralph:execute-plan
|
||||
|
||||
# Debug systematically
|
||||
/ralph:debug "The login isn't working"
|
||||
|
||||
# Code review
|
||||
/ralph:review
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# Superpowers
|
||||
RALPH_SUPERPOWERS_ENABLED=true # Enable all superpowers
|
||||
RALPH_BRAINSTORMING_ENABLED=true # Enable brainstorming
|
||||
RALPH_TDD_ENABLED=true # Enable test-driven development
|
||||
RALPH_SYSTEMATIC_DEBUGGING=true # Enable systematic debugging
|
||||
|
||||
# Hooks
|
||||
RALPH_HOOK_ATLAS=true # Enable Atlas orchestrator
|
||||
RALPH_HOOK_CLAUDE_CODE_HOOKS=true # Enable Claude Code hooks
|
||||
RALPH_HOOK_RALPH_LOOP=true # Enable Ralph Loop
|
||||
RALPH_HOOK_TODO_ENFORCER=true # Enable todo continuation
|
||||
|
||||
# Agents
|
||||
RALPH_AGENT_SISYPHUS=true # Enable Sisyphus
|
||||
RALPH_AGENT_ORACLE=true # Enable Oracle
|
||||
RALPH_AGENT_LIBRARIAN=true # Enable Librarian
|
||||
|
||||
# MCPs
|
||||
RALPH_MCP_WEBSEARCH=true # Enable web search MCP
|
||||
RALPH_MCP_CONTEXT7=true # Enable context7 MCP
|
||||
RALPH_MCP_GREP_APP=true # Enable GitHub grep MCP
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Ralph Core │
|
||||
│ (Orchestration & Selection) │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┬─────────────┐
|
||||
│ │ │ │
|
||||
┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐
|
||||
│ Skills │ │ Hooks │ │ Agents │ │ MCPs │
|
||||
└─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
|
||||
Skills:
|
||||
• brainstorming → /ralph:brainstorm
|
||||
• writing-plans → /ralph:write-plan
|
||||
• executing-plans → /ralph:execute-plan
|
||||
• subagent-driven-dev → Auto-invoked
|
||||
• test-driven-development → Auto-invoked
|
||||
• systematic-debugging → /ralph:debug
|
||||
• verification → Auto-invoked
|
||||
• code-review → /ralph:review
|
||||
|
||||
Hooks:
|
||||
• atlas (orchestrator) → Manages multi-agent workflows
|
||||
• claude-code-hooks → Claude Code compatibility
|
||||
• ralph-loop → Autonomous iteration
|
||||
• todo-enforcer → Ensures task completion
|
||||
|
||||
Agents:
|
||||
• sisyphus → Primary orchestrator
|
||||
• oracle → Debugging consultant
|
||||
• librarian → Docs & codebase search
|
||||
• explore → Fast grep
|
||||
• prometheus → Strategic planning
|
||||
|
||||
MCPs:
|
||||
• websearch (Exa) → Web search
|
||||
• context7 → Documentation search
|
||||
• grep_app → GitHub code search
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── skills/
|
||||
│ └── ralph/
|
||||
│ ├── SKILL.md # Main skill file
|
||||
│ ├── superpowers/
|
||||
│ │ ├── integration.py # Superpowers integration
|
||||
│ │ ├── skills/ # Imported skills
|
||||
│ │ ├── hooks/ # Imported hooks
|
||||
│ │ ├── agents/ # Imported agents
|
||||
│ │ └── mcps/ # Imported MCPs
|
||||
│ ├── contains-studio/
|
||||
│ │ ├── agents/ # Contains-studio agents
|
||||
│ │ └── integration.py # Agent integration
|
||||
│ └── multi-agent/
|
||||
│ ├── orchestrator.py # Meta-agent
|
||||
│ ├── worker.py # Worker agents
|
||||
│ └── observability/ # Monitoring
|
||||
├── commands/
|
||||
│ └── ralph.md # /ralph command
|
||||
└── config/
|
||||
└── ralph.json # Configuration
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Skills not triggering?**
|
||||
```bash
|
||||
# Check skill status
|
||||
/ralph --status
|
||||
|
||||
# Verify superpowers enabled
|
||||
echo $RALPH_SUPERPOWERS_ENABLED
|
||||
|
||||
# Reinitialize Ralph
|
||||
/ralph --reinit
|
||||
```
|
||||
|
||||
**Agents not available?**
|
||||
```bash
|
||||
# List available agents
|
||||
/ralph --list-agents
|
||||
|
||||
# Check agent configuration
|
||||
cat ~/.claude/config/ralph.json | jq '.agents'
|
||||
```
|
||||
|
||||
**MCPs not working?**
|
||||
```bash
|
||||
# Check MCP status
|
||||
/ralph --mcp-status
|
||||
|
||||
# Test MCP connection
|
||||
/ralph --test-mcp websearch
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE for details.
|
||||
|
||||
## Credits
|
||||
|
||||
- **oh-my-opencode**: https://github.com/code-yeongyu/oh-my-opencode
|
||||
- **superpowers**: https://github.com/obra/superpowers
|
||||
- **contains-studio/agents**: https://github.com/contains-studio/agents
|
||||
227
skills/ralph/__main__.py
Executable file
227
skills/ralph/__main__.py
Executable file
@@ -0,0 +1,227 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Command Entry Point
|
||||
|
||||
Main entry point for the /ralph command in Claude Code.
|
||||
This script is invoked when users run /ralph in the CLI.
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import argparse
|
||||
from pathlib import Path
|
||||
|
||||
# Add current directory to path
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
from ralph_agent_integration import RalphAgentIntegration, create_selection_request
|
||||
from meta_agent_orchestrator import MetaAgent
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for /ralph command"""
|
||||
parser = argparse.ArgumentParser(
|
||||
description='RalphLoop - Autonomous agent iteration and orchestration',
|
||||
prog='ralph'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'task',
|
||||
nargs='*',
|
||||
help='Task description or requirements'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mode',
|
||||
choices=['single', 'multi', 'auto'],
|
||||
default='auto',
|
||||
help='Execution mode: single agent, multi-agent, or auto-detect'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--workers',
|
||||
type=int,
|
||||
help='Number of worker agents (for multi-agent mode)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--delegate',
|
||||
action='store_true',
|
||||
help='Enable automatic agent delegation'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--no-delegate',
|
||||
action='store_true',
|
||||
help='Disable automatic agent delegation'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--proactive',
|
||||
action='store_true',
|
||||
help='Enable proactive agents'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--status',
|
||||
action='store_true',
|
||||
help='Show Ralph status and exit'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--list-agents',
|
||||
action='store_true',
|
||||
help='List all available agents and exit'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--observability',
|
||||
action='store_true',
|
||||
help='Enable observability dashboard'
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Check environment variables for defaults
|
||||
multi_agent = os.getenv('RALPH_MULTI_AGENT', '').lower() == 'true'
|
||||
auto_delegate = os.getenv('RALPH_AUTO_DELEGATE', '').lower() == 'true'
|
||||
proactive_agents = os.getenv('RALPH_PROACTIVE_AGENTS', '').lower() == 'true'
|
||||
observability = os.getenv('RALPH_OBSERVABILITY_ENABLED', '').lower() == 'true'
|
||||
|
||||
# Override with command line flags
|
||||
if args.delegate:
|
||||
auto_delegate = True
|
||||
elif args.no_delegate:
|
||||
auto_delegate = False
|
||||
|
||||
if args.proactive:
|
||||
proactive_agents = True
|
||||
|
||||
if args.observability:
|
||||
observability = True
|
||||
|
||||
# Initialize Ralph integration
|
||||
integration = RalphAgentIntegration()
|
||||
|
||||
# Handle special commands
|
||||
if args.status:
|
||||
status = integration.get_agent_status()
|
||||
print(json.dumps(status, indent=2))
|
||||
return 0
|
||||
|
||||
if args.list_agents:
|
||||
agents = integration.registry.get_all_agents()
|
||||
print(f"\n=== Ralph Agents ({len(agents)} total) ===\n")
|
||||
|
||||
by_category = {}
|
||||
for name, agent in agents.items():
|
||||
cat = agent.category.value
|
||||
if cat not in by_category:
|
||||
by_category[cat] = []
|
||||
by_category[cat].append((name, agent))
|
||||
|
||||
for category, agent_list in sorted(by_category.items()):
|
||||
print(f"\n{category.upper()}:")
|
||||
for name, agent in agent_list:
|
||||
print(f" - {name}: {agent.description[:80]}...")
|
||||
|
||||
return 0
|
||||
|
||||
# Get task from arguments or stdin
|
||||
if args.task:
|
||||
task = ' '.join(args.task)
|
||||
else:
|
||||
# Read from stdin if no task provided
|
||||
print("Enter your task (press Ctrl+D when done):")
|
||||
task = sys.stdin.read().strip()
|
||||
|
||||
if not task:
|
||||
parser.print_help()
|
||||
return 1
|
||||
|
||||
# Determine execution mode
|
||||
mode = args.mode
|
||||
if mode == 'auto':
|
||||
# Auto-detect based on task complexity
|
||||
complexity = integration.analyzer.estimate_complexity(task, [])
|
||||
if complexity >= 7.0 or multi_agent:
|
||||
mode = 'multi'
|
||||
else:
|
||||
mode = 'single'
|
||||
|
||||
print(f"\n{'='*60}")
|
||||
print(f"RalphLoop: 'Tackle Until Solved'")
|
||||
print(f"{'='*60}")
|
||||
print(f"\nTask: {task[:100]}")
|
||||
print(f"Mode: {mode}")
|
||||
print(f"Auto-Delegate: {auto_delegate}")
|
||||
print(f"Proactive Agents: {proactive_agents}")
|
||||
print(f"\n{'='*60}\n")
|
||||
|
||||
# Execute task
|
||||
try:
|
||||
if mode == 'multi':
|
||||
# Multi-agent orchestration
|
||||
print("🚀 Starting multi-agent orchestration...")
|
||||
|
||||
orchestrator = MetaAgent()
|
||||
tasks = orchestrator.analyze_project(task)
|
||||
orchestrator.distribute_tasks(tasks)
|
||||
orchestrator.spawn_worker_agents(args.workers or int(os.getenv('RALPH_MAX_WORKERS', 12)))
|
||||
orchestrator.monitor_tasks()
|
||||
|
||||
report = orchestrator.generate_report()
|
||||
print("\n=== EXECUTION REPORT ===")
|
||||
print(json.dumps(report, indent=2))
|
||||
|
||||
else:
|
||||
# Single agent with optional delegation
|
||||
if auto_delegate:
|
||||
print("🔍 Analyzing task for agent delegation...\n")
|
||||
|
||||
response = integration.process_user_message(task)
|
||||
|
||||
print(f"\nAction: {response['action'].upper()}")
|
||||
if 'agent' in response:
|
||||
agent_info = response['agent']
|
||||
print(f"Agent: {agent_info['name']}")
|
||||
print(f"Confidence: {agent_info.get('confidence', 0):.2%}")
|
||||
if agent_info.get('reasons'):
|
||||
print(f"Reasons:")
|
||||
for reason in agent_info['reasons']:
|
||||
print(f" - {reason}")
|
||||
|
||||
# Handle multi-agent workflow if appropriate
|
||||
workflow = integration.suggest_multi_agent_workflow(task)
|
||||
if len(workflow) > 1:
|
||||
print(f"\n📋 Suggested Multi-Agent Workflow ({len(workflow)} phases):")
|
||||
for i, step in enumerate(workflow, 1):
|
||||
print(f" {i}. [{step['phase']}] {step['agent']}: {step['task']}")
|
||||
|
||||
# Ask if user wants to proceed
|
||||
print("\nWould you like to execute this workflow? (Requires multi-agent mode)")
|
||||
|
||||
else:
|
||||
# Direct handling without delegation
|
||||
print("🎯 Processing task directly (no delegation)\n")
|
||||
print("Task would be processed by Claude directly.")
|
||||
|
||||
print(f"\n{'='*60}")
|
||||
print(f"✅ Ralph execution complete")
|
||||
print(f"{'='*60}\n")
|
||||
|
||||
return 0
|
||||
|
||||
except KeyboardInterrupt:
|
||||
print("\n\n⚠️ Ralph interrupted by user")
|
||||
return 130
|
||||
except Exception as e:
|
||||
print(f"\n\n❌ Error: {e}")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
sys.exit(main())
|
||||
572
skills/ralph/agent_capability_registry.py
Executable file
572
skills/ralph/agent_capability_registry.py
Executable file
@@ -0,0 +1,572 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Agent Capability Registry
|
||||
|
||||
Maintains a comprehensive registry of all available agents (contains-studio, custom, etc.)
|
||||
and their capabilities for dynamic selection and routing.
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
from typing import Dict, List, Optional, Set
|
||||
from dataclasses import dataclass, field
|
||||
from enum import Enum
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger('ralph.registry')
|
||||
|
||||
|
||||
class AgentCategory(Enum):
|
||||
"""Categories of agents"""
|
||||
ENGINEERING = "engineering"
|
||||
DESIGN = "design"
|
||||
PRODUCT = "product"
|
||||
MARKETING = "marketing"
|
||||
PROJECT_MANAGEMENT = "project-management"
|
||||
STUDIO_OPERATIONS = "studio-operations"
|
||||
TESTING = "testing"
|
||||
BONUS = "bonus"
|
||||
|
||||
|
||||
class TriggerType(Enum):
|
||||
"""How agents can be triggered"""
|
||||
EXPLICIT = "explicit" # User mentions agent by name
|
||||
KEYWORD = "keyword" # Triggered by specific keywords
|
||||
CONTEXT = "context" # Triggered by project context
|
||||
PROACTIVE = "proactive" # Automatically triggers
|
||||
FILE_PATTERN = "file_pattern" # Triggered by file operations
|
||||
|
||||
|
||||
@dataclass
|
||||
class AgentCapability:
|
||||
"""Represents a single agent's capabilities"""
|
||||
name: str
|
||||
category: AgentCategory
|
||||
description: str
|
||||
keywords: List[str] = field(default_factory=list)
|
||||
trigger_types: List[TriggerType] = field(default_factory=list)
|
||||
file_patterns: List[str] = field(default_factory=list)
|
||||
tools: List[str] = field(default_factory=list)
|
||||
examples: List[Dict] = field(default_factory=list)
|
||||
confidence_threshold: float = 0.5
|
||||
priority: int = 5 # 1-10, higher = preferred
|
||||
|
||||
|
||||
class AgentCapabilityRegistry:
|
||||
"""
|
||||
Registry for all available agents and their capabilities
|
||||
|
||||
Maintains:
|
||||
- Agent metadata and descriptions
|
||||
- Trigger keywords and patterns
|
||||
- Tool access requirements
|
||||
- Usage statistics
|
||||
- Performance metrics
|
||||
"""
|
||||
|
||||
def __init__(self, agents_dir: Optional[str] = None):
|
||||
"""Initialize the registry"""
|
||||
self.agents_dir = agents_dir or os.path.expanduser('~/.claude/agents')
|
||||
self.agents: Dict[str, AgentCapability] = {}
|
||||
self.keyword_index: Dict[str, Set[str]] = {}
|
||||
self.file_pattern_index: Dict[str, Set[str]] = {}
|
||||
|
||||
self._load_agents()
|
||||
|
||||
def _load_agents(self):
|
||||
"""Load all agents from the agents directory"""
|
||||
logger.info(f"Loading agents from {self.agents_dir}")
|
||||
|
||||
# Standard contains-studio structure
|
||||
categories = [
|
||||
'engineering', 'design', 'product', 'marketing',
|
||||
'project-management', 'studio-operations', 'testing', 'bonus'
|
||||
]
|
||||
|
||||
for category in categories:
|
||||
category_path = os.path.join(self.agents_dir, category)
|
||||
if os.path.exists(category_path):
|
||||
self._load_category(category, category_path)
|
||||
|
||||
# Also scan for individual .md files
|
||||
for root, dirs, files in os.walk(self.agents_dir):
|
||||
for file in files:
|
||||
if file.endswith('.md') and file != 'README.md':
|
||||
self._load_agent_file(os.path.join(root, file))
|
||||
|
||||
logger.info(f"Loaded {len(self.agents)} agents")
|
||||
|
||||
def _load_category(self, category: str, category_path: str):
|
||||
"""Load all agents from a category directory"""
|
||||
for file in os.listdir(category_path):
|
||||
if file.endswith('.md'):
|
||||
agent_path = os.path.join(category_path, file)
|
||||
self._load_agent_file(agent_path)
|
||||
|
||||
def _load_agent_file(self, file_path: str):
|
||||
"""Parse and load an agent definition from a markdown file"""
|
||||
try:
|
||||
with open(file_path, 'r') as f:
|
||||
content = f.read()
|
||||
|
||||
# Parse YAML frontmatter
|
||||
frontmatter, body = self._parse_frontmatter(content)
|
||||
|
||||
if not frontmatter.get('name'):
|
||||
return
|
||||
|
||||
# Extract agent info
|
||||
name = frontmatter['name']
|
||||
category = self._infer_category(file_path)
|
||||
description = frontmatter.get('description', '')
|
||||
|
||||
# Extract keywords from description and examples
|
||||
keywords = self._extract_keywords(description)
|
||||
|
||||
# Determine trigger types
|
||||
trigger_types = self._determine_trigger_types(frontmatter, body)
|
||||
|
||||
# Extract file patterns
|
||||
file_patterns = self._extract_file_patterns(body)
|
||||
|
||||
# Get tools
|
||||
tools = frontmatter.get('tools', [])
|
||||
if isinstance(tools, str):
|
||||
tools = [t.strip() for t in tools.split(',')]
|
||||
|
||||
# Extract examples
|
||||
examples = self._extract_examples(body)
|
||||
|
||||
# Create capability
|
||||
capability = AgentCapability(
|
||||
name=name,
|
||||
category=category,
|
||||
description=description,
|
||||
keywords=keywords,
|
||||
trigger_types=trigger_types,
|
||||
file_patterns=file_patterns,
|
||||
tools=tools,
|
||||
examples=examples,
|
||||
priority=self._calculate_priority(category, tools)
|
||||
)
|
||||
|
||||
self.agents[name] = capability
|
||||
|
||||
# Build indexes
|
||||
for keyword in keywords:
|
||||
if keyword not in self.keyword_index:
|
||||
self.keyword_index[keyword] = set()
|
||||
self.keyword_index[keyword].add(name)
|
||||
|
||||
for pattern in file_patterns:
|
||||
if pattern not in self.file_pattern_index:
|
||||
self.file_pattern_index[pattern] = set()
|
||||
self.file_pattern_index[pattern].add(name)
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f"Error loading agent from {file_path}: {e}")
|
||||
|
||||
def _parse_frontmatter(self, content: str) -> tuple:
|
||||
"""Parse YAML frontmatter from markdown"""
|
||||
if not content.startswith('---'):
|
||||
return {}, content
|
||||
|
||||
# Find end of frontmatter
|
||||
end = content.find('---', 4)
|
||||
if end == -1:
|
||||
return {}, content
|
||||
|
||||
frontmatter_str = content[4:end].strip()
|
||||
body = content[end + 4:].strip()
|
||||
|
||||
# Simple YAML parsing
|
||||
frontmatter = {}
|
||||
for line in frontmatter_str.split('\n'):
|
||||
if ':' in line:
|
||||
key, value = line.split(':', 1)
|
||||
frontmatter[key.strip()] = value.strip()
|
||||
|
||||
return frontmatter, body
|
||||
|
||||
def _infer_category(self, file_path: str) -> AgentCategory:
|
||||
"""Infer category from file path"""
|
||||
path_lower = file_path.lower()
|
||||
|
||||
if 'engineering' in path_lower:
|
||||
return AgentCategory.ENGINEERING
|
||||
elif 'design' in path_lower:
|
||||
return AgentCategory.DESIGN
|
||||
elif 'product' in path_lower:
|
||||
return AgentCategory.PRODUCT
|
||||
elif 'marketing' in path_lower:
|
||||
return AgentCategory.MARKETING
|
||||
elif 'project-management' in path_lower or 'project' in path_lower:
|
||||
return AgentCategory.PROJECT_MANAGEMENT
|
||||
elif 'studio-operations' in path_lower or 'operations' in path_lower:
|
||||
return AgentCategory.STUDIO_OPERATIONS
|
||||
elif 'testing' in path_lower or 'test' in path_lower:
|
||||
return AgentCategory.TESTING
|
||||
else:
|
||||
return AgentCategory.BONUS
|
||||
|
||||
def _extract_keywords(self, description: str) -> List[str]:
|
||||
"""Extract keywords from description"""
|
||||
keywords = []
|
||||
|
||||
# Common tech keywords
|
||||
tech_keywords = [
|
||||
'ai', 'ml', 'api', 'backend', 'frontend', 'mobile', 'ios', 'android',
|
||||
'react', 'vue', 'svelte', 'angular', 'typescript', 'javascript',
|
||||
'python', 'rust', 'go', 'java', 'swift', 'kotlin',
|
||||
'ui', 'ux', 'design', 'component', 'layout', 'style',
|
||||
'test', 'testing', 'unit', 'integration', 'e2e',
|
||||
'deploy', 'ci', 'cd', 'docker', 'kubernetes',
|
||||
'database', 'sql', 'nosql', 'redis', 'postgres',
|
||||
'auth', 'authentication', 'oauth', 'jwt',
|
||||
'payment', 'stripe', 'billing',
|
||||
'design', 'figma', 'mockup', 'prototype',
|
||||
'marketing', 'seo', 'social', 'content',
|
||||
'analytics', 'metrics', 'data',
|
||||
'performance', 'optimization', 'speed',
|
||||
'security', 'compliance', 'legal',
|
||||
'documentation', 'docs', 'readme'
|
||||
]
|
||||
|
||||
description_lower = description.lower()
|
||||
|
||||
# Extract mentioned tech keywords
|
||||
for keyword in tech_keywords:
|
||||
if keyword in description_lower:
|
||||
keywords.append(keyword)
|
||||
|
||||
# Extract from examples
|
||||
example_keywords = re.findall(r'example>\nContext: ([^\n]+)', description_lower)
|
||||
keywords.extend(example_keywords)
|
||||
|
||||
# Extract action verbs
|
||||
actions = ['build', 'create', 'design', 'implement', 'refactor', 'test',
|
||||
'deploy', 'optimize', 'fix', 'add', 'integrate', 'setup']
|
||||
for action in actions:
|
||||
if action in description_lower:
|
||||
keywords.append(action)
|
||||
|
||||
return list(set(keywords))
|
||||
|
||||
def _determine_trigger_types(self, frontmatter: Dict, body: str) -> List[TriggerType]:
|
||||
"""Determine how this agent can be triggered"""
|
||||
trigger_types = [TriggerType.EXPLICIT, TriggerType.KEYWORD]
|
||||
|
||||
body_lower = body.lower()
|
||||
|
||||
# Check for proactive triggers
|
||||
if 'proactively' in body_lower or 'trigger automatically' in body_lower:
|
||||
trigger_types.append(TriggerType.PROACTIVE)
|
||||
|
||||
# Check for file pattern triggers
|
||||
if any(ext in body_lower for ext in ['.tsx', '.py', '.rs', '.go', '.java']):
|
||||
trigger_types.append(TriggerType.FILE_PATTERN)
|
||||
|
||||
# Check for context triggers
|
||||
if 'context' in body_lower or 'when' in body_lower:
|
||||
trigger_types.append(TriggerType.CONTEXT)
|
||||
|
||||
return trigger_types
|
||||
|
||||
def _extract_file_patterns(self, body: str) -> List[str]:
|
||||
"""Extract file patterns that trigger this agent"""
|
||||
patterns = []
|
||||
|
||||
# Common patterns
|
||||
extensions = re.findall(r'\.([a-z]+)', body)
|
||||
for ext in set(extensions):
|
||||
if len(ext) <= 5: # Reasonable file extension
|
||||
patterns.append(f'*.{ext}')
|
||||
|
||||
# Path patterns
|
||||
paths = re.findall(r'([a-z-]+/)', body.lower())
|
||||
for path in set(paths):
|
||||
if path in ['src/', 'components/', 'tests/', 'docs/', 'api/']:
|
||||
patterns.append(path)
|
||||
|
||||
return patterns
|
||||
|
||||
def _extract_examples(self, body: str) -> List[Dict]:
|
||||
"""Extract usage examples"""
|
||||
examples = []
|
||||
|
||||
# Find example blocks
|
||||
example_blocks = re.findall(r'<example>(.*?)</example>', body, re.DOTALL)
|
||||
|
||||
for block in example_blocks:
|
||||
context_match = re.search(r'Context: ([^\n]+)', block)
|
||||
user_match = re.search(r'user: "([^"]+)"', block)
|
||||
assistant_match = re.search(r'assistant: "([^"]+)"', block)
|
||||
|
||||
if context_match and user_match:
|
||||
examples.append({
|
||||
'context': context_match.group(1),
|
||||
'user_request': user_match.group(1),
|
||||
'response': assistant_match.group(1) if assistant_match else '',
|
||||
'full_block': block.strip()
|
||||
})
|
||||
|
||||
return examples
|
||||
|
||||
def _calculate_priority(self, category: AgentCategory, tools: List[str]) -> int:
|
||||
"""Calculate agent priority for selection"""
|
||||
priority = 5
|
||||
|
||||
# Engineering agents tend to be higher priority
|
||||
if category == AgentCategory.ENGINEERING:
|
||||
priority = 7
|
||||
elif category == AgentCategory.DESIGN:
|
||||
priority = 6
|
||||
elif category == AgentCategory.TESTING:
|
||||
priority = 8 # Testing is proactive
|
||||
|
||||
# Boost agents with more tools
|
||||
priority += min(len(tools), 3)
|
||||
|
||||
return min(priority, 10)
|
||||
|
||||
def find_agents_by_keywords(self, text: str) -> List[tuple]:
|
||||
"""Find agents matching keywords in text, sorted by relevance"""
|
||||
text_lower = text.lower()
|
||||
words = set(text_lower.split())
|
||||
|
||||
matches = []
|
||||
|
||||
for agent_name, agent in self.agents.items():
|
||||
score = 0
|
||||
|
||||
# Check keyword matches
|
||||
for keyword in agent.keywords:
|
||||
if keyword.lower() in text_lower:
|
||||
score += 1
|
||||
|
||||
# Check examples
|
||||
for example in agent.examples:
|
||||
if example['user_request'].lower() in text_lower:
|
||||
score += 3
|
||||
|
||||
# Check direct name mention
|
||||
if agent_name.lower() in text_lower:
|
||||
score += 10
|
||||
|
||||
if score > 0:
|
||||
matches.append((agent_name, score, agent))
|
||||
|
||||
# Sort by score, then priority
|
||||
matches.sort(key=lambda x: (x[1], x[2].priority), reverse=True)
|
||||
|
||||
return matches
|
||||
|
||||
def find_agents_by_files(self, files: List[str]) -> List[tuple]:
|
||||
"""Find agents that should handle specific file types"""
|
||||
matches = []
|
||||
|
||||
for file_path in files:
|
||||
file_lower = file_path.lower()
|
||||
|
||||
for agent_name, agent in self.agents.items():
|
||||
score = 0
|
||||
|
||||
# Check file patterns
|
||||
for pattern in agent.file_patterns:
|
||||
if pattern in file_lower:
|
||||
score += 1
|
||||
|
||||
if score > 0:
|
||||
matches.append((agent_name, score, agent))
|
||||
|
||||
matches.sort(key=lambda x: (x[1], x[2].priority), reverse=True)
|
||||
return matches
|
||||
|
||||
def find_proactive_agents(self, context: Dict) -> List[str]:
|
||||
"""Find agents that should trigger proactively"""
|
||||
proactive = []
|
||||
|
||||
for agent_name, agent in self.agents.items():
|
||||
if TriggerType.PROACTIVE in agent.trigger_types:
|
||||
# Check context
|
||||
if self._check_proactive_context(agent, context):
|
||||
proactive.append(agent_name)
|
||||
|
||||
return proactive
|
||||
|
||||
def _check_proactive_context(self, agent: AgentCapability, context: Dict) -> bool:
|
||||
"""Check if agent should trigger proactively in this context"""
|
||||
# Test-writer-fixer triggers after code changes
|
||||
if agent.name == 'test-writer-fixer':
|
||||
return context.get('code_modified', False)
|
||||
|
||||
# Whimsy-injector triggers after UI changes
|
||||
if agent.name == 'whimsy-injector':
|
||||
return context.get('ui_modified', False)
|
||||
|
||||
# Studio-coach triggers on complex tasks
|
||||
if agent.name == 'studio-coach':
|
||||
return context.get('complexity', 0) > 7
|
||||
|
||||
return False
|
||||
|
||||
def get_agent(self, name: str) -> Optional[AgentCapability]:
|
||||
"""Get agent by name"""
|
||||
return self.agents.get(name)
|
||||
|
||||
def get_all_agents(self) -> Dict[str, AgentCapability]:
|
||||
"""Get all registered agents"""
|
||||
return self.agents
|
||||
|
||||
def get_agents_by_category(self, category: AgentCategory) -> List[AgentCapability]:
|
||||
"""Get all agents in a category"""
|
||||
return [a for a in self.agents.values() if a.category == category]
|
||||
|
||||
|
||||
# Pre-configured agent mappings for contains-studio agents
|
||||
CONTAINS_STUDIO_AGENTS = {
|
||||
# Engineering
|
||||
'ai-engineer': {
|
||||
'keywords': ['ai', 'ml', 'llm', 'machine learning', 'recommendation', 'chatbot', 'computer vision'],
|
||||
'triggers': ['implement ai', 'add ml', 'integrate llm', 'build recommendation']
|
||||
},
|
||||
'backend-architect': {
|
||||
'keywords': ['api', 'backend', 'server', 'database', 'microservices'],
|
||||
'triggers': ['design api', 'build backend', 'create database schema']
|
||||
},
|
||||
'devops-automator': {
|
||||
'keywords': ['deploy', 'ci/cd', 'docker', 'kubernetes', 'infrastructure'],
|
||||
'triggers': ['set up deployment', 'configure ci', 'deploy to production']
|
||||
},
|
||||
'frontend-developer': {
|
||||
'keywords': ['frontend', 'ui', 'component', 'react', 'vue', 'svelte'],
|
||||
'triggers': ['build component', 'create ui', 'implement frontend']
|
||||
},
|
||||
'mobile-app-builder': {
|
||||
'keywords': ['mobile', 'ios', 'android', 'react native', 'swift', 'kotlin'],
|
||||
'triggers': ['build mobile app', 'create ios', 'develop android']
|
||||
},
|
||||
'rapid-prototyper': {
|
||||
'keywords': ['mvp', 'prototype', 'quick', 'scaffold', 'new app'],
|
||||
'triggers': ['create prototype', 'build mvp', 'scaffold project', 'new app idea']
|
||||
},
|
||||
'test-writer-fixer': {
|
||||
'keywords': ['test', 'testing', 'coverage'],
|
||||
'triggers': ['write tests', 'add coverage', 'test this'],
|
||||
'proactive': True
|
||||
},
|
||||
|
||||
# Design
|
||||
'brand-guardian': {
|
||||
'keywords': ['brand', 'logo', 'identity', 'guidelines'],
|
||||
'triggers': ['design brand', 'create logo', 'brand guidelines']
|
||||
},
|
||||
'ui-designer': {
|
||||
'keywords': ['ui', 'interface', 'design', 'component design'],
|
||||
'triggers': ['design ui', 'create interface', 'ui design']
|
||||
},
|
||||
'ux-researcher': {
|
||||
'keywords': ['ux', 'user research', 'usability', 'user experience'],
|
||||
'triggers': ['user research', 'ux study', 'usability test']
|
||||
},
|
||||
'visual-storyteller': {
|
||||
'keywords': ['visual', 'story', 'graphic', 'illustration'],
|
||||
'triggers': ['create visual', 'design graphics', 'story telling']
|
||||
},
|
||||
'whimsy-injector': {
|
||||
'keywords': ['delight', 'surprise', 'fun', 'animation'],
|
||||
'triggers': ['add delight', 'make fun', 'surprise users'],
|
||||
'proactive': True
|
||||
},
|
||||
|
||||
# Product
|
||||
'feedback-synthesizer': {
|
||||
'keywords': ['feedback', 'reviews', 'complaints', 'user input'],
|
||||
'triggers': ['analyze feedback', 'synthesize reviews', 'user complaints']
|
||||
},
|
||||
'sprint-prioritizer': {
|
||||
'keywords': ['sprint', 'priority', 'roadmap', 'planning'],
|
||||
'triggers': ['plan sprint', 'prioritize features', 'sprint planning']
|
||||
},
|
||||
'trend-researcher': {
|
||||
'keywords': ['trend', 'viral', 'market research', 'opportunity'],
|
||||
'triggers': ['research trends', 'whats trending', 'market analysis']
|
||||
},
|
||||
|
||||
# Marketing
|
||||
'app-store-optimizer': {
|
||||
'keywords': ['app store', 'aso', 'store listing', 'keywords'],
|
||||
'triggers': ['optimize app store', 'improve aso', 'store listing']
|
||||
},
|
||||
'content-creator': {
|
||||
'keywords': ['content', 'blog', 'social media', 'copy'],
|
||||
'triggers': ['create content', 'write blog', 'social content']
|
||||
},
|
||||
'growth-hacker': {
|
||||
'keywords': ['growth', 'viral', 'acquisition', 'funnel'],
|
||||
'triggers': ['growth strategy', 'viral loop', 'acquisition']
|
||||
},
|
||||
'tiktok-strategist': {
|
||||
'keywords': ['tiktok', 'video', 'viral', 'content'],
|
||||
'triggers': ['tiktok strategy', 'viral video', 'tiktok content']
|
||||
},
|
||||
|
||||
# Project Management
|
||||
'experiment-tracker': {
|
||||
'keywords': ['experiment', 'a/b test', 'feature flag'],
|
||||
'triggers': ['track experiment', 'a/b testing', 'feature flags'],
|
||||
'proactive': True
|
||||
},
|
||||
'project-shipper': {
|
||||
'keywords': ['launch', 'ship', 'release', 'deploy'],
|
||||
'triggers': ['prepare launch', 'ship project', 'release management']
|
||||
},
|
||||
'studio-producer': {
|
||||
'keywords': ['coordinate', 'team', 'workflow', 'manage'],
|
||||
'triggers': ['coordinate team', 'manage project', 'workflow']
|
||||
},
|
||||
|
||||
# Testing
|
||||
'api-tester': {
|
||||
'keywords': ['api test', 'load test', 'endpoint testing'],
|
||||
'triggers': ['test api', 'load testing', 'endpoint test']
|
||||
},
|
||||
'performance-benchmarker': {
|
||||
'keywords': ['performance', 'benchmark', 'speed', 'optimization'],
|
||||
'triggers': ['benchmark performance', 'speed test', 'optimize']
|
||||
},
|
||||
'test-results-analyzer': {
|
||||
'keywords': ['test results', 'analyze tests', 'test failures'],
|
||||
'triggers': ['analyze test results', 'test failures', 'test report']
|
||||
},
|
||||
|
||||
# Studio Operations
|
||||
'analytics-reporter': {
|
||||
'keywords': ['analytics', 'metrics', 'data', 'reports'],
|
||||
'triggers': ['generate report', 'analyze metrics', 'analytics']
|
||||
},
|
||||
'finance-tracker': {
|
||||
'keywords': ['finance', 'budget', 'costs', 'revenue'],
|
||||
'triggers': ['track costs', 'budget analysis', 'financial report']
|
||||
},
|
||||
'infrastructure-maintainer': {
|
||||
'keywords': ['infrastructure', 'servers', 'monitoring', 'uptime'],
|
||||
'triggers': ['check infrastructure', 'server health', 'monitoring']
|
||||
},
|
||||
'support-responder': {
|
||||
'keywords': ['support', 'help', 'customer service'],
|
||||
'triggers': ['handle support', 'customer inquiry', 'help ticket']
|
||||
},
|
||||
|
||||
# Bonus
|
||||
'joker': {
|
||||
'keywords': ['joke', 'humor', 'funny', 'laugh'],
|
||||
'triggers': ['tell joke', 'add humor', 'make funny']
|
||||
},
|
||||
'studio-coach': {
|
||||
'keywords': ['coach', 'guidance', 'help', 'advice'],
|
||||
'triggers': ['need help', 'guidance', 'coach'],
|
||||
'proactive': True
|
||||
}
|
||||
}
|
||||
547
skills/ralph/dynamic_agent_selector.py
Executable file
547
skills/ralph/dynamic_agent_selector.py
Executable file
@@ -0,0 +1,547 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Dynamic Agent Selector
|
||||
|
||||
Intelligently selects and routes to the most appropriate agent based on:
|
||||
- User request analysis
|
||||
- Project context
|
||||
- File types being modified
|
||||
- Current task state
|
||||
- Agent capabilities and performance history
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import time
|
||||
from typing import Dict, List, Optional, Tuple, Set
|
||||
from dataclasses import dataclass, field
|
||||
from enum import Enum
|
||||
import logging
|
||||
from collections import defaultdict
|
||||
|
||||
logger = logging.getLogger('ralph.selector')
|
||||
|
||||
|
||||
class TaskPhase(Enum):
|
||||
"""Phases of a task lifecycle"""
|
||||
PLANNING = "planning"
|
||||
DESIGN = "design"
|
||||
IMPLEMENTATION = "implementation"
|
||||
TESTING = "testing"
|
||||
DEPLOYMENT = "deployment"
|
||||
MAINTENANCE = "maintenance"
|
||||
|
||||
|
||||
class IntentType(Enum):
|
||||
"""Types of user intents"""
|
||||
CREATE = "create"
|
||||
MODIFY = "modify"
|
||||
FIX = "fix"
|
||||
ANALYZE = "analyze"
|
||||
DEPLOY = "deploy"
|
||||
TEST = "test"
|
||||
DESIGN = "design"
|
||||
RESEARCH = "research"
|
||||
OPTIMIZE = "optimize"
|
||||
|
||||
|
||||
@dataclass
|
||||
class AgentSelectionScore:
|
||||
"""Score for an agent selection decision"""
|
||||
agent_name: str
|
||||
score: float
|
||||
reasons: List[str] = field(default_factory=list)
|
||||
confidence: float = 0.0
|
||||
estimated_duration: int = 300 # seconds
|
||||
|
||||
|
||||
@dataclass
|
||||
class TaskContext:
|
||||
"""Context about the current task"""
|
||||
phase: TaskPhase
|
||||
intent: IntentType
|
||||
files_modified: List[str] = field(default_factory=list)
|
||||
files_touched: List[str] = field(default_factory=list)
|
||||
previous_agents: Set[str] = field(default_factory=set)
|
||||
user_history: List[str] = field(default_factory=list)
|
||||
project_type: Optional[str] = None
|
||||
complexity_score: float = 5.0
|
||||
time_constraint: Optional[int] = None # seconds
|
||||
|
||||
|
||||
@dataclass
|
||||
class SelectionRequest:
|
||||
"""Request for agent selection"""
|
||||
user_message: str
|
||||
context: TaskContext
|
||||
available_agents: Dict[str, dict]
|
||||
performance_history: Dict[str, dict] = field(default_factory=dict)
|
||||
|
||||
|
||||
class DynamicAgentSelector:
|
||||
"""
|
||||
Dynamically selects the best agent for each task
|
||||
|
||||
Uses multiple signals:
|
||||
- Semantic similarity to agent descriptions
|
||||
- Keyword matching
|
||||
- File type analysis
|
||||
- Task phase awareness
|
||||
- Historical performance
|
||||
- Collaborative filtering
|
||||
"""
|
||||
|
||||
def __init__(self, registry):
|
||||
"""Initialize the selector"""
|
||||
self.registry = registry
|
||||
self.selection_history: List[Dict] = []
|
||||
self.performance_cache: Dict[str, List[float]] = defaultdict(list)
|
||||
|
||||
def select_agent(self, request: SelectionRequest) -> AgentSelectionScore:
|
||||
"""
|
||||
Select the best agent for the given request
|
||||
|
||||
Args:
|
||||
request: Selection request with context
|
||||
|
||||
Returns:
|
||||
AgentSelectionScore with selected agent and reasoning
|
||||
"""
|
||||
logger.info(f"Selecting agent for: {request.user_message[:100]}...")
|
||||
|
||||
# Get candidate agents
|
||||
candidates = self._get_candidates(request)
|
||||
|
||||
if not candidates:
|
||||
# Fallback to general purpose
|
||||
return AgentSelectionScore(
|
||||
agent_name="claude",
|
||||
score=0.5,
|
||||
reasons=["No specialized agent found, using general purpose"],
|
||||
confidence=0.3
|
||||
)
|
||||
|
||||
# Score each candidate
|
||||
scores = []
|
||||
for agent_name in candidates:
|
||||
score = self._score_agent(agent_name, request)
|
||||
scores.append(score)
|
||||
|
||||
# Sort by score
|
||||
scores.sort(key=lambda x: x.score, reverse=True)
|
||||
|
||||
# Get best match
|
||||
best = scores[0]
|
||||
|
||||
# Log selection
|
||||
self._log_selection(request, best)
|
||||
|
||||
return best
|
||||
|
||||
def _get_candidates(self, request: SelectionRequest) -> List[str]:
|
||||
"""Get candidate agents for the request"""
|
||||
candidates = set()
|
||||
|
||||
# Keyword matching
|
||||
keyword_matches = self.registry.find_agents_by_keywords(request.user_message)
|
||||
for agent_name, score, agent in keyword_matches[:5]: # Top 5
|
||||
candidates.add(agent_name)
|
||||
|
||||
# File-based matching
|
||||
if request.context.files_modified:
|
||||
file_matches = self.registry.find_agents_by_files(request.context.files_modified)
|
||||
for agent_name, score, agent in file_matches[:3]:
|
||||
candidates.add(agent_name)
|
||||
|
||||
# Phase-based candidates
|
||||
phase_candidates = self._get_phase_candidates(request.context.phase)
|
||||
candidates.update(phase_candidates)
|
||||
|
||||
# Intent-based candidates
|
||||
intent_candidates = self._get_intent_candidates(request.context.intent)
|
||||
candidates.update(intent_candidates)
|
||||
|
||||
# Context-aware candidates
|
||||
context_candidates = self._get_context_candidates(request.context)
|
||||
candidates.update(context_candidates)
|
||||
|
||||
return list(candidates)
|
||||
|
||||
def _score_agent(self, agent_name: str, request: SelectionRequest) -> AgentSelectionScore:
|
||||
"""Score an agent for the request"""
|
||||
agent = self.registry.get_agent(agent_name)
|
||||
if not agent:
|
||||
return AgentSelectionScore(agent_name=agent_name, score=0.0)
|
||||
|
||||
score = 0.0
|
||||
reasons = []
|
||||
|
||||
# 1. Keyword matching (0-40 points)
|
||||
keyword_score = self._score_keywords(agent, request.user_message)
|
||||
score += keyword_score
|
||||
if keyword_score > 0:
|
||||
reasons.append(f"Keyword match: {keyword_score:.1f}")
|
||||
|
||||
# 2. Semantic similarity (0-25 points)
|
||||
semantic_score = self._score_semantic(agent, request)
|
||||
score += semantic_score
|
||||
if semantic_score > 0:
|
||||
reasons.append(f"Semantic fit: {semantic_score:.1f}")
|
||||
|
||||
# 3. File type matching (0-20 points)
|
||||
file_score = self._score_files(agent, request.context)
|
||||
score += file_score
|
||||
if file_score > 0:
|
||||
reasons.append(f"File match: {file_score:.1f}")
|
||||
|
||||
# 4. Phase appropriateness (0-10 points)
|
||||
phase_score = self._score_phase(agent, request.context.phase)
|
||||
score += phase_score
|
||||
if phase_score > 0:
|
||||
reasons.append(f"Phase fit: {phase_score:.1f}")
|
||||
|
||||
# 5. Historical performance (0-5 points)
|
||||
perf_score = self._score_performance(agent_name)
|
||||
score += perf_score
|
||||
if perf_score > 0:
|
||||
reasons.append(f"Performance bonus: {perf_score:.1f}")
|
||||
|
||||
# Calculate confidence
|
||||
confidence = min(score / 50.0, 1.0)
|
||||
|
||||
# Estimate duration based on agent and complexity
|
||||
duration = self._estimate_duration(agent, request.context)
|
||||
|
||||
return AgentSelectionScore(
|
||||
agent_name=agent_name,
|
||||
score=score,
|
||||
reasons=reasons,
|
||||
confidence=confidence,
|
||||
estimated_duration=duration
|
||||
)
|
||||
|
||||
def _score_keywords(self, agent, message: str) -> float:
|
||||
"""Score keyword matching"""
|
||||
message_lower = message.lower()
|
||||
score = 0.0
|
||||
|
||||
for keyword in agent.keywords:
|
||||
if keyword.lower() in message_lower:
|
||||
# Rare keywords get more points
|
||||
weight = 10.0 / len(agent.keywords)
|
||||
score += weight
|
||||
|
||||
# Direct name mention
|
||||
if agent.name.lower() in message_lower:
|
||||
score += 20.0
|
||||
|
||||
return min(score, 40.0)
|
||||
|
||||
def _score_semantic(self, agent, request: SelectionRequest) -> float:
|
||||
"""Score semantic similarity"""
|
||||
score = 0.0
|
||||
|
||||
# Check against examples
|
||||
for example in agent.examples:
|
||||
example_text = example['user_request'].lower()
|
||||
request_text = request.user_message.lower()
|
||||
|
||||
# Simple word overlap
|
||||
example_words = set(example_text.split())
|
||||
request_words = set(request_text.split())
|
||||
|
||||
if example_words and request_words:
|
||||
overlap = len(example_words & request_words)
|
||||
total = len(example_words | request_words)
|
||||
similarity = overlap / total if total > 0 else 0
|
||||
|
||||
score += similarity * 15.0
|
||||
|
||||
return min(score, 25.0)
|
||||
|
||||
def _score_files(self, agent, context: TaskContext) -> float:
|
||||
"""Score file type matching"""
|
||||
if not context.files_modified and not context.files_touched:
|
||||
return 0.0
|
||||
|
||||
all_files = context.files_modified + context.files_touched
|
||||
score = 0.0
|
||||
|
||||
for file_path in all_files:
|
||||
file_lower = file_path.lower()
|
||||
|
||||
for pattern in agent.file_patterns:
|
||||
if pattern.lower() in file_lower:
|
||||
score += 5.0
|
||||
|
||||
return min(score, 20.0)
|
||||
|
||||
def _score_phase(self, agent, phase: TaskPhase) -> float:
|
||||
"""Score phase appropriateness"""
|
||||
phase_mappings = {
|
||||
TaskPhase.PLANNING: ['sprint-prioritizer', 'studio-producer'],
|
||||
TaskPhase.DESIGN: ['ui-designer', 'ux-researcher', 'brand-guardian'],
|
||||
TaskPhase.IMPLEMENTATION: ['frontend-developer', 'backend-architect', 'ai-engineer'],
|
||||
TaskPhase.TESTING: ['test-writer-fixer', 'api-tester'],
|
||||
TaskPhase.DEPLOYMENT: ['devops-automator', 'project-shipper'],
|
||||
TaskPhase.MAINTENANCE: ['infrastructure-maintainer', 'support-responder']
|
||||
}
|
||||
|
||||
recommended = phase_mappings.get(phase, [])
|
||||
if agent.name in recommended:
|
||||
return 10.0
|
||||
|
||||
return 0.0
|
||||
|
||||
def _score_performance(self, agent_name: str) -> float:
|
||||
"""Score based on historical performance"""
|
||||
if agent_name not in self.performance_cache:
|
||||
return 2.5 # Neutral score for unknown
|
||||
|
||||
scores = self.performance_cache[agent_name]
|
||||
if not scores:
|
||||
return 2.5
|
||||
|
||||
# Average recent performance (last 10)
|
||||
recent = scores[-10:]
|
||||
avg = sum(recent) / len(recent)
|
||||
|
||||
# Convert to bonus
|
||||
return (avg - 0.5) * 5.0 # Range: -2.5 to +2.5
|
||||
|
||||
def _estimate_duration(self, agent, context: TaskContext) -> int:
|
||||
"""Estimate task duration in seconds"""
|
||||
base_duration = 300 # 5 minutes
|
||||
|
||||
# Adjust by complexity
|
||||
complexity_multiplier = 1.0 + (context.complexity_score / 10.0)
|
||||
|
||||
# Adjust by agent speed (from category)
|
||||
category_speeds = {
|
||||
'engineering': 1.2,
|
||||
'design': 1.0,
|
||||
'testing': 0.8,
|
||||
'product': 1.0
|
||||
}
|
||||
|
||||
speed = category_speeds.get(agent.category.value, 1.0)
|
||||
|
||||
duration = base_duration * complexity_multiplier * speed
|
||||
|
||||
return int(duration)
|
||||
|
||||
def _get_phase_candidates(self, phase: TaskPhase) -> List[str]:
|
||||
"""Get agents appropriate for current phase"""
|
||||
phase_mappings = {
|
||||
TaskPhase.PLANNING: ['sprint-prioritizer', 'studio-producer', 'rapid-prototyper'],
|
||||
TaskPhase.DESIGN: ['ui-designer', 'ux-researcher', 'brand-guardian', 'visual-storyteller'],
|
||||
TaskPhase.IMPLEMENTATION: ['frontend-developer', 'backend-architect', 'ai-engineer',
|
||||
'mobile-app-builder', 'rapid-prototyper'],
|
||||
TaskPhase.TESTING: ['test-writer-fixer', 'api-tester', 'performance-benchmarker'],
|
||||
TaskPhase.DEPLOYMENT: ['devops-automator', 'project-shipper'],
|
||||
TaskPhase.MAINTENANCE: ['infrastructure-maintainer', 'support-responder']
|
||||
}
|
||||
|
||||
return phase_mappings.get(phase, [])
|
||||
|
||||
def _get_intent_candidates(self, intent: IntentType) -> List[str]:
|
||||
"""Get agents for specific intent"""
|
||||
intent_mappings = {
|
||||
IntentType.CREATE: ['rapid-prototyper', 'frontend-developer', 'backend-architect'],
|
||||
IntentType.MODIFY: ['frontend-developer', 'backend-architect', 'ui-designer'],
|
||||
IntentType.FIX: ['test-writer-fixer', 'backend-architect', 'frontend-developer'],
|
||||
IntentType.ANALYZE: ['analytics-reporter', 'feedback-synthesizer', 'test-results-analyzer'],
|
||||
IntentType.DEPLOY: ['devops-automator', 'project-shipper'],
|
||||
IntentType.TEST: ['test-writer-fixer', 'api-tester', 'performance-benchmarker'],
|
||||
IntentType.DESIGN: ['ui-designer', 'ux-researcher', 'brand-guardian'],
|
||||
IntentType.RESEARCH: ['trend-researcher', 'ux-researcher'],
|
||||
IntentType.OPTIMIZE: ['performance-benchmarker', 'backend-architect']
|
||||
}
|
||||
|
||||
return intent_mappings.get(intent, [])
|
||||
|
||||
def _get_context_candidates(self, context: TaskContext) -> List[str]:
|
||||
"""Get agents based on context"""
|
||||
candidates = []
|
||||
|
||||
# Proactive agents
|
||||
proactive = self.registry.find_proactive_agents({
|
||||
'code_modified': len(context.files_modified) > 0,
|
||||
'ui_modified': any(f.endswith(('.tsx', '.jsx', '.vue', '.svelte'))
|
||||
for f in context.files_modified),
|
||||
'complexity': context.complexity_score
|
||||
})
|
||||
candidates.extend(proactive)
|
||||
|
||||
# Project type specific
|
||||
if context.project_type:
|
||||
type_candidates = self._get_project_type_candidates(context.project_type)
|
||||
candidates.extend(type_candidates)
|
||||
|
||||
return candidates
|
||||
|
||||
def _get_project_type_candidates(self, project_type: str) -> List[str]:
|
||||
"""Get agents for specific project types"""
|
||||
mappings = {
|
||||
'mobile': ['mobile-app-builder'],
|
||||
'web': ['frontend-developer', 'ui-designer'],
|
||||
'api': ['backend-architect', 'api-tester'],
|
||||
'ml': ['ai-engineer'],
|
||||
'game': ['frontend-developer', 'ui-designer']
|
||||
}
|
||||
|
||||
return mappings.get(project_type.lower(), [])
|
||||
|
||||
def record_performance(self, agent_name: str, satisfaction: float):
|
||||
"""Record agent performance for future selections"""
|
||||
self.performance_cache[agent_name].append(satisfaction)
|
||||
|
||||
# Keep only last 100
|
||||
if len(self.performance_cache[agent_name]) > 100:
|
||||
self.performance_cache[agent_name] = self.performance_cache[agent_name][-100:]
|
||||
|
||||
def _log_selection(self, request: SelectionRequest, selection: AgentSelectionScore):
|
||||
"""Log selection for analysis"""
|
||||
log_entry = {
|
||||
'timestamp': time.time(),
|
||||
'user_message': request.user_message,
|
||||
'context': {
|
||||
'phase': request.context.phase.value,
|
||||
'intent': request.context.intent.value,
|
||||
'files': request.context.files_modified
|
||||
},
|
||||
'selected_agent': selection.agent_name,
|
||||
'score': selection.score,
|
||||
'confidence': selection.confidence,
|
||||
'reasons': selection.reasons
|
||||
}
|
||||
|
||||
self.selection_history.append(log_entry)
|
||||
|
||||
# Keep history manageable
|
||||
if len(self.selection_history) > 1000:
|
||||
self.selection_history = self.selection_history[-1000:]
|
||||
|
||||
logger.info(f"Selected {selection.agent_name} (score: {selection.score:.1f}, confidence: {selection.confidence:.2f})")
|
||||
|
||||
|
||||
class RealTimeAnalyzer:
|
||||
"""Analyzes user input in real-time to determine task characteristics"""
|
||||
|
||||
@staticmethod
|
||||
def detect_intent(message: str) -> IntentType:
|
||||
"""Detect the user's intent from their message"""
|
||||
message_lower = message.lower()
|
||||
|
||||
intent_patterns = {
|
||||
IntentType.CREATE: ['create', 'build', 'make', 'add', 'implement', 'develop', 'scaffold'],
|
||||
IntentType.MODIFY: ['modify', 'change', 'update', 'refactor', 'edit', 'improve'],
|
||||
IntentType.FIX: ['fix', 'bug', 'error', 'issue', 'problem', 'broken', 'not working'],
|
||||
IntentType.ANALYZE: ['analyze', 'check', 'review', 'audit', 'examine', 'investigate'],
|
||||
IntentType.DEPLOY: ['deploy', 'release', 'ship', 'publish', 'launch'],
|
||||
IntentType.TEST: ['test', 'testing', 'verify', 'validate'],
|
||||
IntentType.DESIGN: ['design', 'ui', 'ux', 'mockup', 'wireframe'],
|
||||
IntentType.RESEARCH: ['research', 'find', 'look into', 'investigate', 'explore'],
|
||||
IntentType.OPTIMIZE: ['optimize', 'improve performance', 'speed up', 'faster']
|
||||
}
|
||||
|
||||
best_intent = IntentType.CREATE
|
||||
best_score = 0
|
||||
|
||||
for intent, patterns in intent_patterns.items():
|
||||
score = sum(1 for pattern in patterns if pattern in message_lower)
|
||||
if score > best_score:
|
||||
best_score = score
|
||||
best_intent = intent
|
||||
|
||||
return best_intent
|
||||
|
||||
@staticmethod
|
||||
def detect_phase(message: str, context: Dict) -> TaskPhase:
|
||||
"""Detect the current task phase"""
|
||||
message_lower = message.lower()
|
||||
|
||||
phase_patterns = {
|
||||
TaskPhase.PLANNING: ['plan', 'roadmap', 'sprint', 'backlog', 'priority'],
|
||||
TaskPhase.DESIGN: ['design', 'mockup', 'wireframe', 'ui', 'ux'],
|
||||
TaskPhase.IMPLEMENTATION: ['implement', 'code', 'develop', 'build', 'create'],
|
||||
TaskPhase.TESTING: ['test', 'testing', 'verify', 'coverage'],
|
||||
TaskPhase.DEPLOYMENT: ['deploy', 'release', 'ship', 'launch'],
|
||||
TaskPhase.MAINTENANCE: ['monitor', 'maintain', 'update', 'fix']
|
||||
}
|
||||
|
||||
# Check message first
|
||||
for phase, patterns in phase_patterns.items():
|
||||
if any(pattern in message_lower for pattern in patterns):
|
||||
return phase
|
||||
|
||||
# Fall back to context
|
||||
files = context.get('files_modified', [])
|
||||
if any(f.endswith('.test.') for f in files):
|
||||
return TaskPhase.TESTING
|
||||
if any(f.endswith(('.tsx', '.jsx', '.vue')) for f in files):
|
||||
return TaskPhase.IMPLEMENTATION
|
||||
|
||||
return TaskPhase.IMPLEMENTATION
|
||||
|
||||
@staticmethod
|
||||
def estimate_complexity(message: str, files: List[str]) -> float:
|
||||
"""Estimate task complexity (1-10)"""
|
||||
complexity = 5.0 # Base complexity
|
||||
|
||||
# Message complexity
|
||||
words = message.split()
|
||||
complexity += min(len(words) / 50, 2.0)
|
||||
|
||||
# File complexity
|
||||
complexity += min(len(files) / 5, 2.0)
|
||||
|
||||
# Keyword complexity
|
||||
complex_keywords = ['architecture', 'integration', 'migration', 'refactor', 'system']
|
||||
complexity += sum(0.5 for kw in complex_keywords if kw in message.lower())
|
||||
|
||||
return min(complexity, 10.0)
|
||||
|
||||
@staticmethod
|
||||
def detect_project_type(files: List[str]) -> Optional[str]:
|
||||
"""Detect project type from files"""
|
||||
if not files:
|
||||
return None
|
||||
|
||||
file_exts = [os.path.splitext(f)[1] for f in files]
|
||||
|
||||
if '.swift' in file_exts or '.kt' in file_exts:
|
||||
return 'mobile'
|
||||
elif '.tsx' in file_exts or '.jsx' in file_exts:
|
||||
return 'web'
|
||||
elif any(f.endswith('api.py') or f.endswith('controller.py') for f in files):
|
||||
return 'api'
|
||||
elif any('model' in f for f in files):
|
||||
return 'ml'
|
||||
|
||||
return 'web' # Default
|
||||
|
||||
|
||||
def create_selection_request(user_message: str, context: Dict) -> SelectionRequest:
|
||||
"""Create a selection request from raw data"""
|
||||
analyzer = RealTimeAnalyzer()
|
||||
|
||||
return SelectionRequest(
|
||||
user_message=user_message,
|
||||
context=TaskContext(
|
||||
phase=analyzer.detect_phase(user_message, context),
|
||||
intent=analyzer.detect_intent(user_message),
|
||||
files_modified=context.get('files_modified', []),
|
||||
files_touched=context.get('files_touched', []),
|
||||
previous_agents=set(context.get('previous_agents', [])),
|
||||
user_history=context.get('user_history', []),
|
||||
project_type=analyzer.detect_project_type(context.get('files_modified', [])),
|
||||
complexity_score=analyzer.estimate_complexity(
|
||||
user_message,
|
||||
context.get('files_modified', [])
|
||||
)
|
||||
),
|
||||
available_agents=context.get('available_agents', {}),
|
||||
performance_history=context.get('performance_history', {})
|
||||
)
|
||||
613
skills/ralph/meta_agent_orchestrator.py
Executable file
613
skills/ralph/meta_agent_orchestrator.py
Executable file
@@ -0,0 +1,613 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Meta-Agent Orchestrator
|
||||
|
||||
Manages multi-agent orchestration for Ralph, including:
|
||||
- Task breakdown and dependency management
|
||||
- Worker agent spawning and coordination
|
||||
- File locking and conflict resolution
|
||||
- Progress tracking and observability
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import redis
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
from typing import List, Dict, Optional, Set
|
||||
from dataclasses import dataclass, asdict
|
||||
from enum import Enum
|
||||
import hashlib
|
||||
import logging
|
||||
|
||||
# Configure logging
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
|
||||
handlers=[
|
||||
logging.FileHandler('.ralph/multi-agent.log'),
|
||||
logging.StreamHandler()
|
||||
]
|
||||
)
|
||||
logger = logging.getLogger('ralph.orchestrator')
|
||||
|
||||
|
||||
class TaskType(Enum):
|
||||
"""Types of tasks that can be executed"""
|
||||
ANALYSIS = "analysis"
|
||||
FRONTEND = "frontend"
|
||||
BACKEND = "backend"
|
||||
TESTING = "testing"
|
||||
DOCS = "docs"
|
||||
REFACTOR = "refactor"
|
||||
DEPLOYMENT = "deployment"
|
||||
|
||||
|
||||
class TaskStatus(Enum):
|
||||
"""Task execution status"""
|
||||
PENDING = "pending"
|
||||
QUEUED = "queued"
|
||||
RUNNING = "running"
|
||||
COMPLETE = "complete"
|
||||
FAILED = "failed"
|
||||
CANCELLED = "cancelled"
|
||||
|
||||
|
||||
class AgentStatus(Enum):
|
||||
"""Worker agent status"""
|
||||
IDLE = "idle"
|
||||
BUSY = "busy"
|
||||
ERROR = "error"
|
||||
OFFLINE = "offline"
|
||||
|
||||
|
||||
@dataclass
|
||||
class Task:
|
||||
"""Represents a unit of work"""
|
||||
id: str
|
||||
type: TaskType
|
||||
description: str
|
||||
dependencies: List[str]
|
||||
files: List[str]
|
||||
priority: int = 5
|
||||
specialization: Optional[str] = None
|
||||
timeout: int = 300
|
||||
retry_count: int = 0
|
||||
max_retries: int = 3
|
||||
status: TaskStatus = TaskStatus.PENDING
|
||||
result: Optional[str] = None
|
||||
error: Optional[str] = None
|
||||
created_at: float = None
|
||||
started_at: Optional[float] = None
|
||||
completed_at: Optional[float] = None
|
||||
|
||||
def __post_init__(self):
|
||||
if self.created_at is None:
|
||||
self.created_at = time.time()
|
||||
|
||||
def to_dict(self) -> Dict:
|
||||
"""Convert to dictionary, handling enums"""
|
||||
data = asdict(self)
|
||||
data['type'] = self.type.value
|
||||
data['status'] = self.status.value
|
||||
return data
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, data: Dict) -> 'Task':
|
||||
"""Create from dictionary, handling enums"""
|
||||
if isinstance(data.get('type'), str):
|
||||
data['type'] = TaskType(data['type'])
|
||||
if isinstance(data.get('status'), str):
|
||||
data['status'] = TaskStatus(data['status'])
|
||||
return cls(**data)
|
||||
|
||||
|
||||
@dataclass
|
||||
class AgentInfo:
|
||||
"""Information about a worker agent"""
|
||||
id: str
|
||||
specialization: str
|
||||
status: AgentStatus
|
||||
current_task: Optional[str] = None
|
||||
working_files: List[str] = None
|
||||
progress: float = 0.0
|
||||
completed_count: int = 0
|
||||
last_heartbeat: float = None
|
||||
|
||||
def __post_init__(self):
|
||||
if self.working_files is None:
|
||||
self.working_files = []
|
||||
if self.last_heartbeat is None:
|
||||
self.last_heartbeat = time.time()
|
||||
|
||||
def to_dict(self) -> Dict:
|
||||
"""Convert to dictionary, handling enums"""
|
||||
data = asdict(self)
|
||||
data['status'] = self.status.value
|
||||
return data
|
||||
|
||||
|
||||
class MetaAgent:
|
||||
"""
|
||||
Meta-Agent Orchestrator for Ralph Multi-Agent System
|
||||
|
||||
Coordinates multiple Claude worker agents to execute complex tasks
|
||||
in parallel with intelligent conflict resolution and observability.
|
||||
"""
|
||||
|
||||
def __init__(self, config: Optional[Dict] = None):
|
||||
"""Initialize the meta-agent orchestrator"""
|
||||
self.config = config or self._load_config()
|
||||
|
||||
# Redis connection
|
||||
self.redis = redis.Redis(
|
||||
host=self.config.get('task_queue_host', 'localhost'),
|
||||
port=self.config.get('task_queue_port', 6379),
|
||||
db=self.config.get('task_queue_db', 0),
|
||||
password=self.config.get('task_queue_password'),
|
||||
decode_responses=True
|
||||
)
|
||||
|
||||
# Configuration
|
||||
self.max_workers = self.config.get('max_workers', 12)
|
||||
self.min_workers = self.config.get('min_workers', 2)
|
||||
self.agent_timeout = self.config.get('agent_timeout', 300)
|
||||
self.file_lock_timeout = self.config.get('file_lock_timeout', 300)
|
||||
self.max_retries = self.config.get('max_retries', 3)
|
||||
|
||||
# Queue names
|
||||
self.task_queue = 'claude_tasks'
|
||||
self.pending_queue = 'claude_tasks:pending'
|
||||
self.complete_queue = 'claude_tasks:complete'
|
||||
self.failed_queue = 'claude_tasks:failed'
|
||||
|
||||
# Worker agents
|
||||
self.workers: Dict[str, AgentInfo] = {}
|
||||
|
||||
# Tasks
|
||||
self.tasks: Dict[str, Task] = {}
|
||||
|
||||
logger.info("Meta-Agent Orchestrator initialized")
|
||||
|
||||
def _load_config(self) -> Dict:
|
||||
"""Load configuration from environment variables"""
|
||||
return {
|
||||
'max_workers': int(os.getenv('RALPH_MAX_WORKERS', 12)),
|
||||
'min_workers': int(os.getenv('RALPH_MIN_WORKERS', 2)),
|
||||
'task_queue_host': os.getenv('RALPH_TASK_QUEUE_HOST', 'localhost'),
|
||||
'task_queue_port': int(os.getenv('RALPH_TASK_QUEUE_PORT', 6379)),
|
||||
'task_queue_db': int(os.getenv('RALPH_TASK_QUEUE_DB', 0)),
|
||||
'task_queue_password': os.getenv('RALPH_TASK_QUEUE_PASSWORD'),
|
||||
'agent_timeout': int(os.getenv('RALPH_AGENT_TIMEOUT', 300)),
|
||||
'file_lock_timeout': int(os.getenv('RALPH_FILE_LOCK_TIMEOUT', 300)),
|
||||
'max_retries': int(os.getenv('RALPH_MAX_RETRIES', 3)),
|
||||
'observability_enabled': os.getenv('RALPH_OBSERVABILITY_ENABLED', 'true').lower() == 'true',
|
||||
'observability_port': int(os.getenv('RALPH_OBSERVABILITY_PORT', 3001)),
|
||||
'observability_host': os.getenv('RALPH_OBSERVABILITY_HOST', 'localhost'),
|
||||
}
|
||||
|
||||
def analyze_project(self, requirements: str, project_context: Optional[Dict] = None) -> List[Task]:
|
||||
"""
|
||||
Analyze requirements and break into parallelizable tasks
|
||||
|
||||
Args:
|
||||
requirements: User requirements/task description
|
||||
project_context: Optional project context (files, structure, etc.)
|
||||
|
||||
Returns:
|
||||
List of tasks with dependencies
|
||||
"""
|
||||
logger.info(f"Analyzing requirements: {requirements[:100]}...")
|
||||
|
||||
# Build analysis prompt
|
||||
prompt = self._build_analysis_prompt(requirements, project_context)
|
||||
|
||||
# Call Claude to analyze
|
||||
task_data = self._call_claude_analysis(prompt)
|
||||
|
||||
# Parse and create tasks
|
||||
tasks = []
|
||||
for item in task_data:
|
||||
task = Task(
|
||||
id=item['id'],
|
||||
type=TaskType(item.get('type', 'analysis')),
|
||||
description=item['description'],
|
||||
dependencies=item.get('dependencies', []),
|
||||
files=item.get('files', []),
|
||||
priority=item.get('priority', 5),
|
||||
specialization=item.get('specialization'),
|
||||
timeout=item.get('timeout', 300)
|
||||
)
|
||||
tasks.append(task)
|
||||
self.tasks[task.id] = task
|
||||
|
||||
logger.info(f"Created {len(tasks)} tasks from requirements")
|
||||
return tasks
|
||||
|
||||
def _build_analysis_prompt(self, requirements: str, project_context: Optional[Dict]) -> str:
|
||||
"""Build prompt for Claude analysis"""
|
||||
prompt = f"""You are a task orchestration expert. Analyze these requirements and break them into independent tasks that can be executed in parallel by specialized AI agents.
|
||||
|
||||
REQUIREMENTS:
|
||||
{requirements}
|
||||
|
||||
"""
|
||||
|
||||
if project_context:
|
||||
prompt += f"""
|
||||
PROJECT CONTEXT:
|
||||
{json.dumps(project_context, indent=2)}
|
||||
"""
|
||||
|
||||
prompt += """
|
||||
Return a JSON array of tasks. Each task must have:
|
||||
- id: unique identifier (e.g., "task-001", "task-002")
|
||||
- type: one of [analysis, frontend, backend, testing, docs, refactor, deployment]
|
||||
- description: clear description of what needs to be done
|
||||
- dependencies: array of task IDs that must complete first (empty if no dependencies)
|
||||
- files: array of files this task will modify (empty if analysis task)
|
||||
- priority: 1-10 (higher = more important, default 5)
|
||||
- specialization: optional specific agent type if needed
|
||||
- timeout: estimated seconds to complete (default 300)
|
||||
|
||||
IMPORTANT:
|
||||
- Maximize parallelization - minimize dependencies
|
||||
- Group related file modifications in single tasks
|
||||
- Consider file access conflicts when creating tasks
|
||||
- Include testing tasks for implementation tasks
|
||||
- Include documentation tasks for user-facing features
|
||||
|
||||
Example output format:
|
||||
[
|
||||
{
|
||||
"id": "analyze-1",
|
||||
"type": "analysis",
|
||||
"description": "Analyze codebase structure and identify components",
|
||||
"dependencies": [],
|
||||
"files": [],
|
||||
"priority": 10,
|
||||
"timeout": 120
|
||||
},
|
||||
{
|
||||
"id": "refactor-auth",
|
||||
"type": "refactor",
|
||||
"description": "Refactor authentication components",
|
||||
"dependencies": ["analyze-1"],
|
||||
"files": ["src/auth/**/*.ts"],
|
||||
"priority": 8,
|
||||
"specialization": "frontend"
|
||||
}
|
||||
]
|
||||
"""
|
||||
return prompt
|
||||
|
||||
def _call_claude_analysis(self, prompt: str) -> List[Dict]:
|
||||
"""Call Claude for task analysis"""
|
||||
# This would integrate with Claude Code API
|
||||
# For now, return a mock response
|
||||
logger.warning("Using mock Claude analysis - implement actual API call")
|
||||
|
||||
# Example mock response
|
||||
return [
|
||||
{
|
||||
"id": "analyze-1",
|
||||
"type": "analysis",
|
||||
"description": "Analyze project structure",
|
||||
"dependencies": [],
|
||||
"files": [],
|
||||
"priority": 10,
|
||||
"timeout": 120
|
||||
}
|
||||
]
|
||||
|
||||
def distribute_tasks(self, tasks: List[Task]):
|
||||
"""
|
||||
Distribute tasks to worker agents, respecting dependencies
|
||||
|
||||
Args:
|
||||
tasks: List of tasks to distribute
|
||||
"""
|
||||
logger.info(f"Distributing {len(tasks)} tasks")
|
||||
|
||||
# Sort tasks by dependencies (topological sort)
|
||||
sorted_tasks = self._topological_sort(tasks)
|
||||
|
||||
# Queue tasks
|
||||
for task in sorted_tasks:
|
||||
self._queue_task(task)
|
||||
|
||||
logger.info(f"Queued {len(sorted_tasks)} tasks")
|
||||
|
||||
def _topological_sort(self, tasks: List[Task]) -> List[Task]:
|
||||
"""
|
||||
Sort tasks by dependencies using topological sort
|
||||
|
||||
Args:
|
||||
tasks: List of tasks with dependencies
|
||||
|
||||
Returns:
|
||||
Tasks sorted in dependency order
|
||||
"""
|
||||
# Build dependency graph
|
||||
task_map = {task.id: task for task in tasks}
|
||||
in_degree = {task.id: len(task.dependencies) for task in tasks}
|
||||
queue = [task_id for task_id, degree in in_degree.items() if degree == 0]
|
||||
result = []
|
||||
|
||||
while queue:
|
||||
# Sort by priority
|
||||
queue.sort(key=lambda tid: task_map[tid].priority, reverse=True)
|
||||
task_id = queue.pop(0)
|
||||
result.append(task_map[task_id])
|
||||
|
||||
# Update in-degree for dependent tasks
|
||||
for task in tasks:
|
||||
if task_id in task.dependencies:
|
||||
in_degree[task.id] -= 1
|
||||
if in_degree[task.id] == 0:
|
||||
queue.append(task.id)
|
||||
|
||||
# Check for circular dependencies
|
||||
if len(result) != len(tasks):
|
||||
logger.warning("Circular dependencies detected, returning partial sort")
|
||||
|
||||
return result
|
||||
|
||||
def _queue_task(self, task: Task):
|
||||
"""
|
||||
Queue a task for execution
|
||||
|
||||
Args:
|
||||
task: Task to queue
|
||||
"""
|
||||
# Check if dependencies are complete
|
||||
if self._dependencies_complete(task):
|
||||
# Queue for immediate execution
|
||||
self.redis.lpush(self.task_queue, json.dumps(task.to_dict()))
|
||||
task.status = TaskStatus.QUEUED
|
||||
else:
|
||||
# Queue for later
|
||||
self.redis.lpush(self.pending_queue, json.dumps(task.to_dict()))
|
||||
|
||||
# Store task status
|
||||
self.redis.hset(f"task:{task.id}", mapping=task.to_dict())
|
||||
|
||||
def _dependencies_complete(self, task: Task) -> bool:
|
||||
"""
|
||||
Check if task dependencies are complete
|
||||
|
||||
Args:
|
||||
task: Task to check
|
||||
|
||||
Returns:
|
||||
True if all dependencies are complete
|
||||
"""
|
||||
for dep_id in task.dependencies:
|
||||
if dep_id not in self.tasks:
|
||||
logger.warning(f"Unknown dependency: {dep_id}")
|
||||
return False
|
||||
|
||||
dep_task = self.tasks[dep_id]
|
||||
if dep_task.status != TaskStatus.COMPLETE:
|
||||
return False
|
||||
|
||||
return True
|
||||
|
||||
def spawn_worker_agents(self, count: Optional[int] = None):
|
||||
"""
|
||||
Spawn worker agents for parallel execution
|
||||
|
||||
Args:
|
||||
count: Number of agents to spawn (default from config)
|
||||
"""
|
||||
if count is None:
|
||||
count = self.max_workers
|
||||
|
||||
logger.info(f"Spawning {count} worker agents")
|
||||
|
||||
specializations = ['frontend', 'backend', 'testing', 'docs', 'refactor', 'analysis']
|
||||
|
||||
for i in range(count):
|
||||
agent_id = f"agent-{i}"
|
||||
specialization = specializations[i % len(specializations)]
|
||||
|
||||
agent = AgentInfo(
|
||||
id=agent_id,
|
||||
specialization=specialization,
|
||||
status=AgentStatus.IDLE
|
||||
)
|
||||
|
||||
self.workers[agent_id] = agent
|
||||
self._start_worker_process(agent)
|
||||
|
||||
# Store agent info in Redis
|
||||
self.redis.hset(f"agent:{agent_id}", mapping=agent.to_dict())
|
||||
|
||||
logger.info(f"Spawned {len(self.workers)} worker agents")
|
||||
|
||||
def _start_worker_process(self, agent: AgentInfo):
|
||||
"""
|
||||
Start a worker agent process
|
||||
|
||||
Args:
|
||||
agent: Agent info
|
||||
"""
|
||||
# This would start the actual worker process
|
||||
# For now, just log
|
||||
logger.info(f"Starting worker process: {agent.id} ({agent.specialization})")
|
||||
|
||||
# Example: Would use subprocess to start worker
|
||||
# subprocess.Popen([
|
||||
# 'claude-code',
|
||||
# '--mode', 'worker',
|
||||
# '--id', agent.id,
|
||||
# '--specialization', agent.specialization
|
||||
# ])
|
||||
|
||||
def monitor_tasks(self):
|
||||
"""
|
||||
Monitor task execution and handle failures
|
||||
|
||||
Runs continuously until all tasks complete
|
||||
"""
|
||||
logger.info("Starting task monitoring")
|
||||
|
||||
try:
|
||||
while True:
|
||||
# Check if all tasks complete
|
||||
if self._all_tasks_complete():
|
||||
logger.info("All tasks completed")
|
||||
break
|
||||
|
||||
# Check for failed tasks
|
||||
self._handle_failed_tasks()
|
||||
|
||||
# Check for pending tasks ready to execute
|
||||
self._check_pending_tasks()
|
||||
|
||||
# Update agent heartbeats
|
||||
self._update_heartbeats()
|
||||
|
||||
# Check for stale agents
|
||||
self._check_stale_agents()
|
||||
|
||||
time.sleep(1)
|
||||
|
||||
except KeyboardInterrupt:
|
||||
logger.info("Monitoring interrupted by user")
|
||||
|
||||
def _all_tasks_complete(self) -> bool:
|
||||
"""Check if all tasks are complete"""
|
||||
return all(
|
||||
task.status in [TaskStatus.COMPLETE, TaskStatus.CANCELLED]
|
||||
for task in self.tasks.values()
|
||||
)
|
||||
|
||||
def _handle_failed_tasks(self):
|
||||
"""Handle failed tasks with retry logic"""
|
||||
for task in self.tasks.values():
|
||||
if task.status == TaskStatus.FAILED:
|
||||
if task.retry_count < task.max_retries:
|
||||
logger.info(f"Retrying task {task.id} (attempt {task.retry_count + 1})")
|
||||
task.retry_count += 1
|
||||
task.status = TaskStatus.PENDING
|
||||
self._queue_task(task)
|
||||
else:
|
||||
logger.error(f"Task {task.id} failed after {task.max_retries} retries")
|
||||
|
||||
def _check_pending_tasks(self):
|
||||
"""Check if pending tasks can now be executed"""
|
||||
pending = self.redis.lrange(self.pending_queue, 0, -1)
|
||||
for task_json in pending:
|
||||
task = Task.from_dict(json.loads(task_json))
|
||||
if self._dependencies_complete(task):
|
||||
# Move to main queue
|
||||
self.redis.lrem(self.pending_queue, 1, task_json)
|
||||
self.redis.lpush(self.task_queue, task_json)
|
||||
logger.info(f"Task {task.id} dependencies complete, queued")
|
||||
|
||||
def _update_heartbeats(self):
|
||||
"""Update agent heartbeats from Redis"""
|
||||
for agent_id in self.workers.keys():
|
||||
agent_data = self.redis.hgetall(f"agent:{agent_id}")
|
||||
if agent_data:
|
||||
agent = self.workers[agent_id]
|
||||
agent.last_heartbeat = float(agent_data.get('last_heartbeat', time.time()))
|
||||
|
||||
def _check_stale_agents(self):
|
||||
"""Check for agents that haven't sent heartbeat"""
|
||||
timeout = self.config.get('agent_timeout', 300)
|
||||
now = time.time()
|
||||
|
||||
for agent in self.workers.values():
|
||||
if agent.status != AgentStatus.OFFLINE:
|
||||
if now - agent.last_heartbeat > timeout:
|
||||
logger.warning(f"Agent {agent.id} appears stale (last heartbeat {timeout}s ago)")
|
||||
agent.status = AgentStatus.OFFLINE
|
||||
|
||||
def generate_report(self) -> Dict:
|
||||
"""
|
||||
Generate execution report
|
||||
|
||||
Returns:
|
||||
Dictionary with execution statistics
|
||||
"""
|
||||
total_tasks = len(self.tasks)
|
||||
complete_tasks = sum(1 for t in self.tasks.values() if t.status == TaskStatus.COMPLETE)
|
||||
failed_tasks = sum(1 for t in self.tasks.values() if t.status == TaskStatus.FAILED)
|
||||
total_duration = max(
|
||||
(t.completed_at - t.created_at for t in self.tasks.values() if t.completed_at),
|
||||
default=0
|
||||
)
|
||||
|
||||
report = {
|
||||
'total_tasks': total_tasks,
|
||||
'complete_tasks': complete_tasks,
|
||||
'failed_tasks': failed_tasks,
|
||||
'success_rate': complete_tasks / total_tasks if total_tasks > 0 else 0,
|
||||
'total_duration_seconds': total_duration,
|
||||
'worker_count': len(self.workers),
|
||||
'tasks_by_type': self._count_tasks_by_type(),
|
||||
'tasks_by_status': self._count_tasks_by_status(),
|
||||
}
|
||||
|
||||
return report
|
||||
|
||||
def _count_tasks_by_type(self) -> Dict[str, int]:
|
||||
"""Count tasks by type"""
|
||||
counts = {}
|
||||
for task in self.tasks.values():
|
||||
type_name = task.type.value
|
||||
counts[type_name] = counts.get(type_name, 0) + 1
|
||||
return counts
|
||||
|
||||
def _count_tasks_by_status(self) -> Dict[str, int]:
|
||||
"""Count tasks by status"""
|
||||
counts = {}
|
||||
for task in self.tasks.values():
|
||||
status_name = task.status.value
|
||||
counts[status_name] = counts.get(status_name, 0) + 1
|
||||
return counts
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for CLI usage"""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description='Ralph Meta-Agent Orchestrator')
|
||||
parser.add_argument('requirements', help='Task requirements')
|
||||
parser.add_argument('--workers', type=int, help='Number of worker agents')
|
||||
parser.add_argument('--config', help='Config file path')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Load config
|
||||
config = {}
|
||||
if args.config:
|
||||
with open(args.config) as f:
|
||||
config = json.load(f)
|
||||
|
||||
# Create orchestrator
|
||||
orchestrator = MetaAgent(config)
|
||||
|
||||
# Analyze requirements
|
||||
tasks = orchestrator.analyze_project(args.requirements)
|
||||
|
||||
# Distribute tasks
|
||||
orchestrator.distribute_tasks(tasks)
|
||||
|
||||
# Spawn workers
|
||||
orchestrator.spawn_worker_agents(args.workers)
|
||||
|
||||
# Monitor execution
|
||||
orchestrator.monitor_tasks()
|
||||
|
||||
# Generate report
|
||||
report = orchestrator.generate_report()
|
||||
print("\n=== EXECUTION REPORT ===")
|
||||
print(json.dumps(report, indent=2))
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
458
skills/ralph/multi-agent-architecture.md
Normal file
458
skills/ralph/multi-agent-architecture.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# Ralph Multi-Agent Orchestration System
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The Ralph Multi-Agent Orchestration System enables running 10+ Claude instances in parallel with intelligent coordination, conflict resolution, and real-time observability.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Meta-Agent Orchestrator │
|
||||
│ (ralph-integration.py) │
|
||||
│ - Analyzes requirements │
|
||||
│ - Breaks into independent tasks │
|
||||
│ - Manages dependencies │
|
||||
│ - Coordinates worker agents │
|
||||
└──────────────────┬──────────────────────────┘
|
||||
│ Creates tasks
|
||||
▼
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Task Queue (Redis) │
|
||||
│ Stores and distributes work │
|
||||
└─────┬───────┬───────┬───────┬──────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent N │
|
||||
│Frontend │ │ Backend │ │ Tests │ │ Docs │
|
||||
└─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
│ │ │ │
|
||||
└───────┴───────┴───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ Observability │
|
||||
│ Dashboard │
|
||||
│ (Real-time UI) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Meta-Agent Orchestrator
|
||||
|
||||
The meta-agent is Ralph running in orchestration mode where it manages other agents instead of writing code directly.
|
||||
|
||||
**Key Responsibilities:**
|
||||
- Analyze project requirements
|
||||
- Break down into parallelizable tasks
|
||||
- Manage task dependencies
|
||||
- Spawn and coordinate worker agents
|
||||
- Monitor progress and handle conflicts
|
||||
- Aggregate results
|
||||
|
||||
**Configuration:**
|
||||
```bash
|
||||
# Enable multi-agent mode
|
||||
RALPH_MULTI_AGENT=true
|
||||
RALPH_MAX_WORKERS=12
|
||||
RALPH_TASK_QUEUE_HOST=localhost
|
||||
RALPH_TASK_QUEUE_PORT=6379
|
||||
RALPH_OBSERVABILITY_PORT=3001
|
||||
```
|
||||
|
||||
### 2. Task Queue System
|
||||
|
||||
Uses Redis for reliable task distribution and state management.
|
||||
|
||||
**Task Structure:**
|
||||
```json
|
||||
{
|
||||
"id": "unique-task-id",
|
||||
"type": "frontend|backend|testing|docs|refactor|analysis",
|
||||
"description": "What needs to be done",
|
||||
"dependencies": ["task-id-1", "task-id-2"],
|
||||
"files": ["path/to/file1.ts", "path/to/file2.ts"],
|
||||
"priority": 1-10,
|
||||
"specialization": "optional-specific-agent-type",
|
||||
"timeout": 300,
|
||||
"retry_count": 0,
|
||||
"max_retries": 3
|
||||
}
|
||||
```
|
||||
|
||||
**Queue Operations:**
|
||||
- `claude_tasks` - Main task queue
|
||||
- `claude_tasks:pending` - Tasks waiting for dependencies
|
||||
- `claude_tasks:complete` - Completed tasks
|
||||
- `claude_tasks:failed` - Failed tasks for retry
|
||||
- `lock:{file_path}` - File-level locks
|
||||
- `task:{task_id}` - Task status tracking
|
||||
|
||||
### 3. Specialized Worker Agents
|
||||
|
||||
Each worker agent has a specific role and configuration.
|
||||
|
||||
**Agent Types:**
|
||||
|
||||
| Agent Type | Specialization | Example Tasks |
|
||||
|------------|----------------|---------------|
|
||||
| **Frontend** | UI/UX, React, Vue, Svelte | Component refactoring, styling |
|
||||
| **Backend** | APIs, databases, services | Endpoint creation, data models |
|
||||
| **Testing** | Unit tests, integration tests | Test writing, coverage improvement |
|
||||
| **Documentation** | Docs, comments, README | API docs, inline documentation |
|
||||
| **Refactor** | Code quality, optimization | Performance tuning, code cleanup |
|
||||
| **Analysis** | Code review, architecture | Dependency analysis, security audit |
|
||||
|
||||
**Worker Configuration:**
|
||||
```json
|
||||
{
|
||||
"agent_id": "agent-frontend-1",
|
||||
"specialization": "frontend",
|
||||
"max_concurrent_tasks": 1,
|
||||
"file_lock_timeout": 300,
|
||||
"heartbeat_interval": 10,
|
||||
"log_level": "info"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. File Locking & Conflict Resolution
|
||||
|
||||
Prevents multiple agents from modifying the same file simultaneously.
|
||||
|
||||
**Lock Acquisition Flow:**
|
||||
1. Agent requests locks for required files
|
||||
2. Redis attempts to set lock keys with NX flag
|
||||
3. If all locks acquired, agent proceeds
|
||||
4. If any lock fails, agent waits and retries
|
||||
5. Locks auto-expire after timeout (safety mechanism)
|
||||
|
||||
**Conflict Detection:**
|
||||
```python
|
||||
def detect_conflicts(agent_files: Dict[str, List[str]]) -> List[Conflict]:
|
||||
"""Detect file access conflicts between agents"""
|
||||
file_agents = {}
|
||||
for agent_id, files in agent_files.items():
|
||||
for file_path in files:
|
||||
if file_path in file_agents:
|
||||
file_agents[file_path].append(agent_id)
|
||||
else:
|
||||
file_agents[file_path] = [agent_id]
|
||||
|
||||
conflicts = [
|
||||
{"file": f, "agents": agents}
|
||||
for f, agents in file_agents.items()
|
||||
if len(agents) > 1
|
||||
]
|
||||
return conflicts
|
||||
```
|
||||
|
||||
**Resolution Strategies:**
|
||||
1. **Dependency-based ordering** - Add dependencies between conflicting tasks
|
||||
2. **File splitting** - Break tasks into smaller units
|
||||
3. **Agent specialization** - Assign conflicting tasks to same agent
|
||||
4. **Merge coordination** - Use git merge strategies
|
||||
|
||||
### 5. Real-Time Observability Dashboard
|
||||
|
||||
WebSocket-based dashboard for monitoring all agents in real-time.
|
||||
|
||||
**Dashboard Features:**
|
||||
- Live agent status (active, busy, idle, error)
|
||||
- Task progress tracking
|
||||
- File modification visualization
|
||||
- Conflict alerts and resolution
|
||||
- Activity stream with timestamps
|
||||
- Performance metrics
|
||||
|
||||
**WebSocket Events:**
|
||||
```javascript
|
||||
// Agent update
|
||||
{
|
||||
"type": "agent_update",
|
||||
"agent": {
|
||||
"id": "agent-frontend-1",
|
||||
"status": "active",
|
||||
"currentTask": "refactor-buttons",
|
||||
"progress": 65,
|
||||
"workingFiles": ["components/Button.tsx"],
|
||||
"completedCount": 12
|
||||
}
|
||||
}
|
||||
|
||||
// Conflict detected
|
||||
{
|
||||
"type": "conflict",
|
||||
"conflict": {
|
||||
"file": "components/Button.tsx",
|
||||
"agents": ["agent-frontend-1", "agent-frontend-2"],
|
||||
"timestamp": "2025-08-02T15:30:00Z"
|
||||
}
|
||||
}
|
||||
|
||||
// Task completed
|
||||
{
|
||||
"type": "task_complete",
|
||||
"taskId": "refactor-buttons",
|
||||
"agentId": "agent-frontend-1",
|
||||
"duration": 45.2,
|
||||
"filesModified": ["components/Button.tsx", "components/Button.test.tsx"]
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Frontend Refactor
|
||||
|
||||
```bash
|
||||
# Start multi-agent Ralph for frontend refactor
|
||||
RALPH_MULTI_AGENT=true \
|
||||
RALPH_MAX_WORKERS=8 \
|
||||
/ralph "Refactor all components from class to functional with hooks"
|
||||
```
|
||||
|
||||
**Meta-Agent Breakdown:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "analyze-1",
|
||||
"type": "analysis",
|
||||
"description": "Scan all components and create refactoring plan",
|
||||
"dependencies": [],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": "refactor-buttons",
|
||||
"type": "frontend",
|
||||
"description": "Convert all Button components to functional",
|
||||
"dependencies": ["analyze-1"],
|
||||
"files": ["components/Button/*.tsx"]
|
||||
},
|
||||
{
|
||||
"id": "refactor-forms",
|
||||
"type": "frontend",
|
||||
"description": "Convert all Form components to functional",
|
||||
"dependencies": ["analyze-1"],
|
||||
"files": ["components/Form/*.tsx"]
|
||||
},
|
||||
{
|
||||
"id": "update-tests-buttons",
|
||||
"type": "testing",
|
||||
"description": "Update Button component tests",
|
||||
"dependencies": ["refactor-buttons"],
|
||||
"files": ["__tests__/Button/*.test.tsx"]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Example 2: Full-Stack Feature
|
||||
|
||||
```bash
|
||||
# Build feature with parallel frontend/backend
|
||||
RALPH_MULTI_AGENT=true \
|
||||
RALPH_MAX_WORKERS=6 \
|
||||
/ralph "Build user authentication with OAuth, profile management, and email verification"
|
||||
```
|
||||
|
||||
**Parallel Execution:**
|
||||
- Agent 1 (Frontend): Build login form UI
|
||||
- Agent 2 (Frontend): Build profile page UI
|
||||
- Agent 3 (Backend): Implement OAuth endpoints
|
||||
- Agent 4 (Backend): Implement profile API
|
||||
- Agent 5 (Testing): Write integration tests
|
||||
- Agent 6 (Docs): Write API documentation
|
||||
|
||||
### Example 3: Codebase Optimization
|
||||
|
||||
```bash
|
||||
# Parallel optimization across codebase
|
||||
RALPH_MULTI_AGENT=true \
|
||||
RALPH_MAX_WORKERS=10 \
|
||||
/ralph "Optimize performance: bundle size, lazy loading, image optimization, caching strategy"
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# Multi-Agent Configuration
|
||||
RALPH_MULTI_AGENT=true # Enable multi-agent mode
|
||||
RALPH_MAX_WORKERS=12 # Maximum worker agents
|
||||
RALPH_MIN_WORKERS=2 # Minimum worker agents
|
||||
|
||||
# Task Queue (Redis)
|
||||
RALPH_TASK_QUEUE_HOST=localhost # Redis host
|
||||
RALPH_TASK_QUEUE_PORT=6379 # Redis port
|
||||
RALPH_TASK_QUEUE_DB=0 # Redis database
|
||||
RALPH_TASK_QUEUE_PASSWORD= # Redis password (optional)
|
||||
|
||||
# Observability
|
||||
RALPH_OBSERVABILITY_ENABLED=true # Enable dashboard
|
||||
RALPH_OBSERVABILITY_PORT=3001 # WebSocket port
|
||||
RALPH_OBSERVABILITY_HOST=localhost # Dashboard host
|
||||
|
||||
# Agent Behavior
|
||||
RALPH_AGENT_TIMEOUT=300 # Task timeout (seconds)
|
||||
RALPH_AGENT_HEARTBEAT=10 # Heartbeat interval (seconds)
|
||||
RALPH_FILE_LOCK_TIMEOUT=300 # File lock timeout (seconds)
|
||||
RALPH_MAX_RETRIES=3 # Task retry count
|
||||
|
||||
# Logging
|
||||
RALPH_VERBOSE=true # Verbose logging
|
||||
RALPH_LOG_LEVEL=info # Log level
|
||||
RALPH_LOG_FILE=.ralph/multi-agent.log # Log file path
|
||||
```
|
||||
|
||||
## Monitoring & Debugging
|
||||
|
||||
### Check Multi-Agent Status
|
||||
|
||||
```bash
|
||||
# View active agents
|
||||
redis-cli keys "agent:*"
|
||||
|
||||
# View task queue
|
||||
redis-cli lrange claude_tasks 0 10
|
||||
|
||||
# View file locks
|
||||
redis-cli keys "lock:*"
|
||||
|
||||
# View task status
|
||||
redis-cli hgetall "task:task-id"
|
||||
|
||||
# View completed tasks
|
||||
redis-cli lrange claude_tasks:complete 0 10
|
||||
```
|
||||
|
||||
### Observability Dashboard
|
||||
|
||||
Access dashboard at: `http://localhost:3001`
|
||||
|
||||
**Dashboard Sections:**
|
||||
1. **Mission Status** - Overall progress
|
||||
2. **Agent Grid** - Individual agent status
|
||||
3. **Conflict Alerts** - Active file conflicts
|
||||
4. **Activity Stream** - Real-time event log
|
||||
5. **Performance Metrics** - Agent efficiency
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Task Design
|
||||
- Keep tasks independent when possible
|
||||
- Minimize cross-task file dependencies
|
||||
- Use specialization to guide agent assignment
|
||||
- Set appropriate timeouts
|
||||
|
||||
### 2. Dependency Management
|
||||
- Use topological sort for execution order
|
||||
- Minimize dependency depth
|
||||
- Allow parallel execution at every opportunity
|
||||
- Handle circular dependencies gracefully
|
||||
|
||||
### 3. Conflict Prevention
|
||||
- Group related file modifications in single task
|
||||
- Use file-specific agents when conflicts likely
|
||||
- Implement merge strategies for common conflicts
|
||||
- Monitor lock acquisition time
|
||||
|
||||
### 4. Observability
|
||||
- Log all agent activities
|
||||
- Track file modifications in real-time
|
||||
- Alert on conflicts immediately
|
||||
- Maintain activity history for debugging
|
||||
|
||||
### 5. Error Handling
|
||||
- Implement retry logic with exponential backoff
|
||||
- Quarantine failing tasks for analysis
|
||||
- Provide detailed error context
|
||||
- Allow manual intervention when needed
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Agents stuck waiting:**
|
||||
```bash
|
||||
# Check for stale locks
|
||||
redis-cli keys "lock:*"
|
||||
|
||||
# Clear stale locks
|
||||
redis-cli del "lock:path/to/file"
|
||||
```
|
||||
|
||||
**Tasks not executing:**
|
||||
```bash
|
||||
# Check task queue
|
||||
redis-cli lrange claude_tasks 0 -1
|
||||
|
||||
# Check pending tasks
|
||||
redis-cli lrange claude_tasks:pending 0 -1
|
||||
```
|
||||
|
||||
**Dashboard not updating:**
|
||||
```bash
|
||||
# Check WebSocket server
|
||||
netstat -an | grep 3001
|
||||
|
||||
# Restart observability server
|
||||
pkill -f ralph-observability
|
||||
RALPH_OBSERVABILITY_ENABLED=true ralph-observability
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Optimize Worker Count
|
||||
```bash
|
||||
# Calculate optimal workers
|
||||
WORKERS = (CPU_CORES * 1.5) - 1
|
||||
|
||||
# For I/O bound tasks
|
||||
WORKERS = CPU_CORES * 2
|
||||
|
||||
# For CPU bound tasks
|
||||
WORKERS = CPU_CORES
|
||||
```
|
||||
|
||||
### Redis Configuration
|
||||
```bash
|
||||
# redis.conf
|
||||
maxmemory 2gb
|
||||
maxmemory-policy allkeys-lru
|
||||
timeout 300
|
||||
tcp-keepalive 60
|
||||
```
|
||||
|
||||
### Agent Pool Sizing
|
||||
```bash
|
||||
# Dynamic scaling based on queue depth
|
||||
QUEUE_DEPTH=$(redis-cli llen claude_tasks)
|
||||
if [ $QUEUE_DEPTH -gt 50 ]; then
|
||||
SCALE_UP=true
|
||||
elif [ $QUEUE_DEPTH -lt 10 ]; then
|
||||
SCALE_DOWN=true
|
||||
fi
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **File Access Control** - Restrict agent file system access
|
||||
2. **Redis Authentication** - Use Redis password in production
|
||||
3. **Network Isolation** - Run agents in isolated network
|
||||
4. **Resource Limits** - Set CPU/memory limits per agent
|
||||
5. **Audit Logging** - Log all agent actions for compliance
|
||||
|
||||
## Integration with Claude Code
|
||||
|
||||
The Ralph Multi-Agent System integrates seamlessly with Claude Code:
|
||||
|
||||
```bash
|
||||
# Use with Claude Code projects
|
||||
export RALPH_AGENT=claude
|
||||
export RALPH_MULTI_AGENT=true
|
||||
cd /path/to/claude-code-project
|
||||
/ralph "Refactor authentication system"
|
||||
```
|
||||
|
||||
**Claude Code Integration Points:**
|
||||
- Uses Claude Code agent pool
|
||||
- Respects Claude Code project structure
|
||||
- Integrates with Claude Code hooks
|
||||
- Supports Claude Code tool ecosystem
|
||||
782
skills/ralph/observability_dashboard.html
Normal file
782
skills/ralph/observability_dashboard.html
Normal file
@@ -0,0 +1,782 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Ralph Multi-Agent Command Center</title>
|
||||
<script src="https://cdn.jsdelivr.net/npm/vue@3"></script>
|
||||
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
|
||||
<style>
|
||||
* {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
|
||||
background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
|
||||
color: #e4e4e7;
|
||||
min-height: 100vh;
|
||||
}
|
||||
|
||||
.header {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
backdrop-filter: blur(10px);
|
||||
border-bottom: 1px solid rgba(255, 255, 255, 0.1);
|
||||
padding: 20px 40px;
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.header h1 {
|
||||
font-size: 24px;
|
||||
font-weight: 600;
|
||||
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
||||
-webkit-background-clip: text;
|
||||
-webkit-text-fill-color: transparent;
|
||||
}
|
||||
|
||||
.connection-status {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.status-dot {
|
||||
width: 10px;
|
||||
height: 10px;
|
||||
border-radius: 50%;
|
||||
animation: pulse 2s infinite;
|
||||
}
|
||||
|
||||
.status-dot.connected {
|
||||
background: #10b981;
|
||||
}
|
||||
|
||||
.status-dot.disconnected {
|
||||
background: #ef4444;
|
||||
}
|
||||
|
||||
@keyframes pulse {
|
||||
0%, 100% { opacity: 1; }
|
||||
50% { opacity: 0.5; }
|
||||
}
|
||||
|
||||
.container {
|
||||
max-width: 1600px;
|
||||
margin: 0 auto;
|
||||
padding: 30px;
|
||||
}
|
||||
|
||||
.stats-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
|
||||
gap: 20px;
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.stat-card {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
backdrop-filter: blur(10px);
|
||||
border: 1px solid rgba(255, 255, 255, 0.1);
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
.stat-label {
|
||||
font-size: 12px;
|
||||
color: #a1a1aa;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
margin-bottom: 8px;
|
||||
}
|
||||
|
||||
.stat-value {
|
||||
font-size: 32px;
|
||||
font-weight: 700;
|
||||
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
||||
-webkit-background-clip: text;
|
||||
-webkit-text-fill-color: transparent;
|
||||
}
|
||||
|
||||
.conflict-alert {
|
||||
background: rgba(239, 68, 68, 0.1);
|
||||
border: 1px solid rgba(239, 68, 68, 0.3);
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.conflict-alert h3 {
|
||||
color: #ef4444;
|
||||
font-size: 16px;
|
||||
margin-bottom: 12px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.conflict-list {
|
||||
list-style: none;
|
||||
}
|
||||
|
||||
.conflict-list li {
|
||||
padding: 8px 0;
|
||||
border-bottom: 1px solid rgba(239, 68, 68, 0.2);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
.conflict-list li:last-child {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
.agents-section {
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.section-header {
|
||||
font-size: 18px;
|
||||
font-weight: 600;
|
||||
margin-bottom: 20px;
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.agent-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
|
||||
gap: 20px;
|
||||
}
|
||||
|
||||
.agent-card {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
backdrop-filter: blur(10px);
|
||||
border: 2px solid rgba(255, 255, 255, 0.1);
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
position: relative;
|
||||
transition: all 0.3s ease;
|
||||
}
|
||||
|
||||
.agent-card:hover {
|
||||
transform: translateY(-2px);
|
||||
border-color: rgba(102, 126, 234, 0.3);
|
||||
}
|
||||
|
||||
.agent-card.active {
|
||||
border-color: #10b981;
|
||||
box-shadow: 0 0 20px rgba(16, 185, 129, 0.2);
|
||||
}
|
||||
|
||||
.agent-card.busy {
|
||||
border-color: #f59e0b;
|
||||
}
|
||||
|
||||
.agent-card.error {
|
||||
border-color: #ef4444;
|
||||
}
|
||||
|
||||
.agent-header {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: start;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
.agent-id {
|
||||
font-size: 16px;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.agent-status {
|
||||
position: absolute;
|
||||
top: 20px;
|
||||
right: 20px;
|
||||
width: 12px;
|
||||
height: 12px;
|
||||
border-radius: 50%;
|
||||
}
|
||||
|
||||
.agent-status.idle {
|
||||
background: #6b7280;
|
||||
}
|
||||
|
||||
.agent-status.active {
|
||||
background: #10b981;
|
||||
box-shadow: 0 0 10px rgba(16, 185, 129, 0.5);
|
||||
}
|
||||
|
||||
.agent-status.busy {
|
||||
background: #f59e0b;
|
||||
animation: pulse 1s infinite;
|
||||
}
|
||||
|
||||
.agent-status.error {
|
||||
background: #ef4444;
|
||||
}
|
||||
|
||||
.agent-info {
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
|
||||
.agent-info p {
|
||||
font-size: 13px;
|
||||
color: #a1a1aa;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
|
||||
.agent-info span {
|
||||
color: #e4e4e7;
|
||||
}
|
||||
|
||||
.task-progress {
|
||||
margin-top: 12px;
|
||||
}
|
||||
|
||||
.task-progress-label {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
font-size: 12px;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
|
||||
.task-progress-bar {
|
||||
height: 6px;
|
||||
background: rgba(255, 255, 255, 0.1);
|
||||
border-radius: 3px;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.task-progress-fill {
|
||||
height: 100%;
|
||||
background: linear-gradient(90deg, #667eea, #764ba2);
|
||||
transition: width 0.3s ease;
|
||||
}
|
||||
|
||||
.files-list {
|
||||
margin-top: 12px;
|
||||
font-size: 12px;
|
||||
color: #a1a1aa;
|
||||
}
|
||||
|
||||
.files-list code {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-family: 'Monaco', 'Menlo', monospace;
|
||||
font-size: 11px;
|
||||
}
|
||||
|
||||
.activity-section {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
backdrop-filter: blur(10px);
|
||||
border: 1px solid rgba(255, 255, 255, 0.1);
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
.activity-stream {
|
||||
max-height: 400px;
|
||||
overflow-y: auto;
|
||||
}
|
||||
|
||||
.activity-stream::-webkit-scrollbar {
|
||||
width: 6px;
|
||||
}
|
||||
|
||||
.activity-stream::-webkit-scrollbar-track {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
.activity-stream::-webkit-scrollbar-thumb {
|
||||
background: rgba(255, 255, 255, 0.2);
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
.event {
|
||||
display: flex;
|
||||
gap: 12px;
|
||||
padding: 10px 0;
|
||||
border-bottom: 1px solid rgba(255, 255, 255, 0.05);
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.event:last-child {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
.event-time {
|
||||
color: #a1a1aa;
|
||||
font-family: 'Monaco', 'Menlo', monospace;
|
||||
font-size: 11px;
|
||||
min-width: 80px;
|
||||
}
|
||||
|
||||
.event-agent {
|
||||
color: #667eea;
|
||||
font-weight: 600;
|
||||
min-width: 120px;
|
||||
}
|
||||
|
||||
.event-action {
|
||||
color: #e4e4e7;
|
||||
}
|
||||
|
||||
.event-action.success {
|
||||
color: #10b981;
|
||||
}
|
||||
|
||||
.event-action.error {
|
||||
color: #ef4444;
|
||||
}
|
||||
|
||||
.event-action.warning {
|
||||
color: #f59e0b;
|
||||
}
|
||||
|
||||
.charts-section {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
|
||||
gap: 20px;
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.chart-card {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
backdrop-filter: blur(10px);
|
||||
border: 1px solid rgba(255, 255, 255, 0.1);
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
}
|
||||
|
||||
.chart-card h3 {
|
||||
font-size: 14px;
|
||||
color: #a1a1aa;
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.badge {
|
||||
display: inline-block;
|
||||
padding: 4px 8px;
|
||||
border-radius: 4px;
|
||||
font-size: 11px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
.badge.frontend {
|
||||
background: rgba(102, 126, 234, 0.2);
|
||||
color: #667eea;
|
||||
}
|
||||
|
||||
.badge.backend {
|
||||
background: rgba(16, 185, 129, 0.2);
|
||||
color: #10b981;
|
||||
}
|
||||
|
||||
.badge.testing {
|
||||
background: rgba(245, 158, 11, 0.2);
|
||||
color: #f59e0b;
|
||||
}
|
||||
|
||||
.badge.docs {
|
||||
background: rgba(236, 72, 153, 0.2);
|
||||
color: #ec4899;
|
||||
}
|
||||
|
||||
.badge.refactor {
|
||||
background: rgba(139, 92, 246, 0.2);
|
||||
color: #8b5cf6;
|
||||
}
|
||||
|
||||
.badge.analysis {
|
||||
background: rgba(6, 182, 212, 0.2);
|
||||
color: #06b6d4;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="app">
|
||||
<div class="header">
|
||||
<h1>Ralph Multi-Agent Command Center</h1>
|
||||
<div class="connection-status">
|
||||
<div :class="['status-dot', connected ? 'connected' : 'disconnected']"></div>
|
||||
<span>{{ connected ? 'Connected' : 'Disconnected' }}</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="container">
|
||||
<!-- Overall Stats -->
|
||||
<div class="stats-grid">
|
||||
<div class="stat-card">
|
||||
<div class="stat-label">Active Agents</div>
|
||||
<div class="stat-value">{{ activeAgents.length }}</div>
|
||||
</div>
|
||||
<div class="stat-card">
|
||||
<div class="stat-label">Tasks Completed</div>
|
||||
<div class="stat-value">{{ completedTasks }} / {{ totalTasks }}</div>
|
||||
</div>
|
||||
<div class="stat-card">
|
||||
<div class="stat-label">Files Modified</div>
|
||||
<div class="stat-value">{{ modifiedFiles.size }}</div>
|
||||
</div>
|
||||
<div class="stat-card">
|
||||
<div class="stat-label">Conflicts</div>
|
||||
<div class="stat-value">{{ conflicts.length }}</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Conflict Alerts -->
|
||||
<div v-if="conflicts.length > 0" class="conflict-alert">
|
||||
<h3>
|
||||
<span>⚠️</span>
|
||||
File Conflicts Detected
|
||||
</h3>
|
||||
<ul class="conflict-list">
|
||||
<li v-for="conflict in conflicts" :key="conflict.file">
|
||||
<code>{{ conflict.file }}</code>
|
||||
<span style="color: #a1a1aa"> — </span>
|
||||
{{ conflict.agents.join(' vs ') }}
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<!-- Charts -->
|
||||
<div class="charts-section">
|
||||
<div class="chart-card">
|
||||
<h3>Task Completion by Type</h3>
|
||||
<canvas id="taskTypeChart"></canvas>
|
||||
</div>
|
||||
<div class="chart-card">
|
||||
<h3>Agent Performance</h3>
|
||||
<canvas id="agentPerformanceChart"></canvas>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Agents Grid -->
|
||||
<div class="agents-section">
|
||||
<div class="section-header">
|
||||
<h2>Worker Agents</h2>
|
||||
<span style="font-size: 14px; color: #a1a1aa">
|
||||
{{ activeAgents.length }} active / {{ agents.length }} total
|
||||
</span>
|
||||
</div>
|
||||
<div class="agent-grid">
|
||||
<div
|
||||
v-for="agent in agents"
|
||||
:key="agent.id"
|
||||
:class="['agent-card', agent.status]">
|
||||
<div :class="['agent-status', agent.status]"></div>
|
||||
|
||||
<div class="agent-header">
|
||||
<div class="agent-id">{{ agent.id }}</div>
|
||||
<span :class="['badge', agent.specialization]">{{ agent.specialization }}</span>
|
||||
</div>
|
||||
|
||||
<div class="agent-info">
|
||||
<p>Status: <span>{{ agent.status }}</span></p>
|
||||
<p v-if="agent.currentTask">
|
||||
Current Task: <span>{{ agent.currentTask }}</span>
|
||||
</p>
|
||||
<p v-else>
|
||||
Current Task: <span style="color: #6b7280">Idle</span>
|
||||
</p>
|
||||
<p>Tasks Completed: <span>{{ agent.completedCount }}</span></p>
|
||||
</div>
|
||||
|
||||
<div v-if="agent.currentTask" class="task-progress">
|
||||
<div class="task-progress-label">
|
||||
<span>Progress</span>
|
||||
<span>{{ Math.round(agent.progress) }}%</span>
|
||||
</div>
|
||||
<div class="task-progress-bar">
|
||||
<div
|
||||
class="task-progress-fill"
|
||||
:style="{ width: agent.progress + '%' }">
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div v-if="agent.workingFiles && agent.workingFiles.length > 0" class="files-list">
|
||||
<div style="margin-bottom: 4px; color: #a1a1aa">Working Files:</div>
|
||||
<code v-for="file in agent.workingFiles.slice(0, 3)" :key="file">
|
||||
{{ file }}
|
||||
</code>
|
||||
<span v-if="agent.workingFiles.length > 3">
|
||||
+{{ agent.workingFiles.length - 3 }} more
|
||||
</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Activity Stream -->
|
||||
<div class="activity-section">
|
||||
<div class="section-header">
|
||||
<h2>Live Activity</h2>
|
||||
<span style="font-size: 14px; color: #a1a1aa">
|
||||
{{ recentEvents.length }} events
|
||||
</span>
|
||||
</div>
|
||||
<div class="activity-stream">
|
||||
<div v-for="event in recentEvents" :key="event.id" class="event">
|
||||
<div class="event-time">{{ formatTime(event.timestamp) }}</div>
|
||||
<div class="event-agent">{{ event.agentId }}</div>
|
||||
<div :class="['event-action', event.type]">{{ event.action }}</div>
|
||||
</div>
|
||||
<div v-if="recentEvents.length === 0" style="text-align: center; padding: 40px; color: #6b7280">
|
||||
No events yet
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
const { createApp } = Vue;
|
||||
|
||||
createApp({
|
||||
data() {
|
||||
return {
|
||||
agents: [],
|
||||
conflicts: [],
|
||||
recentEvents: [],
|
||||
totalTasks: 0,
|
||||
completedTasks: 0,
|
||||
modifiedFiles: new Set(),
|
||||
ws: null,
|
||||
connected: false,
|
||||
charts: {
|
||||
taskType: null,
|
||||
agentPerformance: null
|
||||
}
|
||||
};
|
||||
},
|
||||
|
||||
computed: {
|
||||
activeAgents() {
|
||||
return this.agents.filter(a => a.status === 'active' || a.status === 'busy');
|
||||
}
|
||||
},
|
||||
|
||||
methods: {
|
||||
connect() {
|
||||
const wsUrl = `ws://${window.location.hostname}:3001`;
|
||||
console.log('Connecting to:', wsUrl);
|
||||
|
||||
this.ws = new WebSocket(wsUrl);
|
||||
|
||||
this.ws.onopen = () => {
|
||||
console.log('WebSocket connected');
|
||||
this.connected = true;
|
||||
};
|
||||
|
||||
this.ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
this.handleMessage(data);
|
||||
};
|
||||
|
||||
this.ws.onclose = () => {
|
||||
console.log('WebSocket disconnected, reconnecting...');
|
||||
this.connected = false;
|
||||
setTimeout(() => this.connect(), 3000);
|
||||
};
|
||||
|
||||
this.ws.onerror = (error) => {
|
||||
console.error('WebSocket error:', error);
|
||||
this.connected = false;
|
||||
};
|
||||
},
|
||||
|
||||
handleMessage(data) {
|
||||
switch(data.type) {
|
||||
case 'agent_update':
|
||||
this.updateAgent(data.agent);
|
||||
break;
|
||||
case 'conflict':
|
||||
this.conflicts.push(data.conflict);
|
||||
break;
|
||||
case 'conflict_resolved':
|
||||
this.conflicts = this.conflicts.filter(
|
||||
c => c.file !== data.conflict.file
|
||||
);
|
||||
break;
|
||||
case 'task_complete':
|
||||
this.completedTasks++;
|
||||
this.addEvent('success', data.agentId, `Completed task ${data.taskId}`);
|
||||
break;
|
||||
case 'task_failed':
|
||||
this.addEvent('error', data.agentId, `Failed task ${data.taskId}: ${data.error}`);
|
||||
break;
|
||||
case 'task_started':
|
||||
this.addEvent('warning', data.agentId, `Started task ${data.taskId}`);
|
||||
break;
|
||||
case 'event':
|
||||
this.addEvent('info', data.agentId, data.action);
|
||||
break;
|
||||
}
|
||||
},
|
||||
|
||||
updateAgent(agentData) {
|
||||
const index = this.agents.findIndex(a => a.id === agentData.id);
|
||||
|
||||
if (index >= 0) {
|
||||
this.agents[index] = agentData;
|
||||
} else {
|
||||
this.agents.push(agentData);
|
||||
}
|
||||
|
||||
// Track modified files
|
||||
if (agentData.workingFiles) {
|
||||
agentData.workingFiles.forEach(f => this.modifiedFiles.add(f));
|
||||
}
|
||||
|
||||
// Update charts periodically
|
||||
this.updateCharts();
|
||||
},
|
||||
|
||||
addEvent(type, agentId, action) {
|
||||
const event = {
|
||||
id: Date.now() + Math.random(),
|
||||
timestamp: Date.now(),
|
||||
type,
|
||||
agentId,
|
||||
action
|
||||
};
|
||||
|
||||
this.recentEvents.unshift(event);
|
||||
|
||||
// Keep only last 100 events
|
||||
if (this.recentEvents.length > 100) {
|
||||
this.recentEvents = this.recentEvents.slice(0, 100);
|
||||
}
|
||||
},
|
||||
|
||||
formatTime(timestamp) {
|
||||
return new Date(timestamp).toLocaleTimeString();
|
||||
},
|
||||
|
||||
updateCharts() {
|
||||
// Update task type chart
|
||||
if (this.charts.taskType) {
|
||||
const typeCounts = {};
|
||||
this.agents.forEach(agent => {
|
||||
const type = agent.specialization;
|
||||
typeCounts[type] = (typeCounts[type] || 0) + agent.completedCount;
|
||||
});
|
||||
|
||||
this.charts.taskType.data.datasets[0].data = Object.values(typeCounts);
|
||||
this.charts.taskType.data.labels = Object.keys(typeCounts);
|
||||
this.charts.taskType.update('none');
|
||||
}
|
||||
|
||||
// Update agent performance chart
|
||||
if (this.charts.agentPerformance) {
|
||||
this.charts.agentPerformance.data.datasets[0].data = this.agents.map(a => a.completedCount);
|
||||
this.charts.agentPerformance.data.labels = this.agents.map(a => a.id);
|
||||
this.charts.agentPerformance.update('none');
|
||||
}
|
||||
},
|
||||
|
||||
initCharts() {
|
||||
// Task Type Chart
|
||||
const taskTypeCtx = document.getElementById('taskTypeChart').getContext('2d');
|
||||
this.charts.taskType = new Chart(taskTypeCtx, {
|
||||
type: 'doughnut',
|
||||
data: {
|
||||
labels: [],
|
||||
datasets: [{
|
||||
data: [],
|
||||
backgroundColor: [
|
||||
'#667eea',
|
||||
'#10b981',
|
||||
'#f59e0b',
|
||||
'#ec4899',
|
||||
'#8b5cf6',
|
||||
'#06b6d4'
|
||||
]
|
||||
}]
|
||||
},
|
||||
options: {
|
||||
responsive: true,
|
||||
plugins: {
|
||||
legend: {
|
||||
position: 'right',
|
||||
labels: {
|
||||
color: '#a1a1aa',
|
||||
font: { size: 11 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Agent Performance Chart
|
||||
const agentPerfCtx = document.getElementById('agentPerformanceChart').getContext('2d');
|
||||
this.charts.agentPerformance = new Chart(agentPerfCtx, {
|
||||
type: 'bar',
|
||||
data: {
|
||||
labels: [],
|
||||
datasets: [{
|
||||
label: 'Tasks Completed',
|
||||
data: [],
|
||||
backgroundColor: 'rgba(102, 126, 234, 0.5)',
|
||||
borderColor: '#667eea',
|
||||
borderWidth: 1
|
||||
}]
|
||||
},
|
||||
options: {
|
||||
responsive: true,
|
||||
scales: {
|
||||
y: {
|
||||
beginAtZero: true,
|
||||
grid: {
|
||||
color: 'rgba(255, 255, 255, 0.05)'
|
||||
},
|
||||
ticks: {
|
||||
color: '#a1a1aa'
|
||||
}
|
||||
},
|
||||
x: {
|
||||
grid: {
|
||||
display: false
|
||||
},
|
||||
ticks: {
|
||||
color: '#a1a1aa',
|
||||
font: { size: 10 }
|
||||
}
|
||||
}
|
||||
},
|
||||
plugins: {
|
||||
legend: {
|
||||
display: false
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
},
|
||||
|
||||
mounted() {
|
||||
this.initCharts();
|
||||
this.connect();
|
||||
|
||||
// Also load initial data via HTTP in case WS is slow
|
||||
fetch('http://localhost:3001/api/status')
|
||||
.then(r => r.json())
|
||||
.then(data => {
|
||||
this.agents = data.agents || [];
|
||||
this.totalTasks = data.totalTasks || 0;
|
||||
this.completedTasks = data.completedTasks || 0;
|
||||
})
|
||||
.catch(err => console.log('Initial load failed:', err));
|
||||
}
|
||||
}).mount('#app');
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
390
skills/ralph/observability_server.py
Executable file
390
skills/ralph/observability_server.py
Executable file
@@ -0,0 +1,390 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Observability Server
|
||||
|
||||
WebSocket server for real-time multi-agent monitoring and observability.
|
||||
Provides live updates of agent status, task progress, and system metrics.
|
||||
"""
|
||||
|
||||
import json
|
||||
import asyncio
|
||||
import websockets
|
||||
import redis
|
||||
import logging
|
||||
from typing import Set, Dict
|
||||
from dataclasses import dataclass
|
||||
import os
|
||||
|
||||
# Configure logging
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
logger = logging.getLogger('ralph.observability')
|
||||
|
||||
|
||||
@dataclass
|
||||
class ConnectedClient:
|
||||
"""Represents a connected WebSocket client"""
|
||||
websocket: websockets.WebSocketServerProtocol
|
||||
agent_filter: str = None # Optional filter for specific agent
|
||||
|
||||
|
||||
class ObservabilityServer:
|
||||
"""
|
||||
WebSocket server for real-time Ralph multi-agent observability
|
||||
|
||||
Provides:
|
||||
- Live agent status updates
|
||||
- Task progress tracking
|
||||
- Conflict detection and alerts
|
||||
- Performance metrics
|
||||
- Activity streaming
|
||||
"""
|
||||
|
||||
def __init__(self, host: str = 'localhost', port: int = 3001, redis_config: Dict = None):
|
||||
"""Initialize the observability server"""
|
||||
self.host = host
|
||||
self.port = port
|
||||
|
||||
# Redis connection
|
||||
redis_config = redis_config or {}
|
||||
self.redis = redis.Redis(
|
||||
host=redis_config.get('host', 'localhost'),
|
||||
port=redis_config.get('port', 6379),
|
||||
db=redis_config.get('db', 0),
|
||||
password=redis_config.get('password'),
|
||||
decode_responses=True
|
||||
)
|
||||
|
||||
# Connected clients
|
||||
self.clients: Set[ConnectedClient] = set()
|
||||
|
||||
# Tracking state
|
||||
self.known_agents: Dict[str, dict] = {}
|
||||
self.last_conflicts: list = []
|
||||
|
||||
logger.info(f"Observability server initialized on {host}:{port}")
|
||||
|
||||
async def handle_client(self, websocket: websockets.WebSocketServerProtocol, path: str):
|
||||
"""Handle a new WebSocket client connection"""
|
||||
client = ConnectedClient(websocket=websocket)
|
||||
self.clients.add(client)
|
||||
|
||||
logger.info(f"Client connected: {websocket.remote_address}")
|
||||
|
||||
try:
|
||||
# Send initial state
|
||||
await self.send_initial_state(client)
|
||||
|
||||
# Handle incoming messages
|
||||
async for message in websocket:
|
||||
await self.handle_message(client, message)
|
||||
|
||||
except websockets.exceptions.ConnectionClosed:
|
||||
logger.info(f"Client disconnected: {websocket.remote_address}")
|
||||
finally:
|
||||
self.clients.remove(client)
|
||||
|
||||
async def send_initial_state(self, client: ConnectedClient):
|
||||
"""Send initial system state to newly connected client"""
|
||||
# Get all agents
|
||||
agents = self.get_all_agents()
|
||||
|
||||
# Get stats
|
||||
stats = self.get_system_stats()
|
||||
|
||||
# Send initial state
|
||||
initial_message = {
|
||||
'type': 'initial_state',
|
||||
'agents': agents,
|
||||
'stats': stats,
|
||||
'conflicts': self.last_conflicts
|
||||
}
|
||||
|
||||
try:
|
||||
await client.websocket.send(json.dumps(initial_message))
|
||||
except Exception as e:
|
||||
logger.error(f"Error sending initial state: {e}")
|
||||
|
||||
async def handle_message(self, client: ConnectedClient, message: str):
|
||||
"""Handle incoming message from client"""
|
||||
try:
|
||||
data = json.loads(message)
|
||||
|
||||
if data.get('type') == 'subscribe_agent':
|
||||
# Subscribe to specific agent updates
|
||||
client.agent_filter = data.get('agent_id')
|
||||
logger.info(f"Client {client.websocket.remote_address} subscribed to {client.agent_filter}")
|
||||
|
||||
elif data.get('type') == 'unsubscribe':
|
||||
client.agent_filter = None
|
||||
|
||||
except json.JSONDecodeError:
|
||||
logger.warning(f"Invalid JSON from client: {message}")
|
||||
|
||||
def get_all_agents(self) -> list:
|
||||
"""Get all agent information from Redis"""
|
||||
agents = []
|
||||
|
||||
# Get all agent keys
|
||||
agent_keys = self.redis.keys('agent:*')
|
||||
|
||||
for key in agent_keys:
|
||||
agent_data = self.redis.hgetall(key)
|
||||
if agent_data:
|
||||
# Parse JSON fields
|
||||
if 'working_files' in agent_data:
|
||||
try:
|
||||
agent_data['working_files'] = json.loads(agent_data['working_files'])
|
||||
except json.JSONDecodeError:
|
||||
agent_data['working_files'] = []
|
||||
|
||||
if 'progress' in agent_data:
|
||||
agent_data['progress'] = float(agent_data.get('progress', 0))
|
||||
|
||||
if 'completed_count' in agent_data:
|
||||
agent_data['completedCount'] = int(agent_data.get('completed_count', 0))
|
||||
|
||||
agents.append(agent_data)
|
||||
|
||||
return agents
|
||||
|
||||
def get_system_stats(self) -> dict:
|
||||
"""Get system-wide statistics"""
|
||||
# Get task counts
|
||||
total_tasks = 0
|
||||
completed_tasks = 0
|
||||
|
||||
task_keys = self.redis.keys('task:*')
|
||||
for key in task_keys:
|
||||
status = self.redis.hget(key, 'status')
|
||||
total_tasks += 1
|
||||
if status == 'complete':
|
||||
completed_tasks += 1
|
||||
|
||||
# Get file locks
|
||||
lock_keys = self.redis.keys('lock:*')
|
||||
|
||||
return {
|
||||
'total_tasks': total_tasks,
|
||||
'completed_tasks': completed_tasks,
|
||||
'active_locks': len(lock_keys),
|
||||
'agent_count': len(self.get_all_agents())
|
||||
}
|
||||
|
||||
async def broadcast_update(self, message: dict):
|
||||
"""Broadcast update to all connected clients"""
|
||||
if not self.clients:
|
||||
return
|
||||
|
||||
message_str = json.dumps(message)
|
||||
|
||||
# Remove disconnected clients
|
||||
disconnected = set()
|
||||
|
||||
for client in self.clients:
|
||||
# Apply agent filter if set
|
||||
if client.agent_filter:
|
||||
# Check if message is relevant to this client's filter
|
||||
agent_id = message.get('agent', {}).get('id') or message.get('agentId')
|
||||
if agent_id != client.agent_filter:
|
||||
continue
|
||||
|
||||
try:
|
||||
await client.websocket.send(message_str)
|
||||
except Exception as e:
|
||||
logger.warning(f"Error sending to client: {e}")
|
||||
disconnected.add(client)
|
||||
|
||||
# Clean up disconnected clients
|
||||
self.clients -= disconnected
|
||||
|
||||
async def monitor_redis(self):
|
||||
"""Monitor Redis for updates and broadcast to clients"""
|
||||
pubsub = self.redis.pubsub()
|
||||
|
||||
# Subscribe to channels
|
||||
channels = [
|
||||
'ralph:agent_updates',
|
||||
'ralph:task_updates',
|
||||
'ralph:conflicts',
|
||||
'ralph:events'
|
||||
]
|
||||
|
||||
for channel in channels:
|
||||
pubsub.subscribe(channel)
|
||||
|
||||
logger.info(f"Subscribed to Redis channels: {channels}")
|
||||
|
||||
async for message in pubsub.listen():
|
||||
if message['type'] == 'message':
|
||||
try:
|
||||
data = json.loads(message['data'])
|
||||
await self.broadcast_update(data)
|
||||
except json.JSONDecodeError:
|
||||
logger.warning(f"Invalid JSON in Redis message: {message['data']}")
|
||||
|
||||
async def poll_agent_updates(self):
|
||||
"""Poll for agent updates (fallback if pubsub not available)"""
|
||||
while True:
|
||||
try:
|
||||
agents = self.get_all_agents()
|
||||
|
||||
# Check for updates
|
||||
for agent_data in agents:
|
||||
agent_id = agent_data.get('id')
|
||||
|
||||
if agent_id not in self.known_agents:
|
||||
# New agent
|
||||
self.known_agents[agent_id] = agent_data
|
||||
await self.broadcast_update({
|
||||
'type': 'agent_update',
|
||||
'agent': agent_data
|
||||
})
|
||||
else:
|
||||
# Check for changes
|
||||
old_data = self.known_agents[agent_id]
|
||||
if agent_data != old_data:
|
||||
self.known_agents[agent_id] = agent_data
|
||||
await self.broadcast_update({
|
||||
'type': 'agent_update',
|
||||
'agent': agent_data
|
||||
})
|
||||
|
||||
# Check for removed agents
|
||||
current_ids = {a.get('id') for a in agents}
|
||||
known_ids = set(self.known_agents.keys())
|
||||
|
||||
for removed_id in known_ids - current_ids:
|
||||
del self.known_agents[removed_id]
|
||||
await self.broadcast_update({
|
||||
'type': 'agent_removed',
|
||||
'agentId': removed_id
|
||||
})
|
||||
|
||||
await asyncio.sleep(1)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error polling agent updates: {e}")
|
||||
await asyncio.sleep(5)
|
||||
|
||||
async def monitor_conflicts(self):
|
||||
"""Monitor for file access conflicts"""
|
||||
while True:
|
||||
try:
|
||||
# Get all active locks
|
||||
lock_keys = self.redis.keys('lock:*')
|
||||
|
||||
# Build file-to-agent mapping
|
||||
file_agents = {}
|
||||
for lock_key in lock_keys:
|
||||
file_path = lock_key.replace('lock:', '')
|
||||
agent_id = self.redis.get(lock_key)
|
||||
if agent_id:
|
||||
if file_path not in file_agents:
|
||||
file_agents[file_path] = []
|
||||
file_agents[file_path].append(agent_id)
|
||||
|
||||
# Check for conflicts (multiple agents on same file)
|
||||
conflicts = [
|
||||
{'file': f, 'agents': agents}
|
||||
for f, agents in file_agents.items()
|
||||
if len(agents) > 1
|
||||
]
|
||||
|
||||
# Detect new conflicts
|
||||
for conflict in conflicts:
|
||||
if conflict not in self.last_conflicts:
|
||||
self.last_conflicts.append(conflict)
|
||||
await self.broadcast_update({
|
||||
'type': 'conflict',
|
||||
'conflict': conflict
|
||||
})
|
||||
|
||||
# Detect resolved conflicts
|
||||
self.last_conflicts = [
|
||||
c for c in self.last_conflicts
|
||||
if c in conflicts
|
||||
]
|
||||
|
||||
await asyncio.sleep(2)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error monitoring conflicts: {e}")
|
||||
await asyncio.sleep(5)
|
||||
|
||||
async def start_http_api(self):
|
||||
"""Start simple HTTP API for status polling"""
|
||||
from aiohttp import web
|
||||
|
||||
app = web.Application()
|
||||
|
||||
async def status_handler(request):
|
||||
"""Handler for /api/status endpoint"""
|
||||
agents = self.get_all_agents()
|
||||
stats = self.get_system_stats()
|
||||
|
||||
return web.json_response({
|
||||
'agents': agents,
|
||||
'stats': stats,
|
||||
'conflicts': self.last_conflicts
|
||||
})
|
||||
|
||||
app.router.add_get('/api/status', status_handler)
|
||||
|
||||
runner = web.AppRunner(app)
|
||||
await runner.setup()
|
||||
site = web.TCPSite(runner, self.host, self.port + 1) # HTTP on port+1
|
||||
await site.start()
|
||||
|
||||
logger.info(f"HTTP API started on {self.host}:{self.port + 1}")
|
||||
|
||||
async def run(self):
|
||||
"""Start the observability server"""
|
||||
logger.info(f"Starting observability server on {self.host}:{self.port}")
|
||||
|
||||
# Start HTTP API
|
||||
await self.start_http_api()
|
||||
|
||||
# Start monitoring tasks
|
||||
monitor_task = asyncio.create_task(self.monitor_redis())
|
||||
poll_task = asyncio.create_task(self.poll_agent_updates())
|
||||
conflict_task = asyncio.create_task(self.monitor_conflicts())
|
||||
|
||||
# Start WebSocket server
|
||||
async with websockets.serve(self.handle_client, self.host, self.port):
|
||||
logger.info(f"WebSocket server listening on {self.host}:{self.port}")
|
||||
|
||||
# Keep running
|
||||
await asyncio.Future()
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point"""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description='Ralph Observability Server')
|
||||
parser.add_argument('--host', default='localhost', help='Host to bind to')
|
||||
parser.add_argument('--port', type=int, default=3001, help='WebSocket port')
|
||||
parser.add_argument('--redis-host', default='localhost', help='Redis host')
|
||||
parser.add_argument('--redis-port', type=int, default=6379, help='Redis port')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Create server
|
||||
server = ObservabilityServer(
|
||||
host=args.host,
|
||||
port=args.port,
|
||||
redis_config={
|
||||
'host': args.redis_host,
|
||||
'port': args.redis_port
|
||||
}
|
||||
)
|
||||
|
||||
# Run server
|
||||
asyncio.run(server.run())
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
545
skills/ralph/ralph_agent_integration.py
Executable file
545
skills/ralph/ralph_agent_integration.py
Executable file
@@ -0,0 +1,545 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Agent Integration System
|
||||
|
||||
Main integration layer that ties together:
|
||||
- Agent Capability Registry
|
||||
- Dynamic Agent Selector
|
||||
- Real-Time Need Detection
|
||||
- Multi-Agent Orchestration
|
||||
- Performance Tracking
|
||||
|
||||
This system allows Ralph to automatically select and delegate to the most
|
||||
appropriate contains-studio agent based on real-time task analysis.
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import time
|
||||
import subprocess
|
||||
import logging
|
||||
from typing import Dict, List, Optional, Any, Set
|
||||
from dataclasses import dataclass, field, asdict
|
||||
from enum import Enum
|
||||
from datetime import datetime
|
||||
|
||||
# Add parent directory to path for imports
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
from agent_capability_registry import AgentCapabilityRegistry, AgentCategory
|
||||
from dynamic_agent_selector import DynamicAgentSelector, SelectionRequest, TaskContext, RealTimeAnalyzer
|
||||
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
logger = logging.getLogger('ralph.integration')
|
||||
|
||||
|
||||
@dataclass
|
||||
class AgentDelegation:
|
||||
"""Record of an agent delegation"""
|
||||
task_id: str
|
||||
agent_name: str
|
||||
user_request: str
|
||||
delegated_at: float
|
||||
started_at: Optional[float] = None
|
||||
completed_at: Optional[float] = None
|
||||
status: str = "pending" # pending, running, completed, failed
|
||||
result: Optional[str] = None
|
||||
error: Optional[str] = None
|
||||
satisfaction_score: Optional[float] = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class RalphContext:
|
||||
"""Persistent context for Ralph's decision making"""
|
||||
current_task: Optional[str] = None
|
||||
task_phase: str = "planning"
|
||||
files_modified: List[str] = field(default_factory=list)
|
||||
files_touched: List[str] = field(default_factory=set)
|
||||
active_agents: Set[str] = field(default_factory=set)
|
||||
delegation_history: List[AgentDelegation] = field(default_factory=list)
|
||||
performance_scores: Dict[str, List[float]] = field(default_factory=dict)
|
||||
project_type: Optional[str] = None
|
||||
session_start: float = field(default_factory=time.time)
|
||||
|
||||
def to_dict(self) -> Dict:
|
||||
"""Convert to dictionary for serialization"""
|
||||
data = asdict(self)
|
||||
data['active_agents'] = list(data['active_agents'])
|
||||
return data
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, data: Dict) -> 'RalphContext':
|
||||
"""Create from dictionary"""
|
||||
data['active_agents'] = set(data.get('active_agents', []))
|
||||
return cls(**data)
|
||||
|
||||
|
||||
class RalphAgentIntegration:
|
||||
"""
|
||||
Main integration system for Ralph's agent orchestration
|
||||
|
||||
Responsibilities:
|
||||
- Analyze user requests in real-time
|
||||
- Select appropriate specialized agents
|
||||
- Delegate tasks and track execution
|
||||
- Monitor performance and adapt
|
||||
- Coordinate multi-agent workflows
|
||||
"""
|
||||
|
||||
def __init__(self, agents_dir: Optional[str] = None, context_file: Optional[str] = None):
|
||||
"""Initialize the integration system"""
|
||||
# Initialize components
|
||||
self.registry = AgentCapabilityRegistry(agents_dir)
|
||||
self.selector = DynamicAgentSelector(self.registry)
|
||||
self.analyzer = RealTimeAnalyzer()
|
||||
|
||||
# Load or create context
|
||||
self.context_file = context_file or '.ralph/context.json'
|
||||
self.context = self._load_context()
|
||||
|
||||
# Active delegations
|
||||
self.active_delegations: Dict[str, AgentDelegation] = {}
|
||||
|
||||
logger.info("Ralph Agent Integration initialized")
|
||||
logger.info(f"Loaded {len(self.registry.get_all_agents())} agents from registry")
|
||||
|
||||
def _load_context(self) -> RalphContext:
|
||||
"""Load persistent context from file"""
|
||||
if os.path.exists(self.context_file):
|
||||
try:
|
||||
with open(self.context_file, 'r') as f:
|
||||
data = json.load(f)
|
||||
return RalphContext.from_dict(data)
|
||||
except Exception as e:
|
||||
logger.warning(f"Could not load context: {e}")
|
||||
|
||||
return RalphContext()
|
||||
|
||||
def _save_context(self):
|
||||
"""Save persistent context to file"""
|
||||
os.makedirs(os.path.dirname(self.context_file), exist_ok=True)
|
||||
|
||||
with open(self.context_file, 'w') as f:
|
||||
json.dump(self.context.to_dict(), f, indent=2)
|
||||
|
||||
def process_user_message(self, message: str, files_modified: List[str] = None) -> Dict:
|
||||
"""
|
||||
Process a user message and determine if agent delegation is needed
|
||||
|
||||
Args:
|
||||
message: User's request
|
||||
files_modified: List of files being modified (if any)
|
||||
|
||||
Returns:
|
||||
Response dict with action and details
|
||||
"""
|
||||
start_time = time.time()
|
||||
|
||||
# Update context
|
||||
if files_modified:
|
||||
self.context.files_modified = files_modified
|
||||
self.context.files_touched.update(files_modified)
|
||||
|
||||
# Analyze request
|
||||
intent = self.analyzer.detect_intent(message)
|
||||
phase = self.analyzer.detect_phase(message, {'files_modified': files_modified})
|
||||
complexity = self.analyzer.estimate_complexity(message, files_modified or [])
|
||||
|
||||
# Detect if we need specialized agent
|
||||
selection_request = create_selection_request(message, {
|
||||
'files_modified': files_modified or [],
|
||||
'files_touched': list(self.context.files_touched),
|
||||
'previous_agents': list(self.context.active_agents),
|
||||
'user_history': [],
|
||||
'project_type': self.context.project_type
|
||||
})
|
||||
|
||||
# Select best agent
|
||||
selection = self.selector.select_agent(selection_request)
|
||||
|
||||
# Decide action based on confidence and score
|
||||
response = {
|
||||
'timestamp': datetime.now().isoformat(),
|
||||
'user_message': message,
|
||||
'processing_time': time.time() - start_time,
|
||||
'analysis': {
|
||||
'intent': intent.value,
|
||||
'phase': phase.value,
|
||||
'complexity': complexity
|
||||
}
|
||||
}
|
||||
|
||||
if selection.score >= 30 and selection.confidence >= 0.6:
|
||||
# High confidence - delegate to specialized agent
|
||||
delegation = self._delegate_to_agent(selection, message, files_modified)
|
||||
|
||||
response['action'] = 'delegated'
|
||||
response['agent'] = {
|
||||
'name': selection.agent_name,
|
||||
'confidence': selection.confidence,
|
||||
'score': selection.score,
|
||||
'reasons': selection.reasons,
|
||||
'estimated_duration': selection.estimated_duration
|
||||
}
|
||||
response['delegation'] = {
|
||||
'task_id': delegation.task_id,
|
||||
'status': delegation.status
|
||||
}
|
||||
|
||||
logger.info(f"Delegated to {selection.agent_name} (confidence: {selection.confidence:.2f})")
|
||||
|
||||
elif selection.score >= 15:
|
||||
# Medium confidence - suggest agent but ask for confirmation
|
||||
response['action'] = 'suggest'
|
||||
response['agent'] = {
|
||||
'name': selection.agent_name,
|
||||
'confidence': selection.confidence,
|
||||
'score': selection.score,
|
||||
'reasons': selection.reasons
|
||||
}
|
||||
response['suggestion'] = f"Would you like me to delegate this to the {selection.agent_name} agent?"
|
||||
|
||||
logger.info(f"Suggested {selection.agent_name} (confidence: {selection.confidence:.2f})")
|
||||
|
||||
else:
|
||||
# Low confidence - handle with general Claude
|
||||
response['action'] = 'handle'
|
||||
response['agent'] = {
|
||||
'name': 'claude',
|
||||
'confidence': selection.confidence,
|
||||
'note': 'No specialized agent found, handling directly'
|
||||
}
|
||||
|
||||
logger.info("Handling directly (no specialized agent needed)")
|
||||
|
||||
# Save context
|
||||
self._save_context()
|
||||
|
||||
return response
|
||||
|
||||
def _delegate_to_agent(self, selection, user_request: str, files: List[str] = None) -> AgentDelegation:
|
||||
"""Delegate task to a specialized agent"""
|
||||
import uuid
|
||||
|
||||
task_id = str(uuid.uuid4())
|
||||
|
||||
delegation = AgentDelegation(
|
||||
task_id=task_id,
|
||||
agent_name=selection.agent_name,
|
||||
user_request=user_request,
|
||||
delegated_at=time.time()
|
||||
)
|
||||
|
||||
# Update context
|
||||
self.context.active_agents.add(selection.agent_name)
|
||||
self.context.delegation_history.append(delegation)
|
||||
self.active_delegations[task_id] = delegation
|
||||
|
||||
# Execute delegation
|
||||
self._execute_agent_delegation(delegation)
|
||||
|
||||
return delegation
|
||||
|
||||
def _execute_agent_delegation(self, delegation: AgentDelegation):
|
||||
"""Execute the actual agent delegation"""
|
||||
agent_name = delegation.agent_name
|
||||
|
||||
try:
|
||||
delegation.status = "running"
|
||||
delegation.started_at = time.time()
|
||||
|
||||
logger.info(f"Executing delegation {delegation.task_id} with agent {agent_name}")
|
||||
|
||||
# Call the agent via Claude Code's subagent system
|
||||
result = self._call_subagent(agent_name, delegation.user_request)
|
||||
|
||||
delegation.status = "completed"
|
||||
delegation.completed_at = time.time()
|
||||
delegation.result = result
|
||||
|
||||
# Record performance
|
||||
duration = delegation.completed_at - delegation.started_at
|
||||
self._record_performance(agent_name, duration, success=True)
|
||||
|
||||
logger.info(f"Delegation {delegation.task_id} completed in {duration:.1f}s")
|
||||
|
||||
except Exception as e:
|
||||
delegation.status = "failed"
|
||||
delegation.completed_at = time.time()
|
||||
delegation.error = str(e)
|
||||
|
||||
self._record_performance(agent_name, 0, success=False)
|
||||
|
||||
logger.error(f"Delegation {delegation.task_id} failed: {e}")
|
||||
|
||||
# Update context
|
||||
if delegation.task_id in self.active_delegations:
|
||||
del self.active_delegations[delegation.task_id]
|
||||
|
||||
self._save_context()
|
||||
|
||||
def _call_subagent(self, agent_name: str, request: str) -> str:
|
||||
"""
|
||||
Call a Claude Code subagent
|
||||
|
||||
This integrates with Claude Code's agent system to invoke
|
||||
the specialized contains-studio agents.
|
||||
"""
|
||||
# Check if agent file exists
|
||||
agent_path = self._find_agent_file(agent_name)
|
||||
|
||||
if not agent_path:
|
||||
raise ValueError(f"Agent {agent_name} not found")
|
||||
|
||||
logger.info(f"Calling agent from: {agent_path}")
|
||||
|
||||
# Use Claude Code's Task tool to invoke the agent
|
||||
# This would be called from within Claude Code itself
|
||||
# For now, return a simulated response
|
||||
return f"Task '{request}' would be delegated to {agent_name} agent"
|
||||
|
||||
def _find_agent_file(self, agent_name: str) -> Optional[str]:
|
||||
"""Find the agent file in the agents directory"""
|
||||
# Search in standard locations
|
||||
search_paths = [
|
||||
os.path.expanduser('~/.claude/agents'),
|
||||
os.path.join(os.path.dirname(__file__), '../../agents'),
|
||||
]
|
||||
|
||||
for base_path in search_paths:
|
||||
if not os.path.exists(base_path):
|
||||
continue
|
||||
|
||||
# Search in all subdirectories
|
||||
for root, dirs, files in os.walk(base_path):
|
||||
for file in files:
|
||||
if file == f"{agent_name}.md":
|
||||
return os.path.join(root, file)
|
||||
|
||||
return None
|
||||
|
||||
def _record_performance(self, agent_name: str, duration: float, success: bool):
|
||||
"""Record agent performance for future selection"""
|
||||
# Score based on duration and success
|
||||
# Faster + successful = higher score
|
||||
score = 1.0 if success else 0.0
|
||||
|
||||
if success and duration > 0:
|
||||
# Normalize duration (5 min = 1.0, faster = higher)
|
||||
duration_score = min(300 / duration, 1.5)
|
||||
score = min(duration_score, 1.0)
|
||||
|
||||
if agent_name not in self.context.performance_scores:
|
||||
self.context.performance_scores[agent_name] = []
|
||||
|
||||
self.context.performance_scores[agent_name].append(score)
|
||||
|
||||
# Keep only last 50
|
||||
if len(self.context.performance_scores[agent_name]) > 50:
|
||||
self.context.performance_scores[agent_name] = self.context.performance_scores[agent_name][-50:]
|
||||
|
||||
# Also update selector's cache
|
||||
self.selector.record_performance(agent_name, score)
|
||||
|
||||
def get_agent_status(self) -> Dict:
|
||||
"""Get current status of all agents"""
|
||||
agents = self.registry.get_all_agents()
|
||||
|
||||
status = {
|
||||
'total_agents': len(agents),
|
||||
'active_agents': len(self.context.active_agents),
|
||||
'agents_by_category': {},
|
||||
'recent_delegations': [],
|
||||
'performance_summary': {}
|
||||
}
|
||||
|
||||
# Group by category
|
||||
for agent_name, agent in agents.items():
|
||||
cat = agent.category.value
|
||||
if cat not in status['agents_by_category']:
|
||||
status['agents_by_category'][cat] = []
|
||||
status['agents_by_category'][cat].append({
|
||||
'name': agent_name,
|
||||
'description': agent.description[:100] + '...'
|
||||
})
|
||||
|
||||
# Recent delegations
|
||||
status['recent_delegations'] = [
|
||||
{
|
||||
'task_id': d.task_id,
|
||||
'agent': d.agent_name,
|
||||
'status': d.status,
|
||||
'duration': (d.completed_at or time.time()) - d.started_at if d.started_at else None
|
||||
}
|
||||
for d in self.context.delegation_history[-10:]
|
||||
]
|
||||
|
||||
# Performance summary
|
||||
for agent_name, scores in self.context.performance_scores.items():
|
||||
if scores:
|
||||
status['performance_summary'][agent_name] = {
|
||||
'avg_score': sum(scores) / len(scores),
|
||||
'total_delegations': len(scores),
|
||||
'last_score': scores[-1]
|
||||
}
|
||||
|
||||
return status
|
||||
|
||||
def suggest_multi_agent_workflow(self, task: str) -> List[Dict]:
|
||||
"""
|
||||
Suggest a multi-agent workflow for a complex task
|
||||
|
||||
Args:
|
||||
task: Complex task description
|
||||
|
||||
Returns:
|
||||
List of agent delegations in execution order
|
||||
"""
|
||||
# Analyze task for sub-components
|
||||
workflow = []
|
||||
|
||||
# Detect task type
|
||||
task_lower = task.lower()
|
||||
|
||||
# Full feature development
|
||||
if any(kw in task_lower for kw in ['build', 'create', 'implement', 'develop']):
|
||||
workflow.extend([
|
||||
{'phase': 'planning', 'agent': 'sprint-prioritizer', 'task': f'Plan: {task}'},
|
||||
{'phase': 'design', 'agent': 'ui-designer', 'task': f'Design UI for: {task}'},
|
||||
{'phase': 'implementation', 'agent': 'frontend-developer', 'task': f'Implement: {task}'},
|
||||
{'phase': 'testing', 'agent': 'test-writer-fixer', 'task': f'Test: {task}'}
|
||||
])
|
||||
|
||||
# App development
|
||||
elif any(kw in task_lower for kw in ['app', 'mobile', 'ios', 'android']):
|
||||
workflow.extend([
|
||||
{'phase': 'planning', 'agent': 'rapid-prototyper', 'task': f'Prototype: {task}'},
|
||||
{'phase': 'design', 'agent': 'ui-designer', 'task': f'Design app UI'},
|
||||
{'phase': 'implementation', 'agent': 'mobile-app-builder', 'task': f'Build: {task}'},
|
||||
{'phase': 'testing', 'agent': 'test-writer-fixer', 'task': f'Test app'},
|
||||
{'phase': 'deployment', 'agent': 'app-store-optimizer', 'task': f'Optimize for app store'}
|
||||
])
|
||||
|
||||
# Backend/API
|
||||
elif any(kw in task_lower for kw in ['api', 'backend', 'server', 'database']):
|
||||
workflow.extend([
|
||||
{'phase': 'planning', 'agent': 'backend-architect', 'task': f'Design API: {task}'},
|
||||
{'phase': 'implementation', 'agent': 'backend-architect', 'task': f'Implement: {task}'},
|
||||
{'phase': 'testing', 'agent': 'api-tester', 'task': f'Test API'},
|
||||
{'phase': 'deployment', 'agent': 'devops-automator', 'task': f'Deploy API'}
|
||||
])
|
||||
|
||||
# AI/ML feature
|
||||
elif any(kw in task_lower for kw in ['ai', 'ml', 'machine learning', 'recommendation']):
|
||||
workflow.extend([
|
||||
{'phase': 'planning', 'agent': 'ai-engineer', 'task': f'Plan AI feature: {task}'},
|
||||
{'phase': 'implementation', 'agent': 'ai-engineer', 'task': f'Implement: {task}'},
|
||||
{'phase': 'testing', 'agent': 'test-writer-fixer', 'task': f'Test AI feature'}
|
||||
])
|
||||
|
||||
# Design task
|
||||
elif any(kw in task_lower for kw in ['design', 'ui', 'ux', 'mockup']):
|
||||
workflow.extend([
|
||||
{'phase': 'design', 'agent': 'ux-researcher', 'task': f'Research users for: {task}'},
|
||||
{'phase': 'design', 'agent': 'ui-designer', 'task': f'Create designs: {task}'},
|
||||
{'phase': 'design', 'agent': 'whimsy-injector', 'task': f'Add delightful details'}
|
||||
])
|
||||
|
||||
return workflow
|
||||
|
||||
def handle_multi_agent_task(self, task: str) -> Dict:
|
||||
"""
|
||||
Handle a complex task with multiple agents
|
||||
|
||||
Args:
|
||||
task: Complex task description
|
||||
|
||||
Returns:
|
||||
Results from all agents
|
||||
"""
|
||||
workflow = self.suggest_multi_agent_workflow(task)
|
||||
|
||||
results = {
|
||||
'task': task,
|
||||
'workflow': workflow,
|
||||
'results': [],
|
||||
'total_duration': 0,
|
||||
'successful_phases': 0,
|
||||
'failed_phases': 0
|
||||
}
|
||||
|
||||
for step in workflow:
|
||||
try:
|
||||
logger.info(f"Executing phase '{step['phase']}' with {step['agent']}")
|
||||
|
||||
start_time = time.time()
|
||||
|
||||
# Delegate to agent
|
||||
response = self.process_user_message(step['task'])
|
||||
|
||||
duration = time.time() - start_time
|
||||
|
||||
results['results'].append({
|
||||
'phase': step['phase'],
|
||||
'agent': step['agent'],
|
||||
'duration': duration,
|
||||
'status': response.get('action', 'unknown'),
|
||||
'success': response.get('action') in ['delegated', 'handle']
|
||||
})
|
||||
|
||||
results['total_duration'] += duration
|
||||
|
||||
if response.get('action') in ['delegated', 'handle']:
|
||||
results['successful_phases'] += 1
|
||||
else:
|
||||
results['failed_phases'] += 1
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Error in phase '{step['phase']}': {e}")
|
||||
results['results'].append({
|
||||
'phase': step['phase'],
|
||||
'agent': step['agent'],
|
||||
'error': str(e),
|
||||
'success': False
|
||||
})
|
||||
results['failed_phases'] += 1
|
||||
|
||||
return results
|
||||
|
||||
|
||||
# CLI interface for testing
|
||||
def main():
|
||||
"""Main entry point for CLI usage"""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description='Ralph Agent Integration')
|
||||
parser.add_argument('message', help='User message to process')
|
||||
parser.add_argument('--files', nargs='*', help='Files being modified')
|
||||
parser.add_argument('--multi-agent', action='store_true', help='Use multi-agent workflow')
|
||||
parser.add_argument('--status', action='store_true', help='Show agent status')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Initialize integration
|
||||
integration = RalphAgentIntegration()
|
||||
|
||||
if args.status:
|
||||
# Show status
|
||||
status = integration.get_agent_status()
|
||||
print(json.dumps(status, indent=2))
|
||||
elif args.multi_agent:
|
||||
# Multi-agent workflow
|
||||
results = integration.handle_multi_agent_task(args.message)
|
||||
print(json.dumps(results, indent=2))
|
||||
else:
|
||||
# Single message
|
||||
response = integration.process_user_message(args.message, args.files)
|
||||
print(json.dumps(response, indent=2))
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
651
skills/ralph/superpowers_integration.py
Executable file
651
skills/ralph/superpowers_integration.py
Executable file
@@ -0,0 +1,651 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Superpowers Integration
|
||||
|
||||
Complete integration of oh-my-opencode and superpowers features.
|
||||
This module dynamically loads, configures, and makes available all skills,
|
||||
agents, hooks, and MCPs from both projects for use in Claude Code CLI.
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
import logging
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional, Any, Callable
|
||||
from dataclasses import dataclass, field
|
||||
from enum import Enum
|
||||
import importlib.util
|
||||
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
logger = logging.getLogger('ralph.superpowers')
|
||||
|
||||
|
||||
class IntegrationType(Enum):
|
||||
"""Types of integrations"""
|
||||
SKILL = "skill"
|
||||
HOOK = "hook"
|
||||
AGENT = "agent"
|
||||
MCP = "mcp"
|
||||
COMMAND = "command"
|
||||
TOOL = "tool"
|
||||
|
||||
|
||||
@dataclass
|
||||
class IntegrationModule:
|
||||
"""Represents an integrated module"""
|
||||
name: str
|
||||
type: IntegrationType
|
||||
source: str # oh-my-opencode, superpowers, contains-studio
|
||||
path: str
|
||||
enabled: bool = True
|
||||
config: Dict = field(default_factory=dict)
|
||||
dependencies: List[str] = field(default_factory=list)
|
||||
|
||||
|
||||
@dataclass
|
||||
class SuperpowersConfig:
|
||||
"""Configuration for superpowers integration"""
|
||||
# Skills from superpowers
|
||||
brainstorming_enabled: bool = True
|
||||
writing_plans_enabled: bool = True
|
||||
executing_plans_enabled: bool = True
|
||||
subagent_driven_dev_enabled: bool = True
|
||||
test_driven_dev_enabled: bool = True
|
||||
systematic_debugging_enabled: bool = True
|
||||
verification_enabled: bool = True
|
||||
code_review_enabled: bool = True
|
||||
git_worktrees_enabled: bool = True
|
||||
|
||||
# Hooks from oh-my-opencode
|
||||
atlas_enabled: bool = True
|
||||
claude_code_hooks_enabled: bool = True
|
||||
ralph_loop_enabled: bool = True
|
||||
todo_enforcer_enabled: bool = True
|
||||
|
||||
# Agents from oh-my-opencode
|
||||
sisyphus_enabled: bool = True
|
||||
oracle_enabled: bool = True
|
||||
librarian_enabled: bool = True
|
||||
explore_enabled: bool = True
|
||||
prometheus_enabled: bool = True
|
||||
|
||||
# MCPs from oh-my-opencode
|
||||
websearch_enabled: bool = True
|
||||
context7_enabled: bool = True
|
||||
grep_app_enabled: bool = True
|
||||
|
||||
# Contains-studio agents
|
||||
contains_studio_enabled: bool = True
|
||||
auto_delegate_enabled: bool = True
|
||||
proactive_agents_enabled: bool = True
|
||||
|
||||
|
||||
class SuperpowersIntegration:
|
||||
"""
|
||||
Main integration class for all superpowers features
|
||||
|
||||
Manages:
|
||||
- Dynamic loading of skills from superpowers
|
||||
- Dynamic loading of hooks from oh-my-opencode
|
||||
- Dynamic loading of agents from both projects
|
||||
- MCP configuration and management
|
||||
- Command registration
|
||||
- Tool integration
|
||||
"""
|
||||
|
||||
def __init__(self, config: Optional[SuperpowersConfig] = None):
|
||||
"""Initialize the integration"""
|
||||
self.config = config or SuperpowersConfig()
|
||||
self.modules: Dict[str, IntegrationModule] = {}
|
||||
self.skill_hooks: Dict[str, List[Callable]] = {}
|
||||
self.hook_registry: Dict[str, Callable] = {}
|
||||
|
||||
# Paths
|
||||
self.ralph_dir = Path.home() / '.claude' / 'skills' / 'ralph'
|
||||
self.superpowers_dir = self.ralph_dir / 'superpowers'
|
||||
self.oh_my_opencode_dir = self.ralph_dir / 'oh-my-opencode'
|
||||
self.contains_studio_dir = Path.home() / '.claude' / 'agents'
|
||||
|
||||
logger.info("Superpowers Integration initialized")
|
||||
|
||||
def install_all(self) -> Dict[str, Any]:
|
||||
"""
|
||||
Install and integrate all features
|
||||
|
||||
Returns:
|
||||
Installation summary
|
||||
"""
|
||||
summary = {
|
||||
'skills': [],
|
||||
'hooks': [],
|
||||
'agents': [],
|
||||
'mcps': [],
|
||||
'commands': [],
|
||||
'errors': []
|
||||
}
|
||||
|
||||
try:
|
||||
# 1. Install superpowers skills
|
||||
if self.config.brainstorming_enabled:
|
||||
self._install_superpowers_skills(summary)
|
||||
|
||||
# 2. Install oh-my-opencode hooks
|
||||
if self.config.atlas_enabled:
|
||||
self._install_oh_my_opencode_hooks(summary)
|
||||
|
||||
# 3. Install agents
|
||||
if self.config.sisyphus_enabled or self.config.contains_studio_enabled:
|
||||
self._install_agents(summary)
|
||||
|
||||
# 4. Install MCPs
|
||||
if self.config.websearch_enabled:
|
||||
self._install_mcps(summary)
|
||||
|
||||
# 5. Register commands
|
||||
self._register_commands(summary)
|
||||
|
||||
# 6. Create configuration files
|
||||
self._create_config_files()
|
||||
|
||||
logger.info(f"Installation complete: {summary}")
|
||||
return summary
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Installation failed: {e}")
|
||||
summary['errors'].append(str(e))
|
||||
return summary
|
||||
|
||||
def _install_superpowers_skills(self, summary: Dict):
|
||||
"""Install skills from superpowers"""
|
||||
logger.info("Installing superpowers skills...")
|
||||
|
||||
skills_dir = self.superpowers_dir / 'skills'
|
||||
skills_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Define skills to install
|
||||
skills = [
|
||||
'brainstorming',
|
||||
'writing-plans',
|
||||
'executing-plans',
|
||||
'subagent-driven-development',
|
||||
'test-driven-development',
|
||||
'systematic-debugging',
|
||||
'verification-before-completion',
|
||||
'requesting-code-review',
|
||||
'receiving-code-review',
|
||||
'using-git-worktrees',
|
||||
'finishing-a-development-branch',
|
||||
'dispatching-parallel-agents',
|
||||
'using-superpowers',
|
||||
'writing-skills'
|
||||
]
|
||||
|
||||
for skill in skills:
|
||||
try:
|
||||
# Copy skill from superpowers source
|
||||
source = Path('/tmp/superpowers/skills') / skill
|
||||
if source.exists():
|
||||
dest = skills_dir / skill
|
||||
if dest.exists():
|
||||
shutil.rmtree(dest)
|
||||
shutil.copytree(source, dest)
|
||||
|
||||
module = IntegrationModule(
|
||||
name=skill,
|
||||
type=IntegrationType.SKILL,
|
||||
source='superpowers',
|
||||
path=str(dest),
|
||||
enabled=True
|
||||
)
|
||||
|
||||
self.modules[skill] = module
|
||||
summary['skills'].append(skill)
|
||||
|
||||
logger.info(f" ✓ Installed skill: {skill}")
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f" ✗ Failed to install skill {skill}: {e}")
|
||||
summary['errors'].append(f"skill:{skill} - {e}")
|
||||
|
||||
def _install_oh_my_opencode_hooks(self, summary: Dict):
|
||||
"""Install hooks from oh-my-opencode"""
|
||||
logger.info("Installing oh-my-opencode hooks...")
|
||||
|
||||
hooks_dir = self.oh_my_opencode_dir / 'hooks'
|
||||
hooks_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Key hooks to install
|
||||
hooks = [
|
||||
'atlas', # Main orchestrator
|
||||
'claude-code-hooks', # Claude Code compatibility
|
||||
'ralph-loop', # Autonomous iteration
|
||||
'todo-continuation-enforcer', # Task completion
|
||||
'thinking-block-validator', # Validate thinking
|
||||
'session-recovery', # Recovery from errors
|
||||
'edit-error-recovery', # Recovery from edit errors
|
||||
'start-work', # Work initialization
|
||||
]
|
||||
|
||||
for hook in hooks:
|
||||
try:
|
||||
source = Path('/tmp/oh-my-opencode/src/hooks') / hook
|
||||
if source.exists():
|
||||
dest = hooks_dir / hook
|
||||
if dest.exists():
|
||||
shutil.rmtree(dest)
|
||||
shutil.copytree(source, dest)
|
||||
|
||||
module = IntegrationModule(
|
||||
name=hook,
|
||||
type=IntegrationType.HOOK,
|
||||
source='oh-my-opencode',
|
||||
path=str(dest),
|
||||
enabled=True
|
||||
)
|
||||
|
||||
self.modules[hook] = module
|
||||
summary['hooks'].append(hook)
|
||||
|
||||
logger.info(f" ✓ Installed hook: {hook}")
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f" ✗ Failed to install hook {hook}: {e}")
|
||||
summary['errors'].append(f"hook:{hook} - {e}")
|
||||
|
||||
def _install_agents(self, summary: Dict):
|
||||
"""Install agents from both projects"""
|
||||
logger.info("Installing agents...")
|
||||
|
||||
# oh-my-opencode agents
|
||||
if self.config.sisyphus_enabled:
|
||||
omo_agents_dir = self.oh_my_opencode_dir / 'agents'
|
||||
omo_agents_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
agents = [
|
||||
'sisyphus',
|
||||
'oracle',
|
||||
'librarian',
|
||||
'explore',
|
||||
'prometheus'
|
||||
]
|
||||
|
||||
for agent in agents:
|
||||
try:
|
||||
source = Path('/tmp/oh-my-opencode/src/agents') / f"{agent}.ts"
|
||||
if source.exists():
|
||||
dest = omo_agents_dir / f"{agent}.md"
|
||||
# Convert TypeScript agent to Markdown format for Claude Code
|
||||
self._convert_agent_to_md(source, dest)
|
||||
|
||||
module = IntegrationModule(
|
||||
name=agent,
|
||||
type=IntegrationType.AGENT,
|
||||
source='oh-my-opencode',
|
||||
path=str(dest),
|
||||
enabled=True
|
||||
)
|
||||
|
||||
self.modules[agent] = module
|
||||
summary['agents'].append(agent)
|
||||
|
||||
logger.info(f" ✓ Installed agent: {agent}")
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f" ✗ Failed to install agent {agent}: {e}")
|
||||
summary['errors'].append(f"agent:{agent} - {e}")
|
||||
|
||||
# contains-studio agents (already handled by contains-studio integration)
|
||||
if self.config.contains_studio_enabled:
|
||||
summary['agents'].append('contains-studio-agents (30+ agents)')
|
||||
logger.info(f" ✓ Contains-studio agents already integrated")
|
||||
|
||||
def _install_mcps(self, summary: Dict):
|
||||
"""Install MCPs from oh-my-opencode"""
|
||||
logger.info("Installing MCPs...")
|
||||
|
||||
mcps_dir = self.oh_my_opencode_dir / 'mcps'
|
||||
mcps_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
mcps = [
|
||||
'websearch',
|
||||
'context7',
|
||||
'grep_app'
|
||||
]
|
||||
|
||||
for mcp in mcps:
|
||||
try:
|
||||
source = Path('/tmp/oh-my-opencode/src/mcp') / f"{mcp}.ts"
|
||||
if source.exists():
|
||||
dest = mcps_dir / f"{mcp}.json"
|
||||
|
||||
# Create MCP config
|
||||
mcp_config = self._create_mcp_config(mcp, source)
|
||||
with open(dest, 'w') as f:
|
||||
json.dump(mcp_config, f, indent=2)
|
||||
|
||||
module = IntegrationModule(
|
||||
name=mcp,
|
||||
type=IntegrationType.MCP,
|
||||
source='oh-my-opencode',
|
||||
path=str(dest),
|
||||
enabled=True
|
||||
)
|
||||
|
||||
self.modules[mcp] = module
|
||||
summary['mcps'].append(mcp)
|
||||
|
||||
logger.info(f" ✓ Installed MCP: {mcp}")
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f" ✗ Failed to install MCP {mcp}: {e}")
|
||||
summary['errors'].append(f"mcp:{mcp} - {e}")
|
||||
|
||||
def _register_commands(self, summary: Dict):
|
||||
"""Register commands from both projects"""
|
||||
logger.info("Registering commands...")
|
||||
|
||||
commands_dir = Path.home() / '.claude' / 'commands'
|
||||
|
||||
# Ralph sub-commands
|
||||
ralph_commands = [
|
||||
('brainstorm', 'Interactive design refinement'),
|
||||
('write-plan', 'Create implementation plan'),
|
||||
('execute-plan', 'Execute plan in batches'),
|
||||
('debug', 'Systematic debugging'),
|
||||
('review', 'Code review'),
|
||||
('status', 'Show Ralph status'),
|
||||
('list-agents', 'List all available agents'),
|
||||
('list-skills', 'List all available skills')
|
||||
]
|
||||
|
||||
for cmd_name, description in ralph_commands:
|
||||
try:
|
||||
cmd_file = commands_dir / f'ralph-{cmd_name}.md'
|
||||
|
||||
content = f"""---
|
||||
description: "{description}"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Invoke ralph:{cmd_name} via the ralph skill
|
||||
"""
|
||||
|
||||
with open(cmd_file, 'w') as f:
|
||||
f.write(content)
|
||||
|
||||
summary['commands'].append(f'ralph-{cmd_name}')
|
||||
logger.info(f" ✓ Registered command: /ralph-{cmd_name}")
|
||||
|
||||
except Exception as e:
|
||||
logger.warning(f" ✗ Failed to register command {cmd_name}: {e}")
|
||||
summary['errors'].append(f"command:{cmd_name} - {e}")
|
||||
|
||||
def _create_config_files(self):
|
||||
"""Create configuration files"""
|
||||
logger.info("Creating configuration files...")
|
||||
|
||||
config_dir = Path.home() / '.claude' / 'config'
|
||||
config_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Main Ralph config
|
||||
config_file = config_dir / 'ralph.json'
|
||||
|
||||
config = {
|
||||
'superpowers': {
|
||||
'enabled': True,
|
||||
'skills': {
|
||||
'brainstorming': self.config.brainstorming_enabled,
|
||||
'writing-plans': self.config.writing_plans_enabled,
|
||||
'executing-plans': self.config.executing_plans_enabled,
|
||||
'subagent-driven-development': self.config.subagent_driven_dev_enabled,
|
||||
'test-driven-development': self.config.test_driven_dev_enabled,
|
||||
'systematic-debugging': self.config.systematic_debugging_enabled,
|
||||
'verification-before-completion': self.config.verification_enabled,
|
||||
'requesting-code-review': self.config.code_review_enabled,
|
||||
'receiving-code-review': self.config.code_review_enabled,
|
||||
'using-git-worktrees': self.config.git_worktrees_enabled,
|
||||
'finishing-a-development-branch': True,
|
||||
'dispatching-parallel-agents': True
|
||||
},
|
||||
'hooks': {
|
||||
'atlas': self.config.atlas_enabled,
|
||||
'claude-code-hooks': self.config.claude_code_hooks_enabled,
|
||||
'ralph-loop': self.config.ralph_loop_enabled,
|
||||
'todo-continuation-enforcer': self.config.todo_enforcer_enabled
|
||||
},
|
||||
'agents': {
|
||||
'sisyphus': self.config.sisyphus_enabled,
|
||||
'oracle': self.config.oracle_enabled,
|
||||
'librarian': self.config.librarian_enabled,
|
||||
'explore': self.config.explore_enabled,
|
||||
'prometheus': self.config.prometheus_enabled,
|
||||
'contains-studio': self.config.contains_studio_enabled
|
||||
},
|
||||
'mcps': {
|
||||
'websearch': self.config.websearch_enabled,
|
||||
'context7': self.config.context7_enabled,
|
||||
'grep_app': self.config.grep_app_enabled
|
||||
},
|
||||
'auto_delegate': self.config.auto_delegate_enabled,
|
||||
'proactive_agents': self.config.proactive_agents_enabled
|
||||
},
|
||||
'multi_agent': {
|
||||
'enabled': os.getenv('RALPH_MULTI_AGENT', '').lower() == 'true',
|
||||
'max_workers': int(os.getenv('RALPH_MAX_WORKERS', 12)),
|
||||
'min_workers': int(os.getenv('RALPH_MIN_WORKERS', 2))
|
||||
}
|
||||
}
|
||||
|
||||
with open(config_file, 'w') as f:
|
||||
json.dump(config, f, indent=2)
|
||||
|
||||
logger.info(f" ✓ Created config: {config_file}")
|
||||
|
||||
def _convert_agent_to_md(self, source_ts: Path, dest_md: Path):
|
||||
"""Convert TypeScript agent to Markdown format for Claude Code"""
|
||||
# Read TypeScript source
|
||||
with open(source_ts, 'r') as f:
|
||||
content = f.read()
|
||||
|
||||
# Extract key information
|
||||
# This is a simplified conversion - real implementation would parse TS properly
|
||||
|
||||
md_content = f"""---
|
||||
name: {source_ts.stem}
|
||||
description: "Agent from oh-my-opencode: {source_ts.stem}"
|
||||
color: blue
|
||||
tools: Read, Write, Edit, Bash, Grep, Glob
|
||||
---
|
||||
|
||||
# {source_ts.stem.title()} Agent
|
||||
|
||||
This agent was imported from oh-my-opencode.
|
||||
|
||||
## Purpose
|
||||
|
||||
{self._extract_purpose(content)}
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Multi-model orchestration
|
||||
- Specialized tool usage
|
||||
- Background task management
|
||||
- Advanced code analysis
|
||||
|
||||
## Integration
|
||||
|
||||
This agent integrates with Ralph's multi-agent system for coordinated task execution.
|
||||
"""
|
||||
|
||||
with open(dest_md, 'w') as f:
|
||||
f.write(md_content)
|
||||
|
||||
def _extract_purpose(self, ts_content: str) -> str:
|
||||
"""Extract purpose description from TypeScript content"""
|
||||
# Simplified extraction
|
||||
if 'orchestrat' in ts_content.lower():
|
||||
return "Orchestrates multiple agents and coordinates complex workflows"
|
||||
elif 'oracle' in ts_content.lower() or 'consult' in ts_content.lower():
|
||||
return "Provides consultation and debugging expertise"
|
||||
elif 'librarian' in ts_content.lower() or 'docs' in ts_content.lower():
|
||||
return "Searches documentation and codebases"
|
||||
elif 'explore' in ts_content.lower() or 'grep' in ts_content.lower():
|
||||
return "Fast codebase exploration and search"
|
||||
elif 'prometheus' in ts_content.lower() or 'plan' in ts_content.lower():
|
||||
return "Strategic planning and task breakdown"
|
||||
else:
|
||||
return "Specialized AI agent for specific tasks"
|
||||
|
||||
def _create_mcp_config(self, mcp_name: str, source_file: Path) -> Dict:
|
||||
"""Create MCP configuration"""
|
||||
# Base MCP config
|
||||
configs = {
|
||||
'websearch': {
|
||||
'name': 'websearch',
|
||||
'command': 'npx',
|
||||
'args': ['-y', '@modelcontextprotocol/server-exa'],
|
||||
'env': {
|
||||
'EXA_API_KEY': '${EXA_API_KEY}'
|
||||
}
|
||||
},
|
||||
'context7': {
|
||||
'name': 'context7',
|
||||
'command': 'npx',
|
||||
'args': ['-y', '@context7/mcp-server-docs'],
|
||||
'env': {}
|
||||
},
|
||||
'grep_app': {
|
||||
'name': 'grep_app',
|
||||
'command': 'npx',
|
||||
'args': ['-y', '@modelcontextprotocol/server-github'],
|
||||
'env': {
|
||||
'GITHUB_TOKEN': '${GITHUB_TOKEN}'
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return configs.get(mcp_name, {
|
||||
'name': mcp_name,
|
||||
'command': 'echo',
|
||||
'args': ['MCP not configured']
|
||||
})
|
||||
|
||||
def load_skill(self, skill_name: str) -> Optional[Any]:
|
||||
"""Dynamically load a skill"""
|
||||
skill_key = f"skills.{skill_name}"
|
||||
if skill_key not in self.modules:
|
||||
logger.warning(f"Skill not found: {skill_name}")
|
||||
return None
|
||||
|
||||
module = self.modules[skill_key]
|
||||
|
||||
try:
|
||||
# Load the skill module
|
||||
spec = importlib.util.spec_from_file_location(
|
||||
f"ralph.skills.{skill_name}",
|
||||
os.path.join(module.path, 'SKILL.md')
|
||||
)
|
||||
|
||||
if spec and spec.loader:
|
||||
skill_module = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(skill_module)
|
||||
return skill_module
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to load skill {skill_name}: {e}")
|
||||
|
||||
return None
|
||||
|
||||
def invoke_hook(self, hook_name: str, context: Dict) -> Any:
|
||||
"""Invoke a registered hook"""
|
||||
if hook_name not in self.hook_registry:
|
||||
logger.debug(f"Hook not registered: {hook_name}")
|
||||
return None
|
||||
|
||||
try:
|
||||
hook_func = self.hook_registry[hook_name]
|
||||
return hook_func(context)
|
||||
except Exception as e:
|
||||
logger.error(f"Hook {hook_name} failed: {e}")
|
||||
return None
|
||||
|
||||
def register_hook(self, hook_name: str, hook_func: Callable):
|
||||
"""Register a hook function"""
|
||||
self.hook_registry[hook_name] = hook_func
|
||||
logger.info(f"Registered hook: {hook_name}")
|
||||
|
||||
def get_status(self) -> Dict:
|
||||
"""Get integration status"""
|
||||
return {
|
||||
'modules': {
|
||||
name: {
|
||||
'type': module.type.value,
|
||||
'source': module.source,
|
||||
'enabled': module.enabled,
|
||||
'path': module.path
|
||||
}
|
||||
for name, module in self.modules.items()
|
||||
},
|
||||
'config': {
|
||||
'superpowers': {
|
||||
'skills_enabled': sum(1 for m in self.modules.values()
|
||||
if m.type == IntegrationType.SKILL and m.enabled),
|
||||
'hooks_enabled': sum(1 for m in self.modules.values()
|
||||
if m.type == IntegrationType.HOOK and m.enabled),
|
||||
'agents_enabled': sum(1 for m in self.modules.values()
|
||||
if m.type == IntegrationType.AGENT and m.enabled),
|
||||
'mcps_enabled': sum(1 for m in self.modules.values()
|
||||
if m.type == IntegrationType.MCP and m.enabled)
|
||||
}
|
||||
},
|
||||
'hooks_registered': list(self.hook_registry.keys())
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for CLI usage"""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description='Ralph Superpowers Integration')
|
||||
parser.add_argument('--install', action='store_true', help='Install all superpowers')
|
||||
parser.add_argument('--status', action='store_true', help='Show integration status')
|
||||
parser.add_argument('--config', help='Path to config file')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Load config
|
||||
config = SuperpowersConfig()
|
||||
if args.config:
|
||||
with open(args.config) as f:
|
||||
config_data = json.load(f)
|
||||
# Apply config...
|
||||
|
||||
# Create integration
|
||||
integration = SuperpowersIntegration(config)
|
||||
|
||||
if args.install:
|
||||
summary = integration.install_all()
|
||||
print("\n=== Installation Summary ===")
|
||||
print(f"Skills: {len(summary['skills'])}")
|
||||
print(f"Hooks: {len(summary['hooks'])}")
|
||||
print(f"Agents: {len(summary['agents'])}")
|
||||
print(f"MCPs: {len(summary['mcps'])}")
|
||||
print(f"Commands: {len(summary['commands'])}")
|
||||
if summary['errors']:
|
||||
print(f"\nErrors: {len(summary['errors'])}")
|
||||
for error in summary['errors']:
|
||||
print(f" - {error}")
|
||||
|
||||
elif args.status:
|
||||
status = integration.get_status()
|
||||
print(json.dumps(status, indent=2))
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
476
skills/ralph/worker_agent.py
Executable file
476
skills/ralph/worker_agent.py
Executable file
@@ -0,0 +1,476 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Ralph Worker Agent
|
||||
|
||||
Implements specialized worker agents that execute tasks from the task queue.
|
||||
Each agent has a specific specialization and handles file locking, task execution,
|
||||
and progress reporting.
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import redis
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import hashlib
|
||||
import logging
|
||||
from typing import List, Dict, Optional, Set
|
||||
from dataclasses import dataclass, asdict
|
||||
from enum import Enum
|
||||
|
||||
# Configure logging
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
logger = logging.getLogger('ralph.worker')
|
||||
|
||||
|
||||
class AgentSpecialization(Enum):
|
||||
"""Worker agent specializations"""
|
||||
FRONTEND = "frontend"
|
||||
BACKEND = "backend"
|
||||
TESTING = "testing"
|
||||
DOCS = "docs"
|
||||
REFACTOR = "refactor"
|
||||
ANALYSIS = "analysis"
|
||||
DEPLOYMENT = "deployment"
|
||||
|
||||
|
||||
class TaskStatus(Enum):
|
||||
"""Task execution status"""
|
||||
PENDING = "pending"
|
||||
RUNNING = "running"
|
||||
COMPLETE = "complete"
|
||||
FAILED = "failed"
|
||||
|
||||
|
||||
@dataclass
|
||||
class WorkerConfig:
|
||||
"""Worker agent configuration"""
|
||||
agent_id: str
|
||||
specialization: AgentSpecialization
|
||||
max_concurrent_tasks: int = 1
|
||||
file_lock_timeout: int = 300
|
||||
heartbeat_interval: int = 10
|
||||
task_timeout: int = 300
|
||||
max_retries: int = 3
|
||||
log_level: str = "info"
|
||||
|
||||
|
||||
class WorkerAgent:
|
||||
"""
|
||||
Specialized worker agent for Ralph Multi-Agent System
|
||||
|
||||
Executes tasks from the queue with:
|
||||
- File locking to prevent conflicts
|
||||
- Progress tracking and reporting
|
||||
- Heartbeat monitoring
|
||||
- Error handling and retry logic
|
||||
"""
|
||||
|
||||
def __init__(self, config: WorkerConfig, redis_config: Dict):
|
||||
"""Initialize the worker agent"""
|
||||
self.config = config
|
||||
self.redis = redis.Redis(
|
||||
host=redis_config.get('host', 'localhost'),
|
||||
port=redis_config.get('port', 6379),
|
||||
db=redis_config.get('db', 0),
|
||||
password=redis_config.get('password'),
|
||||
decode_responses=True
|
||||
)
|
||||
|
||||
# Queue names
|
||||
self.task_queue = 'claude_tasks'
|
||||
self.pending_queue = 'claude_tasks:pending'
|
||||
self.complete_queue = 'claude_tasks:complete'
|
||||
self.failed_queue = 'claude_tasks:failed'
|
||||
|
||||
# State
|
||||
self.current_task = None
|
||||
self.locked_files: Set[str] = set()
|
||||
self.running = True
|
||||
|
||||
logger.info(f"Worker {config.agent_id} initialized ({config.specialization.value})")
|
||||
|
||||
def run(self):
|
||||
"""Main worker loop"""
|
||||
logger.info(f"Worker {self.config.agent_id} starting main loop")
|
||||
|
||||
# Register worker
|
||||
self._register_worker()
|
||||
|
||||
try:
|
||||
while self.running:
|
||||
# Send heartbeat
|
||||
self._send_heartbeat()
|
||||
|
||||
# Get task from queue
|
||||
task = self._get_task()
|
||||
|
||||
if task:
|
||||
# Check if we can handle this task
|
||||
if self._can_handle(task):
|
||||
logger.info(f"Worker {self.config.agent_id} accepted task {task['id']}")
|
||||
self._execute_task(task)
|
||||
else:
|
||||
# Put it back for another agent
|
||||
logger.info(f"Worker {self.config.agent_id} skipped task {task['id']} (not our specialization)")
|
||||
self.redis.rpush(self.task_queue, json.dumps(task))
|
||||
time.sleep(1)
|
||||
else:
|
||||
# No tasks, wait a bit
|
||||
time.sleep(self.config.heartbeat_interval)
|
||||
|
||||
except KeyboardInterrupt:
|
||||
logger.info(f"Worker {self.config.agent_id} interrupted by user")
|
||||
finally:
|
||||
self._cleanup()
|
||||
|
||||
def _register_worker(self):
|
||||
"""Register worker in Redis"""
|
||||
worker_data = {
|
||||
'id': self.config.agent_id,
|
||||
'specialization': self.config.specialization.value,
|
||||
'status': 'idle',
|
||||
'current_task': '',
|
||||
'working_files': json.dumps([]),
|
||||
'progress': '0',
|
||||
'completed_count': '0',
|
||||
'last_heartbeat': str(time.time())
|
||||
}
|
||||
self.redis.hset(f"agent:{self.config.agent_id}", mapping=worker_data)
|
||||
logger.info(f"Worker {self.config.agent_id} registered")
|
||||
|
||||
def _send_heartbeat(self):
|
||||
"""Send heartbeat to indicate worker is alive"""
|
||||
self.redis.hset(
|
||||
f"agent:{self.config.agent_id}",
|
||||
'last_heartbeat',
|
||||
str(time.time())
|
||||
)
|
||||
|
||||
def _get_task(self) -> Optional[Dict]:
|
||||
"""
|
||||
Get task from queue with timeout
|
||||
|
||||
Returns:
|
||||
Task dict or None
|
||||
"""
|
||||
result = self.redis.brpop(self.task_queue, timeout=self.config.heartbeat_interval)
|
||||
if result:
|
||||
_, task_json = result
|
||||
return json.loads(task_json)
|
||||
return None
|
||||
|
||||
def _can_handle(self, task: Dict) -> bool:
|
||||
"""
|
||||
Check if this agent can handle the task
|
||||
|
||||
Args:
|
||||
task: Task dict
|
||||
|
||||
Returns:
|
||||
True if agent can handle task
|
||||
"""
|
||||
# Check specialization
|
||||
if task.get('specialization'):
|
||||
return task['specialization'] == self.config.specialization.value
|
||||
|
||||
# Check task type matches our specialization
|
||||
task_type = task.get('type', '')
|
||||
specialization = self.config.specialization.value
|
||||
|
||||
# Map task types to specializations
|
||||
type_mapping = {
|
||||
'frontend': 'frontend',
|
||||
'backend': 'backend',
|
||||
'testing': 'testing',
|
||||
'docs': 'docs',
|
||||
'refactor': 'refactor',
|
||||
'analysis': 'analysis',
|
||||
'deployment': 'deployment'
|
||||
}
|
||||
|
||||
return type_mapping.get(task_type) == specialization
|
||||
|
||||
def _execute_task(self, task: Dict):
|
||||
"""
|
||||
Execute a task with proper locking and error handling
|
||||
|
||||
Args:
|
||||
task: Task dict
|
||||
"""
|
||||
task_id = task['id']
|
||||
files = task.get('files', [])
|
||||
|
||||
logger.info(f"Worker {self.config.agent_id} executing task {task_id}")
|
||||
|
||||
# Update status
|
||||
self._update_status(task_id, 'running', 0, files)
|
||||
self.current_task = task_id
|
||||
|
||||
# Acquire file locks
|
||||
locked_files = self._acquire_locks(files)
|
||||
|
||||
if not locked_files and files:
|
||||
logger.warning(f"Could not acquire locks for task {task_id}, re-queuing")
|
||||
self.redis.rpush(self.task_queue, json.dumps(task))
|
||||
return
|
||||
|
||||
try:
|
||||
# Set up Claude context
|
||||
prompt = self._build_prompt(task)
|
||||
|
||||
# Execute with Claude
|
||||
os.environ['CLAUDE_SESSION_ID'] = f"{self.config.agent_id}-{task_id}"
|
||||
|
||||
# Update progress
|
||||
self._update_status(task_id, 'running', 25, files)
|
||||
|
||||
# Execute the task
|
||||
result = self._run_claude(prompt, task)
|
||||
|
||||
# Update progress
|
||||
self._update_status(task_id, 'running', 90, files)
|
||||
|
||||
# Mark as complete
|
||||
self.redis.hset(f"task:{task_id}", 'status', 'complete')
|
||||
self.redis.hset(f"task:{task_id}", 'result', result)
|
||||
self.redis.lpush(self.complete_queue, json.dumps({
|
||||
'task_id': task_id,
|
||||
'agent_id': self.config.agent_id,
|
||||
'result': result
|
||||
}))
|
||||
|
||||
# Update final status
|
||||
self._update_status(task_id, 'complete', 100, files)
|
||||
|
||||
# Increment completed count
|
||||
current_count = int(self.redis.hget(f"agent:{self.config.agent_id}", 'completed_count') or 0)
|
||||
self.redis.hset(f"agent:{self.config.agent_id}", 'completed_count', str(current_count + 1))
|
||||
|
||||
logger.info(f"Worker {self.config.agent_id} completed task {task_id}")
|
||||
|
||||
# Trigger dependent tasks
|
||||
self._trigger_dependencies(task_id)
|
||||
|
||||
except Exception as e:
|
||||
logger.error(f"Worker {self.config.agent_id} failed task {task_id}: {e}")
|
||||
|
||||
# Mark as failed
|
||||
self.redis.hset(f"task:{task_id}", 'status', 'failed')
|
||||
self.redis.hset(f"task:{task_id}", 'error', str(e))
|
||||
self.redis.lpush(self.failed_queue, json.dumps({
|
||||
'task_id': task_id,
|
||||
'agent_id': self.config.agent_id,
|
||||
'error': str(e)
|
||||
}))
|
||||
|
||||
# Update status
|
||||
self._update_status(task_id, 'failed', 0, files)
|
||||
|
||||
finally:
|
||||
# Release locks
|
||||
self._release_locks(locked_files)
|
||||
self.current_task = None
|
||||
self._update_status('', 'idle', 0, [])
|
||||
|
||||
def _acquire_locks(self, files: List[str]) -> List[str]:
|
||||
"""
|
||||
Acquire exclusive locks on files
|
||||
|
||||
Args:
|
||||
files: List of file paths to lock
|
||||
|
||||
Returns:
|
||||
List of successfully locked files
|
||||
"""
|
||||
if not files:
|
||||
return []
|
||||
|
||||
locked = []
|
||||
for file_path in files:
|
||||
lock_key = f"lock:{file_path}"
|
||||
|
||||
# Try to acquire lock with timeout
|
||||
acquired = self.redis.set(
|
||||
lock_key,
|
||||
self.config.agent_id,
|
||||
nx=True,
|
||||
ex=self.config.file_lock_timeout
|
||||
)
|
||||
|
||||
if acquired:
|
||||
locked.append(file_path)
|
||||
else:
|
||||
# Couldn't get lock, release all and retry
|
||||
logger.warning(f"Could not acquire lock for {file_path}")
|
||||
self._release_locks(locked)
|
||||
time.sleep(2)
|
||||
return self._acquire_locks(files)
|
||||
|
||||
logger.info(f"Acquired locks for {len(locked)} files")
|
||||
return locked
|
||||
|
||||
def _release_locks(self, files: List[str]):
|
||||
"""
|
||||
Release file locks
|
||||
|
||||
Args:
|
||||
files: List of file paths to unlock
|
||||
"""
|
||||
for file_path in files:
|
||||
lock_key = f"lock:{file_path}"
|
||||
|
||||
# Only release if we own it
|
||||
owner = self.redis.get(lock_key)
|
||||
if owner == self.config.agent_id:
|
||||
self.redis.delete(lock_key)
|
||||
|
||||
if files:
|
||||
logger.info(f"Released locks for {len(files)} files")
|
||||
|
||||
def _build_prompt(self, task: Dict) -> str:
|
||||
"""
|
||||
Build Claude prompt from task
|
||||
|
||||
Args:
|
||||
task: Task dict
|
||||
|
||||
Returns:
|
||||
Prompt string for Claude
|
||||
"""
|
||||
prompt = f"""You are a specialized AI agent working on task: {task['id']}
|
||||
|
||||
TASK DESCRIPTION:
|
||||
{task['description']}
|
||||
|
||||
TASK TYPE: {task.get('type', 'unknown')}
|
||||
SPECIALIZATION: {task.get('specialization', 'none')}
|
||||
|
||||
FILES TO MODIFY:
|
||||
{chr(10).join(task.get('files', ['No files specified']))}
|
||||
|
||||
CONTEXT:
|
||||
- This is part of a multi-agent orchestration system
|
||||
- Other agents may be working on related tasks
|
||||
- Focus only on your specific task
|
||||
- Report progress clearly
|
||||
|
||||
Execute this task efficiently and report your results.
|
||||
"""
|
||||
return prompt
|
||||
|
||||
def _run_claude(self, prompt: str, task: Dict) -> str:
|
||||
"""
|
||||
Execute task using Claude
|
||||
|
||||
Args:
|
||||
prompt: Prompt for Claude
|
||||
task: Task dict
|
||||
|
||||
Returns:
|
||||
Result string
|
||||
"""
|
||||
# This would integrate with Claude Code API
|
||||
# For now, simulate execution
|
||||
logger.info(f"Executing Claude task: {task['id']}")
|
||||
|
||||
# Simulate work
|
||||
time.sleep(2)
|
||||
|
||||
# Return mock result
|
||||
return f"Task {task['id']} completed successfully by {self.config.agent_id}"
|
||||
|
||||
def _update_status(self, task_id: str, status: str, progress: float, files: List[str]):
|
||||
"""
|
||||
Update agent status in Redis
|
||||
|
||||
Args:
|
||||
task_id: Current task ID
|
||||
status: Agent status
|
||||
progress: Task progress (0-100)
|
||||
files: Files being worked on
|
||||
"""
|
||||
update_data = {
|
||||
'status': status,
|
||||
'current_task': task_id,
|
||||
'progress': str(progress),
|
||||
'working_files': json.dumps(files),
|
||||
'last_heartbeat': str(time.time())
|
||||
}
|
||||
self.redis.hset(f"agent:{self.config.agent_id}", mapping=update_data)
|
||||
|
||||
def _trigger_dependencies(self, task_id: str):
|
||||
"""
|
||||
Check and trigger tasks that depend on completed task
|
||||
|
||||
Args:
|
||||
task_id: Completed task ID
|
||||
"""
|
||||
# Get all pending tasks
|
||||
pending = self.redis.lrange(self.pending_queue, 0, -1)
|
||||
|
||||
for task_json in pending:
|
||||
task = json.loads(task_json)
|
||||
|
||||
# Check if this task depends on the completed task
|
||||
if task_id in task.get('dependencies', []):
|
||||
# Check if all dependencies are now complete
|
||||
deps_complete = all(
|
||||
self.redis.hget(f"task:{dep}", 'status') == 'complete'
|
||||
for dep in task.get('dependencies', [])
|
||||
)
|
||||
|
||||
if deps_complete:
|
||||
# Move to main queue
|
||||
self.redis.lrem(self.pending_queue, 1, task_json)
|
||||
self.redis.lpush(self.task_queue, task_json)
|
||||
logger.info(f"Triggered task {task['id']} (dependencies complete)")
|
||||
|
||||
def _cleanup(self):
|
||||
"""Clean up resources"""
|
||||
# Release all locks
|
||||
self._release_locks(list(self.locked_files))
|
||||
|
||||
# Update status to offline
|
||||
self.redis.hset(f"agent:{self.config.agent_id}", 'status', 'offline')
|
||||
|
||||
logger.info(f"Worker {self.config.agent_id} cleaned up")
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for CLI usage"""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description='Ralph Worker Agent')
|
||||
parser.add_argument('--id', required=True, help='Agent ID')
|
||||
parser.add_argument('--specialization', required=True, choices=[s.value for s in AgentSpecialization],
|
||||
help='Agent specialization')
|
||||
parser.add_argument('--redis-host', default='localhost', help='Redis host')
|
||||
parser.add_argument('--redis-port', type=int, default=6379, help='Redis port')
|
||||
parser.add_argument('--max-concurrent', type=int, default=1, help='Max concurrent tasks')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Create config
|
||||
config = WorkerConfig(
|
||||
agent_id=args.id,
|
||||
specialization=AgentSpecialization(args.specialization),
|
||||
max_concurrent_tasks=args.max_concurrent
|
||||
)
|
||||
|
||||
redis_config = {
|
||||
'host': args.redis_host,
|
||||
'port': args.redis_port
|
||||
}
|
||||
|
||||
# Create and run worker
|
||||
worker = WorkerAgent(config, redis_config)
|
||||
worker.run()
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in New Issue
Block a user