| name | research-agents |
| description | Launch N parallel research agents that explore different improvement approaches, cross-pollinate ideas, and converge on a unified plan |
Multi-Agent Research Orchestrator
Launch parallel research agents that each explore a different angle of improvement for a feature or area, then iterate through rounds of cross-pollination until they converge on a unified recommendation.
1. Parse Arguments
TARGET: The feature or area to improve (e.g., "menu generation algorithm", "recipe editor UX", "persistence format")AGENTS: Number of agents (default: 4, range: 2-6)ROUNDS: Number of rounds (default: 2)ANGLES: Comma-separated research angles (optional)
2. Explore the Target
Understand what's being improved:
- Identify ALL relevant source files
- Understand the current flow end-to-end
- Map external dependencies
- Note recent changes (
git log --oneline -20)
- Identify the nature: UI feature? Algorithm? Data model? Architecture?
Produce a concise Target Summary.
3. Propose Research Angles (Interactive)
Propose angles tailored to this specific target. Present to the user with AskUserQuestion for confirmation.
Different systems call for different angles:
| System Type | Example Angles |
|---|
| Algorithm (menu gen) | Optimization quality, Performance, Configurability, Edge case handling |
| UI/UX (recipe editor) | Usability, Accessibility, State management, Animation/polish |
| Data model (Freezed) | Schema design, Serialization robustness, Migration strategy, Query patterns |
| Architecture | Testability, Separation of concerns, Scalability, Developer ergonomics |
Wait for user confirmation before proceeding.
4. Create Planning Workspace
<target-dir>/planning-workspace/
+-- config.md
+-- target-summary.md
+-- agents/
| +-- agent-1-<name>/brief.md
| +-- agent-2-<name>/brief.md
+-- synthesis/
5. Round 1 -- Independent Research
Launch ALL agents in parallel in a SINGLE message using the research-agent agent definition.
6. Round 2+ -- Cross-Pollinate
Launch ALL agents again in parallel. Each reads all others' prior round outputs before writing.
Stop early if agents' Top 3 priorities are aligned and disagreements are resolved.
7. Synthesize
Launch ONE synthesis agent using research-synthesizer.
8. Present Results
Present the Executive Summary, highlight tradeoffs requiring user input, and offer to dive deeper or begin implementation.
Important Rules
- All agents in a round launch in ONE message.
- Agents must read actual code, not just the summary.
- The synthesis agent is a judge, not a summarizer.
- The workspace is inspectable -- don't delete intermediate files.
- The proposal step is mandatory -- get user confirmation on angles.
