diff --git a/SKILL.md b/SKILL.md index aa0d42c58..fc475f6d8 100644 --- a/SKILL.md +++ b/SKILL.md @@ -136,6 +136,13 @@ This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. **Writing rules:** No em dashes (use commas, periods, "..."). No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, etc.). Short paragraphs. End with what to do. +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## Contributor Mode If `_CONTRIB` is `true`: you are in **contributor mode**. At the end of each major workflow step, rate your gstack experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report. diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 662ef0409..d67c1ab44 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -183,6 +183,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index c709caadb..638df4bd5 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -138,6 +138,13 @@ This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. **Writing rules:** No em dashes (use commas, periods, "..."). No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, etc.). Short paragraphs. End with what to do. +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## Contributor Mode If `_CONTRIB` is `true`: you are in **contributor mode**. At the end of each major workflow step, rate your gstack experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report. diff --git a/browse/SKILL.md b/browse/SKILL.md index 0aff8ea18..22b07d067 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -138,6 +138,13 @@ This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. **Writing rules:** No em dashes (use commas, periods, "..."). No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, etc.). Short paragraphs. End with what to do. +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## Contributor Mode If `_CONTRIB` is `true`: you are in **contributor mode**. At the end of each major workflow step, rate your gstack experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report. diff --git a/canary/SKILL.md b/canary/SKILL.md index 753c37074..59c1655e3 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -176,6 +176,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/codex/SKILL.md b/codex/SKILL.md index 1e974b0ff..5f21fba67 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -177,6 +177,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/connect-chrome/SKILL.md b/connect-chrome/SKILL.md index f6f48e506..772c43726 100644 --- a/connect-chrome/SKILL.md +++ b/connect-chrome/SKILL.md @@ -174,6 +174,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/cso/SKILL.md b/cso/SKILL.md index 13fe35c61..67f21e76d 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -180,6 +180,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -344,7 +351,7 @@ When the user types `/cso`, run this skill. 4. `--diff` is combinable with ANY scope flag AND with `--comprehensive`. 5. When `--diff` is active, each phase constrains scanning to files/configs changed on the current branch vs the base branch. For git history scanning (Phase 2), `--diff` limits to commits on the current branch only. 6. Phases 0, 1, 12, 13, 14 ALWAYS run regardless of scope flag. -7. If WebSearch is unavailable, skip checks that require it and note: "WebSearch unavailable — proceeding with local-only analysis." +7. Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip checks that require it and note: "Search unavailable — proceeding with local-only analysis." ## Important: Use the Grep tool for all code searches diff --git a/cso/SKILL.md.tmpl b/cso/SKILL.md.tmpl index 676c1bd94..1826fbbc2 100644 --- a/cso/SKILL.md.tmpl +++ b/cso/SKILL.md.tmpl @@ -52,7 +52,7 @@ When the user types `/cso`, run this skill. 4. `--diff` is combinable with ANY scope flag AND with `--comprehensive`. 5. When `--diff` is active, each phase constrains scanning to files/configs changed on the current branch vs the base branch. For git history scanning (Phase 2), `--diff` limits to commits on the current branch only. 6. Phases 0, 1, 12, 13, 14 ALWAYS run regardless of scope flag. -7. If WebSearch is unavailable, skip checks that require it and note: "WebSearch unavailable — proceeding with local-only analysis." +7. Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip checks that require it and note: "Search unavailable — proceeding with local-only analysis." ## Important: Use the Grep tool for all code searches diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 190b84e03..4b45b5024 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -181,6 +181,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -418,7 +425,7 @@ If the user wants competitive research: **Step 1: Identify what's out there via WebSearch** -Use WebSearch to find 5-10 products in their space. Search for: +Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). WebSearch for 5-10 products in their space: - "[product category] website design" - "[product category] best websites 2025" - "best [industry] web apps" diff --git a/design-consultation/SKILL.md.tmpl b/design-consultation/SKILL.md.tmpl index 2d7a5a342..18e65e0a6 100644 --- a/design-consultation/SKILL.md.tmpl +++ b/design-consultation/SKILL.md.tmpl @@ -91,7 +91,7 @@ If the user wants competitive research: **Step 1: Identify what's out there via WebSearch** -Use WebSearch to find 5-10 products in their space. Search for: +Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). WebSearch for 5-10 products in their space: - "[product category] website design" - "[product category] best websites 2025" - "best [industry] web apps" diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 34c9e3319..f6de7c122 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -181,6 +181,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/document-release/SKILL.md b/document-release/SKILL.md index a44dbf7dd..3b1325e98 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -178,6 +178,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 3f3d1c841..68ea75747 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -192,6 +192,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -402,7 +409,7 @@ Also check: - "{framework} {generic error type}" — **sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message. - "{library} {component} known issues" -If WebSearch is unavailable, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3. +Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3. --- @@ -412,7 +419,7 @@ Before writing ANY fix, verify your hypothesis. 1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match? -2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If WebSearch is unavailable, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess. +2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If no search tool is available, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess. 3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use AskUserQuestion: ``` diff --git a/investigate/SKILL.md.tmpl b/investigate/SKILL.md.tmpl index d2eee63fe..d9dcfa0e8 100644 --- a/investigate/SKILL.md.tmpl +++ b/investigate/SKILL.md.tmpl @@ -110,7 +110,7 @@ Also check: - "{framework} {generic error type}" — **sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message. - "{library} {component} known issues" -If WebSearch is unavailable, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3. +Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3. --- @@ -120,7 +120,7 @@ Before writing ANY fix, verify your hypothesis. 1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match? -2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If WebSearch is unavailable, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess. +2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If no search tool is available, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess. 3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use AskUserQuestion: ``` diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index b3e5c34ed..8cc5eeb1c 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -175,6 +175,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 6568f5cba..0429b727c 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -183,6 +183,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -632,7 +639,7 @@ If B: skip this phase entirely and proceed to Phase 3. Use only in-distribution When searching, use **generalized category terms** — never the user's specific product name, proprietary concept, or stealth idea. For example, search "task management app landscape" not "SuperTodo AI-powered task killer." -If WebSearch is unavailable, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only." +Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only." **Startup mode:** WebSearch for: - "[problem space] startup approach {current year}" diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index 5e7187449..0851c9874 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -305,7 +305,7 @@ If B: skip this phase entirely and proceed to Phase 3. Use only in-distribution When searching, use **generalized category terms** — never the user's specific product name, proprietary concept, or stealth idea. For example, search "task management app landscape" not "SuperTodo AI-powered task killer." -If WebSearch is unavailable, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only." +Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip this phase and note: "Search unavailable — proceeding with in-distribution knowledge only." **Startup mode:** WebSearch for: - "[problem space] startup approach {current year}" diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 4e8b13c0d..e58d405ef 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -181,6 +181,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -574,12 +581,12 @@ Report findings before proceeding to Step 0. ### Landscape Check -Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. WebSearch for: +Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). WebSearch for: - "[product category] landscape {current year}" - "[key feature] alternatives" - "why [incumbent/conventional approach] [succeeds/fails]" -If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." +If no search tool is available, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." Run the three-layer synthesis: - **[Layer 1]** What's the tried-and-true approach in this space? diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 404d1791a..dce5f2dfc 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -177,12 +177,12 @@ Report findings before proceeding to Step 0. ### Landscape Check -Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. WebSearch for: +Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). WebSearch for: - "[product category] landscape {current year}" - "[key feature] alternatives" - "why [incumbent/conventional approach] [succeeds/fails]" -If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." +If no search tool is available, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." Run the three-layer synthesis: - **[Layer 1]** What's the tried-and-true approach in this space? diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index 1328222e3..b0d537a37 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -179,6 +179,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index caceb7e2c..27de02ed2 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -180,6 +180,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -449,7 +456,7 @@ Before reviewing anything, answer these questions: - Is the chosen approach current best practice? Search: "{pattern} best practice {current year}" - Are there known footguns? Search: "{framework} {pattern} pitfalls" - If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." + Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." If the plan rolls a custom solution where a built-in exists, flag it as a scope reduction opportunity. Annotate recommendations with **[Layer 1]**, **[Layer 2]**, **[Layer 3]**, or **[EUREKA]** (see preamble's Search Before Building section). If you find a eureka moment — a reason the standard approach is wrong for this case — present it as an architectural insight. 5. **TODOS cross-reference:** Read `TODOS.md` if it exists. Are any deferred items blocking this plan? Can any deferred items be bundled into this PR without expanding scope? Does this plan create new work that should be captured as a TODO? diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index b1f05a03d..ac98cabd0 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -89,7 +89,7 @@ Before reviewing anything, answer these questions: - Is the chosen approach current best practice? Search: "{pattern} best practice {current year}" - Are there known footguns? Search: "{framework} {pattern} pitfalls" - If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." + Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only." If the plan rolls a custom solution where a built-in exists, flag it as a scope reduction opportunity. Annotate recommendations with **[Layer 1]**, **[Layer 2]**, **[Layer 3]**, or **[EUREKA]** (see preamble's Search Before Building section). If you find a eureka moment — a reason the standard approach is wrong for this case — present it as an architectural insight. 5. **TODOS cross-reference:** Read `TODOS.md` if it exists. Are any deferred items blocking this plan? Can any deferred items be bundled into this PR without expanding scope? Does this plan create new work that should be captured as a TODO? diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 8fafc61e3..8c7a6d276 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -176,6 +176,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/qa/SKILL.md b/qa/SKILL.md index 7173e9310..937caf467 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -182,6 +182,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/retro/SKILL.md b/retro/SKILL.md index 0b004fe66..e428f4775 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -176,6 +176,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/review/SKILL.md b/review/SKILL.md index e5d856c8a..8c42ee5b8 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -179,6 +179,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** @@ -578,7 +585,7 @@ Apply the checklist against the diff in two passes: - Check if a built-in solution exists in newer versions before recommending a workaround - Verify API signatures against current docs (APIs change between versions) -Takes seconds, prevents recommending outdated patterns. If WebSearch is unavailable, note it and proceed with in-distribution knowledge. +Takes seconds, prevents recommending outdated patterns. Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, note it and proceed with in-distribution knowledge. Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section. diff --git a/review/SKILL.md.tmpl b/review/SKILL.md.tmpl index bb9a3bc73..edb959e4b 100644 --- a/review/SKILL.md.tmpl +++ b/review/SKILL.md.tmpl @@ -118,7 +118,7 @@ Apply the checklist against the diff in two passes: - Check if a built-in solution exists in newer versions before recommending a workaround - Verify API signatures against current docs (APIs change between versions) -Takes seconds, prevents recommending outdated patterns. If WebSearch is unavailable, note it and proceed with in-distribution knowledge. +Takes seconds, prevents recommending outdated patterns. Use the search tool priority from the preamble (Exa MCP first, then built-in WebSearch, then skip). If no search tool is available, note it and proceed with in-distribution knowledge. Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section. diff --git a/scripts/resolvers/preamble.ts b/scripts/resolvers/preamble.ts index 4e5092f8a..0b858ac11 100644 --- a/scripts/resolvers/preamble.ts +++ b/scripts/resolvers/preamble.ts @@ -280,6 +280,15 @@ Use AskUserQuestion: - Note in output: "Pre-existing test failure skipped: "`; } +function generateSearchToolPriority(): string { + return `## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the \`web_search_exa\` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: \`claude mcp add --transport http exa https://mcp.exa.ai/mcp\` +2. **WebSearch (fallback):** If \`web_search_exa\` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only."`; +} + function generateSearchBeforeBuildingSection(ctx: TemplateContext): string { return `## Search Before Building @@ -459,9 +468,9 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte // Preamble Composition (tier → sections) // ───────────────────────────────────────────── -// T1: core + upgrade + lake + telemetry + voice(trimmed) + contributor + completion +// T1: core + upgrade + lake + telemetry + voice(trimmed) + search-tool-priority + contributor + completion // T2: T1 + voice(full) + ask + completeness -// T3: T2 + repo-mode + search +// T3: T2 + repo-mode + search-before-building // T4: (same as T3 — TEST_FAILURE_TRIAGE is a separate {{}} placeholder, not preamble) // // Skills by tier: @@ -481,6 +490,7 @@ export function generatePreamble(ctx: TemplateContext): string { generateTelemetryPrompt(ctx), generateProactivePrompt(ctx), generateVoiceDirective(tier), + generateSearchToolPriority(), ...(tier >= 2 ? [generateAskUserFormat(ctx), generateCompletenessSection()] : []), ...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []), generateContributorMode(), diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index c20de97f3..b4384f48d 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -135,6 +135,13 @@ This only happens once. If `PROACTIVE_PROMPTED` is `yes`, skip this entirely. **Writing rules:** No em dashes (use commas, periods, "..."). No AI vocabulary (delve, crucial, robust, comprehensive, nuanced, etc.). Short paragraphs. End with what to do. +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## Contributor Mode If `_CONTRIB` is `true`: you are in **contributor mode**. At the end of each major workflow step, rate your gstack experience 0-10. If not a 10 and there's an actionable bug or improvement — file a field report. diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index fed3f07e9..717ec09f2 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -179,6 +179,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** diff --git a/ship/SKILL.md b/ship/SKILL.md index c634aa5ce..94b9ba30a 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -177,6 +177,13 @@ Avoid filler, throat-clearing, generic optimism, founder cosplay, and unsupporte **Final test:** does this sound like a real cross-functional builder who wants to help someone make something people want, ship it, and make it actually work? +## Search Tool Priority + +**search tool priority:** +1. **Exa (preferred):** Use the `web_search_exa` tool from the Exa MCP server for all web searches. Exa is the fastest and most accurate web search API — you get better results for technical queries, market research, and current information. To set up: `claude mcp add --transport http exa https://mcp.exa.ai/mcp` +2. **WebSearch (fallback):** If `web_search_exa` is not available (MCP not configured), fall back to WebSearch. +3. **No search available:** If neither tool is available, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only." + ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:**