From 816bf2a5fc45bcbca69ad53d7e39c43189da0b0c Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 29 Jun 2026 10:14:35 +0200 Subject: [PATCH] refactor(agents): relocate example blocks to body (researchers + gemini-bridge) --- agents/community-researcher.md | 42 +++++++++++++++++---------------- agents/contrarian-researcher.md | 42 +++++++++++++++++---------------- agents/docs-researcher.md | 42 +++++++++++++++++---------------- agents/gemini-bridge.md | 40 ++++++++++++++++--------------- agents/security-researcher.md | 42 +++++++++++++++++---------------- 5 files changed, 109 insertions(+), 99 deletions(-) diff --git a/agents/community-researcher.md b/agents/community-researcher.md index 6317d86..89eb8b6 100644 --- a/agents/community-researcher.md +++ b/agents/community-researcher.md @@ -4,26 +4,6 @@ description: | Use this agent when the research task requires practical, real-world experience rather than official documentation — community sentiment, production war stories, known gotchas, and what developers actually encounter when using a technology. - - - Context: trekresearch needs real-world experience data on a database migration - user: "/trekresearch What's the real-world experience with migrating from MongoDB to PostgreSQL?" - assistant: "Launching community-researcher to find migration stories, GitHub discussions, and community experience reports." - - Official docs won't cover migration regrets or production war stories. community-researcher - targets GitHub issues, blog posts, and discussions where real experience lives. - - - - - Context: trekresearch is building a technology comparison - user: "/trekresearch Research community sentiment around adopting SvelteKit vs Next.js" - assistant: "I'll use community-researcher to find discussions, blog posts, and community reports on both frameworks." - - Framework comparisons live in community discourse, not official docs. community-researcher - finds the practical signal that helps teams make adoption decisions. - - model: opus color: green tools: ["WebSearch", "WebFetch", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research"] @@ -133,3 +113,25 @@ End with a summary table: Do not pick a side — report the split. - **Flag if a "problem" has since been fixed.** Check if the issue/complaint references a version that has since been patched or superseded. + +## When to use — examples + + +Context: trekresearch needs real-world experience data on a database migration +user: "/trekresearch What's the real-world experience with migrating from MongoDB to PostgreSQL?" +assistant: "Launching community-researcher to find migration stories, GitHub discussions, and community experience reports." + +Official docs won't cover migration regrets or production war stories. community-researcher +targets GitHub issues, blog posts, and discussions where real experience lives. + + + + +Context: trekresearch is building a technology comparison +user: "/trekresearch Research community sentiment around adopting SvelteKit vs Next.js" +assistant: "I'll use community-researcher to find discussions, blog posts, and community reports on both frameworks." + +Framework comparisons live in community discourse, not official docs. community-researcher +finds the practical signal that helps teams make adoption decisions. + + diff --git a/agents/contrarian-researcher.md b/agents/contrarian-researcher.md index 5411ec2..a1027b1 100644 --- a/agents/contrarian-researcher.md +++ b/agents/contrarian-researcher.md @@ -4,26 +4,6 @@ description: | Use this agent when the research task has an emerging conclusion that needs adversarial stress-testing — find counter-evidence, overlooked alternatives, and reasons the leading answer might be wrong. - - - Context: trekresearch has found evidence favoring a technology and needs the other side - user: "/trekresearch We're leaning toward adopting Kafka for our event streaming needs" - assistant: "Launching contrarian-researcher to find the strongest arguments against Kafka and what alternatives might serve better." - - The research equivalent of plan-critic. When one option is emerging as the answer, - contrarian-researcher actively seeks disconfirming evidence to pressure-test the conclusion. - - - - - Context: trekresearch is comparing options and needs the downsides of the leading candidate - user: "/trekresearch Compare Redis vs Memcached — initial research favors Redis" - assistant: "I'll use contrarian-researcher to find the strongest case against Redis and scenarios where Memcached wins." - - Contrarian-researcher finds the downsides of the leading option — not to be negative, - but to ensure the final recommendation is genuinely considered. - - model: opus effort: high color: red @@ -152,3 +132,25 @@ Followed by a **Verdict** section: apply to a read-heavy workload. Assess relevance before reporting. - **Check recency.** A problem from 2019 that the project fixed in 2021 is not current counter-evidence. Flag whether issues are current or historical. + +## When to use — examples + + +Context: trekresearch has found evidence favoring a technology and needs the other side +user: "/trekresearch We're leaning toward adopting Kafka for our event streaming needs" +assistant: "Launching contrarian-researcher to find the strongest arguments against Kafka and what alternatives might serve better." + +The research equivalent of plan-critic. When one option is emerging as the answer, +contrarian-researcher actively seeks disconfirming evidence to pressure-test the conclusion. + + + + +Context: trekresearch is comparing options and needs the downsides of the leading candidate +user: "/trekresearch Compare Redis vs Memcached — initial research favors Redis" +assistant: "I'll use contrarian-researcher to find the strongest case against Redis and scenarios where Memcached wins." + +Contrarian-researcher finds the downsides of the leading option — not to be negative, +but to ensure the final recommendation is genuinely considered. + + diff --git a/agents/docs-researcher.md b/agents/docs-researcher.md index 364a3e8..6a99790 100644 --- a/agents/docs-researcher.md +++ b/agents/docs-researcher.md @@ -3,26 +3,6 @@ name: docs-researcher description: | Use this agent when the research task requires authoritative information from official documentation, RFCs, vendor specifications, or Microsoft/Azure documentation. - - - Context: trekresearch needs to ground an OAuth2 implementation in official specs - user: "/trekresearch Research OAuth2 PKCE flow for our SPA" - assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE." - - docs-researcher targets authoritative sources — RFCs, specs, official vendor docs — - not community opinions. This is the right agent for protocol and standards questions. - - - - - Context: trekresearch encounters an Azure-specific technology - user: "/trekresearch How should we configure Azure Service Bus for our event pipeline?" - assistant: "I'll use docs-researcher with Microsoft Learn to get authoritative Azure Service Bus documentation." - - Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search, - microsoft_docs_fetch) that docs-researcher uses for higher-quality results. - - model: opus color: blue tools: ["WebSearch", "WebFetch", "Read", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research", "mcp__microsoft-learn__microsoft_docs_search", "mcp__microsoft-learn__microsoft_docs_fetch"] @@ -119,3 +99,25 @@ End with a summary table: - **Flag conflicts between official sources.** When vendor docs and the spec disagree, report both. - **Stay focused.** Research only what the research question asks. Do not explore tangentially. - **Official sources only.** If you cannot find an official source, say so — do not substitute a blog post. + +## When to use — examples + + +Context: trekresearch needs to ground an OAuth2 implementation in official specs +user: "/trekresearch Research OAuth2 PKCE flow for our SPA" +assistant: "Launching docs-researcher to find the official RFC and vendor documentation for OAuth2 PKCE." + +docs-researcher targets authoritative sources — RFCs, specs, official vendor docs — +not community opinions. This is the right agent for protocol and standards questions. + + + + +Context: trekresearch encounters an Azure-specific technology +user: "/trekresearch How should we configure Azure Service Bus for our event pipeline?" +assistant: "I'll use docs-researcher with Microsoft Learn to get authoritative Azure Service Bus documentation." + +Microsoft/Azure technologies have dedicated MCP tools (microsoft_docs_search, +microsoft_docs_fetch) that docs-researcher uses for higher-quality results. + + diff --git a/agents/gemini-bridge.md b/agents/gemini-bridge.md index a15de55..1a3c964 100644 --- a/agents/gemini-bridge.md +++ b/agents/gemini-bridge.md @@ -5,25 +5,6 @@ description: | needed on a technology choice, architectural question, or complex research topic. Provides triangulation value by running a completely independent research path that can confirm or challenge findings from other agents. - - - Context: trekresearch launches gemini-bridge for an independent second opinion on a technology choice - user: "/trekplan Should we use Kafka or NATS for our event streaming layer?" - assistant: "Launching gemini-bridge for an independent second opinion on Kafka vs NATS." - - Technology choice with significant architectural implications triggers gemini-bridge - to provide an independent research path alongside local exploration agents. - - - - - Context: user wants deep research via Gemini on a complex architectural question - user: "Get me a Gemini deep research on event sourcing patterns for distributed systems" - assistant: "I'll use the gemini-bridge agent to run a deep research on event sourcing patterns." - - Direct request for Gemini research on a complex architectural question triggers the agent. - - model: opus color: magenta tools: ["mcp__gemini-mcp__gemini_deep_research", "mcp__gemini-mcp__gemini_get_research_status", "mcp__gemini-mcp__gemini_get_research_result", "mcp__gemini-mcp__gemini_research_followup"] @@ -147,3 +128,24 @@ and other external agents:* - **Graceful degradation at every step.** Unavailable tool, failed research, timeout — all are handled with a clear status message and immediate return. Never leave the pipeline hanging. + +## When to use — examples + + +Context: trekresearch launches gemini-bridge for an independent second opinion on a technology choice +user: "/trekplan Should we use Kafka or NATS for our event streaming layer?" +assistant: "Launching gemini-bridge for an independent second opinion on Kafka vs NATS." + +Technology choice with significant architectural implications triggers gemini-bridge +to provide an independent research path alongside local exploration agents. + + + + +Context: user wants deep research via Gemini on a complex architectural question +user: "Get me a Gemini deep research on event sourcing patterns for distributed systems" +assistant: "I'll use the gemini-bridge agent to run a deep research on event sourcing patterns." + +Direct request for Gemini research on a complex architectural question triggers the agent. + + diff --git a/agents/security-researcher.md b/agents/security-researcher.md index d960c0d..a4516ca 100644 --- a/agents/security-researcher.md +++ b/agents/security-researcher.md @@ -3,26 +3,6 @@ name: security-researcher description: | Use this agent when the research task requires security investigation of a technology, dependency, or library — CVEs, audit history, supply chain risks, and OWASP relevance. - - - Context: trekresearch is evaluating whether a dependency is safe to adopt - user: "/trekresearch Research whether we should trust the `node-fetch` library" - assistant: "Launching security-researcher to check CVE history, supply chain risk, and audit reports for node-fetch." - - Before adopting a dependency, security-researcher checks the attack surface: known - vulnerabilities, maintainer health, and whether past issues were handled responsibly. - - - - - Context: trekresearch is assessing the security posture of a technology choice - user: "/trekresearch Evaluate the security implications of using JWT for session management" - assistant: "I'll use security-researcher to check known JWT vulnerabilities, OWASP guidance, and community security reports." - - Technology choices have security tradeoffs. security-researcher maps the threat surface - using CVE databases, OWASP categories, and verified audit reports. - - model: opus color: red tools: ["WebSearch", "WebFetch", "mcp__tavily__tavily_search", "mcp__tavily__tavily_research"] @@ -140,3 +120,25 @@ End with an overall security summary table: risks from incomplete information. - **Severity matters.** A CVSS 9.8 is not equivalent to a CVSS 3.2 — report scores and distinguish between critical and low-severity findings. + +## When to use — examples + + +Context: trekresearch is evaluating whether a dependency is safe to adopt +user: "/trekresearch Research whether we should trust the `node-fetch` library" +assistant: "Launching security-researcher to check CVE history, supply chain risk, and audit reports for node-fetch." + +Before adopting a dependency, security-researcher checks the attack surface: known +vulnerabilities, maintainer health, and whether past issues were handled responsibly. + + + + +Context: trekresearch is assessing the security posture of a technology choice +user: "/trekresearch Evaluate the security implications of using JWT for session management" +assistant: "I'll use security-researcher to check known JWT vulnerabilities, OWASP guidance, and community security reports." + +Technology choices have security tradeoffs. security-researcher maps the threat surface +using CVE databases, OWASP categories, and verified audit reports. + +