claude-code-glm-suite/MASTER-PROMPT.md

# 🚀 Claude Code & GLM Suite - Master Integration Prompt

> **Complete installation with ALL sources, explanations, and real-life examples**

---

## ⚠️ BEFORE YOU BEGIN - Read This First!

### **If Using Z.AI / GLM Coding Plan (90% cheaper):**

**You MUST configure GLM FIRST before using Claude Code!**

**🎯 EASIEST METHOD - Use Z.AI Coding Helper Wizard:**

```bash
# Step 1: Install the coding helper
npm install -g @z_ai/coding-helper

# Step 2: Run the interactive GLM setup wizard
npx @z_ai/coding-helper init

# The wizard will:
# - Ask for your Z.AI API key
# - Configure Claude Code for GLM automatically
# - Set up proper model mappings (glm-4.5-air, glm-4.7)
# - Verify everything works

# Step 3: Start Claude Code with GLM configured
claude

# Step 4: Verify GLM is working (enter /status when prompted)
/status
```

**📖 Official GLM Documentation:** https://docs.z.ai/devpack/tool/claude

---

**Alternative: Manual Configuration (if you prefer):**

```bash
# Step 1: Get your API key
# Visit: https://z.ai/
# Sign up for GLM Coding Plan and copy your API key

# Step 2: Install Claude Code (if not installed)
npm install -g @anthropic-ai/claude-code

# Step 3: Create 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

# Step 4: Start Claude Code
claude
```

---

### **If Using Anthropic Claude (Official API):**

```bash
# Step 1: Get your API key
# Visit: https://console.anthropic.com/

# Step 2: Create Claude Code settings
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}
EOF

# Step 3: Install Claude Code (if not installed)
npm install -g @anthropic-ai/claude-code

# Step 4: Start Claude Code
claude
```

---

## 📋 HOW TO USE THE MASTER PROMPT

**Once Claude Code is running and configured:**

### **✂️ COPY FROM HERE:**

