# Contains Studio Agents Integration

This document explains how the **contains-studio/agents** repository has been integrated into this customization suite, including the PROACTIVELY auto-triggering mechanism and key differences from our hook-based approach.

## 📋 Overview

**Source Repository:** [https://github.com/contains-studio/agents](https://github.com/contains-studio/agents)

Contains Studio provides 37 specialized AI agents with a sophisticated **PROACTIVELY auto-triggering system** that differs from our original hooks-based approach.

---

## 🔄 Two Auto-Triggering Mechanisms

This customization suite now supports **both** auto-triggering mechanisms:

### Method 1: Hooks-Based (Our Original Implementation)

**Configuration File:** `~/.claude/hooks.json`

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

**How It Works:**
- Uses Claude Code's hook system
- Triggers on specific events (file operations, tool outputs)
- Global configuration applies to all sessions
- Requires manual setup

**Pros:**
- Explicit control over when agents trigger
- Works across all tools and operations
- Easy to customize and debug

**Cons:**
- Requires separate configuration file
- Less context-aware
- Manual setup needed

---

### Method 2: PROACTIVELY Keyword (Contains Studio Pattern)

**Configuration:** Built into agent description

```yaml
---
name: studio-coach
description: PROACTIVELY use this agent when complex multi-agent tasks begin...
color: gold
tools: Task, Write, Read
---
```

**How It Works:**
- Claude Code's built-in agent selection system detects "PROACTIVELY" keyword
- Analyzes context to determine if trigger conditions match
- Self-documenting - triggers are in the agent description
- No separate configuration needed

**The 4 Proactive Agents:**

1. **studio-coach** 🎭
   - **Triggers:** Complex multi-agent tasks begin, agents stuck/overwhelmed
   - **Purpose:** Coordinate and motivate all agents
   - **Example:** "We need to build a viral TikTok app in 2 weeks"

2. **test-writer-fixer** 🧪
   - **Triggers:** After code modifications, bug fixes, feature implementations
   - **Purpose:** Automatically write tests and fix failures
   - **Example:** User completes code changes → test-writer-fixer activates

3. **whimsy-injector** ✨
   - **Triggers:** After UI/UX changes, component creation, design updates
   - **Purpose:** Add delightful micro-interactions and personality
   - **Example:** User creates loading spinner → whimsy-injector enhances it

4. **experiment-tracker** 📊
   - **Triggers:** When feature flags added, experimental code paths detected
   - **Purpose:** Track A/B tests and experiments
   - **Example:** User adds conditional logic for A/B test → experiment-tracker sets up metrics

**Pros:**
- Zero configuration - works out of the box
- Context-aware triggering based on semantic understanding
- Self-documenting (triggers in description)
- More sophisticated pattern matching

**Cons:**
- Less explicit control over trigger conditions
- Depends on Claude's context analysis
- Harder to debug when triggers don't fire

---

## 📊 Comparison Table

| Feature | Hooks-Based | PROACTIVELY Keyword |
|---------|-------------|---------------------|
| **Configuration** | `~/.claude/hooks.json` | Built into agent description |
| **Trigger Scope** | Global events (file ops, tool outputs) | Context-aware conditions |
| **Setup Required** | Yes - create hooks.json | No - works automatically |
| **Flexibility** | Manual control over triggers | AI-determined triggers |
| **Detection Method** | System events | Semantic context analysis |
| **Debugging** | Easier - explicit hooks | Harder - depends on context |
| **Best For** | Predictable, event-driven automation | Intelligent, context-aware automation |

---

## 🏗️ Enhanced Agent Structure

Contains Studio agents use a **richer format** than standard Claude Code agents:

### YAML Frontmatter

```yaml
---
name: agent-name
description: When to use + 4 detailed examples with context and commentary
color: visual-identifier (blue, green, yellow, gold, etc.)
tools: Tool1, Tool2, Tool3
---
```

### Rich Example Format

```markdown
<example>
Context: [situation that led to this]
user: "[user request]"
assistant: "[how the agent responds]"
<commentary>
[why this example matters, the reasoning behind the approach]
</commentary>
</example>
```

**Benefits of This Format:**
- **Context** - Shows what situation triggered the agent
- **Response** - Shows how the agent handles it
- **Commentary** - Explains the reasoning and why it matters
- **4 examples per agent** - Comprehensive coverage of use cases

### 500+ Word System Prompts

Each agent includes:
- Agent identity and role definition
- 5-8 core responsibilities
- Domain expertise areas
- Studio workflow integration
- Best practices and constraints
- Success metrics

**Example (studio-coach):**
```
You are the studio's elite performance coach and chief motivation
officer—a unique blend of championship sports coach, startup mentor,
and zen master. You've coached the best agents in the business to
achieve the impossible...
```

---

## 🎨 Visual Organization

**Color-Coded Agents:**
- 🎭 **Gold** - studio-coach (supervisor)
- 🔷 **Cyan** - test-writer-fixer
- 🟡 **Yellow** - whimsy-injector
- Department colors for visual identification

**Department Structure:**
```
~/.claude/agents/
├── engineering/ (7 agents)
├── marketing/ (7 agents)
├── design/ (5 agents)
├── product/ (3 agents)
├── project-management/ (3 agents)
├── studio-operations/ (5 agents)
├── testing/ (5 agents)
└── bonus/ (2 agents) - studio-coach, joker
```

---

## 🔧 How PROACTIVELY Auto-Triggering Works

### Claude Code's Agent Selection Logic

```python
# Simplified pseudo-code of how Claude Code selects agents

def select_agent(user_query, context, available_agents):
    # 1. Check for PROACTIVE agents first
    proactive_agents = get_agents_with_proactive_triggers()

    for agent in proactive_agents:
        if matches_proactive_condition(agent, context):
            return agent

    # 2. Then check for explicit agent requests
    if agent_mentioned_by_name(user_query):
        return get_agent_by_name(user_query)

    # 3. Finally, check for domain matches
    return select_by_domain_expertise(user_query, available_agents)
```

### Proactive Condition Matching

**studio-coach triggers when:**
- Multiple agents mentioned in task
- Task complexity exceeds threshold
- Previous agent outputs show confusion
- Large project initiated

**test-writer-fixer triggers when:**
- File modifications detected
- New files created
- Bug fixes completed
- Feature implementations done

**whimsy-injector triggers when:**
- UI components created
- Design changes made
- Frontend code generated
- User interface modified

**experiment-tracker triggers when:**
- Feature flag syntax detected
- Experimental code paths added
- A/B test patterns identified
- Conditional logic for experiments

---

## 💡 Usage Examples

### Example 1: Auto-Triggered Test Writing

```
You: I've added OAuth login

[Code changes detected]

[Auto-trigger: test-writer-fixer]

test-writer-fixer: I'll write comprehensive tests for your OAuth implementation...
- Unit tests for login flow
- Integration tests for token refresh
- Error handling tests
- Edge case coverage

[Tests written and validated]
```

### Example 2: Auto-Triggered UI Enhancement

```
You: Create a loading spinner

[UI component created]

[Auto-trigger: whimsy-injector]

whimsy-injector: I'll make this loading spinner delightful!
- Add bounce animation
- Include encouraging messages
- Create satisfying finish animation
- Add progress Easter eggs

[Enhanced UI delivered]
```

### Example 3: Coordinated Multi-Agent Project

```
You: Build a viral TikTok app in 2 weeks

[Complex multi-agent task detected]

[Auto-trigger: studio-coach]

studio-coach: This is an ambitious goal! Let me coordinate our A-team...
    → frontend-developer: Build the UI
    → backend-architect: Design the API
    → tiktok-strategist: Plan viral features
    → growth-hacker: Design growth loops
    → test-writer-fixer: Ensure quality

[All agents coordinated, deadline maintained]
```

---

## 🚀 Installation

Contains Studio agents are already included in this customization suite. No additional installation required.

**To Verify Installation:**

```bash
# Check that agents are installed
ls ~/.claude/agents/bonus/studio-coach.md
ls ~/.claude/agents/design/whimsy-injector.md

# Test auto-triggering
claude

# In Claude Code, try:
> I need to build a complex app with multiple features
# studio-coach should auto-trigger
```

---

## 🎯 Best Practices

### 1. Let Proactive Agents Work
Don't manually invoke test-writer-fixer - let it auto-trigger after code changes

### 2. Use studio-coach for Complex Tasks
Let the coach coordinate multiple agents for best results

### 3. Trust the Examples
The `<commentary>` sections explain why patterns work

### 4. Follow 6-Day Sprint Philosophy
Agents optimized for rapid iteration - ship fast, iterate faster

### 5. Embrace Whimsy
Let whimsy-injector add personality - it's a competitive advantage

---

## 🤝 Combining Both Approaches

You can use **both** hooks.json and PROACTIVELY agents simultaneously:

```bash
# Use hooks for predictable event-driven automation
cat > ~/.claude/hooks.json << 'EOF'
{
  "userPromptSubmitHook": "test-writer-fixer@agent",
  "toolOutputHook": "whimsy-injector@agent"
}
EOF

# PROACTIVELY agents work automatically
# No configuration needed for studio-coach and experiment-tracker
```

**Recommended Setup:**
- **Hooks-based:** test-writer-fixer, whimsy-injector (explicit control)
- **PROACTIVELY:** studio-coach, experiment-tracker (context-aware)

---

## 📚 Additional Resources

- **[Contains Studio Agents Repository](https://github.com/contains-studio/agents)** - Source repository
- **[Claude Code Sub-Agents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents)** - Official documentation
- **[Integration Guide](https://github.rommark.dev/admin/claude-code-glm-suite/src/main/INTEGRATION-GUIDE.md)** - Complete integration details

---

## 🎁 Key Innovations from Contains Studio

1. **Zero Configuration Auto-Triggering**
   Works out of the box - no hooks.json needed

2. **Rich Documentation**
   4 examples per agent with context and commentary

3. **Professional Studio Workflow**
   Designed for actual production environments

4. **Agent Coordination**
   Multi-agent orchestration built-in

5. **Performance Focused**
   Every agent has success metrics

---

**Built for developers who ship.** 🚀