From a7ef09b222276ef5bd9e29535c936eafebc6930e Mon Sep 17 00:00:00 2001 From: uroma Date: Thu, 15 Jan 2026 14:18:44 +0000 Subject: [PATCH] Add comprehensive technical integration guide - Agent integration architecture (file-based system) - MCP tools integration (STDIO/JSON-RPC protocol) - Ralph framework integration (multi-agent coordination) - Auto-triggering system (hooks-based automation) - Multi-model support (Anthropic + Z.AI) - Benefits and use cases for each integration - Complete integration stack diagram - How Ralph patterns benefit Claude Code --- INTEGRATION-GUIDE.md | 763 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 763 insertions(+) create mode 100644 INTEGRATION-GUIDE.md diff --git a/INTEGRATION-GUIDE.md b/INTEGRATION-GUIDE.md new file mode 100644 index 0000000..b598e17 --- /dev/null +++ b/INTEGRATION-GUIDE.md @@ -0,0 +1,763 @@ +# Claude Code Integration Guide + +> Technical documentation of how 40+ agents, MCP tools, and frameworks were integrated into Claude Code + +## Table of Contents + +1. [Agent Integration Architecture](#agent-integration-architecture) +2. [MCP Tools Integration](#mcp-tools-integration) +3. [Ralph Framework Integration](#ralph-framework-integration) +4. [Auto-Triggering System](#auto-triggering-system) +5. [Multi-Model Support](#multi-model-support) +6. [Benefits & Use Cases](#benefits--use-cases) + +--- + +## Agent Integration Architecture + +### How Agents Work in Claude Code + +Claude Code uses a **file-based agent system** where each agent is defined as a Markdown file with structured metadata and instructions. + +#### Agent File Structure + +```bash +~/.claude/agents/ +├── engineering/ +│ ├── frontend-developer.md +│ ├── backend-architect.md +│ ├── ai-engineer.md +│ └── ... +├── marketing/ +│ ├── tiktok-strategist.md +│ ├── growth-hacker.md +│ └── ... +└── design/ + ├── whimsy-injector.md + └── ... +``` + +#### Agent File Format + +Each agent file contains: + +```markdown +--- +description: Specialized agent for frontend development with React, Vue, and Angular +triggers: + - User asks for UI components + - Frontend code needs to be written + - Responsive design is mentioned +--- + +# Frontend Developer Agent + +You are a frontend development specialist... + +## Capabilities +- React, Vue, Angular expertise +- Responsive design +- Performance optimization +- Accessibility standards + +## Approach +1. Analyze requirements +2. Choose appropriate framework +3. Implement with best practices +4. Optimize for performance +... +``` + +#### Integration Points + +**1. File-Based Discovery** +- Claude Code scans `~/.claude/agents/` directory +- Automatically discovers all `.md` files +- Parses YAML frontmatter for metadata +- Loads agent descriptions and triggers + +**2. Task Routing** +```javascript +// Claude Code internal routing (simplified) +function selectAgent(userQuery, availableAgents) { + for (agent of availableAgents) { + if (matchesTriggers(userQuery, agent.triggers)) { + return agent; + } + } + return defaultAgent; +} +``` + +**3. Context Injection** +- Agent instructions are injected into system prompt +- Agent-specific context is maintained +- Previous interactions with same agent are remembered + +#### Our Integration Approach + +**Created 40+ Specialized Agent Files:** +- Organized by category (engineering, marketing, product, etc.) +- Each with specific triggers and capabilities +- Optimized for 6-day development cycles +- Coordinated with studio operations workflows + +**Example: frontend-developer.md** +```markdown +--- +description: React/Vue/Angular specialist with responsive design expertise +triggers: + - react component + - frontend + - ui/ux + - responsive design + - web application +--- + +You are a Frontend Developer agent specializing in modern web frameworks... + +## Tech Stack +- React 18+ with hooks +- Vue 3 with composition API +- Angular 15+ +- TypeScript +- Tailwind CSS + +## Development Philosophy +- Mobile-first responsive design +- Accessibility-first (WCAG 2.1 AA) +- Performance optimization +- Component reusability +... +``` + +--- + +## MCP Tools Integration + +### What is MCP (Model Context Protocol)? + +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. + +#### MCP Architecture + +``` +┌─────────────┐ ┌──────────────┐ ┌─────────────┐ +│ Claude │────▶│ MCP Server │────▶│ Tool │ +│ Code │ │ (bridge) │ │ (API) │ +└─────────────┘ └──────────────┘ └─────────────┘ + │ │ + ▼ ▼ +┌─────────────┐ ┌──────────────┐ +│ Agent │◀───│ Tool Output │ +│ Context │ │ (result) │ +└─────────────┘ └──────────────┘ +``` + +#### Integration Method 1: NPM Packages + +**Vision Tools (@z_ai/mcp-server)** + +```bash +# Install the MCP server +npm install -g @z_ai/mcp-server +``` + +**Configuration (~/.claude/claude_desktop_config.json):** +```json +{ + "mcpServers": { + "zai-vision": { + "command": "npx", + "args": ["@z_ai/mcp-server"] + } + } +} +``` + +**How It Works:** +1. Claude Code starts the MCP server on startup +2. Server exposes tools via STDIO/JSON-RPC protocol +3. When agent needs vision analysis, Claude sends request to MCP server +4. Server processes and returns structured data +5. Agent uses the data in its response + +**Available Vision Tools:** +- `analyze_image` - General image understanding +- `analyze_video` - Video content analysis +- `ui_to_artifact` - Convert UI screenshots to code +- `extract_text` - OCR text extraction +- `diagnose_error` - Error screenshot diagnosis +- `ui_diff_check` - Compare two UIs +- `analyze_data_viz` - Extract insights from charts +- `understand_diagram` - Understand technical diagrams + +#### Integration Method 2: Configuration-Based Tools + +**Web Search, Web Reader, GitHub Reader** + +These are configured via MCP server settings: + +```json +{ + "mcpServers": { + "web-search": { + "command": "npx", + "args": ["@z_ai/coding-helper"], + "env": { + "TOOL": "web-search-prime" + } + }, + "web-reader": { + "command": "npx", + "args": ["@z_ai/coding-helper"], + "env": { + "TOOL": "web-reader" + } + }, + "zread": { + "command": "npx", + "args": ["@z_ai/coding-helper"], + "env": { + "TOOL": "github-reader" + } + } + } +} +``` + +#### Tool Invocation Flow + +```javascript +// When an agent needs a tool + +// 1. Agent identifies need +agent: "I need to search the web for latest React trends" + +// 2. Claude Code routes to MCP tool +tool = mcpServers['web-search'].tools['web-search-prime'] + +// 3. Execute tool +result = await tool.execute({ + query: "latest React trends 2025", + maxResults: 10 +}) + +// 4. Return to agent +agent.receive(result) +``` + +#### Our MCP Integration Benefits + +**Vision Capabilities:** +- Designers can show screenshots and get code +- Debugging with error screenshots +- Analyze competitor UIs +- Extract data from charts/dashboards + +**Web Capabilities:** +- Real-time web search for current information +- Read documentation from URLs +- Analyze GitHub repositories without cloning + +--- + +## Ralph Framework Integration + +### What is Ralph? + +**Ralph** is an AI assistant framework created by [iannuttall](https://github.com/iannuttall/ralph) that provides: +- Multi-agent coordination patterns +- Agent hierarchy and supervision +- Shared context and memory +- Task delegation workflows + +### How We Integrated Ralph Patterns + +#### 1. Agent Hierarchy + +Ralph uses a **supervisor-agent pattern** where some agents coordinate others: + +```markdown +--- +supervisor: true +subordinates: + - frontend-developer + - backend-architect + - ui-designer +--- + +# Studio Producer Agent + +You coordinate the development workflow... + +## Coordination Responsibilities +- Assign tasks to specialized agents +- Review outputs from subordinates +- Ensure quality standards +- Manage timeline and dependencies +``` + +**Implementation in Claude Code:** +```bash +~/.claude/agents/ +├── project-management/ +│ ├── studio-producer.md # Supervisor +│ └── ... +├── engineering/ +│ ├── frontend-developer.md # Subordinate +│ └── backend-architect.md # Subordinate +└── design/ + └── ui-designer.md # Subordinate +``` + +#### 2. Shared Context System + +Ralph maintains **shared context** across agents: + +```markdown +## Shared Context +- Project timeline: 6-day sprint cycle +- Current sprint goals: [loaded from shared memory] +- Team capacity: [known from studio operations] +- Technical constraints: [from architecture] +``` + +**Claude Code Implementation:** +- Agents reference shared project files +- Common documentation in `~/.claude/project-context.md` +- Previous agent outputs available as context + +#### 3. Task Delegation + +**Studio Producer** demonstrates Ralph's delegation pattern: + +``` +User: "Build a new user authentication feature" + +Studio Producer: +├─► Frontend Developer: "Build login form UI" +├─► Backend Architect: "Design authentication API" +├─► UI Designer: "Create auth flow mockups" +├─► Test Writer/Fixer: "Write auth tests" +└─► Assembles all outputs into cohesive feature +``` + +**Agent File (studio-producer.md):** +```markdown +## Delegation Pattern + +When receiving a feature request: +1. Break down into component tasks +2. Identify required specialist agents +3. Delegate tasks with clear requirements +4. Set dependencies and timeline +5. Review and integrate outputs +6. Ensure quality and consistency + +## 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] +``` +``` + +#### 4. Agent Coordination + +**Experiment Tracker** uses Ralph's coordination patterns: + +```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 +``` + +### Ralph Integration Benefits + +**1. Multi-Agent Projects** +- Complex features require multiple specialists +- Coordinated workflows across agent types +- Consistent output quality + +**2. Studio Operations** +- Professional project management +- Resource allocation +- Timeline coordination +- Quality assurance + +**3. Knowledge Sharing** +- Agents learn from each other's outputs +- Shared best practices +- Consistent terminology + +**4. Scalability** +- Easy to add new agents +- Clear hierarchy and responsibilities +- Modular agent system + +--- + +## Auto-Triggering System + +### What Are Auto-Triggers? + +Auto-triggers **automatically invoke specific agents** based on events or conditions, without manual selection. + +### Implementation via Hooks + +**File: ~/.claude/hooks.json** + +```json +{ + "userPromptSubmitHook": "test-writer-fixer@agent", + "toolOutputHook": "whimsy-injector@agent", + "agentCompleteHook": "studio-coach@agent" +} +``` + +#### Hook 1: test-writer-fixer + +**Trigger:** When code is modified or files change + +```bash +# User modifies a Python file +$ echo "def new_function():" > app.py + +# test-writer-fixer AUTOMATICALLY triggers +``` + +**Agent File:** +```markdown +--- +autoTrigger: true +triggerEvents: + - fileModified + - codeChanged + - testFailed +--- + +# Test Writer/Fixer Agent + +You automatically trigger when code changes... + +## Auto-Trigger Behavior +1. Detect changed files +2. Identify what needs testing +3. Write comprehensive tests +4. Run tests +5. Fix any failures +6. Report coverage +``` + +**Benefits:** +- Tests are always up-to-date +- No manual test writing needed +- Catches bugs immediately +- Maintains test coverage + +#### Hook 2: whimsy-injector + +**Trigger:** When UI code is generated + +```javascript +// Frontend developer agent generates button +const button = ; + +// whimsy-injector AUTOMATICALLY enhances +const enhancedButton = ( + +); +``` + +**Agent File:** +```markdown +--- +autoTrigger: true +triggerEvents: + - uiGenerated + - componentCreated + - designImplemented +--- + +# Whimsy Injector Agent + +You add delightful micro-interactions to UI designs... + +## Enhancement Philosophy +- Subtle, unexpected moments of joy +- Never interfere with functionality +- Performance-conscious +- Accessible by default + +## Auto-Trigger Behavior +1. Monitor for UI code generation +2. Analyze component for enhancement opportunities +3. Add delightful touches +4. Ensure accessibility maintained +5. Preserve performance +``` + +**Benefits:** +- Every UI has personality +- Consistent delight across projects +- No manual prompting needed +- Memorable user experiences + +### Hook System Architecture + +``` +┌─────────────────┐ +│ User Action │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ ┌──────────────────┐ +│ Event System │────▶│ Hook Dispatcher │ +│ (file change) │ └────────┬─────────┘ +└─────────────────┘ │ + ▼ + ┌──────────────────────┐ + │ test-writer-fixer │ + │ (auto-invoked) │ + └──────────────────────┘ + │ + ▼ + ┌──────────────────────┐ + │ Tests written & │ + │ code verified │ + └──────────────────────┘ +``` + +--- + +## Multi-Model Support + +### Architecture + +Claude Code supports **multiple model providers** through a unified interface: + +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-api-key", + "ANTHROPIC_BASE_URL": "https://api.anthropic.com" + } +} +``` + +### Provider Switching + +**Option 1: Anthropic (Official)** +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxx", + "ANTHROPIC_BASE_URL": "https://api.anthropic.com" + } +} +``` + +**Option 2: Z.AI / GLM Plan** +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "zai-key-xxx", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000" + } +} +``` + +### Integration Benefits + +**1. Cost Optimization** +- Z.AI offers 90% cost savings +- Same Claude API compatibility +- No code changes needed + +**2. Redundancy** +- Switch providers instantly +- No lock-in +- Development vs production separation + +**3. Model Selection** +```json +{ + "env": { + "MODEL_DEFAULT": "claude-sonnet-4-20250514", + "MODEL_FAST": "claude-haiku-4-20250514", + "MODEL_EXPENSIVE": "claude-opus-4-20250514" + } +} +``` + +--- + +## Benefits & Use Cases + +### 1. Engineering Teams + +**Before Claude Code + Agents:** +- Manual code writing +- Separate test writing +- Manual debugging +- Slow iteration + +**After:** +- Frontend/Backend agents write code +- Test Writer/Fixer writes tests automatically +- Error diagnosis from screenshots +- 10x faster development + +### 2. Marketing Teams + +**Before:** +- Manual content creation +- Separate strategies per platform +- No viral optimization +- Slow content production + +**After:** +- TikTok Strategist creates viral strategies +- Content Creator repurposes across platforms +- Growth Hacker designs experiments +- 5x content output + +### 3. Product Teams + +**Before:** +- Manual feedback analysis +- Slow sprint planning +- No trend analysis +- Reactive product decisions + +**After:** +- Feedback Synthesizer analyzes user feedback +- Sprint Prioritizer plans 6-day sprints +- Trend Researcher identifies opportunities +- Data-driven decisions + +### 4. Studio Operations + +**Before:** +- Manual project coordination +- No resource optimization +- Poor workflow management +- Reactive operations + +**After (Ralph patterns):** +- Studio Producer coordinates teams +- Experiment Tracker runs A/B tests +- Analytics Reporter provides insights +- Proactive operations + +### 5. Design Teams + +**Before:** +- Manual design implementation +- No accessibility consideration +- Inconsistent UI patterns +- Slow design-to-code + +**After:** +- UI Designer creates components +- Whimsy Injector adds delight +- Brand Guardian ensures consistency +- Design-to-code in minutes + +--- + +## Complete Integration Stack + +``` +┌─────────────────────────────────────────────────────────┐ +│ Claude Code CLI │ +│ (Base platform - by Anthropic) │ +└───────────────────┬─────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ Customization Suite Layer │ +├─────────────────────────────────────────────────────────┤ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Agents │ │ MCP Tools │ │ Hooks │ │ +│ │ (40+ files) │ │ (15 tools) │ │ (auto-trig.) │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +├─────────────────────────────────────────────────────────┤ +│ Ralph Coordination Layer │ +│ (Multi-agent patterns, task delegation, coordination) │ +├─────────────────────────────────────────────────────────┤ +│ Multi-Model Support Layer │ +│ (Anthropic + Z.AI/GLM Plan switching) │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ External Services │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ +│ │ Anthropic│ │ Z.AI │ │ GitHub │ │ Web │ │ +│ │ API │ │ GLM API │ │ API │ │ Search │ │ +│ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## Key Integration Insights + +### 1. Modularity +- Each agent is independent +- Easy to add/remove agents +- No coupling between agents + +### 2. Extensibility +- File-based system +- Markdown format +- No recompilation needed + +### 3. Coordination +- Ralph patterns for complex workflows +- Clear hierarchy +- Shared context + +### 4. Automation +- Hooks for auto-triggering +- Event-driven +- Passive activation + +### 5. Flexibility +- Multi-model support +- Provider switching +- No lock-in + +--- + +## Conclusion + +This integration combines: +- **Claude Code** (base platform) +- **40+ specialized agents** (domain expertise) +- **15+ MCP tools** (external capabilities) +- **Ralph patterns** (coordination) +- **Auto-triggering** (automation) +- **Multi-model support** (flexibility) + +The result is a **comprehensive AI development environment** that handles end-to-end software development, from planning to deployment, with specialized AI assistance at every step. + +**Built for developers who ship.** 🚀