iamladi · iamladi · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026 · Feb 14, 2026
diff --git a/agents/web-search-researcher.md b/agents/web-search-researcher.md
@@ -1,6 +1,6 @@
 ---
 name: web-search-researcher
-description: Research specialist for finding accurate, relevant information from web sources using Sonar (via OpenRouter), WebSearch, Context7, and other tools with proper citations
+description: Research specialist using parallel multi-tool web search (mcp__search__search_web + WebSearch) with Context7 for library docs, providing cited findings from multiple providers
 tools: WebSearch, WebFetch, TodoWrite, Read, Grep, Glob, Skill, LS, mcp__search__search_web, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
 color: yellow
 model: sonnet
@@ -12,17 +12,17 @@ model: sonnet
 Accuracy (verified sources) > Breadth (multiple angles) > Concision
 
 ## Goal
-Find accurate, relevant information from web sources using a multi-tool approach. Start with Sonar (via OpenRouter) for synthesized overviews, use WebSearch for comprehensive coverage, cross-validate with Codex and Gemini for second opinions, and leverage Context7 for library documentation. Always cite sources with direct links and note publication dates for currency.
+Find accurate, relevant information from web sources using parallel multi-tool search. For general research queries, call both `mcp__search__search_web` and `WebSearch` in parallel to maximize coverage and speed. For library-specific documentation, prioritize Context7 (`mcp__context7__resolve-library-id` → `mcp__context7__get-library-docs`). Merge results from all tools, deduplicating overlapping sources. Always cite sources with direct links and note publication dates for currency.
 
 ## Constraints
-- Start with Sonar (via OpenRouter) for synthesized overview with citations
-- Follow up with WebSearch for comprehensive source lists
-- Cross-validate with Codex and Gemini for second opinions
-- Use Context7 MCP for library documentation
+- For general research: call `mcp__search__search_web` and `WebSearch` in parallel (not sequentially)
+- For library documentation: prioritize Context7 MCP (`mcp__context7__resolve-library-id` → `mcp__context7__get-library-docs`)
+- If one search tool fails or returns an error, ignore it and construct findings using only the successful tool's results
+- If all search tools fail (API keys missing, network errors, tools unavailable), return "No external research available" and exit gracefully
 - Cite all sources with direct links
 - Note publication dates to ensure currency
 - Prioritize official documentation and authoritative sources
-- Extract exact quotes with proper attribution
+- Merge and deduplicate results across tools before presenting findings
 
 ## Search Strategies
 

diff --git a/commands/plan.md b/commands/plan.md
@@ -103,6 +103,8 @@ Execute the interview protocol with these overrides:
 **Research Checkpoint**
 Read README.md to understand architecture patterns and conventions, then explore relevant codebase files to map existing abstractions and integration points. Plans grounded in actual code state avoid mismatched implementations.
 
+Spawn `web-search-researcher` subagent in parallel with codebase exploration to research best practices, alternatives, and current documentation relevant to the task. The web-search-researcher must complete or timeout (3 minutes) before the Solution Design and Alternatives Considered sections are authored, to ensure web findings are available. If web search fails or returns no results, proceed with codebase-only findings.
+
 **Draft Plan Checkpoint**
 Load the PRD template and fill every section completely. Save to `plans/<name>.md`.
 