```text
═══════════════════════════════════════════════════════════════════════════════

I want to install the Ultimate Claude Code & GLM Customization Suite with ALL integrations including agents, MCP tools, code analysis, and automation. Please perform the following complete integration:

## Overview: What We're Installing

This suite includes 6 major components from open-source projects:

1. **contains-studio/agents** - 38 specialized AI agents with PROACTIVELY auto-triggering
2. **@z_ai/mcp-server** - 8 vision and analysis tools (screenshots, videos, diagrams)
3. **@z_ai/coding-helper** - Web search, GitHub integration, GLM setup wizard
4. **llm-tldr** - Token-efficient code analysis (95% reduction, semantic search)
5. **ui-ux-pro-max-skill** - Professional UI/UX design agent with PROACTIVELY auto-triggering
6. **claude-codex-settings** - MCP configuration patterns and best practices (reference)

**Agent Architecture Patterns:**
The PROACTIVELY coordinator agents (studio-coach, studio-producer, experiment-tracker, project-shipper) implement proven coordination patterns from autonomous agent frameworks like Ralph, using supervisor-agent delegation and shared context management.

Each component is explained below with real-life examples showing the benefits.

---

## Step 1: Install Contains Studio Agents (38 agents with PROACTIVELY auto-triggering)

Source: https://github.com/contains-studio/agents

Clone the contains-studio/agents repository:
git clone https://github.com/contains-studio/agents.git /tmp/contains-studio-agents

Copy all agents to Claude Code agents directory:
cp -r /tmp/contains-studio-agents/agents/* ~/.claude/agents/

### What This Provides:

37 specialized agents across 8 departments:
- **Engineering (7):** AI Engineer, Backend Architect, DevOps Automator, Frontend Developer, Mobile Builder, Rapid Prototyper, Test Writer/Fixer
- **Marketing (7):** TikTok Strategist, Growth Hacker, Content Creator, Instagram Curator, Reddit Builder, Twitter Engager, App Store Optimizer
- **Design (6):** Brand Guardian, UI Designer, UX Researcher, Visual Storyteller, Whimsy Injector, **UI/UX Pro Max**
- **Product (3):** Feedback Synthesizer, Sprint Prioritizer, Trend Researcher
- **Project Management (3):** Experiment Tracker, Project Shipper, Studio Producer
- **Studio Operations (5):** Analytics Reporter, Finance Tracker, Infrastructure Maintainer, Legal Compliance Checker, Support Responder
- **Testing (5):** API Tester, Performance Benchmarker, Test Results Analyzer, Tool Evaluator, Workflow Optimizer
- **Bonus (3):** Studio Coach, Agent Updater, Joker

### 🎯 Auto-Triggering System: How Agents Coordinate

**Architecture Overview:**

The 38 agents are divided into two types:
- **7 PROACTIVELY Coordinators** - Auto-trigger based on context and coordinate specialists
- **1 Utility Agent** - Manually triggered for maintenance (agent-updater)
- **30 Specialist Agents** - Execute specific domain tasks when called

**How It Works:**

There are **two pathways** to use agents:

1. **Automatic** - Coordinators auto-trigger and call specialists as needed
2. **Direct** - You manually invoke any specialist for precise control

This gives you automation when you want it, control when you need it.

---

**7 PROACTIVELY Agents** (meta-coordinators that auto-trigger based on context):

**Plus 1 Utility Agent** (manually triggered for maintenance):

#### Design Department (2)

1. **ui-ux-pro-max** - Triggers on UI/UX design work
   - Professional design patterns and accessibility
   - 50+ styles, 97 color palettes, WCAG compliance
   - Example: "Create a pricing page" → ui-ux-pro-max applies professional design patterns

2. **whimsy-injector** - Triggers after UI/UX changes
   - Adds delightful micro-interactions
   - Makes interfaces memorable
   - Example: You create a loading spinner → whimsy-injector adds bounce animation and encouraging messages

#### Engineering Department (1)

3. **test-writer-fixer** - Triggers after code modifications
   - Automatically writes comprehensive tests
   - Fixes broken tests
   - Example: You modify authentication code → test-writer-fixer writes unit tests automatically

#### Project Management Department (3)

4. **experiment-tracker** - Triggers when experiments are started or modified
   - Tracks A/B tests and feature experiments
   - Defines metrics and monitors results
   - Example: You add a feature flag → experiment-tracker sets up tracking and success metrics

5. **studio-producer** - Triggers when coordinating across multiple teams
   - Cross-team coordination and resource allocation
   - Workflow optimization and dependency management
   - Example: "Design and engineering need to collaborate" → studio-producer schedules and coordinates

6. **project-shipper** - Triggers when approaching launch milestones
   - Launch coordination and release management
   - Go-to-market strategy and stakeholder communication
   - Example: "We're releasing next week" → project-shipper plans launch activities

#### Bonus Department (1)

7. **studio-coach** - Triggers on complex multi-agent tasks
   - Coordinates multiple specialists
   - Motivates and aligns agents when stuck
   - Example: "Build a viral TikTok app in 2 weeks" → studio-coach organizes frontend, backend, marketing agents

#### Utility Agent (On-Demand)

8. **agent-updater** - Manually triggered for agent synchronization
   - Checks GitHub for agent updates
   - Downloads and installs new/updated agents safely
   - Preserves local customizations
   - Example: "Check for agent updates" → agent-updater fetches latest from GitHub and syncs your installation

---

**🔄 Real Workflow Example:**

You: "I need a viral TikTok app in 2 weeks"
      ↓
[studio-coach PROACTIVELY triggers]
      ↓
studio-coach analyzes and coordinates:
  → rapid-prototyper (specialist) builds MVP
  → tiktok-strategist (specialist) plans viral features
  → frontend-developer (specialist) builds UI
      ↓
[whimsy-injector PROACTIVELY triggers]
      ↓
whimsy-injector adds delightful touches
      ↓
[project-shipper PROACTIVELY triggers]
      ↓
project-shipper plans launch strategy
      ↓
Result: Complete app, launch-ready ✓

**Key Point:** You don't need to manually orchestrate! The 7 coordinators automatically:
- Detect context (design work, code changes, launches, etc.)
- Call appropriate specialist agents
- Coordinate multi-agent workflows
- Ensure quality and completeness

You can ALSO directly call any specialist agent anytime for manual control.

---

## Step 1.5: Install UI/UX Pro Max Agent (PROACTIVELY Auto-Triggers)

Source: https://github.com/nextlevelbuilder/ui-ux-pro-max-skill

Clone the ui-ux-pro-max-skill repository:
git clone https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git /tmp/ui-ux-pro-max-skill

Install UI/UX Pro Max agent with PROACTIVELY triggers:
mkdir -p ~/.claude/agents/design
wget -O ~/.claude/agents/design/ui-ux-pro-max.md https://raw.githubusercontent.com/github.rommark.dev/admin/claude-code-glm-suite/main/agents/design/ui-ux-pro-max.md

Also install the SKILL file for enhanced compatibility:
mkdir -p ~/.claude/skills/ui-ux-pro-max
cp /tmp/ui-ux-pro-max-skill/.claude/skills/ui-ux-pro-max/SKILL.md ~/.claude/skills/ui-ux-pro-max/

### What This Provides:

**ui-ux-pro-max agent** with PROACTIVELY auto-triggering for:
- UI component creation (buttons, modals, forms, cards, navbars)
- Page design (landing pages, dashboards, pricing pages)
- UI/UX review and audits
- Style guide application (colors, typography, spacing)
- 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)

**Key Features:**
- Automatic UI/UX review during design work
- Professional design patterns applied proactively
- Accessibility-first approach (WCAG 2.1 AA/AAA)
- Comprehensive styling guidelines

---

## Step 1.75: Install Agent Sync Script (Keep Agents Updated)

Source: https://github.rommark.dev/admin/claude-code-glm-suite

Install the automated sync script to keep your agents up-to-date:

# Download sync-agents.sh
wget -O ~/.claude/sync-agents.sh https://raw.githubusercontent.com/github.rommark.dev/admin/claude-code-glm-suite/main/sync-agents.sh

# Make it executable
chmod +x ~/.claude/sync-agents.sh

### What This Provides:

**Automated agent synchronization:**
- Fetches latest agents from official GitHub repository
- Creates timestamped backups before updating
- Detects new, updated, and customized agents
- Safely updates while preserving your customizations
- Commits changes to git (if configured)
- Pushes updates to your Gitea repository

**Usage:**

# Run sync manually
~/.claude/sync-agents.sh

# Or set Gitea repository URL to auto-push
export GITEA_REPO_URL="https://github.rommark.dev/admin/claude-code-glm-suite.git"
~/.claude/sync-agents.sh

# Also update repository agents (for installers)
export REPO_AGENTS_DIR="/path/to/claude-code-glm-suite/agents"
~/.claude/sync-agents.sh

**How it works:**
1. Clones latest agents from `https://github.com/contains-studio/agents`
2. Compares with your local `~/.claude/agents/`
3. Identifies:
   - ✨ New agents to add
   - 📝 Updated agents to refresh
   - ⚠️ Custom agents to preserve
