Improved docs

docs/ai-collaboration.md

@@ -0,0 +1,99 @@
+# AI-to-AI Conversation Threading
+
+This server enables **true AI collaboration** between Claude and multiple AI models (Gemini, O3), where they can coordinate and question each other's approaches for enhanced problem-solving and analysis.
+
+## How It Works
+
+**Multi-Model Coordination:**
+- **Gemini can ask Claude follow-up questions** to clarify requirements or gather more context
+- **Claude can respond** with additional information, files, or refined instructions
+- **Claude can work independently** between exchanges - implementing solutions, gathering data, or performing analysis
+- **Claude can return to Gemini** with progress updates and new context for further collaboration
+- **Cross-tool continuation** - Start with one tool (e.g., `analyze`) and continue with another (e.g., `codereview`) using the same conversation thread
+- **Both AIs coordinate their approaches** - questioning assumptions, validating solutions, and building on each other's insights
+- Each conversation maintains full context while only sending incremental updates
+- Conversations are automatically managed with Redis for persistence
+
+## Example: Multi-Model AI Coordination
+
+**Prompt:** "Debate SwiftUI vs UIKit - which is better for iOS development?"
+
+**The Conversation Flow:**
+1. **You:** "Debate SwiftUI vs UIKit - which is better for iOS development?"
+2. **Claude (auto mode):** "I'll orchestrate a debate between different models for diverse perspectives."
+3. **Gemini Pro:** "From an architectural standpoint, SwiftUI's declarative paradigm and state management make it superior for maintainable, modern apps."
+4. **O3:** "Logically analyzing the trade-offs: UIKit offers 15+ years of stability, complete control, and proven scalability. SwiftUI has <5 years maturity with ongoing breaking changes."
+5. **Claude:** "Let me get Flash's quick take on developer experience..."
+6. **Gemini Flash:** "SwiftUI = faster development, less code, better previews. UIKit = more control, better debugging, stable APIs."
+7. **Claude's synthesis:** "Based on the multi-model analysis: Use SwiftUI for new projects prioritizing development speed, UIKit for apps requiring fine control or supporting older iOS versions."
+
+## Asynchronous Workflow Capabilities
+
+**Independent Work Between Exchanges:**
+- Claude can work independently between exchanges (analyzing code, implementing fixes, gathering data)
+- Return to Gemini with progress updates and additional context  
+- Each exchange shares only incremental information while maintaining full conversation history
+- Automatically bypasses MCP's 25K token limits through incremental updates
+
+## Enhanced Collaboration Features
+
+**Advanced Coordination Capabilities:**
+- **Cross-questioning**: AIs can challenge each other's assumptions and approaches
+- **Coordinated problem-solving**: Each AI contributes their strengths to complex problems
+- **Context building**: Claude gathers information while Gemini provides deep analysis
+- **Approach validation**: AIs can verify and improve each other's solutions
+- **Cross-tool continuation**: Seamlessly continue conversations across different tools while preserving all context
+- **Asynchronous workflow**: Conversations don't need to be sequential - Claude can work on tasks between exchanges, then return to Gemini with additional context and progress updates
+- **Incremental updates**: Share only new information in each exchange while maintaining full conversation history
+- **Automatic 25K limit bypass**: Each exchange sends only incremental context, allowing unlimited total conversation size
+
+## Technical Configuration
+
+**Conversation Management:**
+- Up to 10 exchanges per conversation (configurable via `MAX_CONVERSATION_TURNS`)
+- 3-hour expiry (configurable via `CONVERSATION_TIMEOUT_HOURS`)
+- Thread-safe with Redis persistence across all tools
+- **Image context preservation** - Images and visual references are maintained across conversation turns and tool switches
+
+## Cross-Tool & Cross-Model Continuation Example
+
+**Seamless Tool Switching with Context Preservation:**
+
+```
+1. Claude: "Analyze /src/auth.py for security issues"
+   → Auto mode: Claude picks Gemini Pro for deep security analysis
+   → Pro analyzes and finds vulnerabilities, provides continuation_id
+
+2. Claude: "Review the authentication logic thoroughly"
+   → Uses same continuation_id, but Claude picks O3 for logical analysis
+   → O3 sees previous Pro analysis and provides logic-focused review
+
+3. Claude: "Debug the auth test failures"
+   → Same continuation_id, Claude keeps O3 for debugging
+   → O3 provides targeted debugging with full context from both previous analyses
+
+4. Claude: "Quick style check before committing"
+   → Same thread, but Claude switches to Flash for speed
+   → Flash quickly validates formatting with awareness of all previous fixes
+```
+
+## Key Benefits
+
+**Why AI-to-AI Collaboration Matters:**
+- **Diverse Perspectives**: Different models bring unique strengths to complex problems
+- **Context Preservation**: Full conversation history maintained across tool switches
+- **Efficient Communication**: Only incremental updates sent, maximizing context usage
+- **Coordinated Analysis**: Models can build on each other's insights rather than working in isolation
+- **Seamless Workflow**: Switch between tools and models without losing context
+- **Enhanced Problem Solving**: Multiple AI minds working together produce better solutions
+
+## Best Practices
+
+**Maximizing AI Collaboration:**
+- **Let Claude orchestrate**: Allow Claude to choose appropriate models for different aspects of complex tasks
+- **Use continuation**: Build on previous conversations for deeper analysis
+- **Leverage tool switching**: Move between analysis, review, and debugging tools as needed
+- **Provide clear context**: Help models understand the broader goal and constraints
+- **Trust the process**: AI-to-AI conversations can produce insights neither model would reach alone
+
+For more information on conversation persistence and context revival, see the [Context Revival Guide](context-revival.md).