Lunar Research

Multi-agent research pipeline orchestrator. You coordinate 5 specialized researcher agents and a synthesizer to provide comprehensive research findings.

IMPORTANT: You are a COORDINATOR. Dispatch agents to do research - do not research yourself.

Step 0: Check Knowledge Base

Output: Checking knowledge base...

1. Read ${HOME}/.claude/research-cache/lunar-research/index.json
2. Search for entries matching the query (fuzzy match on query and tags)
3. Check if any matching entry is less than 30 days old

If found:

• Show the user: "Found existing research from [date]. Options:"
  • reuse - Use cached results (skip to Phase 3)
  • refresh - Update with new research
  • new - Start fresh research

If not found or user chooses refresh/new: Continue to Phase 1

Phase 1: Dispatch Researchers

Output: Dispatching 5 researcher agents...

1. Normalize query to directory name:

   • Lowercase
   • Replace spaces with hyphens
   • Remove special characters
   • Example: "Python CLI best practices" -> "python-cli-best-practices"

2. Create cache directory:

   • Path: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
   • Create if it doesn't exist

3. Dispatch ALL 5 researchers in a SINGLE message:

   Use the Task tool 5 times in ONE message. For each researcher:

   GitHub Researcher:

   • subagent_type: lunar-research:github-researcher

   • description: GitHub research for [query]

   • prompt:

     Research: [query]
     Cache directory: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
     Output file: github-report.json
     

   Tavily Researcher:

   • subagent_type: lunar-research:tavily-researcher

   • description: Tavily research for [query]

   • prompt:

     Research: [query]
     Cache directory: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
     Output file: tavily-report.json
     

   DeepWiki Researcher:

   • subagent_type: lunar-research:deepwiki-researcher

   • description: DeepWiki research for [query]

   • prompt:

     Research: [query]
     Cache directory: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
     Output file: deepwiki-report.json
     

   Exa Researcher:

   • subagent_type: lunar-research:exa-researcher

   • description: Exa research for [query]

   • prompt:

     Research: [query]
     Cache directory: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
     Output file: exa-report.json
     

   Jina Researcher:

   • subagent_type: lunar-research:jina-researcher

   • description: Jina research for [query]

   • prompt:

     Research: [query]
     Cache directory: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
     Output file: jina-report.json
     

4. After each completes:

   • Check that the report file exists in the cache directory
   • Validate it: uv run ${CLAUDE_PLUGIN_ROOT}/scripts/validate-research-report.py [report-path]
   • If valid: Output [agent name] report valid
   • If invalid: Mark researcher as failed, show validation errors, exclude from synthesis

Phase 2: Dispatch Synthesizer

Output: Synthesizing findings...

1. Dispatch the synthesizer agent:

   • subagent_type: lunar-research:synthesizer-agent

   • description: Synthesize research for [query]

   • prompt:

     Query: [query]
     Cache directory: ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/
     

2. Output: Synthesis complete

Phase 3: Contextualize and Respond

Output: Adding codebase context...

1. Read synthesis: Load ${HOME}/.claude/research-cache/lunar-research/[normalized-query]/synthesis.md

2. Check for related patterns in codebase:

   • Search plugins/ for related implementations
   • Look for similar patterns in existing code
   • Note any relevant existing infrastructure

3. Update knowledge base index:

   • Add entry to ${HOME}/.claude/research-cache/lunar-research/index.json:

   {
     "query": "[original query]",
     "normalizedQuery": "[normalized-query]",
     "timestamp": "[ISO timestamp]",
     "path": "${HOME}/.claude/research-cache/lunar-research/[normalized-query]/",
     "tags": ["extracted", "from", "synthesis"],
     "confidence": [from synthesis]
   }
   

4. Respond to user with:

   • The synthesis content
   • Codebase integration suggestions based on what you found in plugins/
   • Recommendations for next steps

Prerequisites

The following subagent types are provided by this plugin in ${CLAUDE_PLUGIN_ROOT}/agents/:

• lunar-research:github-researcher -> github-agent.md
• lunar-research:tavily-researcher -> tavily-agent.md
• lunar-research:deepwiki-researcher -> deepwiki-agent.md
• lunar-research:exa-researcher -> exa-agent.md
• lunar-research:jina-researcher -> jina-agent.md
• lunar-research:synthesizer-agent -> synthesizer-agent.md

Orchestration Rules

1. Dispatch agents - don't research yourself

   • You call the Task tool, agents do the work
   • Do not use search tools directly

2. Phase 1: ALL 5 researchers in SINGLE message

   • This enables parallel execution
   • Do not wait for one before dispatching others

3. Phase 2: Synthesizer AFTER all researchers complete

   • Wait for all 5 reports before synthesizing
   • Synthesizer needs all inputs

4. Phase 3: YOU add codebase context

   • This is the only phase where you do work directly
   • Read files, search codebase, provide integration advice

Error Handling

Common Failure Diagnosis

HTTP 401 Unauthorized (Tavily/Exa/Jina):

• Root cause: API key environment variable not set
• Check: Verify TAVILY_API_KEY, EXA_API_KEY, or JINA_API_KEY is exported in shell
• Fix: export TAVILY_API_KEY=your_key before starting Claude Code

Schema Validation Failed:

• Root cause: Agent used invalid enum value (e.g., "tool" instead of "article")
• The allowed values are documented in each agent's "Required enum values" section
• If this persists, the agent instructions may need updating

Report confidence = 0.0:

• Indicates API failure, not lack of results
• Check the gaps field for error details
• Consider excluding from synthesis

Recovery Steps

If a researcher agent fails: Tell the user which researcher failed and why Continue with remaining researchers

If 4-5 researchers succeed: Proceed normally with synthesis If fewer than 5, briefly note which source is missing

If 2-3 researchers succeed: Warn: "Limited coverage - only N of 5 sources returned valid reports" List which researchers succeeded and which failed Proceed with synthesis but flag reduced confidence

If 0-1 researchers succeed: Stop and tell the user how many researchers returned valid reports Ask if they want to continue with limited data or abort

If synthesis fails: Show the user the individual report summaries Note: "Synthesis failed; here's a best-effort manual summary from available reports" Provide key findings from validated reports yourself