4. Creates backup: `~/.claude/agents.backup.YYYYMMDD-HHMMSS/`
5. Applies updates safely
6. Reports all changes
7. [Optional] Commits to git and pushes to Gitea

**Key Features:**
- **Safe Updates**: Always creates backups before modifying
- **Smart Detection**: Preserves agents you've customized
- **Dual Sync**: Updates both local agents AND repository agents
- **Git Integration**: Commits and pushes automatically
- **Detailed Logging**: Tracks all changes in `~/.claude/agents/update.log`

**Keeping Agents Updated:**
Run the sync script regularly (weekly or monthly) to get the latest agent improvements:

# Add to crontab for automatic weekly sync
0 2 * * 0 ~/.claude/sync-agents.sh

Or manually check for updates anytime:

~/.claude/sync-agents.sh

**Rollback if needed:**

# List backups
ls -la ~/.claude/agents.backup.*

# Restore a backup
rm -rf ~/.claude/agents
mv ~/.claude/agents.backup.YYYYMMDD-HHMMSS ~/.claude/agents

---

## Step 2: Install MCP Vision & Analysis Tools

Source: https://github.com/zai-ai/mcp-server

Install Z.AI MCP server for vision tools:
npm install -g @z_ai/mcp-server

Verify installation:
npx @z_ai/mcp-server --help

### What This Provides (8 MCP Tools):

1. **analyze_image** - Understand any image (screenshots, photos, designs)
2. **analyze_video** - Analyze video content for key moments
3. **ui_to_artifact** - Convert UI screenshots to code
4. **extract_text** - OCR text extraction from images
5. **diagnose_error** - Understand errors from screenshots
6. **ui_diff_check** - Compare two UI screenshots
7. **analyze_data_viz** - Extract insights from dashboards/charts
8. **understand_diagram** - Understand technical diagrams (UML, flowcharts)

