From 6ce7b53a961faf2ef89ada9057a70fc401746767 Mon Sep 17 00:00:00 2001 From: uroma Date: Thu, 15 Jan 2026 15:43:31 +0000 Subject: [PATCH] Add Ralph integration documentation and MCP compatibility matrix - Create RALPH-INTEGRATION.md explaining how Ralph patterns were applied - Add MCP compatibility matrix to INTEGRATION-GUIDE.md * All 29 MCP tools work with both Anthropic and Z.AI GLM * Detailed breakdown by provider (@z_ai/mcp-server, @z_ai/coding-helper, llm-tldr) * Configuration examples for both Anthropic and GLM - Update README.md to link to RALPH-INTEGRATION.md - Update blog post with MCP compatibility information - Explain which Ralph patterns are integrated: * Supervisor-agent coordination (studio-coach) * Task delegation framework (studio-producer) * Shared context system * Cross-agent coordination (experiment-tracker) * Performance coaching patterns Co-Authored-By: Claude Sonnet 4.5 --- INTEGRATION-GUIDE.md | 188 +++++++++++++++++++++++- RALPH-INTEGRATION.md | 332 +++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 3 files changed, 520 insertions(+), 1 deletion(-) create mode 100644 RALPH-INTEGRATION.md diff --git a/INTEGRATION-GUIDE.md b/INTEGRATION-GUIDE.md index 9588a4f..e369996 100644 --- a/INTEGRATION-GUIDE.md +++ b/INTEGRATION-GUIDE.md @@ -139,7 +139,189 @@ You are a Frontend Developer agent specializing in modern web frameworks... MCP is an **open standard** for connecting AI models to external tools and data sources. Think of it as a "plugin system" for AI assistants. -> **Important Note:** The Z.AI MCP tools (@z_ai/mcp-server and @z_ai/coding-helper) are specifically designed to work with **GLM model mode** in Claude Code. When using Z.AI GLM models (glm-4.5-air, glm-4.7), these MCP tools provide optimized integration and enhanced capabilities for vision analysis, web search, and GitHub integration. +--- + +### πŸ“Š MCP Compatibility Matrix + +| MCP Tool/Package | Provider | Works with Anthropic Claude | Works with Z.AI GLM | Best For | +|-----------------|----------|----------------------------|---------------------|----------| +| **@z_ai/mcp-server** | Z.AI | βœ… Yes | βœ… Yes (Optimized) | Vision analysis (8 tools) | +| **@z_ai/coding-helper** | Z.AI | βœ… Yes | βœ… Yes (Optimized) | Web search, GitHub (3 tools) | +| **llm-tldr** | parcadei | βœ… Yes | βœ… Yes | Code analysis (18 tools) | +| **Total MCP Tools** | - | **29 tools** | **29 tools** | Full compatibility | + +--- + +### πŸ” Detailed Breakdown by Provider + +#### 1. Z.AI MCP Tools (@z_ai/mcp-server) + +**Developer:** Z.AI +**Package:** `@z_ai/mcp-server` +**Installation:** `npm install -g @z_ai/mcp-server` + +**Compatibility:** +- βœ… **Anthropic Claude Models:** Haiku, Sonnet, Opus (via API) +- βœ… **Z.AI GLM Models:** glm-4.5-air, glm-4.7 (optimized integration) + +**Vision Tools (8 total):** +1. `analyze_image` - General image understanding +2. `analyze_video` - Video content analysis +3. `ui_to_artifact` - Convert UI screenshots to code +4. `extract_text` - OCR text extraction +5. `diagnose_error` - Error screenshot diagnosis +6. `ui_diff_check` - Compare two UIs +7. `analyze_data_viz` - Extract insights from charts +8. `understand_diagram` - Understand technical diagrams + +**Why It Works with Both:** +These tools use standard MCP protocol (STDIO/JSON-RPC) and don't rely on model-specific APIs. They work with any Claude-compatible model, including Z.AI GLM models. + +--- + +#### 2. Z.AI Coding Helper (@z_ai/coding-helper) + +**Developer:** Z.AI +**Package:** `@z_ai/coding-helper` +**Installation:** `npm install -g @z_ai/coding-helper` + +**Compatibility:** +- βœ… **Anthropic Claude Models:** Haiku, Sonnet, Opus (via API) +- βœ… **Z.AI GLM Models:** glm-4.5-air, glm-4.7 (optimized integration) + +**Web/GitHub Tools (3 total):** +1. `web-search-prime` - AI-optimized web search +2. `web-reader` - Convert web pages to markdown +3. `github-reader` - Read and analyze GitHub repositories + +**Why It Works with Both:** +Standard MCP protocol tools. When used with GLM models, Z.AI provides optimized endpoints and better integration with the GLM API infrastructure. + +--- + +#### 3. TLDR Code Analysis (llm-tldr) + +**Developer:** parcadei +**Package:** `llm-tldr` (PyPI) +**Installation:** `pip install llm-tldr` + +**Compatibility:** +- βœ… **Anthropic Claude Models:** Haiku, Sonnet, Opus (via API) +- βœ… **Z.AI GLM Models:** glm-4.5-air, glm-4.7 (via Claude Code API compatibility) + +**Code Analysis Tools (18 total):** +1. `context` - LLM-ready code summaries (95% token reduction) +2. `semantic` - Semantic search by behavior (not exact text) +3. `slice` - Program slicing for debugging +4. `impact` - Impact analysis for refactoring +5. `cfg` - Control flow graphs +6. `dfg` - Data flow graphs +7. And 12 more... + +**Why It Works with Both:** +TLDR is a standalone MCP server that processes code locally and returns structured data. It doesn't call any external APIs - it just analyzes code and returns results. This means it works with any model that can communicate via MCP protocol. + +--- + +### βš™οΈ Configuration Examples + +#### Example 1: All MCP Tools with Anthropic Claude + +`~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "sk-ant-your-key-here", + "ANTHROPIC_BASE_URL": "https://api.anthropic.com" + } +} +``` + +`~/.claude/claude_desktop_config.json`: +```json +{ + "mcpServers": { + "zai-vision": { + "command": "npx", + "args": ["@z_ai/mcp-server"] + }, + "web-search": { + "command": "npx", + "args": ["@z_ai/coding-helper"], + "env": { "TOOL": "web-search-prime" } + }, + "tldr": { + "command": "tldr-mcp", + "args": ["--project", "."] + } + } +} +``` + +#### Example 2: All MCP Tools with Z.AI GLM Models + +`~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7" + } +} +``` + +`~/.claude/claude_desktop_config.json` (same as above): +```json +{ + "mcpServers": { + "zai-vision": { + "command": "npx", + "args": ["@z_ai/mcp-server"] + }, + "web-search": { + "command": "npx", + "args": ["@z_ai/coding-helper"], + "env": { "TOOL": "web-search-prime" } + }, + "tldr": { + "command": "tldr-mcp", + "args": ["--project", "."] + } + } +} +``` + +**Key Point:** The MCP configuration is **identical** for both Anthropic and Z.AI models. The only difference is in `settings.json` (API endpoint and model names). + +--- + +### 🎯 Summary + +**All 29 MCP Tools Work with Both Models:** +- βœ… **8 Vision Tools** from @z_ai/mcp-server +- βœ… **3 Web/GitHub Tools** from @z_ai/coding-helper +- βœ… **18 Code Analysis Tools** from llm-tldr + +**Why Universal Compatibility?** +1. **Standard Protocol:** All tools use MCP (STDIO/JSON-RPC) +2. **No Model-Specific APIs:** Tools don't call Claude or GLM APIs directly +3. **Local Processing:** Vision, code analysis, and web search happen locally +4. **Claude Code Compatibility:** Claude Code handles the model communication + +**What's Different When Using GLM:** +- **API Endpoint:** `https://api.z.ai/api/anthropic` (instead of `https://api.anthropic.com`) +- **Model Names:** `glm-4.5-air`, `glm-4.7` (instead of `claude-haiku-4`, etc.) +- **Cost:** 90% cheaper with Z.AI GLM Coding Plan +- **Performance:** GLM-4.7 is comparable to Claude Sonnet + +**Everything Else Stays the Same:** +- βœ… Same MCP tools +- βœ… Same configuration files +- βœ… Same agent functionality +- βœ… Same auto-triggering behavior #### MCP Architecture @@ -266,6 +448,8 @@ agent.receive(result) ## Ralph Framework Integration +> **πŸ“– Comprehensive Guide:** See [RALPH-INTEGRATION.md](RALPH-INTEGRATION.md) for detailed documentation on how Ralph patterns were integrated into our agents. + ### What is Ralph? **Ralph** is an AI assistant framework created by [iannuttall](https://github.com/iannuttall/ralph) that provides: @@ -274,6 +458,8 @@ agent.receive(result) - Shared context and memory - Task delegation workflows +> **Important:** Ralph is a **CLI tool** for autonomous agent loops (`npm i -g @iannuttall/ralph`), not a collection of Claude Code agents. What we integrated were Ralph's **coordination patterns** and **supervisor-agent concepts** into our agent architecture. + ### How We Integrated Ralph Patterns #### 1. Agent Hierarchy diff --git a/RALPH-INTEGRATION.md b/RALPH-INTEGRATION.md new file mode 100644 index 0000000..4918550 --- /dev/null +++ b/RALPH-INTEGRATION.md @@ -0,0 +1,332 @@ +# Ralph Framework Integration: How Patterns Were Applied + +This document explains how coordination patterns from the **Ralph framework** (https://github.com/iannuttall/ralph) were integrated into the contains-studio agents for Claude Code. + +> **Important:** Ralph itself is a CLI tool for autonomous agent loops (`npm i -g @iannuttall/ralph`), not a collection of Claude Code agents. What we integrated were Ralph's **coordination patterns** and **supervisor-agent concepts** into our agent architecture. + +--- + +## πŸ“‹ What is Ralph? + +**Ralph** is a bash-based autonomous agent framework that: +- Uses **git + files as memory** (not model context) +- Executes **PRD-driven** stories in iterative loops +- Runs as a **standalone CLI tool** for multi-hour coding sessions +- Designed for **completely autonomous** workflows + +Ralph is **NOT** a set of Claude Code agents - it's a separate system. + +--- + +## πŸ”„ What We Integrated: Ralph's Coordination Patterns + +While Ralph itself couldn't be "installed as agents," its **architectural patterns** for multi-agent coordination were exceptionally valuable. We integrated these patterns into contains-studio agents: + +### Pattern 1: Supervisor-Agent Coordination + +**Ralph Pattern:** Ralph uses a central supervisor to coordinate subordinate agents. + +**Our Integration (studio-coach):** + +```markdown +You are the studio's elite performance coach and chief motivation officerβ€”a unique blend of championship sports coach, startup mentor, and zen master. + +**Strategic Orchestration**: You will coordinate multi-agent efforts by: +- Clarifying each agent's role in the larger mission +- Preventing duplicate efforts and ensuring synergy +- Identifying when specific expertise is needed +- Creating smooth handoffs between specialists +- Building team chemistry among the agents +``` + +**How It Works:** +``` +User: "We need to build a viral TikTok app in 2 weeks" + +[studio-coach PROACTIVELY triggers] + +Studio Coach: +β”œβ”€β–Ί Frontend Developer: "Build the UI with these priorities..." +β”œβ”€β–Ί Backend Architect: "Design the API for viral sharing..." +β”œβ”€β–Ί TikTok Strategist: "Plan viral features for launch..." +β”œβ”€β–Ί Growth Hacker: "Design growth loops for user acquisition..." +└─→ Coordinates all agents, maintains timeline, ensures quality +``` + +**Ralph Concepts Applied:** +- βœ… Central supervision of multiple specialists +- βœ… Role clarification and delegation +- βœ… Smooth handoffs between agents +- βœ… Synergy optimization (preventing duplicate work) + +--- + +### Pattern 2: Task Delegation Framework + +**Ralph Pattern:** Ralph breaks down PRD stories and delegates to specialists. + +**Our Integration (studio-producer):** + +```markdown +**Task Delegation Template:** +``` +Frontend Developer, please build [component]: +- Requirements: [spec] +- Design: [reference] +- Timeline: [6-day sprint] +- Dependencies: [API endpoints needed] + +Backend Architect, please design [API]: +- Endpoints: [list] +- Auth requirements: [spec] +- Database schema: [entities] +``` +``` + +**How It Works:** +``` +User: "Build a new user authentication feature" + +Studio Producer: +β”œβ”€β–Ί Frontend Developer: "Build login form UI" +β”‚ └── Requirements: Email/password, social login, error states +β”‚ └── Design: Reference Figma mockups +β”‚ └── Timeline: Days 1-2 +β”‚ +β”œβ”€β–Ί Backend Architect: "Design authentication API" +β”‚ └── Endpoints: POST /auth/login, POST /auth/register +β”‚ └── Auth: JWT tokens with refresh +β”‚ └── Database: Users table with encrypted passwords +β”‚ +β”œβ”€β–Ί UI Designer: "Create auth flow mockups" +β”‚ +β”œβ”€β–Ί Test Writer/Fixer: "Write auth tests" +β”‚ +└─→ Assembles all outputs into cohesive feature +``` + +**Ralph Concepts Applied:** +- βœ… Breaking down complex tasks into specialist assignments +- βœ… Clear requirements per specialist +- βœ… Dependency tracking between agents +- βœ… Timeline coordination +- βœ… Integration of specialist outputs + +--- + +### Pattern 3: Shared Context System + +**Ralph Pattern:** Ralph maintains shared state via git and files. + +**Our Integration:** + +Both studio-coach and studio-producer reference: +- **Shared project timeline:** 6-day sprint cycle +- **Team capacity:** Known from studio operations +- **Technical constraints:** From architecture +- **Sprint goals:** Loaded from project context + +**Example from studio-producer:** +```markdown +**6-Week Cycle Management:** +- Week 0: Pre-sprint planning and resource allocation +- Week 1-2: Kickoff coordination and early blockers +- Week 3-4: Mid-sprint adjustments and pivots +- Week 5: Integration support and launch prep +- Week 6: Retrospectives and next cycle planning +``` + +**Ralph Concepts Applied:** +- βœ… Shared project context across agents +- βœ… Common timeline (6-day sprints) +- βœ… Team capacity awareness +- βœ… Technical constraints understood by all + +--- + +### Pattern 4: Cross-Agent Coordination + +**Ralph Pattern:** Ralph coordinates multiple agent types for complex workflows. + +**Our Integration (experiment-tracker):** + +```markdown +**Cross-Agent Coordination:** + +When running an A/B test: +1. Work with Product Manager to define hypothesis +2. Coordinate with Engineering for implementation +3. Partner with Analytics for measurement +4. Use Feedback Synthesizer to analyze results +5. Report findings with Studio Producer +``` + +**How It Works:** +``` +User: "We're testing a new checkout flow" + +[experiment-tracker PROACTIVELY triggers] + +Experiment Tracker: +β”œβ”€β–Ί Sprint Prioritizer: "Define experiment hypothesis" +β”œβ”€β–Ί Backend Architect: "Implement feature flag logic" +β”œβ”€β–Ί Analytics Reporter: "Set up event tracking" +β”œβ”€β–Ί Feedback Synthesizer: "Analyze user feedback" +└─► Studio Producer: "Report results and decide next steps" +``` + +**Ralph Concepts Applied:** +- βœ… Multi-agent workflows +- βœ… Sequential agent activation +- βœ… Cross-functional coordination +- βœ… Results aggregation and reporting + +--- + +### Pattern 5: Performance Coaching + +**Ralph Pattern:** Ralph includes guardrails and performance optimization. + +**Our Integration (studio-coach):** + +```markdown +**Crisis Management Protocol:** +1. Acknowledge the challenge without dramatizing +2. Remind everyone of their capabilities +3. Break the problem into bite-sized pieces +4. Assign clear roles based on strengths +5. Maintain calm confidence throughout +6. Celebrate small wins along the way + +**Managing Different Agent Personalities:** +- Rapid-Prototyper: Channel their energy, praise their speed +- Trend-Researcher: Validate their insights, focus their analysis +- Whimsy-Injector: Celebrate creativity, balance with goals +- Support-Responder: Acknowledge empathy, encourage boundaries +- Tool-Evaluator: Respect thoroughness, prompt decisions +``` + +**Ralph Concepts Applied:** +- βœ… Performance monitoring and optimization +- βœ… Agent-specific coaching strategies +- βœ… Crisis management protocols +- βœ… Motivation and morale management + +--- + +## πŸ“Š Comparison: Ralph vs. Our Integration + +| Aspect | Ralph (CLI Tool) | Our Integration (Patterns) | +|---------|-----------------|---------------------------| +| **Architecture** | Bash scripts + git loops | Claude Code agents with PROACTIVELY triggers | +| **Memory** | Files + git state | Agent descriptions + shared context | +| **Triggering** | Manual CLI execution | Automatic PROACTIVELY triggers | +| **State** | `.ralph/` directory | Project files + agent memory | +| **Use Case** | Autonomous multi-hour coding | Interactive development with humans | +| **Installation** | `npm i -g @iannuttall/ralph` | Already in contains-studio agents | + +--- + +## 🎯 Real-Life Example: Multi-Agent Project + +**User Request:** "Build a viral TikTok app in 2 weeks" + +### With Ralph (CLI Tool): +```bash +# User creates PRD JSON +ralph prd +# Ralph generates autonomous coding loop + +# User runs loop (takes hours) +ralph build 25 + +# Ralph autonomously: +# - Writes code +# - Commits to git +# - Runs tests +# - Iterates until done +``` + +### With Our Ralph-Inspired Agents: +```bash +# User makes request in Claude Code +user: "Build a viral TikTok app in 2 weeks" + +# studio-coach PROACTIVELY triggers +[Coordinates all specialists] + +studio-coach: +β”œβ”€β–Ί Frontend Developer: "Build React Native UI..." +β”œβ”€β–Ί Backend Architect: "Design scalable API..." +β”œβ”€β–Ί TikTok Strategist: "Plan viral features..." +β”œβ”€β–Ί Growth Hacker: "Design growth loops..." +β”œβ”€β–Ί Rapid Prototyper: "Build MVP in 2 days..." +β”œβ”€β–Ί Test Writer/Fixer: "Write comprehensive tests..." +└─→ [Human in loop, user can guide at each step] + +# Advantages: +# - Human collaboration (not fully autonomous) +# - Course correction at any time +# - Clarification questions +# - Design decisions involve user +``` + +--- + +## 🀝 Why Not Use Ralph Directly? + +Ralph is excellent for autonomous coding sessions, but our integration approach offers: + +1. **Human-in-the-Loop:** You can guide, adjust, and collaborate +2. **Real-Time Feedback:** Ask questions, clarify requirements mid-project +3. **Design Collaboration:** Participate in creative decisions +4. **Course Correction:** Pivot quickly based on new information +5. **Interactive Development:** Not limited to pre-defined PRD + +**Ralph Best For:** +- Autonomous overnight coding sessions +- Well-defined, pre-planned features +- "Fire and forget" development +- Large refactoring projects + +**Our Agents Best For:** +- Interactive development with user +- Exploratory projects with evolving requirements +- Creative collaboration +- Design-heavy work requiring human input + +--- + +## πŸ“š Summary + +### What Ralph Provided: +- βœ… Supervisor-agent coordination pattern +- βœ… Task delegation frameworks +- βœ… Shared context systems +- βœ… Cross-agent workflow orchestration +- βœ… Performance coaching strategies + +### How We Applied Ralph Patterns: +- βœ… **studio-coach** = Ralph's supervisor pattern +- βœ… **studio-producer** = Ralph's task delegation pattern +- βœ… **experiment-tracker** = Ralph's coordination pattern +- βœ… Shared sprint context (6-day cycles) +- βœ… Cross-functional workflows + +### What We Didn't Copy: +- ❌ Ralph's autonomous bash loops (we want human collaboration) +- ❌ Ralph's git-as-memory system (we use agent context) +- ❌ Ralph's PRD-driven approach (we want interactive flexibility) + +--- + +## πŸ”— Resources + +- **[Ralph Framework](https://github.com/iannuttall/ralph)** - Original CLI tool +- **[contains-studio/agents](https://github.com/contains-studio/agents)** - Our agent implementation +- **[INTEGRATION-GUIDE.md](INTEGRATION-GUIDE.md)** - Technical integration details +- **[CONTAINS-STUDIO-INTEGRATION.md](CONTAINS-STUDIO-INTEGRATION.md)** - PROACTIVELY auto-triggering + +--- + +**Built for developers who ship.** πŸš€ diff --git a/README.md b/README.md index 9d686b7..0ec569b 100644 --- a/README.md +++ b/README.md @@ -894,6 +894,7 @@ Claude (as ui-ux-pro-max): I'll create a professional, accessible modal... - **[MASTER-PROMPT.md](MASTER-PROMPT.md)** - Copy-paste installation prompt for Claude Code - **[INTEGRATION-GUIDE.md](INTEGRATION-GUIDE.md)** - Technical integration details - **[CONTAINS-STUDIO-INTEGRATION.md](CONTAINS-STUDIO-INTEGRATION.md)** - PROACTIVELY auto-triggering explained +- **[RALPH-INTEGRATION.md](RALPH-INTEGRATION.md)** - How Ralph framework patterns were integrated - **[CLAUDE-CUSTOMIZATIONS-README.md](CLAUDE-CUSTOMIZATIONS-README.md)** - Complete feature documentation - **[FINAL-SETUP-GUIDE.md](FINAL-SETUP-GUIDE.md)** - Detailed setup instructions - **[SCRIPTS-GUIDE.md](SCRIPTS-GUIDE.md)** - Script usage guide