claude-code-glm-suite/INTEGRATION-GUIDE.md

# 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.

> **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 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 = <button>Click me</button>;

// whimsy-injector AUTOMATICALLY enhances
const enhancedButton = (
  <button className="hover:scale-105 active:scale-95 transition-transform">
    Click me
    <SparkleOnHover />
  </button>
);
```

**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.** 🚀