**Key Features:**
- Screenshot-to-code conversion
- Error diagnosis from images
- Video and diagram understanding
- UI comparison and analysis

---

## Step 3: Install MCP Web & GitHub Tools

Source: https://github.com/fcakyon/claude-codex-settings (inspired by)

Install Z.AI coding helper:
npm install -g @z_ai/coding-helper

Verify installation:
npx @z_ai/coding-helper --help

### What This Provides (3 MCP Tools):

1. **web-search-prime** - AI-optimized web search for current information
2. **web-reader** - Convert any web page to clean markdown
3. **zread** - Read and analyze entire GitHub repositories

**Key Features:**
- Real-time web search for current information
- Repository analysis without manual file pasting
- Web page to clean markdown conversion

---

## Step 4: Install llm-tldr (Token-Efficient Code Analysis)

Source: https://github.com/parcadei/llm-tldr

Install llm-tldr:
pip install llm-tldr

Initialize for current directory:
tldr warm .

### What This Provides:

**95% token reduction** while preserving code understanding via 5-layer analysis:
- **Layer 1 (AST)** - Functions, classes, imports structure
- **Layer 2 (Call Graph)** - Who calls what (forward/backward)
- **Layer 3 (CFG)** - Control flow, complexity metrics
- **Layer 4 (DFG)** - Data flow, variable transformations
- **Layer 5 (PDG)** - Program dependence, slicing for debugging

**18 MCP Tools including:**
- `context` - LLM-ready summaries (95% token savings)
- `semantic` - Search by behavior, not just text
- `slice` - Show only code affecting a specific line
- `impact` - Who calls this function? (refactoring safety)
- `cfg` - Control flow graph
- `dfg` - Data flow graph
- And 12 more...

**Key Features:**
- 95% token reduction for large codebases
- Semantic search by behavior (not just text)
- Program slicing for precise debugging
- Impact analysis for safe refactoring

---

## Step 5: Configure MCP Servers in Claude Code

Create MCP configuration for TLDR:
mkdir -p ~/.claude
cat > ~/.claude/claude_desktop_config.json << 'EOF'
{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    },
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    }
  }
}
EOF

Note: TLDR MCP server provides 18 tools for code analysis.
Vision tools from @z_ai/mcp-server are automatically available.

---

## Step 6: Configure Ralph CLI Autonomous Looping (Advanced - Optional)

Source: https://github.com/iannuttall/ralph

**What Ralph Provides:**
Ralph is an autonomous agent orchestration tool that creates infinite loops until task completion. Unlike single-pass PROACTIVELY agents, Ralph maintains state across multiple iterations and coordinates agents through complex workflows.

**Key Differences:**
- **PROACTIVELY Agents**: Single-pass coordination, one interaction
- **Ralph CLI**: Infinite looping, stateful, autonomous until done

### Installation:

Install Ralph CLI:
npm install -g @iannuttall/ralph

Verify installation:
ralph --version

### Create Ralph Auto-Trigger Hook:

mkdir -p ~/.claude/hooks
cat > ~/.claude/hooks/ralph-auto-trigger.sh << 'EOF'
#!/bin/bash

# Ralph Auto-Trigger Hook
# Automatically starts Ralph loop when user requests something
# Set RALPH_AUTO_MODE environment variable to control behavior:
#   "always"    - Always start Ralph for every request
#   "agents"    - Only start Ralph for agent requests (default)
#   "off"       - Disable auto-trigger

set -euo pipefail

# Read hook input from stdin
HOOK_INPUT=$(cat)

# Get the user prompt from hook input
USER_PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty')

# Check if auto-trigger is enabled (default: agents)
RALPH_AUTO_MODE="${RALPH_AUTO_MODE:-agents}"

# Exit if auto-trigger is disabled
if [[ "$RALPH_AUTO_MODE" == "off" ]]; then
  exit 0
fi

# Exit if Ralph is already active
RALPH_STATE_FILE=".claude/ralph-loop.local.md"
if [[ -f "$RALPH_STATE_FILE" ]]; then
  exit 0
fi

