hauggseb/DnD-Kampagne
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Sebastian
2026-08-29 15:41:29 +02:00
commit e2903b96dc
3828 changed files with 188535 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.opencode/MULTI_MODEL_SETUP.md
+552
View File
@@ -0,0 +1,552 @@
# Multi-Model DnD Agent System - Complete Setup
This document describes the **complete multi-model agent orchestration system** for your DnD campaign vault, optimized for cost-effectiveness and specialized capabilities.
## 🎯 System Architecture
The system implements a **three-tier architecture** with clear role separation:
```
┌─────────────────────────────────────────────────────────────────────┐
│ TIER 1: ORCHESTRATOR │
│ (Mistral Medium - 2604) │
│ ┌─────────────────────────────────────────────────────────────────┐│
│ │ • Analyzes user requests in campaign context ││
│ │ • Delegates concrete steps to Tier 2 workers ││
│ │ • Requests creative ideas from Tier 3 (single API call) ││
│ │ • Synthesizes results and presents to user ││
│ │ • Coordinates all multi-agent workflows ││
│ └─────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ TIER 2: WORKERS │ │ TIER 2: WORKERS │ │ TIER 2: WORKERS │
│ (Mistral Small - 2604) │ │ (Mistral Small - 2604) │ │ (Mistral Small - 2604) │
│ • Session Prep Worker │ │ • Implementer Worker │ │ • Generator Worker │
│ • Analyzes sessions │ │ • Extracts entities │ │ • Creates content │
│ • Reviews story arcs │ │ • Creates files │ │ • Applies templates │
│ • Generates prep docs │ │ • Links content │ │ • Links to existing │
└─────────────────────────┘ └─────────────────────┘ └─────────────────────┘
│
┌───────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────┐
│ TIER 3: CREATIVE │
│ (Claude Opus - 4.5) │
│ ┌─────────────────────────────────────────────────────────────────┐│
│ │ • Generates creative ideas ONLY ││
│ │ • Single API call per request (cost optimization) ││
│ │ • Minimal context provided (token optimization) ││
│ │ • Returns concise concepts only (no explanation) ││
│ │ • ZERO tool access (security isolation) ││
│ └─────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘
```
## 📊 Cost Optimization Strategy
| Model | Usage | Cost Level | Purpose |
|-------|-------|------------|---------|
| Mistral Medium | Orchestrator (1 instance) | Medium | Coordination, reasoning, synthesis |
| Mistral Small | Workers (4 instances) | Low | All concrete execution |
| Claude Opus | Creative (1 instance) | High | Creative ideas only |
**Estimated Savings**: ~70-80% compared to using Claude Opus for everything
**Token Usage Pattern**:
- 60%: Mistral Small (workers doing the heavy lifting)
- 25%: Mistral Medium (orchestrator coordinating)
- 15%: Claude Opus (creative ideas only when needed)
---
## 🤖 Agent Specifications
### Tier 1: Orchestrator
**Agent**: `dnd-orchestrator`
- **Model**: `mistral/mistral-medium-2604`
- **Mode**: `primary`
- **Temperature**: 0.3 (balanced reasoning)
- **Color**: Brown (#8B4513)
- **File**: `.opencode/agents/dnd-orchestrator.md`
**Capabilities**:
- ✅ Full tool access (read, write, glob, grep, edit, bash)
- ✅ Full skill access (all dnd-*)
- ✅ Can delegate to all worker agents (`dnd-worker-*`)
- ✅ Can request from creative agent (`dnd-creative`) with confirmation
- ✅ Can use question tool for user input
- ❌ Cannot access external resources (webfetch denied)
**Responsibilities**:
1. Understand user requests in full campaign context
2. Break down complex tasks into delegatable steps
3. Request creative ideas from creative agent when needed
4. Implement creative ideas using worker agents
5. Synthesize all results and present to user
6. Ensure campaign consistency across all work
---
### Tier 2: Worker Agents
All workers use `mistral/mistral-small-2604` for cost-effective execution.
#### 1. dnd-worker-session-prep
- **Temperature**: 0.2 (very focused)
- **Color**: Green (#228B22)
- **File**: `.opencode/agents/dnd-worker-session-prep.md`
**Handles**:
- Analyzing session notes and extracting key information
- Reviewing active story arcs and identifying threads
- Checking NPC and location statuses
- Generating session prep document sections
- Creating preparation checklists
**Permissions**:
- ✅ Full tool access (read, write, glob, grep, edit, bash)
- ✅ Full skill access (all dnd-*)
- ❌ CANNOT delegate to other agents (task: deny)
- ❌ CANNOT access external resources
---
#### 2. dnd-worker-implementer
- **Temperature**: 0.2 (very focused)
- **Color**: Green (#228B22)
- **File**: `.opencode/agents/dnd-worker-implementer.md`
**Handles**:
- Parsing session notes for entities and events
- Extracting NPCs, locations, items, organizations
- Creating new content files from extracted information
- Linking content with wiki links
- Moving files between directories
- Validating content structure
**Permissions**: Same as session-prep worker
---
#### 3. dnd-worker-generator
- **Temperature**: 0.3 (slightly creative)
- **Color**: Green (#228B22)
- **File**: `.opencode/agents/dnd-worker-generator.md`
**Handles**:
- Creating new locations with detailed descriptions
- Creating new NPCs with full profiles
- Creating new quests and story arcs
- Creating new items and equipment
- Applying templates and metadata
- Linking new content to existing vault elements
**Permissions**: Same as other workers
---
#### 4. dnd-worker-organizer
- **Temperature**: 0.1 (very focused)
- **Color**: Green (#228B22)
- **File**: `.opencode/agents/dnd-worker-organizer.md`
**Handles**:
- Validating vault structure against standards
- Checking and repairing wiki links
- Identifying duplicate content
- Finding orphaned files
- Cleaning up Inbox directory
- Generating vault health reports
**Permissions**: Same as other workers
---
### Tier 3: Creative Agent
**Agent**: `dnd-creative`
- **Model**: `anthropic/claude-opus-4.5`
- **Mode**: `subagent`
- **Temperature**: 1.0 (maximum creativity)
- **Color**: Purple (#9370DB)
- **File**: `.opencode/agents/dnd-creative.md`
**Capabilities**:
- ✅ Generate creative DnD concepts
- ✅ Return concise ideas (single sentences)
- ✅ Single API call per request
- ❌ CANNOT access ANY tools (all permissions: deny)
- ❌ CANNOT use any skills (skill: deny)
- ❌ CANNOT delegate to other agents (task: deny)
- ❌ CANNOT ask questions (question: deny)
- ❌ CANNOT fetch external resources (webfetch: deny)
**Responsibilities**:
1. Generate creative ideas when requested by orchestrator
2. Provide ONLY the ideas (no explanation, no implementation)
3. Use minimal context (orchestrator provides brief context)
4. Respond in ONE message (single API call)
5. Return ideas in German language
**Response Format**:
```
Idea 1 as a single concise sentence.
Idea 2 as a single concise sentence.
Idea 3 as a single concise sentence.
```
---
## 🔄 Workflow Examples
### Example 1: Session Preparation
**User Request**: "Prepare materials for next session"
**Workflow**:
```
1. User → dnd-orchestrator (Medium)
"Prepare materials for next session"
2. dnd-orchestrator analyzes campaign state
- Reads last session notes
- Reviews active story arcs
- Checks current campaign status
3. dnd-orchestrator delegates to workers (Small):
@dnd-worker-session-prep "Analyze Session 15 and identify unresolved plot hooks"
@dnd-worker-session-prep "Review active quests and their status"
4. dnd-orchestrator requests creative input (Opus):
@dnd-creative "Generate 3 creative session hook ideas for campaign with stolen amulet"
→ Returns: 3 single-sentence ideas
5. dnd-orchestrator implements best idea using workers (Small):
@dnd-worker-generator "Create session prep document with selected hook"
6. dnd-orchestrator synthesizes all results
→ Presents comprehensive session prep to user
```
**Token Usage**:
- Medium: ~500 tokens (orchestration)
- Small: ~2000 tokens (worker execution)
- Opus: ~50 tokens (creative ideas)
- **Total**: ~2550 tokens (optimized)
---
### Example 2: Story Implementation
**User Request**: "Process session notes from Session 15"
**Workflow**:
```
1. User → dnd-orchestrator (Medium)
"Process session notes from 01-Sessions/Session 15 - Title.md"
2. dnd-orchestrator reads session notes
3. dnd-orchestrator delegates to workers (Small):
@dnd-worker-implementer "Extract all NPCs and create/update files"
@dnd-worker-implementer "Extract all locations and create/update files"
@dnd-worker-implementer "Extract quest progress and update arc files"
@dnd-worker-implementer "Link all new content with wiki links"
4. dnd-orchestrator verifies all work
5. dnd-orchestrator presents results to user
```
**Token Usage**:
- Medium: ~300 tokens (orchestration)
- Small: ~3000 tokens (worker execution)
- Opus: 0 tokens (no creative needed)
- **Total**: ~3300 tokens
---
### Example 3: Content Creation
**User Request**: "Create a new city for the Sword Coast"
**Workflow**:
```
1. User → dnd-orchestrator (Medium)
"Create a new city for the Sword Coast region"
2. dnd-orchestrator analyzes existing Sword Coast content
3. dnd-orchestrator requests creative input (Opus):
@dnd-creative "Generate 3 unique city concepts for Sword Coast region"
→ Returns: 3 single-sentence concepts
4. User selects: "Eldrin, a port city with hidden Underdark entrance"
5. dnd-orchestrator delegates to workers (Small):
@dnd-worker-generator "Create detailed city file for Eldrin"
@dnd-worker-generator "Generate 3 relevant NPCs for Eldrin"
@dnd-worker-generator "Create 2 quest hooks connected to Eldrin"
@dnd-worker-implementer "Link all new content together"
6. dnd-orchestrator verifies consistency
7. dnd-orchestrator presents results to user
```
**Token Usage**:
- Medium: ~400 tokens (orchestration)
- Small: ~2500 tokens (worker execution)
- Opus: ~30 tokens (creative ideas)
- **Total**: ~2930 tokens
---
## 📋 Configuration Files
### 1. opencode.json
Main configuration file with all agent definitions:
```json
{
"agent": {
"dnd-orchestrator": {
"model": "mistral/mistral-medium-2604",
"mode": "primary",
"temperature": 0.3,
"task": {
"dnd-worker-*": "allow",
"dnd-creative": "ask"
}
},
"dnd-worker-*": {
"model": "mistral/mistral-small-2604",
"mode": "subagent",
"task": "deny"
},
"dnd-creative": {
"model": "anthropic/claude-opus-4.5",
"mode": "subagent",
"permission": {
"read": "deny",
"write": "deny",
"task": "deny",
"skill": "deny"
}
}
}
}
```
### 2. Agent Definition Files
Each agent has a markdown file in `.opencode/agents/`:
- `dnd-orchestrator.md` - Primary coordinator
- `dnd-worker-session-prep.md` - Session preparation worker
- `dnd-worker-implementer.md` - Story implementation worker
- `dnd-worker-generator.md` - Content generation worker
- `dnd-worker-organizer.md` - Vault organization worker
- `dnd-creative.md` - Creative ideas agent
---
## 🚀 Usage Instructions
### Starting a Session
1. **Load the orchestrator**:
```
@dnd-orchestrator [your request]
```
2. **Let it coordinate**: The orchestrator will:
- Analyze your request
- Delegate to appropriate workers
- Request creative ideas if needed
- Synthesize and present results
### Direct Agent Invocation
You can also invoke agents directly:
```
# For session preparation
@dnd-worker-session-prep Analyze Session 15 and identify plot hooks
# For story implementation
@dnd-worker-implementer Extract NPCs from Session 15 notes
# For content generation
@dnd-worker-generator Create a new NPC file for Veylin
# For vault organization
@dnd-worker-organizer Validate all wiki links in 01-Sessions/
# For creative ideas (orchestrator will usually handle this)
@dnd-creative Generate 3 quest ideas for the Cult of the Eclipse
```
---
## 🛡️ Security & Safety Features
### Creative Agent Isolation
- **Zero tool access**: Cannot read, write, or modify any files
- **Zero skill access**: Cannot use any skills or templates
- **Zero delegation**: Cannot invoke other agents
- **Pure generation**: Only provides creative ideas, never implements
### Worker Agent Restrictions
- **No delegation**: Workers cannot invoke other agents
- **Controlled access**: Only have permissions they need
- **Focused scope**: Each worker has specific, limited responsibilities
### Orchestrator Control
- **Single point of coordination**: Only orchestrator can manage multi-agent workflows
- **Permission boundaries**: Orchestrator has full access but follows delegation rules
- **User confirmation**: Creative agent requests require confirmation
---
## 📊 Performance Metrics
### Response Times
| Agent | Typical Response Time | Complexity |
|-------|----------------------|------------|
| Orchestrator | 5-10 seconds | High |
| Workers | 2-5 seconds | Medium |
| Creative | 3-8 seconds | Low (simple generation) |
### Cost Comparison
| Approach | Estimated Cost | Quality |
|----------|---------------|---------|
| All Opus | $$$$$ | ⭐⭐⭐⭐⭐ |
| All Medium | $$$ | ⭐⭐⭐⭐ |
| **This System** | **$$** | **⭐⭐⭐⭐⭐** |
| All Small | $ | ⭐⭐ |
---
## 🎯 Best Practices
### For Users
1. **Start with orchestrator** for complex tasks
2. **Provide clear context** for better results
3. **Review creative options** before selection
4. **Trust the delegation** - workers are optimized for their tasks
5. **Use direct invocation** for simple, focused tasks
### For Orchestrator
1. **Analyze first** - Understand the full context
2. **Delegate appropriately** - Use the right worker for each task
3. **Minimize creative context** - Give creative agent only what it needs
4. **Verify all work** - Check worker results before presenting
5. **Synthesize clearly** - Present organized, ready-to-use results
### For Workers
1. **Follow instructions exactly** - Do only what you're asked
2. **Use templates** - Apply appropriate skill templates
3. **Link everything** - Always use wiki links for references
4. **Validate work** - Check your results before returning
5. **Be concise** - Return only what was requested
### For Creative Agent
1. **Ideas only** - Never explain or implement
2. **Single sentences** - Each idea as one concise sentence
3. **One message** - Respond in a single API call
4. **German language** - All ideas in German
5. **No questions** - Never ask for clarification
---
## 🔧 Setup Requirements
### Model Access
You need access to these models:
- **Mistral Medium 2604** (for orchestrator)
- **Mistral Small 2604** (for all workers)
- **Claude Opus 4.5** (for creative ideas)
### Configuration
1. Set up provider credentials in OpenCode
2. Verify models are available: `/models`
3. Test each agent individually
4. Start with simple tasks to verify workflow
### MCP Servers (Optional but Recommended)
Configure these verified MCP servers for enhanced capabilities:
- `dnd-5e-mcp` - DnD 5e content via Open5e API
- `obsidian-mcp` - Direct vault access
- `gamemaster-mcp` - Campaign management
---
## 📁 File Structure
```
.opencode/
├── agents/ # Agent definitions
│ ├── dnd-orchestrator.md # Primary coordinator (Medium)
│ ├── dnd-worker-session-prep.md # Session prep worker (Small)
│ ├── dnd-worker-implementer.md # Implementation worker (Small)
│ ├── dnd-worker-generator.md # Content generation worker (Small)
│ ├── dnd-worker-organizer.md # Vault organization worker (Small)
│ ├── dnd-creative.md # Creative ideas agent (Opus)
│ └── README.md # Agent documentation
│
├── skills/ # Skill definitions (unchanged)
│ ├── dnd-session-manager/
│ ├── dnd-npc-creator/
│ ├── dnd-location-builder/
│ ├── ...
│ └── README.md
│
├── opencode.json # Main configuration
└── MULTI_MODEL_SETUP.md # This file
```
---
## 🆘 Troubleshooting
### Orchestrator Issues
- **Not delegating**: Check task permissions in opencode.json
- **Not synthesizing**: Verify worker responses are being received
- **Creative not responding**: Check that creative agent is not disabled
### Worker Issues
- **Permission denied**: Check agent permissions in opencode.json
- **Not executing**: Verify worker has required tool access
- **Delegating**: Workers should NOT delegate - check configuration
### Creative Agent Issues
- **Explaining ideas**: Remind agent to return ONLY ideas
- **Multiple messages**: Check temperature and instructions
- **Not creative**: Verify model is Claude Opus 4.5
---
## 📚 Additional Documentation
- **Agent Details**: `.opencode/agents/README.md` - Comprehensive agent documentation
- **Skills**: `.opencode/skills/README.md` - Skill definitions and usage
- **OpenCode Docs**: [opencode.ai/docs/agents/](https://opencode.ai/docs/agents/) - Official agent documentation
---
## 🎉 Summary
This **multi-model agent system** provides:
✅ **Optimal cost-effectiveness** - Uses cheaper models for most work
✅ **Specialized capabilities** - Each agent optimized for its role
✅ **Clear separation of concerns** - Orchestrator coordinates, workers execute, creative inspires
✅ **Security isolation** - Creative agent has zero access to tools/files
✅ **Scalable architecture** - Easy to add more workers or agents
✅ **Campaign-optimized** - Designed specifically for DnD vault management
**Result**: High-quality DnD campaign management at a fraction of the cost of using premium models for everything.