diff --git a/README.md b/README.md index ed2f39a..8bc7f9b 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,68 @@ # 🚀 Ultimate Claude Code & GLM Suite -> 40+ specialized AI agents, MCP tools, auto-triggering automation for Claude Code. Works with Anthropic Claude and Z.AI/GLM models. +> **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). > 💡 **Tip:** Use invite token `R0K78RJKNW` for **10% OFF** Z.AI GLM Plan subscription: https://z.ai/subscribe?ic=R0K78RJKNW -[![Agents](https://img.shields.io/badge/Agents-40+-purple)](agents/) -[![MCP Tools](https://img.shields.io/badge/MCP_Tools-15+-blue)](#mcp-tools) +[![Agents](https://img.shields.io/badge/Agents-38+-purple)](agents/) +[![PROACTIVELY](https://img.shields.io/badge/PROACTIVELY_Agents-7-green)](#-proactively-auto-coordination) +[![MCP Tools](https://img.shields.io/badge/MCP_Tools-15+-blue)](#-mcp-tools) [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE) +--- + +## 🎯 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 ✓ +``` + +--- + ## 🚀 Quick Start ```bash @@ -27,11 +82,9 @@ chmod +x interactive-install-claude.sh # ✅ Launch Claude Code ``` -## 🎯 Installation Options +--- -Choose the installation method that works best for you: - -### ⚠️ IMPORTANT: For Z.AI / GLM Users +## ⚠️ IMPORTANT: For Z.AI / GLM Users **If using the GLM Coding Plan (90% cheaper), you MUST configure GLM FIRST before using Claude Code!** @@ -74,11 +127,13 @@ 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](https://github.rommark.dev/admin/claude-code-glm-suite/src/main/MASTER-PROMPT.md)** +📄 **[MASTER-PROMPT.md](MASTER-PROMPT.md)** **⚡ Quick Start:** 1. **If using GLM:** Configure GLM first (see above) @@ -116,270 +171,18 @@ Follow the step-by-step guide below for full control over each component. ## ✨ What's Included -- **🤖 40+ Custom Agents** across 8 categories +- **🤖 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 -- **⚡ Auto-Triggering** test writer and UI enhancement agents +- **⚡ Intelligent Coordination** - Coordinators automatically detect context and orchestrate workflows - **🎛️ Interactive Installation** with model selection (Anthropic/Z.AI) - **🛡️ One-Click Setup** with comprehensive verification - -## 📋 Complete Integration Guide - -### Step 1: Choose Your Model Provider - -Choose **Option A** (Anthropic) or **Option B** (Z.AI/GLM Plan) below. +- **📚 Complete Documentation** with real-world workflow examples --- -### 🔵 Option A: Anthropic Claude (Official API) - -**Best for:** Production, highest quality, official support - -#### 1.1 Get Your API Key - -```bash -# Visit: https://console.anthropic.com/ -# Create an account and get your API key -``` - -#### 1.2 Configure Claude Code - -```bash -# Create/update your Claude Code settings -mkdir -p ~/.claude -cat > ~/.claude/settings.json << 'EOF' -{ - "env": { - "ANTHROPIC_AUTH_TOKEN": "sk-ant-your-actual-api-key-here", - "ANTHROPIC_BASE_URL": "https://api.anthropic.com" - } -} -EOF -``` - -#### 1.3 Install Claude Code (if not installed) - -```bash -# Using npm -npm install -g @anthropic-ai/claude-code - -# Or using curl -curl -fsSL https://claude.ai/install.sh | sh -``` - -#### 1.4 Verify Installation - -```bash -# Test Claude Code -claude --version - -# Test API connection -echo "Hello, Claude!" | claude -``` - ---- - -### 🟢 Option B: Z.AI / GLM Coding Plan (Cost-Effective) - -**Best for:** Development, testing, cost savings (up to 90% cheaper) - -**Official Documentation:** https://docs.z.ai/devpack/tool/claude - -#### 1.1 Get Your API Key - -```bash -# Visit: https://z.ai/ -# Create an account and get your GLM Coding Plan API key -``` - -#### 1.2 Configure Claude Code for GLM - -```bash -# Create/update your Claude Code settings -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 -``` - -**GLM Models Available:** -- `glm-4.5-air` - Fast, efficient (Haiku equivalent) -- `glm-4.7` - High quality (Sonnet/Opus equivalent) - -#### 1.3 Install Claude Code (if not installed) - -```bash -# Install Claude Code (requires Node.js 18+) -npm install -g @anthropic-ai/claude-code - -# Verify version (recommended: 2.0.14+) -claude --version - -# Upgrade if needed -claude update -``` - -#### 1.4 Verify Installation - -```bash -# Start Claude Code -claude - -# Check model status (enter /status when prompted) -/status - -# Troubleshooting: -# - Close all Claude Code windows and reopen -# - Or delete ~/.claude/settings.json and reconfigure -# - Verify JSON format is correct -``` - ---- - -### Step 2: Install This Customization Suite - -```bash -# Clone this repository -git clone https://github.rommark.dev/admin/claude-code-glm-suite.git -cd claude-code-glm-suite - -# Run the interactive installer -chmod +x interactive-install-claude.sh -./interactive-install-claude.sh -``` - -**The installer will:** -- ✅ Detect your Claude Code installation -- ✅ Backup existing customizations -- ✅ Let you choose agent categories to install -- ✅ Configure MCP tools -- ✅ Set up auto-triggering agents -- ✅ Verify everything works - -**Installation options:** -``` -Step 1: Model Selection - [ ] Already configured - skip model setup - [ ] Anthropic Claude (official API) - [ ] Z.AI / GLM Coding Plan - -Step 2: Agent Categories - [ ] Engineering (7 agents) - RECOMMENDED - [ ] Marketing (7 agents) - [ ] Product (3 agents) - [ ] Project Management (3 agents) - [ ] Studio Operations (5 agents) - [ ] Testing (5 agents) - RECOMMENDED - [ ] Design (5 agents) - [ ] Bonus (2 agents) - -Step 3: MCP Tools - [ ] Vision Tools (8 tools) - RECOMMENDED - [ ] Web Tools (search, reader) - [ ] GitHub Tools (zread) - -Step 4: Plugins & Hooks - [ ] Auto-triggering agents - [ ] Custom hooks -``` - ---- - -### Step 3: Install MCP Tools (Optional but Recommended) - -#### 3.1 Vision Tools (8 tools) - -```bash -# Install Z.AI MCP server for vision tools -npm install -g @z_ai/mcp-server - -# Verify installation -npx @z_ai/mcp-server --help -``` - -#### 3.2 Web & GitHub Tools - -```bash -# Install Z.AI coding helper -npm install -g @z_ai/coding-helper - -# Verify installation -npx @z_ai/coding-helper --help -``` - ---- - -### Step 4: Verify Your Installation - -```bash -# Run the verification script -chmod +x verify-claude-setup.sh -./verify-claude-setup.sh -``` - -**Expected output:** -``` -✅ Claude Code installed -✅ Settings configured -✅ Agents directory exists -✅ 37 agent files found -✅ MCP tools available -✅ Configuration valid -``` - ---- - -### Step 5: Test Your Setup - -#### 5.1 Test Basic Functionality - -```bash -# Start Claude Code -claude - -# Try a simple command -> List all available agents -``` - -#### 5.2 Test an Agent - -```bash -# In Claude Code, try: -> Use the frontend-developer agent to create a React component -``` - -#### 5.3 Test MCP Tools (if installed) - -```bash -# In Claude Code, try: -> Analyze this image: [path to image] -> Search the web for "latest AI trends" -> Read the documentation from https://example.com -``` - ---- - -## 📦 Installation Scripts - -| Script | Description | Size | -|--------|-------------|------| -| `interactive-install-claude.sh` | Full interactive installer (recommended) | 33KB | -| `claude-setup-manager.sh` | Menu-driven setup manager | 11KB | -| `create-complete-package.sh` | Create distributable packages | 16KB | -| `verify-claude-setup.sh` | Verify your installation | 9KB | -| `export-claude-customizations.sh` | Export existing customizations | 6.5KB | - ---- - -## 🤖 Agent Categories +## 🤖 Agent Departments ### Engineering (7 agents) - **AI Engineer** - ML & LLM integration, prompt engineering @@ -388,7 +191,25 @@ claude - **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 +- **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 @@ -399,16 +220,6 @@ claude - **Twitter Engager** - Twitter strategy and tactics - **App Store Optimizer** - ASO optimization -### Product (3 agents) -- **Feedback Synthesizer** - User feedback analysis -- **Sprint Prioritizer** - 6-day sprint planning -- **Trend Researcher** - Market trend analysis - -### Project Management (3 agents) -- **Experiment Tracker** - A/B test tracking -- **Project Shipper** - Launch coordination -- **Studio Producer** - Team workflow optimization - ### Studio Operations (5 agents) - **Analytics Reporter** - Data analysis and reporting - **Finance Tracker** - Financial tracking @@ -423,16 +234,133 @@ claude - **Tool Evaluator** - Tool evaluation - **Workflow Optimizer** - Workflow optimization -### Design (5 agents) -- **Brand Guardian** - Brand consistency -- **UI Designer** - UI design and implementation -- **UX Researcher** - User experience research -- **Visual Storyteller** - Visual communication -- **Whimsy Injector** - Delightful UI enhancements - ### Bonus (2 agents) +- **Studio Coach** - Team coaching and motivation for complex tasks (PROACTIVELY) - **Joker** - Humor and team morale -- **Studio Coach** - Team coaching and motivation + +--- + +## 🎯 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 + +``` +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 ✓ +``` + +**Key Benefits:** +- ✅ No manual orchestration required +- ✅ Automatic quality gates (testing, UX, launches) +- ✅ Intelligent specialist selection +- ✅ Seamless multi-agent workflows +- ✅ Consistent delivery quality --- @@ -453,430 +381,60 @@ claude ### Web & GitHub Tools | Tool | Function | Source | |------|----------|--------| -| `web-search-prime` | AI-optimized web search | [claude-codex-settings](https://github.com/fcakyon/claude-codex-settings) | -| `web-reader` | Web page to markdown conversion | [claude-codex-settings](https://github.com/fcakyon/claude-codex-settings) | -| `zread` | GitHub repository reader | [claude-codex-settings](https://github.com/fcakyon/claude-codex-settings) | +| `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/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) | --- -## 📚 Advanced Configuration +## 📚 Documentation -### Auto-Triggering Agents - -This suite supports **two auto-triggering mechanisms**: - -#### Method 1: Hooks-Based (Our Implementation) - -Configure hooks.json for automatic agent invocation: - -```bash -cat > ~/.claude/hooks.json << 'EOF' -{ - "userPromptSubmitHook": "test-writer-fixer@agent", - "toolOutputHook": "whimsy-injector@agent" -} -EOF -``` - -#### Method 2: PROACTIVELY Keyword (Contains Studio Pattern) - -Agents with `PROACTIVELY` in their description automatically trigger based on context: - -```yaml ---- -name: studio-coach -description: PROACTIVELY use this agent when complex multi-agent tasks begin... ---- -``` - -**The 4 Proactive Agents:** -1. **studio-coach** - Triggers on complex multi-agent tasks -2. **test-writer-fixer** - Triggers after code modifications -3. **whimsy-injector** - Triggers after UI/UX changes -4. **experiment-tracker** - Triggers when feature flags are added - -This method requires no hooks.json - Claude Code's built-in agent selection system detects the PROACTIVELY keyword and automatically invokes agents when matching conditions occur. - -**Key Differences:** -| Feature | Hooks-Based | PROACTIVELY Keyword | -|---------|-------------|---------------------| -| Configuration | hooks.json file | Built into agent description | -| Trigger Scope | Global events | Context-aware conditions | -| Flexibility | Manual setup | Self-documenting | -| Detection | File/tool operations | Semantic context | - -### Custom Model Selection - -Use specific models for different tasks: - -```bash -# Add to settings.json -{ - "env": { - "MODEL_DEFAULT": "claude-sonnet-4-20250514", - "MODEL_FAST": "claude-haiku-4-20250514", - "MODEL_EXPENSIVE": "claude-opus-4-20250514" - } -} -``` +- **[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 --- -## 📖 Complete Source Guide with Real-Life Examples +## 📖 Complete Source Guide -This suite integrates **6 major open-source projects**, each providing unique capabilities. Below is a comprehensive guide explaining what each source does, how it integrates, and real-life examples showing the benefits. +This suite integrates **6 major open-source projects**: ### 1. contains-studio/agents 🎭 - **Source:** https://github.com/contains-studio/agents -**Type:** Agent Collection (37 agents) -**Installation:** Copied to `~/.claude/agents/` -**Key Innovation:** PROACTIVELY auto-triggering system - -#### How It Works - -Agents are Markdown files with YAML frontmatter. When the description contains "PROACTIVELY", Claude Code automatically invokes them based on context. - -```yaml ---- -name: test-writer-fixer -description: PROACTIVELY use this agent after code modifications... -tools: Bash, Write, Read, Grep, Glob ---- -``` - -#### Real-Life Example: Auto-Test Writing - -**BEFORE (Without auto-triggering):** -``` -You: I've added OAuth login -Claude: [Writes OAuth code] -You: [Must remember to write tests later] -[Time passes...] -You: [Manually writes tests, misses edge cases] -[Deploy with insufficient tests] -[Bug in production] -``` - -**AFTER (With PROACTIVELY auto-triggering):** -``` -You: I've added OAuth login -Claude: [Writes OAuth code] -[test-writer-fixer PROACTIVELY triggers] -Claude (as test-writer-fixer): I'll write comprehensive tests... -✓ Unit tests for login flow -✓ Integration tests for token refresh -✓ Error handling tests -✓ Edge case coverage -✓ All tests passing! - -[Immediately tested, production ready] -``` - -#### Benefits - -- **Zero Configuration** - Works out of the box -- **Context-Aware** - Triggers based on what you're doing -- **Rich Examples** - Each agent has 4 detailed examples with commentary -- **Department-Based** - Organized by function (engineering, marketing, design, etc.) - ---- +**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 -**Type:** MCP Server (8 vision tools) -**Installation:** `npm install -g @z_ai/mcp-server` -**Key Feature:** Understands images, videos, diagrams - -#### Tools Provided - -| Tool | Function | Real-World Use | -|------|----------|----------------| -| `analyze_image` | Understand any image | Analyze screenshots, photos, designs | -| `analyze_video` | Analyze video content | Review tutorial videos, identify key moments | -| `ui_to_artifact` | Convert UI to code | Implement design mockups | -| `extract_text` | OCR text extraction | Extract text from screenshots, scans | -| `diagnose_error` | Understand error screenshots | Debug errors from screen captures | -| `ui_diff_check` | Compare UI screenshots | Visual regression testing | -| `analyze_data_viz` | Extract insights from charts | Analyze dashboards, reports | -| `understand_diagram` | Understand technical diagrams | Parse UML, flowcharts, architecture | - -#### Real-Life Example: Error Diagnosis - -**BEFORE (Without vision tools):** -``` -You: [Shows error screenshot on phone] -Claude: I cannot see images. Please paste the error text. -You: [Manually types error message] -Claude: [Helps based on text only] -[Misses visual context: line numbers, file paths, variables shown in screenshot] -``` - -**AFTER (With diagnose_error tool):** -``` -You: [Uploads error-screenshot.png] -You: What's wrong with this error? -Claude: [Using diagnose_error tool] -I can see from the screenshot: -- File: src/services/auth.ts, line 47 -- Error: "Cannot read property 'id' of undefined" -- Context: Inside validateUser() function -- Root cause: The user object is null when API call fails - -Fix: Add null check after fetching user: -```typescript -const user = await api.getUser(id); -if (!user) throw new NotFoundError('User not found'); -``` - -[Precise fix with full visual context] -``` - -#### Benefits - -- **Visual Context** - See what Claude sees -- **Faster Debugging** - No manual transcription -- **Exact Implementation** - UI to code matches designs -- **Video Analysis** - Understand motion graphics and animations - ---- +**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 (same repository) -**Type:** MCP Server (3 tools) + CLI wizard -**Installation:** `npm install -g @z_ai/coding-helper` -**Key Feature:** Interactive GLM setup wizard + web/GitHub integration - -#### Tools Provided - -| Tool | Function | Real-World Use | -|------|----------|----------------| -| `web-search-prime` | AI-optimized web search | Get current information | -| `web-reader` | Convert web pages to markdown | Read documentation, articles | -| `zread` | Read GitHub repositories | Understand open-source projects | - -#### Real-Life Example: Current Information - -**BEFORE (Without web search):** -``` -You: What's the latest Next.js version? -Claude: Next.js 13 was released in 2022. -[Information is 2+ years old] -You: [Makes decisions based on outdated info] -``` - -**AFTER (With web-search-prime):** -``` -You: What's the latest Next.js version and features? -Claude: [Using web-search-prime tool] -Searching current web... -Next.js 15 was released in December 2024 with: -- Turbopack for faster builds -- Partial Prerendering -- Improved Server Actions -- Better TypeScript support - -[Always current, better decisions] -``` - -#### GLM Setup Wizard - -```bash -# One command to configure GLM -npx @z_ai/coding-helper init - -# Wizard asks for: -# 1. Z.AI API key -# 2. Automatically configures settings.json -# 3. Sets model mappings (glm-4.5-air, glm-4.7) -# 4. Verifies everything works -``` - -#### Benefits - -- **Always Current** - Real-time web search -- **Repository Analysis** - Read entire GitHub repos without manual pasting -- **Simplified GLM Setup** - Interactive wizard vs manual JSON editing -- **Documentation Access** - Convert any web page to clean markdown - ---- +**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 -**Type:** MCP Server (18 tools) + CLI -**Installation:** `pip install llm-tldr && tldr warm .` -**Key Feature:** 95% token reduction via 5-layer code analysis - -#### The 5 Analysis Layers - -``` -Layer 5: Program Dependence (PDG) → "What affects line 42?" -Layer 4: Data Flow (DFG) → "Where does this data go?" -Layer 3: Control Flow (CFG) → "How complex is this code?" -Layer 2: Call Graph → "Who calls this function?" -Layer 1: AST → "What functions exist?" -``` - -#### Key MCP Tools - -| Tool | Function | Real-World Use | -|------|----------|----------------| -| `context` | LLM-ready code summaries | Understand large codebases with 95% fewer tokens | -| `semantic` | Search by behavior | Find code without knowing exact names | -| `slice` | Show only lines affecting a specific line | Debug faster | -| `impact` | Who calls this function? | Refactor safely | -| `cfg` | Control flow graph | Understand complexity | -| `dfg` | Data flow graph | Trace data transformations | -| `dead` | Find unreachable code | Clean up codebase | -| `arch` | Detect architectural layers | Understand codebase structure | -| And 10 more... | | | - -#### Real-Life Example: Semantic Code Search - -**BEFORE (Without llm-tldr):** -``` -You: Where's the JWT validation code? -Claude: [Searches for "JWT" or "validation"] -I found no results. -[Search failed because function is named "verify_access_token"] -``` - -**AFTER (With semantic search):** -``` -You: Find the JWT validation code -Claude: [Using tldr semantic tool] -Searching by behavior: "validate JWT tokens"... - -Found: verify_access_token() in src/auth/middleware.py -This function: -- Validates JWT signature -- Checks expiration time -- Extracts user claims -- Throws exception if invalid - -[Finds by behavior/intent, not exact name match] -``` - -#### Real-Life Example: Token Savings - -**BEFORE (Raw code):** -``` -100K-line codebase = 104,000 tokens -Cost: $2.60 per query -[Expensive, slow] -``` - -**AFTER (TLDR context):** -``` -100K-line codebase = 12,000 tokens (89% reduction) -Cost: $0.30 per query -[Faster, cheaper, same understanding] -``` - -#### Benefits - -- **95% Token Savings** - $100/month savings for large codebases -- **Semantic Search** - Find code by what it does, not what it's named -- **Impact Analysis** - Refactor safely, see what will break -- **Program Slicing** - Debug faster by seeing only relevant lines -- **Architecture Detection** - Understand codebase organization - ---- - -### 5. claude-codex-settings 📋 - -**Source:** https://github.com/fcakyon/claude-codex-settings -**Type:** Reference/Patterns (not installed directly) -**Integration:** Inspires MCP configuration patterns -**Key Feature:** Best practices for MCP integration - -#### What It Provides - -This is a reference project that shows: -- How to configure MCP servers properly -- Common MCP configuration patterns -- Tool integration best practices -- Example setups for various tools - -#### How It Helps - -Our suite uses these patterns: -- MCP server configuration in `claude_desktop_config.json` -- Tool invocation patterns -- Environment variable setup -- Error handling approaches - -#### Benefits - -- **Best Practices** - Proven configuration patterns -- **Community Knowledge** - Learn from others' setups -- **Troubleshooting** - Common issues and solutions - ---- - -### 6. ui-ux-pro-max-skill 🎨 +**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 -**Type:** Agent + Skill (now installed with PROACTIVELY auto-triggering) -**Integration:** Installed as `~/.claude/agents/design/ui-ux-pro-max.md` and `~/.claude/skills/ui-ux-pro-max/SKILL.md` -**Key Feature:** Professional UI/UX design agent with comprehensive patterns +**Provides:** Professional UI/UX design agent with comprehensive patterns +**Key Feature:** PROACTIVELY auto-triggering for all design work -#### What It Provides - -**PROACTIVELY Auto-Triggering Agent:** -- Triggers on UI component creation (buttons, modals, forms, cards, navbars) -- Triggers on page design (landing pages, dashboards, pricing pages) -- Triggers on UI/UX review and audits -- Applies accessibility compliance (WCAG 2.1 AA/AAA) -- Tech-stack specific patterns (React, Next.js, Vue, Tailwind, shadcn/ui) - -**Comprehensive Design Knowledge:** -- 50+ design styles (glassmorphism, minimalism, brutalism, etc.) -- 97 color palettes by industry -- 57 font pairings with Google Fonts imports -- Accessibility standards (contrast ratios, keyboard nav, ARIA labels) -- Professional design patterns (no emoji icons, proper hover states) - -#### Real-Life Example: UI Component Creation - -**BEFORE (Without ui-ux-pro-max):** -``` -You: Create a modal for user settings -Claude: [Creates basic modal without accessibility] -[Missing: ARIA labels, focus trapping, keyboard support] -[Result: Modal doesn't work with screen readers] -``` - -**AFTER (With ui-ux-pro-max PROACTIVELY triggers):** -``` -You: Create a modal for user settings -[ui-ux-pro-max auto-triggers] -Claude (as ui-ux-pro-max): I'll create a professional, accessible modal... -✓ Proper ARIA labels and roles -✓ Focus trap implementation -✓ Escape key and backdrop click handling -✓ Smooth animations (150-300ms) -✓ Mobile-responsive sizing -✓ WCAG 2.1 AA compliant colors -[Result: Modal works perfectly for all users] -``` - -#### Benefits - -- **Professional Quality** - Agency-level design patterns automatically applied -- **Accessibility First** - WCAG 2.1 AA/AAA compliance built-in -- **No Emoji Icons** - Professional SVG icons from Heroicons/Lucide -- **Proper Hover States** - No layout shift, smooth transitions -- **Contrast Compliant** - All color combinations meet 4.5:1 minimum +### 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 Suite +## 🎯 Real-Life Impact: Before vs After | Scenario | Without Suite | With Suite | Impact | |----------|--------------|-----------|--------| @@ -887,61 +445,7 @@ Claude (as ui-ux-pro-max): I'll create a professional, accessible modal... | **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 | -| **Learning Codebase** | Manual file reading | Context summaries, call graphs | 89% fewer tokens | - ---- - -## 📚 Documentation - -- **[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 - ---- - -## 🙏 Acknowledgments & Sources - -This customization suite is built upon excellent open-source projects and community contributions. - -### Core Inspiration - -- **[contains-studio/agents](https://github.com/contains-studio/agents)** by [contains-studio](https://github.com/contains-studio) - - 37 specialized agents with PROACTIVELY auto-triggering system - - Inspired rich example format with tags and 500+ word system prompts - - Source of studio-coach coordination patterns and department-based organization - - Integrated directly into this suite - -- **[claude-codex-settings](https://github.com/fcakyon/claude-codex-settings)** by [fcakyon](https://github.com/fcakyon) - - Comprehensive Claude Code settings and MCP configurations - - Foundation for MCP tool integration patterns (reference) - -- **[ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)** by [nextlevelbuilder](https://github.com/nextlevelbuilder) - - Professional UI/UX design patterns converted to PROACTIVELY auto-triggering agent - - Installed as `~/.claude/agents/design/ui-ux-pro-max.md` with full design system knowledge - - Also installed as SKILL file for enhanced compatibility - -- **[Ralph](https://github.com/iannuttall/ralph)** by [iannuttall](https://github.com/iannuttall) - - CLI framework for autonomous agent loops (installed separately via `npm i -g @iannuttall/ralph`) - - Agent coordination patterns (supervisor-agent, task delegation) already integrated into contains-studio agents - - Note: Ralph is a standalone tool, not Claude Code agents - its patterns inspired studio-producer and studio-coach - -### MCP Tool Sources - -- **[@z_ai/mcp-server](https://github.com/zai-ai/mcp-server)** - Vision analysis, OCR, UI comparison, video analysis, and diagram understanding -- **[llm-tldr](https://github.com/parcadei/llm-tldr)** - Token-efficient code analysis with 95% reduction, semantic search, and 5-layer program analysis -- **[Z.AI GLM Documentation](https://docs.z.ai/devpack/tool/claude)** - Official GLM Coding Plan integration guide for Claude Code -- **[Model Context Protocol](https://github.com/modelcontextprotocol)** - Open standard for connecting AI models to tools -- **[Claude Code](https://github.com/anthropics/claude-code)** - Official Claude Code CLI by Anthropic - -### Agent Architecture - -- **6-Day Development Cycle** - Inspired by rapid iteration methodologies and startup best practices -- **Studio Operations** - Professional studio management patterns applied to software development -- **Auto-Triggering Agents** - Proactive agent invocation patterns for test writing and UI enhancement +| **Multi-Agent Tasks** | Manual orchestration | Automatic coordination | Hands-free delivery | ---