# Check if this is an agent request (list of known agents)
KNOWN_AGENTS="frontend-developer|backend-architect|mobile-app-builder|ai-engineer|devops-automator|rapid-prototyper|test-writer-fixer|studio-coach|studio-producer|sprint-prioritizer|experiment-tracker|whimsy-injector|joker|trend-researcher|tiktok-strategist|feedback-synthesizer|ui-ux-pro-max"

# Determine if we should start Ralph
START_RALPH=false

case "$RALPH_AUTO_MODE" in
  "always")
    # Start Ralph for everything
    START_RALPH=true
    ;;
  "agents")
    # Check if prompt mentions an agent or uses agent-like language
    if echo "$USER_PROMPT" | grep -qiE "use (the |a )?($KNOWN_AGENTS) agent|launch ($KNOWN_AGENTS)|agent:|delegate to|run (the |a )?($KNOWN_AGENTS)" || \
       echo "$USER_PROMPT" | grep -qiE "build|create|implement|develop|fix|add|refactor|optimize"; then
      START_RALPH=true
    fi
    ;;
esac

if [[ "$START_RALPH" == "true" ]]; then
  # Create Ralph state file with default settings
  mkdir -p .claude

  cat > "$RALPH_STATE_FILE" <<EOF
---
active: true
iteration: 1
max_iterations: 0
completion_promise: null
started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
auto_triggered: true
---

$USER_PROMPT
EOF

  # Notify that Ralph was auto-triggered
  echo "🔄 Ralph auto-triggered!" >&2
  echo "   Mode: $RALPH_AUTO_MODE" >&2
  echo "   Ralph will loop this request indefinitely." >&2
  echo "   Set RALPH_AUTO_MODE=off to disable, or use /cancel-ralph to stop." >&2
fi

exit 0
EOF

chmod +x ~/.claude/hooks/ralph-auto-trigger.sh

### Configure Hooks:

Create hooks.json to enable Ralph auto-trigger:
cat > ~/.claude/hooks.json << 'EOF'
{
  "description": "User hooks for Ralph auto-trigger",
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/home/uroma/.claude/hooks/ralph-auto-trigger.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}
EOF

Note: Replace "/home/uroma" with your actual home directory if different.

### What This Provides:

**Autonomous Looping:**
- Ralph keeps iterating until task completion
- State preserved in `.claude/ralph-loop.local.md`
- Can handle complex multi-step workflows

**Control Modes:**

# Mode 1: Auto-loop only for agent requests (default)
export RALPH_AUTO_MODE="agents"

# Mode 2: Auto-loop for everything
export RALPH_AUTO_MODE="always"

# Mode 3: Disable auto-loop
export RALPH_AUTO_MODE="off"

### How It Works:

1. You request: "Build a TikTok app in 2 weeks"
2. Hook detects agent language
3. Ralph creates state file and starts loop
4. Ralph iterates through agents:
   - Iteration 1: rapid-prototyper builds MVP
   - Iteration 2: tiktok-strategist plans viral features
   - Iteration 3: frontend-developer builds UI
   - Continues until Ralph is satisfied
5. Ralph updates `.claude/ralph-loop.local.md` each iteration
6. Stop with: /cancel-ralph command or delete state file

### Canceling Ralph:

If Ralph is looping and you want to stop:

# Method 1: Use cancel command
/cancel-ralph

# Method 2: Delete state file
rm .claude/ralph-loop.local.md

# Method 3: Disable auto-mode
export RALPH_AUTO_MODE="off"

### Ralph vs PROACTIVELY Agents:

| Feature | Ralph CLI | PROACTIVELY Agents |
|---------|-----------|-------------------|
| **Execution** | Multi-loop iterations | Single interaction |
| **State** | Persisted in file | Context only |
| **Control** | Manual stop required | Automatic |
| **Complexity** | Handles complex workflows | Quick coordination |
| **Setup** | Requires hook + script | Built-in to agents |

**You can use BOTH together:**
- Use Ralph for complex, multi-step projects
- Use PROACTIVELY agents for quick tasks
- Set RALPH_AUTO_MODE="agents" for hybrid approach

---

## Step 7: Verify Complete Installation

Run comprehensive checks:

# 1. Verify agents (should be 38+ files)
ls -la ~/.claude/agents/
find ~/.claude/agents -name "*.md" | wc -l

