research-agents

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.