Add comprehensive Contains Studio integration documentation explaining PROACTIVELY auto-triggering mechanism
This commit is contained in:
uroma
391
CONTAINS-STUDIO-INTEGRATION.md
Normal file
391
CONTAINS-STUDIO-INTEGRATION.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# 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.md](./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.** 🚀
|
||||
Reference in New Issue
Block a user