# 2. Verify MCP tools
npx @z_ai/mcp-server --help
npx @z_ai/coding-helper --help
tldr --help

# 3. Verify TLDR indexing
tldr status .

# 4. Verify Ralph CLI (if installed)
ralph --version

# 5. Verify Ralph hook
ls -la ~/.claude/hooks/ralph-auto-trigger.sh

# 6. Test Claude Code
claude --version

Expected results:
- ✅ 39+ agent files (38 agents + README)
- ✅ All 8 departments present
- ✅ MCP tools accessible
- ✅ TLDR indexed current directory
- ✅ Settings configured
- ⚠️ Ralph CLI (optional - verify if installed in Step 6)

---

## Summary: What You Now Have

### 40+ AI Agents
Organized across 8 departments with PROACTIVELY auto-triggering

### 15+ MCP Tools
- 8 vision/analysis tools (@z_ai/mcp-server)
- 3 web/GitHub tools (@z_ai/coding-helper)
- 18 code analysis tools (llm-tldr)

### Three Auto-Triggering Systems
- **PROACTIVELY keyword** (context-aware, built into agents)
- **Ralph CLI** (autonomous looping, optional advanced setup)
- **Hooks-based** (event-driven, for Ralph integration)

### Complete Integration Benefits

**Token Efficiency:**
- TLDR reduces code context by 95%
- $100/month savings on API costs for large codebases

**Code Understanding:**
- 5-layer analysis (AST → PDG)
- Semantic search by behavior
- Impact analysis for safe refactoring

**Visual Capabilities:**
- Screenshot-to-code conversion
- Error diagnosis from images
- Video and diagram understanding

**Automation:**
- Auto-test writing after code changes
- Auto-UI enhancement after design changes
- Auto-coordination for complex tasks

**Up-to-Date Information:**
- Real-time web search
- Repository analysis
- Current documentation

Please execute this complete integration step by step and confirm when each component is installed.

