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