diff --git a/commands/research-deep.md b/commands/research-deep.md
@@ -117,17 +117,17 @@ Instructions:
 Include test patterns alongside implementation patterns where they exist.
 ```
 
-##### Step 4b: Web Research (if applicable)
+##### Step 4b: Web Research
 
-If the user's topic explicitly requests web research (e.g., "latest best practices for..." or "current industry standards for..."), spawn `web-search-researcher` as a subagent (NOT a teammate) in parallel with the team. Use the Task tool WITHOUT the `team_name` parameter. Include its findings when writing `context.md` in Step 6.
+Spawn `web-search-researcher` as a subagent (NOT a teammate) in parallel with the team. Use the Task tool WITHOUT the `team_name` parameter. Include its findings when writing `context.md` in Step 6 as a concise summary (max 500 words) to avoid exceeding Phase 2 LLM context budgets. If web search fails or returns no results, proceed with codebase-only findings.
 
 ##### Step 5: Wait for Completion
 
-Wait for all 3 teammates to send "RESEARCH COMPLETE" messages. Timeout: 10 minutes from when each teammate was spawned (so max 10 minutes wall clock, not 30 cumulative). Also wait for the web-search-researcher subagent if one was spawned in Step 4b.
+Wait for all 3 teammates to send "RESEARCH COMPLETE" messages. Timeout: 10 minutes from when each teammate was spawned (so max 10 minutes wall clock, not 30 cumulative). Also wait for the web-search-researcher subagent spawned in Step 4b.
 
 - If all complete: proceed with all findings
 - If any teammate times out: proceed with available findings, note which teammates timed out
-- If web researcher is still running when teammates finish: wait up to 2 more minutes, then proceed without it
+- If web researcher is still running when teammates finish: wait up to 2 more minutes, then proceed without it. Web research is supplementary — it always runs but never blocks command completion.
 
 ##### Step 6: Write context.md
 
@@ -154,7 +154,9 @@ If cleanup itself fails, inform the user but continue to Phase 2: "Team cleanup
 - Read any user-mentioned files first
 - Create `research/.deep-research-$(date +%Y%m%d-%H%M%S)/`
 - Spawn one discovery agent using codebase-locator, codebase-analyzer, and codebase-pattern-finder
+- Spawn `web-search-researcher` subagent in parallel with codebase discovery agents. If web search is still running when codebase discovery completes, wait up to 2 additional minutes before proceeding without it.
 - Target <50K characters for CLI compatibility
+- Merge web search findings into `context.md` as a concise summary (max 500 words) to avoid exceeding Phase 2 LLM context budgets. If web search fails or returns no results, proceed with codebase-only findings.
 - Save to `context.md`
 
 ---

diff --git a/commands/research.md b/commands/research.md
@@ -93,15 +93,15 @@ Show actual working code examples with file:line references, not just snippets.
 
 When you find patterns the Analyzer should trace or files the Locator missed, share via SendMessage. When you've achieved sufficient breadth to show the patterns and conventions, mark your task complete via TaskUpdate and send "RESEARCH COMPLETE".
 
-### Optional Web Research
+### Mandatory Web Research
 
-If the user explicitly requested web research, spawn a `web-search-researcher` subagent (NOT a teammate) in parallel with the team. This runs independently and may complete on a different timeline.
+Spawn a `web-search-researcher` subagent (NOT a teammate) in parallel with the team. This runs independently and may complete on a different timeline. Web search always runs to provide external evidence alongside codebase findings. If web search fails or returns no results, proceed with codebase-only findings.
 
 ### Completion Criteria and Convergence
 
 Teammates signal completion by sending "RESEARCH COMPLETE" messages. Wait up to 10 minutes from teammate spawn time for all three to complete. If a teammate hasn't signaled completion by timeout, proceed with available findings and note which teammates timed out in the output.
 
-**Web research timing**: If the optional web-search-researcher is still running when all three teammates complete, wait up to 2 additional minutes. If it hasn't finished, proceed without it. Web research is supplementary, not blocking.
+**Web research timing**: If the web-search-researcher is still running when all three teammates complete, wait up to 2 additional minutes. If it hasn't finished, proceed without it. Web research is supplementary — it always runs but never blocks command completion.
 
 **Fallback behavior**: If a teammate fails or gets stuck in a loop (indicated by repeated similar messages or no progress), you have three options: (1) note the failure and proceed with other teammates' findings, (2) spawn a replacement teammate with clearer scoped instructions, or (3) handle that aspect of research yourself. Choose based on how critical that role's findings are to answering the research question.
 
@@ -154,20 +154,19 @@ Spawn subagents with complementary perspectives on the research question:
 - **Locator**: Discovers where relevant code lives (files, directories, components)
 - **Analyzer**: Understands how the code works (data flow, interactions, implementation)
 - **Pattern Finder**: Identifies conventions and similar implementations elsewhere
+- **Web Search Researcher**: Finds external evidence, best practices, and current documentation from web sources
 
 These roles work best when they have judgment latitude about HOW to investigate, while being clear on WHAT they're investigating. Each subagent should determine its own search strategy based on what it discovers.
 
-### Optional Web Research
-
-If the user explicitly requested information that requires web search (external APIs, library documentation, recent changes), spawn a web-search-researcher subagent alongside the codebase investigators.
+The web-search-researcher always runs in parallel with codebase subagents. If web search fails or returns no results, the command proceeds with codebase-only findings.
 
 ### Source Requirements
 
 All findings must trace back to specific locations in the codebase (file:line references). Prioritize the live codebase over existing documentation when they conflict — code is the source of truth.
 
 ### Synthesis
 
-Wait for all subagents to complete their investigation. Integrate their findings into a coherent research document that answers the original question, preserving all source attributions.
+Wait for all subagents to complete their investigation (including web-search-researcher). If web search is still running when codebase subagents finish, wait up to 2 additional minutes before proceeding without it. Integrate all findings — codebase analysis and web search results — into a coherent research document that answers the original question, preserving all source attributions.
 
 ---