═══════════════════════════════════════════════════════════════════════════════
```

**✂️ COPY ENDS HERE**

---

---

# ═══════════════════════════════════════════════════════════════════════════════
# 📖 REAL-LIFE EXAMPLES: HOW AUTO-TRIGGERING WORKS
# ═══════════════════════════════════════════════════════════════════════════════

> ⚠️ **IMPORTANT: These are ILLUSTRATIVE EXAMPLES ONLY**
>
> The examples below demonstrate the conceptual difference between working **without** auto-triggering agents versus **with** auto-triggering agents.
> These are simplified scenarios to help you understand how the PROACTIVELY system improves your workflow.
>
> **These are not actual output promises** - actual results will vary based on your specific use case, context, and model capabilities.

## Example 1: Adding OAuth Authentication

### ❌ WITHOUT Auto-Triggering Agents

You: Help me add OAuth to my app
Claude: [Writes code, but no tests]
You: [Manually write tests later]
Claude: [Fixes bugs]

### ✅ WITH Auto-Triggering Agents

You: Help me add OAuth to my app
Claude: [Writes code]
[test-writer-fixer PROACTIVELY triggers]
test-writer-fixer: I've automatically created comprehensive tests for your OAuth implementation
Result: Code + tests complete in one interaction ✓

---

## Example 2: Creating a Loading Spinner

### ❌ WITHOUT Auto-Triggering Agents

You: Create a loading spinner
Claude: [Creates basic spinner]
You: [Manually request improvements later]
Claude: [Adds animation]

### ✅ WITH Auto-Triggering Agents

You: Create a loading spinner
Claude: [Creates spinner]
[whimsy-injector PROACTIVELY triggers]
whimsy-injector: I've enhanced your spinner with bounce animation and encouraging messages
Result: Delightful spinner created automatically ✓

---

## Example 3: Launching a New Feature

### ❌ WITHOUT Auto-Triggering Agents

You: We're launching next week
Claude: [Doesn't know what to prepare]
You: [Manually create launch checklist]
Claude: [Helps with specific items]

### ✅ WITH Auto-Triggering Agents

You: We're launching next week
[project-shipper PROACTIVELY triggers]
project-shipper: I've created a complete launch plan with:
- Pre-launch readiness checklist
- Go-to-market strategy
- Stakeholder communication plan
- Success metrics and monitoring
Result: Launch-ready plan created automatically ✓

---

## Example 4: Adding a Feature Flag

### ❌ WITHOUT Auto-Triggering Agents

You: Add feature flag for new checkout
Claude: [Adds flag, but no tracking]
You: [Manually set up analytics later]

### ✅ WITH Auto-Triggering Agents

You: Add feature flag for new checkout
Claude: [Adds flag]
[experiment-tracker PROACTIVELY triggers]
experiment-tracker: I've configured tracking for this experiment:
- Success metrics defined
- Analytics events set up
- Rollout plan created
- Sample size calculated
Result: A/B test ready to run ✓

---

## Example 5: Complex Multi-Agent Task

### ❌ WITHOUT Auto-Triggering Agents

You: Build viral TikTok app in 2 weeks
Claude: [Overwhelmed, doesn't know where to start]
You: [Manually coordinate frontend, backend, marketing teams]

### ✅ WITH Auto-Triggering Agents

You: Build viral TikTok app in 2 weeks
[studio-coach PROACTIVELY triggers]
studio-coach: I'll coordinate this complex project:
→ Calling rapid-prototyper for MVP
→ Calling tiktok-strategist for viral features
→ Calling frontend-developer for UI
→ Calling project-hipper for launch planning
[All agents work together seamlessly]
Result: Complete app, launch-ready, on time ✓

---

## Key Differences Summary

| Aspect | Without Auto-Trigger | With Auto-Trigger |
|--------|---------------------|-------------------|
| **Test Coverage** | Manual, forgettable | Automatic, comprehensive |
| **UI Polish** | Basic, functional | Delightful, memorable |
| **Launch Prep** | Last-minute, chaotic | Planned, organized |
| **Experiment Tracking** | Missing, incomplete | Defined, measurable |
| **Complex Projects** | Overwhelming, fragmented | Coordinated, smooth |
| **Follow-up Required** | Always needed | Built-in |

---

## Why This Matters

**Time Savings:**
- Without: Multiple back-and-forth interactions
- With: Complete in one interaction

**Quality:**
- Without: Inconsistent, forgets steps
- With: Comprehensive, best practices applied

**Peace of Mind:**
- Without: Did I remember everything?
- With: Agents handle it automatically

**Scalability:**
- Without: Manual coordination doesn't scale
- With: Automated coordination handles complexity

---

## ⚡ PROACTIVELY vs Hooks-Based

### PROACTIVELY System (Context-Aware)

**How it works:**
- Claude analyzes the context of your request
- Automatically determines which coordinator to trigger
- Coordinator calls specialist agents as needed

**Examples:**
- You write code → test-writer-fixer triggers
- You design UI → whimsy-injector triggers
- You mention launch → project-shipper triggers

**Benefits:**
- No configuration needed
- Works based on natural language context
- Can be overridden by manual requests

### Hooks-Based System (Event-Driven)

**How it works:**
- Configured in `~/.claude/hooks.json`
- Triggers on specific events (prompt submit, tool output, etc.)

**Example Configuration:**
```json
{
  "userPromptSubmitHook": "test-writer-fixer@agent",
  "toolOutputHook": "whimsy-injector@agent"
}
```

**Benefits:**
- Predictable triggers
- Fine-grained control
- Works alongside PROACTIVELY system

### Combined Power

You can use BOTH systems together:
- PROACTIVELY: Automatic context-aware triggers
- Hooks: Additional event-driven triggers
- Result: Comprehensive automation coverage

---

# 📚 AGENT DEPARTMENTS AND SPECIALTIES

## Engineering Department (7 agents)

1. **ai-engineer** - ML/LLM feature integration
2. **backend-architect** - API design, database optimization
3. **devops-automator** - CI/CD, cloud infrastructure
4. **frontend-developer** - React/Vue/Angular UI development
5. **mobile-app-builder** - iOS/Android native apps
6. **rapid-prototyper** - Quick MVPs and prototypes
7. **test-writer-fixer** - Auto test writing (PROACTIVELY)

## Marketing Department (7 agents)

1. **tiktok-strategist** - Viral TikTok marketing
2. **growth-hacker** - Viral growth loops
3. **content-creator** - Multi-platform content
4. **instagram-curator** - Visual content strategy
5. **reddit-community-builder** - Reddit engagement
6. **twitter-engager** - Twitter growth
7. **app-store-optimizer** - ASO and rankings

## Design Department (6 agents)

1. **brand-guardian** - Brand consistency
2. **ui-designer** - Interface design
3. **ux-researcher** - User research
4. **visual-storyteller** - Visual narratives
5. **whimsy-injector** - Delight injection (PROACTIVELY)
6. **ui-ux-pro-max** - Professional UI/UX (PROACTIVELY)

## Product Department (3 agents)

1. **feedback-synthesizer** - User feedback analysis
2. **sprint-prioritizer** - Feature prioritization
3. **trend-researcher** - Market trend identification

## Project Management Department (3 agents)

1. **experiment-tracker** - A/B test tracking (PROACTIVELY)
2. **project-shipper** - Launch coordination (PROACTIVELY)
3. **studio-producer** - Team coordination (PROACTIVELY)

## Studio Operations Department (5 agents)

1. **analytics-reporter** - Data insights
2. **finance-tracker** - Financial management
3. **infrastructure-maintainer** - System maintenance
4. **legal-compliance-checker** - Legal compliance
5. **support-responder** - Customer support

## Testing Department (5 agents)

1. **api-tester** - API testing
2. **performance-benchmarker** - Performance optimization
3. **test-results-analyzer** - Test analysis
4. **tool-evaluator** - Tool assessment
5. **workflow-optimizer** - Process improvement

## Bonus Department (3 agents)

1. **studio-coach** - Agent coordination (PROACTIVELY)
2. **agent-updater** - Agent updates (on-demand)
3. **joker** - Humor injection

---

# 🔧 CONFIGURATION FILES

## ~/.claude/settings.json

Main Claude Code configuration file:

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "3000000"
  }
}
```

