fix: agent YAML format, add freshness hooks, upgrade models #51
Conversation
- Fix tools field format in agents (string → array) - Add SessionStart freshness hooks for otelwiki and ancplua-docs-librarian - Use NuGet API as source of truth for version checking - Upgrade agents to opus model for better reasoning - Add WebSearch/WebFetch tools to agents - Document xUnit v3 + MTP requirements (exe output, matching versions) - Add hooks declarations to plugin.json files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
📝 WalkthroughWalkthroughThis PR adds hooks infrastructure to three plugins and upgrades their configurations. It fixes tools field formatting in agent configs from strings to YAML lists, upgrades models from haiku/sonnet to opus, adds WebSearch/WebFetch capabilities to agents, introduces SessionStart hooks with freshness-check prompts, and updates agent guidance documentation to reflect new capabilities and version-checking workflows. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Plugin as Plugin<br/>(SessionStart)
participant Hook as SessionStart Hook
participant VersionCheck as Freshness Check<br/>(Local/NuGet)
participant Prompt as Prompt Output
User ->> Plugin: Load plugin
Plugin ->> Hook: Trigger SessionStart hook
Hook ->> VersionCheck: Check VERSION.md & NuGet
alt Version data exists
VersionCheck ->> VersionCheck: Compare SDK versions
VersionCheck ->> Prompt: Generate version mismatch alert
else Not initialized
VersionCheck ->> Prompt: Generate init suggestion
end
Prompt ->> User: Display freshness/setup prompt
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @ANcpLua, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the reliability, intelligence, and data freshness of the agent ecosystem. By standardizing agent tool configurations, upgrading to more capable language models, and implementing proactive version checking mechanisms, the agents are now better equipped to provide accurate and current information, preventing the use of outdated APIs or patterns. The changes ensure agents can self-verify information and provide more relevant guidance. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces significant updates across several plugins, primarily focusing on agent capabilities and documentation freshness. Key changes include standardizing agent tools fields to YAML array format, adding WebSearch and WebFetch tools to most agents for improved information retrieval, and upgrading agent models (e.g., from haiku/sonnet to opus) for enhanced reasoning. The PR also integrates new SessionStart hooks into ancplua-docs-librarian, metacognitive-guard, and otelwiki plugins to proactively check for documentation and package version freshness, prompting users for updates or automatically proceeding based on keywords. Specifically, the ancplua-docs-librarian agent now includes detailed testing requirements for xUnit v3 and MTP, and both ancplua-docs-librarian and otelwiki agents received new 'Web Capabilities' guidance. The otelwiki freshness script was refactored to simplify its prompting logic. Review comments highlighted the need to add set -euo pipefail to a shell script for robustness, specify the language for a code block in ancplua-librarian.md as text, and remove trailing spaces in a prompt string within ancplua-docs-librarian/hooks/hooks.json.
| @@ -1,24 +1,13 @@ | |||
| #!/bin/bash | |||
There was a problem hiding this comment.
The repository style guide requires shell scripts to start with set -euo pipefail for robustness and to prevent unexpected behavior on errors. This script is missing that declaration.
| #!/bin/bash | |
| #!/bin/bash | |
| set -euo pipefail |
References
- Repository style guide line 62: 'Use
set -euo pipefailat script start' (link)
| - Run tests with: `dotnet run` (not `dotnet test`) or use MTP runner | ||
|
|
||
| **NuGet API for version check:** | ||
| ``` |
There was a problem hiding this comment.
The repository style guide requires that all code blocks specify a language. This block containing URLs is missing its specifier. Using text would be appropriate here.
| ``` | |
| ```text |
References
- Repository style guide line 77: 'Code blocks must specify language' (link)
| "hooks": [ | ||
| { | ||
| "type": "prompt", | ||
| "prompt": "ANcpLua Docs Librarian loaded.\n\n**Auto-freshness** (if user says search/latest/update/versions) OR ask 'Quick version check? (yes/no)':\n\n**NuGet API is source of truth:**\n1. WebFetch 'https://api.nuget.org/v3-flatcontainer/ancplua.net.sdk/index.json' → latest SDK version\n2. WebFetch 'https://api.nuget.org/v3-flatcontainer/microsoft.codeanalysis.csharp/index.json' → latest Roslyn\n3. Read local Version.props in each repo → current versions\n4. Compare → report delta\n\n**Key packages:**\n- ancplua.net.sdk\n- ancplua.analyzers \n- microsoft.codeanalysis.csharp\n- xunit.v3 + xunit.v3.mtp-v2 (must match, exe output required)\n\n**If mismatch:** 'Local uses X.Y, NuGet has A.B - verifying patterns still apply'\n\nKeep it quick - user is waiting." |
There was a problem hiding this comment.
There are some trailing spaces after ancplua.analyzers. These should be removed for cleanliness.
| "prompt": "ANcpLua Docs Librarian loaded.\n\n**Auto-freshness** (if user says search/latest/update/versions) OR ask 'Quick version check? (yes/no)':\n\n**NuGet API is source of truth:**\n1. WebFetch 'https://api.nuget.org/v3-flatcontainer/ancplua.net.sdk/index.json' → latest SDK version\n2. WebFetch 'https://api.nuget.org/v3-flatcontainer/microsoft.codeanalysis.csharp/index.json' → latest Roslyn\n3. Read local Version.props in each repo → current versions\n4. Compare → report delta\n\n**Key packages:**\n- ancplua.net.sdk\n- ancplua.analyzers \n- microsoft.codeanalysis.csharp\n- xunit.v3 + xunit.v3.mtp-v2 (must match, exe output required)\n\n**If mismatch:** 'Local uses X.Y, NuGet has A.B - verifying patterns still apply'\n\nKeep it quick - user is waiting." | |
| "prompt": "ANcpLua Docs Librarian loaded.\n\n**Auto-freshness** (if user says search/latest/update/versions) OR ask 'Quick version check? (yes/no)':\n\n**NuGet API is source of truth:**\n1. WebFetch 'https://api.nuget.org/v3-flatcontainer/ancplua.net.sdk/index.json' → latest SDK version\n2. WebFetch 'https://api.nuget.org/v3-flatcontainer/microsoft.codeanalysis.csharp/index.json' → latest Roslyn\n3. Read local Version.props in each repo → current versions\n4. Compare → report delta\n\n**Key packages:**\n- ancplua.net.sdk\n- ancplua.analyzers\n- microsoft.codeanalysis.csharp\n- xunit.v3 + xunit.v3.mtp-v2 (must match, exe output required)\n\n**If mismatch:** 'Local uses X.Y, NuGet has A.B - verifying patterns still apply'\n\nKeep it quick - user is waiting." |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
plugins/otelwiki/agents/otel-guide.md (1)
81-89: Consider clarifying the sync mechanism.The guidance clearly lists when to use web tools. However, line 89 references
/otelwiki:syncwithout explaining what this command does or how to invoke it. Consider adding a brief note (e.g., "synced via the /otelwiki:sync skill command").plugins/ancplua-docs-librarian/hooks/hooks.json (1)
8-8: Consider formatting the long prompt for better maintainability.The entire SessionStart prompt is on a single line (282+ characters), which makes it harder to read and maintain. While JSON doesn't require line breaks in strings, consider either:
- Using proper JSON string escaping with
\nto preserve the multiline format explicitly- Documenting that the prompt formatting is intentional for runtime rendering
This is a minor readability concern and doesn't affect functionality.
plugins/otelwiki/hooks/hooks.json (1)
10-13: Consider extracting long prompt to separate file for maintainability.The SessionStart prompt hook is correctly implemented and provides clear freshness-checking workflow instructions. However, the 500+ character prompt string on line 12 could be difficult to maintain inline.
🔎 Optional refactor to improve maintainability
Consider extracting the prompt to a separate file (e.g.,
prompts/session-start.txt) and referencing it:{ "type": "prompt", - "prompt": "OTel docs plugin loaded. Follow this flow:\n\n1. IF user mentions 'search/web/latest/update' → auto-proceed with checks (don't ask)\n\n2. OTHERWISE ask: 'Sync OTel docs? (yes/no)'\n\n**Freshness sources:**\n- Semconv: WebFetch 'https://api.github.com/repos/open-telemetry/semantic-conventions/releases/latest'\n- .NET SDK: WebFetch 'https://api.nuget.org/v3-flatcontainer/opentelemetry/index.json'\n- Read ${CLAUDE_PLUGIN_ROOT}/docs/VERSION.md → local version\n- Compare → report delta\n\n**On YES:** run /otelwiki:sync, then show what changed\n**On NO:** 'Check for patches?' → YES = fetch latest release notes, NO = proceed\n\nKeep it quick - user is waiting." + "promptFile": "${CLAUDE_PLUGIN_ROOT}/prompts/session-start.txt" }Note: This assumes the hooks system supports
promptFileas an alternative to inlineprompt. If not supported, the current approach is acceptable.plugins/otelwiki/scripts/check-freshness.sh (2)
9-9: Consider more robust version extraction pattern.The current regex
'[0-9]+\.[0-9]+\.[0-9]+'will match any three-part number in the line, which could extract an unintended version if the file contains multiple semver patterns.🔎 More specific pattern
- CURRENT_VERSION=$(grep -m1 "semconv" "$VERSION_FILE" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown") + CURRENT_VERSION=$(grep -m1 "semconv" "$VERSION_FILE" | grep -oP 'semconv[:\s]+v?\K[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")This pattern:
- Uses
\Kto exclude the "semconv" prefix from the match- Handles optional "v" prefix (v1.2.3)
- Anchors to "semconv" followed by colon or whitespace
1-13: Consider adding bash strict mode for defensive coding.While the script is simple and handles errors with fallbacks, adding strict mode flags would align with shellcheck best practices.
🔎 Add strict mode
#!/bin/bash +set -euo pipefail # Prompt user to sync OTel docs at session startBenefits:
-e: Exit on error-u: Error on undefined variables-o pipefail: Catch errors in pipelines
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (12)
CHANGELOG.mdplugins/ancplua-docs-librarian/.claude-plugin/plugin.jsonplugins/ancplua-docs-librarian/agents/ancplua-librarian.mdplugins/ancplua-docs-librarian/hooks/hooks.jsonplugins/metacognitive-guard/.claude-plugin/plugin.jsonplugins/metacognitive-guard/agents/arch-reviewer.mdplugins/metacognitive-guard/agents/impl-reviewer.mdplugins/otelwiki/.claude-plugin/plugin.jsonplugins/otelwiki/agents/otel-guide.mdplugins/otelwiki/agents/otel-librarian.mdplugins/otelwiki/hooks/hooks.jsonplugins/otelwiki/scripts/check-freshness.sh
🧰 Additional context used
📓 Path-based instructions (1)
plugins/**
⚙️ CodeRabbit configuration file
plugins/**: Review for:
- Plugin structure compliance (plugin.json, skills/, commands/)
- SKILL.md has proper YAML frontmatter
- Security: no hardcoded secrets
- Shell scripts are shellcheck-compliant
Files:
plugins/otelwiki/agents/otel-librarian.mdplugins/ancplua-docs-librarian/agents/ancplua-librarian.mdplugins/metacognitive-guard/agents/impl-reviewer.mdplugins/otelwiki/agents/otel-guide.mdplugins/otelwiki/hooks/hooks.jsonplugins/otelwiki/scripts/check-freshness.shplugins/metacognitive-guard/agents/arch-reviewer.mdplugins/ancplua-docs-librarian/hooks/hooks.json
🔇 Additional comments (15)
plugins/otelwiki/agents/otel-guide.md (1)
4-10: LGTM! Tools array format fixed and model upgraded.The conversion from string to proper YAML array format resolves the plugins stuck in "installed" state issue. The addition of WebSearch and WebFetch tools, combined with the opus model upgrade, enables the enhanced version-checking capabilities described in the PR objectives.
plugins/ancplua-docs-librarian/.claude-plugin/plugin.json (1)
14-15: LGTM! Hooks property added correctly.The addition of the "hooks" property with the relative path
"./hooks/hooks.json"follows the same pattern used in other plugins (e.g., metacognitive-guard). JSON syntax is valid and the structure complies with plugin manifest requirements.plugins/metacognitive-guard/.claude-plugin/plugin.json (1)
27-28: LGTM! Hooks declaration added.The hooks property addition follows the established pattern and is syntactically correct.
plugins/metacognitive-guard/agents/arch-reviewer.md (2)
7-12: LGTM! Model upgraded and WebSearch tool added.The opus model upgrade and WebSearch addition align with the PR's goal of improving reasoning capabilities and enabling real-time pattern verification. The YAML array format is correct.
91-105: Excellent WebSearch guidance section.The new section provides clear, actionable guidance on when to use WebSearch, complete with relevant examples and site-specific search patterns. The directive to verify rather than guess architecture patterns strengthens the review quality and reduces potential hallucinations.
The example searches demonstrating
site:learn.microsoft.comusage are particularly helpful for ensuring authoritative sources.plugins/ancplua-docs-librarian/hooks/hooks.json (1)
1-14: The nested "hooks" structure is the standard pattern in this repository.All hooks.json files across the plugins (ancplua-docs-librarian, dotnet-architecture-lint, metacognitive-guard, otelwiki) follow the same two-level nesting: root "hooks" object containing event types (SessionStart, PostToolUse, etc.), with an inner "hooks" array holding the actual hook definitions. This consistent structure is clearly intentional and represents the expected schema for Claude plugins in this codebase.
plugins/metacognitive-guard/agents/impl-reviewer.md (1)
7-12: LGTM! Model upgrade and Glob tool addition enhance capabilities.The upgrade to opus and addition of Glob tool are appropriate for the implementation reviewer's fact-checking and code discovery needs. The YAML tools array format is correct.
plugins/ancplua-docs-librarian/agents/ancplua-librarian.md (3)
4-10: LGTM! Tools format fixed and web capabilities added.The conversion to YAML array format resolves the plugin installation issue mentioned in the PR objectives. The addition of WebSearch and WebFetch aligns with the freshness-checking workflow, and the opus model upgrade enhances the librarian's reasoning capabilities.
201-210: LGTM! Clear guidance on web capabilities.The Web Capabilities section provides clear guidance on when to use WebSearch/WebFetch and appropriately distinguishes between local repositories (development source of truth) and NuGet (consumer source of truth). This aligns well with the freshness-checking workflow introduced in this PR.
161-181: NuGet endpoints and package versions are current and valid.The xUnit v3 and xunit.v3.mtp-v2 package versions (3.2.1) are currently the latest stable releases. The NuGet API endpoints are correctly formatted and functional. The technical guidance—OutputType=Exe, MTP v2 adapter requirement, and
dotnet runfor execution—is accurate. No changes needed.plugins/otelwiki/.claude-plugin/plugin.json (1)
16-17: LGTM! Hooks declaration properly added.The hooks field correctly references
./hooks/hooks.jsonand the JSON syntax is valid with proper comma placement.plugins/otelwiki/agents/otel-librarian.md (1)
4-12: LGTM! Tools format corrected and capabilities enhanced.The YAML array format is correct and resolves the installation issue. The addition of WebFetch and WebSearch enables the librarian to perform version checks and freshness validation as described in the PR objectives. The opus model upgrade enhances the agent's reasoning capabilities for complex documentation sync operations.
plugins/otelwiki/scripts/check-freshness.sh (1)
2-3: Clear design rationale.The comment explains the simplified approach well—always offering a sync opportunity at session start is a reasonable UX choice for freshness checks.
CHANGELOG.md (2)
28-34: Well-documented changes.The changelog entry accurately captures the YAML format fix, tool additions, and model upgrades. The list of affected agents provides clear traceability.
40-47: Comprehensive freshness hooks documentation.The entry clearly explains the SessionStart hook behavior, trigger conditions, and the value proposition of preventing outdated suggestions. The specific implementations for each plugin provide good detail.
Summary
toolsfield format in agents (string → YAML array) - this was causing plugins to be stuck in "installed" stateChanges
otelwiki/agents/*.mdmetacognitive-guard/agents/*.mdancplua-docs-librarian/agents/*.md*/hooks/hooks.json*/.claude-plugin/plugin.jsonTest plan
🤖 Generated with Claude Code
Summary by CodeRabbit
Bug Fixes
New Features
Improvements
✏️ Tip: You can customize this high-level summary in your review settings.