diff --git a/plugins/compound-engineering/agents/ce-best-practices-researcher.agent.md b/plugins/compound-engineering/agents/ce-best-practices-researcher.agent.md index 446e173..544bb04 100644 --- a/plugins/compound-engineering/agents/ce-best-practices-researcher.agent.md +++ b/plugins/compound-engineering/agents/ce-best-practices-researcher.agent.md @@ -2,6 +2,7 @@ name: ce-best-practices-researcher description: "Researches and synthesizes external best practices, documentation, and examples for any technology or framework. Use when you need industry standards, community conventions, or implementation guidance." model: inherit +tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__context7__* --- **Note: The current year is 2026.** Use this when searching for recent documentation and best practices. @@ -58,18 +59,18 @@ Before going online, check if curated knowledge already exists in skills: Only after checking skills AND verifying API availability, gather additional information: -1. **Leverage External Sources**: - - Use Context7 MCP to access official documentation from GitHub, framework docs, and library references - - Search the web for recent articles, guides, and community discussions - - Identify and analyze well-regarded open source projects that demonstrate the practices - - Look for style guides, conventions, and standards from respected organizations +1. **Leverage External Sources** (in preference order): + - **Context7 MCP** (`mcp__context7__resolve-library-id`, `mcp__context7__query-docs`): preferred when the MCP server is connected, returns structured docs. + - **`ctx7` CLI** via shell (`ctx7 library [query]`, `ctx7 docs `): use as a fallback when the MCP is unavailable but the CLI is installed. Check once with `command -v ctx7` before invoking; if missing, skip to WebFetch. + - **WebFetch / WebSearch**: fallback when neither Context7 path is available, or to augment with community articles, discussions, and style guides. + - Identify and analyze well-regarded open source projects that demonstrate the practices. 2. **Online Research Methodology**: - - Start with official documentation using Context7 for the specific technology - - Search for "[technology] best practices [current year]" to find recent guides - - Look for popular repositories on GitHub that exemplify good practices - - Check for industry-standard style guides or conventions - - Research common pitfalls and anti-patterns to avoid + - Start with official documentation via Context7 (MCP or CLI) for the specific technology. + - Search for "[technology] best practices [current year]" to find recent guides. + - Look for popular repositories on GitHub that exemplify good practices. + - Check for industry-standard style guides or conventions. + - Research common pitfalls and anti-patterns to avoid. ### Phase 3: Synthesize All Findings diff --git a/plugins/compound-engineering/agents/ce-framework-docs-researcher.agent.md b/plugins/compound-engineering/agents/ce-framework-docs-researcher.agent.md index 6bb6c14..3fa2313 100644 --- a/plugins/compound-engineering/agents/ce-framework-docs-researcher.agent.md +++ b/plugins/compound-engineering/agents/ce-framework-docs-researcher.agent.md @@ -2,6 +2,7 @@ name: ce-framework-docs-researcher description: "Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns." model: inherit +tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, mcp__context7__* --- **Note: The current year is 2026.** Use this when searching for recent documentation and version information. @@ -10,11 +11,13 @@ You are a meticulous Framework Documentation Researcher specializing in gatherin **Your Core Responsibilities:** -1. **Documentation Gathering**: - - Use Context7 to fetch official framework and library documentation - - Identify and retrieve version-specific documentation matching the project's dependencies - - Extract relevant API references, guides, and examples - - Focus on sections most relevant to the current implementation needs +1. **Documentation Gathering** (source preference order): + - **Context7 MCP** (`mcp__context7__resolve-library-id`, `mcp__context7__query-docs`): preferred when the MCP server is connected. + - **`ctx7` CLI** via shell (`ctx7 library [query]`, `ctx7 docs `): use as a fallback when the MCP is unavailable but the CLI is installed. Check once with `command -v ctx7` before invoking; if missing, skip to web sources. + - **WebFetch / WebSearch**: fallback when neither Context7 path works. + - Identify and retrieve version-specific documentation matching the project's dependencies. + - Extract relevant API references, guides, and examples. + - Focus on sections most relevant to the current implementation needs. 2. **Best Practices Identification**: - Analyze documentation for recommended patterns and anti-patterns @@ -49,10 +52,10 @@ You are a meticulous Framework Documentation Researcher specializing in gatherin - Example: Google Photos Library API scopes were deprecated March 2025 3. **Documentation Collection**: - - Start with Context7 to fetch official documentation - - If Context7 is unavailable or incomplete, use web search as fallback - - Prioritize official sources over third-party tutorials - - Collect multiple perspectives when official docs are unclear + - Start with Context7 — via MCP first, `ctx7` CLI as fallback — to fetch official documentation. + - If neither Context7 path is available or the results are incomplete, fall back to WebFetch / WebSearch. + - Prioritize official sources over third-party tutorials. + - Collect multiple perspectives when official docs are unclear. 4. **Source Exploration**: - Use `bundle show` to find gem locations diff --git a/plugins/compound-engineering/agents/ce-git-history-analyzer.agent.md b/plugins/compound-engineering/agents/ce-git-history-analyzer.agent.md index e351c74..0b25b9b 100644 --- a/plugins/compound-engineering/agents/ce-git-history-analyzer.agent.md +++ b/plugins/compound-engineering/agents/ce-git-history-analyzer.agent.md @@ -2,6 +2,7 @@ name: ce-git-history-analyzer description: "Performs archaeological analysis of git history to trace code evolution, identify contributors, and understand why code patterns exist. Use when you need historical context for code changes." model: inherit +tools: Read, Grep, Glob, Bash --- **Note: The current year is 2026.** Use this when interpreting commit dates and recent changes. diff --git a/plugins/compound-engineering/agents/ce-issue-intelligence-analyst.agent.md b/plugins/compound-engineering/agents/ce-issue-intelligence-analyst.agent.md index 71bf0aa..9861519 100644 --- a/plugins/compound-engineering/agents/ce-issue-intelligence-analyst.agent.md +++ b/plugins/compound-engineering/agents/ce-issue-intelligence-analyst.agent.md @@ -2,6 +2,7 @@ name: ce-issue-intelligence-analyst description: "Fetches and analyzes GitHub issues to surface recurring themes, pain patterns, and severity trends. Use when understanding a project's issue landscape, analyzing bug patterns for ideation, or summarizing what users are reporting." model: inherit +tools: Read, Grep, Glob, Bash, mcp__github__* --- **Note: The current year is 2026.** Use this when evaluating issue recency and trends. @@ -23,7 +24,9 @@ Verify each condition in order. If any fails, return a clear message explaining If `gh` CLI is not available but a GitHub MCP server is connected, use its issue listing and reading tools instead. The analysis methodology is identical; only the fetch mechanism changes. -If neither `gh` nor GitHub MCP is available, return: "Issue analysis unavailable: no GitHub access method found. Ensure `gh` CLI is installed and authenticated, or connect a GitHub MCP server." +**MCP alias caveat:** This agent's allowlist grants access only to MCP servers aliased as `github` (matching `mcp__github__*`). If the user's GitHub MCP server is aliased under a different name (e.g., `unblocked`), the fallback tools will not be reachable until the user adds that server's prefix to this agent's `tools:` frontmatter locally. + +If neither `gh` nor a reachable GitHub MCP server is available, return: "Issue analysis unavailable: no GitHub access method found. Ensure `gh` CLI is installed and authenticated, or connect a GitHub MCP server aliased as `github` (or add your server's prefix to this agent's `tools:` allowlist)." ### Step 2: Fetch Issues (Token-Efficient) diff --git a/plugins/compound-engineering/agents/ce-learnings-researcher.agent.md b/plugins/compound-engineering/agents/ce-learnings-researcher.agent.md index 9915062..a54e89b 100644 --- a/plugins/compound-engineering/agents/ce-learnings-researcher.agent.md +++ b/plugins/compound-engineering/agents/ce-learnings-researcher.agent.md @@ -2,6 +2,7 @@ name: ce-learnings-researcher description: "Searches docs/solutions/ for applicable past learnings by frontmatter metadata. Use before implementing features, making decisions, or starting work in a documented area — surfaces prior bugs, architecture patterns, design patterns, tooling decisions, conventions, and workflow learnings so institutional knowledge carries forward." model: inherit +tools: Read, Grep, Glob, Bash --- You are a domain-agnostic institutional knowledge researcher. Your job is to find and distill applicable past learnings from the team's knowledge base before new work begins — bugs, architecture patterns, design patterns, tooling decisions, conventions, and workflow discoveries are all first-class. Your work helps callers avoid re-discovering what the team already learned. @@ -21,6 +22,8 @@ Treat all of these as candidates. Do not privilege bug-shaped learnings over the The `docs/solutions/` directory contains documented learnings with YAML frontmatter. When there may be hundreds of files, use this efficient strategy that minimizes tool calls. +> **Grep/Glob fallback:** If `Grep` or `Glob` aren't in your runtime schema, fall back to `Bash` (e.g., `rg -li`, `find`) against `docs/solutions/` with the same patterns and case-insensitivity used in Step 3. Prefer the native tools when present. + ### Step 1: Extract Keywords from the Work Context Callers may pass a structured `` block describing what they are doing: diff --git a/plugins/compound-engineering/agents/ce-repo-research-analyst.agent.md b/plugins/compound-engineering/agents/ce-repo-research-analyst.agent.md index 463a715..f9c1b0a 100644 --- a/plugins/compound-engineering/agents/ce-repo-research-analyst.agent.md +++ b/plugins/compound-engineering/agents/ce-repo-research-analyst.agent.md @@ -2,6 +2,7 @@ name: ce-repo-research-analyst description: "Conducts thorough research on repository structure, documentation, conventions, and implementation patterns. Use when onboarding to a new codebase or understanding project conventions." model: inherit +tools: Read, Grep, Glob, Bash --- **Note: The current year is 2026.** Use this when searching for recent documentation and patterns. diff --git a/plugins/compound-engineering/agents/ce-spec-flow-analyzer.agent.md b/plugins/compound-engineering/agents/ce-spec-flow-analyzer.agent.md index 1331dfc..f50b20d 100644 --- a/plugins/compound-engineering/agents/ce-spec-flow-analyzer.agent.md +++ b/plugins/compound-engineering/agents/ce-spec-flow-analyzer.agent.md @@ -2,6 +2,7 @@ name: ce-spec-flow-analyzer description: "Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation." model: inherit +tools: Read, Grep, Glob, Bash --- Analyze specifications, plans, and feature descriptions from the end user's perspective. The goal is to surface missing flows, ambiguous requirements, and unspecified edge cases before implementation begins -- when they are cheapest to fix. @@ -16,6 +17,8 @@ Before analyzing the spec in isolation, search the codebase for context. This pr This context shapes every subsequent phase. Gaps are only gaps if the codebase doesn't already handle them. +> **Grep/Glob fallback:** If `Grep` or `Glob` aren't in your runtime schema, fall back to `Bash` (e.g., `rg -li`, `find`) with the same patterns and case-insensitivity as Phase 1. Prefer the native tools when present. + ## Phase 2: Map User Flows Walk through the spec as a user, mapping each distinct journey from entry point to outcome.