### For Z.AI / GLM:

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-zai-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

MCP server configuration:

```json
{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "."]
    },
    "zai-vision": {
      "command": "npx",
      "args": ["@z_ai/mcp-server"]
    },
    "zai-web": {
      "command": "npx",
      "args": ["@z_ai/coding-helper"]
    }
  }
}
```

## ~/.claude/hooks.json

Auto-triggering hooks:

```json
{
  "userPromptSubmitHook": "test-writer-fixer@agent",
  "toolOutputHook": "whimsy-injector@agent"
}
```

---

# 🎯 QUICK REFERENCE

## Available Commands

### Sync Agents
```bash
~/.claude/sync-agents.sh
```

### Verify Installation
```bash
./verify-claude-setup.sh
```

### Check TLDR Status
```bash
tldr status .
```

### Test Claude Code
```bash
claude --version
```

## Environment Variables

```bash
# Auto-push to Gitea after sync
export GITEA_REPO_URL="https://github.rommark.dev/admin/claude-code-glm-suite.git"

# Update repository agents during sync
export REPO_AGENTS_DIR="/path/to/repo/agents"
```

## Troubleshooting

### Agents not triggering?
- Check `~/.claude/agents/` directory
- Verify agent files exist and have content
- Restart Claude Code

### MCP tools not available?
- Check `~/.claude/claude_desktop_config.json`
- Verify MCP servers are installed
- Restart Claude Code

### TLDR not working?
- Run `tldr warm .` in project directory
- Check Python installation
- Verify `tldr-mcp` is in PATH

---

# 📖 ADDITIONAL RESOURCES

## Official Documentation
- **Claude Code**: https://docs.anthropic.com/en/docs/claude-code
- **Z.AI / GLM**: https://docs.z.ai/devpack/tool/claude
- **contains-studio/agents**: https://github.com/contains-studio/agents
- **@z_ai/mcp-server**: https://github.com/zai-ai/mcp-server
- **llm-tldr**: https://github.com/parcadei/llm-tldr

## Community & Support
- **Claude Code Sub-Agents**: https://docs.anthropic.com/en/docs/claude-code/sub-agents
- **Gitea Repository**: https://github.rommark.dev/admin/claude-code-glm-suite

## Changelog & Updates
- Check the repository regularly for updates
- Use `~/.claude/sync-agents.sh` to keep agents current
- Review MASTER-PROMPT.md for latest features

---

**Last Updated**: 2025-01-16
**Version**: 2.0
**Maintained By**: rommark.dev