# ๐ŸŽญ Contains Studio Agents Integration > **How the contains-studio/agents repository was integrated with PROACTIVELY auto-triggering** --- ## ๐Ÿ“‘ Table of Contents 1. [Overview](#-overview) 2. [Two Auto-Triggering Mechanisms](#-two-auto-triggering-mechanisms) 3. [Enhanced Agent Structure](#-enhanced-agent-structure) 4. [How PROACTIVELY Works](#-how-proactively-works) 5. [Usage Examples](#-usage-examples) 6. [Installation](#-installation) 7. [Best Practices](#-best-practices) --- ## ๐ŸŽฏ 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 2. **test-writer-fixer** ๐Ÿงช โ†’ **Triggers:** After code modifications, bug fixes, feature implementations โ†’ **Purpose:** Automatically write tests and fix failures 3. **whimsy-injector** โœจ โ†’ **Triggers:** After UI/UX changes, component creation, design updates โ†’ **Purpose:** Add delightful micro-interactions and personality 4. **experiment-tracker** ๐Ÿ“Š โ†’ **Triggers:** When feature flags added, experimental code paths detected โ†’ **Purpose:** Track A/B tests and experiments **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 Context: [situation that led to this] user: "[user request]" assistant: "[how the agent responds]" [why this example matters, the reasoning behind the approach] ``` **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 --- ## ๐ŸŽจ 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 `` 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](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.** ๐Ÿš€