DnD-Kampagne/.opencode/MULTI_MODEL_SETUP.md

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:

{
  "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/ - 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.