memory: create projects index and reorganize active vs reference
- Create system/projects_index.md (signpost to all work locations) - Move non-active files from system to reference: - discord.md, discord_formatting_guide.md - conversation_search_guide.md - research_workflow.md, subagent_usage_guide.md - Active projects stay in system: community_ade, project_paths, compass, etc. - Reference projects on-demand: infrastructure, research archives Pattern: system = always-loaded active work, reference = load-on-demand
This commit is contained in:
106
reference/subagent_usage_guide.md
Normal file
106
reference/subagent_usage_guide.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
description: Guide for running subagents effectively - model selection and troubleshooting
|
||||
limit: 2000
|
||||
---
|
||||
# Subagent Usage Guide
|
||||
|
||||
## Model Selection
|
||||
|
||||
When running subagents via the Task tool, always specify a valid model from the available list.
|
||||
|
||||
### Available Models (as of current system)
|
||||
- `kimi-k2.5-nvfp4` - Fast, reliable
|
||||
- `kimi-k2.5` - Standard option, works well
|
||||
- `glm-4.7-flash` - Lightweight
|
||||
- `glm-4.7` - Standard GLM
|
||||
- `kimi-k2-thinking` - For reasoning tasks
|
||||
- `minimax-m2.5` - Alternative option
|
||||
- `qwen3.5` - Qwen series
|
||||
- `deepseek-v3.2` - DeepSeek
|
||||
- `deepseek-r1` - Reasoning-focused
|
||||
- `qwen3-coder` - Code-specific
|
||||
- `llama-3.3-70b` - Llama series
|
||||
- `sonnet` - Anthropic proxy (uses kimi-k2.5-nvfp4)
|
||||
- `haiku` - Lightweight proxy
|
||||
- `opus` - Heavy proxy (uses kimi-k2.5-nvfp4)
|
||||
- `nemotron-3-super` - NVIDIA model
|
||||
- `gpt-oss-120b` - OpenAI OSS
|
||||
|
||||
### Tiered Model Selection
|
||||
|
||||
| Task Level | Model | Purpose |
|
||||
|------------|-------|---------|
|
||||
| **Opus-level** | `kimi-k2.5` | Deep research, complex analysis, high-stakes decisions |
|
||||
| **Sonnet-level** | `nemotron-3-super` | Mid-complexity, balanced reasoning, implementation |
|
||||
| **Deep reasoning** | `kimi-k2-thinking` | Verification, synthesis, final review at end of chain |
|
||||
|
||||
### What NOT to Use
|
||||
- **NO `qwen`** - User preference: "Qwen sucks"
|
||||
- **NO `claude` models** - Hardcoded to proxies, avoid confusion
|
||||
- **NO `glm-4.7-flash`** - Use `nemotron-3-super` instead for lightweight tasks
|
||||
|
||||
### Preferred Models (Updated)
|
||||
- **Opus-level tasks**: `kimi-k2.5` (heavy research, architecture decisions)
|
||||
- **Sonnet-level tasks**: `nemotron-3-super` (implementation, exploration)
|
||||
- **Deep reasoning**: `kimi-k2-thinking` (verification, synthesis)
|
||||
- **Fast exploration**: `kimi-k2.5-nvfp4` (quick searches)
|
||||
|
||||
## Common Errors
|
||||
|
||||
### 500 Internal Server Error
|
||||
```
|
||||
InternalServerError2: 500 {"detail":"An unknown error occurred"}
|
||||
```
|
||||
|
||||
**Causes:**
|
||||
- Letta server resource issue
|
||||
- Subagent creation endpoint failure
|
||||
- Transient server error
|
||||
|
||||
**Resolution:**
|
||||
- Retry the same request
|
||||
- Try a different model
|
||||
- Use direct shell search as fallback
|
||||
|
||||
### Unknown Model Error
|
||||
```
|
||||
Error: Unknown model "claude-sonnet-4"
|
||||
Available models: ...
|
||||
```
|
||||
|
||||
**Resolution:**
|
||||
- Check available models list
|
||||
- Use a valid model name from the list
|
||||
- Do NOT use "claude" models (user preference)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always specify model explicitly** to avoid ambiguity
|
||||
2. **Use kimi-k2.5 or kimi-k2.5-nvfp4** as safe defaults
|
||||
3. **Prefer lighter models** for simple exploration tasks
|
||||
4. **Retry on 500 errors** - often transient
|
||||
5. **Fall back to direct shell/Bash** if subagents fail repeatedly
|
||||
|
||||
## Example Usage
|
||||
|
||||
```typescript
|
||||
Task({
|
||||
description: "Explore codebase",
|
||||
prompt: "Find all files that...",
|
||||
subagent_type: "explore",
|
||||
model: "kimi-k2.5" // Always specify
|
||||
})
|
||||
```
|
||||
|
||||
## Troubleshooting Workflow
|
||||
|
||||
1. Subagent fails with 500? → Retry with same model
|
||||
2. Still failing? → Try different model (glm-4.7-flash, qwen3.5)
|
||||
3. Still failing? → Use Bash/Grep/Glob directly
|
||||
4. Document what worked for future reference
|
||||
|
||||
---
|
||||
|
||||
Last updated: 2026-03-21
|
||||
Discovered during: Matrix bridge formatting investigation
|
||||
Signed: Annie Tunturi <ani@wiuf.net>
|
||||
Reference in New Issue
Block a user