docs: improve README maintainability and add AI-CONTEXT block#130
docs: improve README maintainability and add AI-CONTEXT block#130marcusquinn merged 5 commits intomainfrom
Conversation
- Remove hardcoded version badge (2.66.0) - use dynamic GitHub release badge - Remove hardcoded lines of code badge - goes stale quickly - Add AI-CONTEXT block with quick reference for AI assistants - Fix Architecture section: remove duplicates, add proper structure - Update MCP badge to 20+ (approximate count) These changes follow maintainability guidelines from workflows/readme-create-update.md
Summary of ChangesHello @marcusquinn, 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 focuses on enhancing the 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
|
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughREADME.md was restructured to replace static version badges with dynamic badges, add an AI-context quick reference block and expanded documentation (AGENTS.md, tools, MCP/Repomix/context sections). A validation script (.agent/scripts/validate-version-consistency.sh) was updated to accept dynamic GitHub release badges and soften missing-badge handling to warnings. Changes
Sequence Diagram(s)(omitted — changes are documentation and a small script tweak without new multi-component control flow) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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 |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 21 00:24:49 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![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
The pull request effectively improves the README.md by removing stale, hardcoded badges and introducing a well-structured AI-CONTEXT block, enhancing both maintainability and machine readability. The architectural section has also been refined for better clarity and accuracy. Overall, these changes are positive and align with the stated goals.
README.md
Outdated
| - **Entry**: `aidevops` CLI, `~/.aidevops/agents/AGENTS.md` | ||
| - **Stack**: Bash scripts, TypeScript (Bun), MCP servers | ||
|
|
||
| **Key Commands**: |
There was a problem hiding this comment.
For improved semantic structure and clarity within the 'Quick Reference' section, consider using a level 3 Markdown heading (###) for 'Key Commands' instead of just bolding the text. This would make the structure more consistent and potentially easier for AI assistants to parse as distinct sub-sections.
| **Key Commands**: | |
| ### Key Commands |
README.md
Outdated
| - `aidevops update` - Update framework | ||
| - `/onboarding` - Interactive setup wizard (in AI assistant) | ||
|
|
||
| **Agent Structure**: |
There was a problem hiding this comment.
Similar to the 'Key Commands' section, using a level 3 Markdown heading (###) for 'Agent Structure' would enhance the semantic structure and consistency within the 'Quick Reference' block, improving its machine readability.
| **Agent Structure**: | |
| ### Agent Structure |
🤖 Augment PR SummarySummary: This PR improves README maintainability by removing hardcoded, quickly-stale badges and adding a machine-friendly AI context section. Changes:
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
README.md
Outdated
|
|
||
| **Agent Structure**: | ||
|
|
||
| - 14 main agents (Plan+, Build+, SEO, WordPress, etc.) |
There was a problem hiding this comment.
The AI-CONTEXT block aims to be low-maintenance, but the exact count 14 main agents is likely to drift over time (similar to the removed hardcoded badges). Consider making this count explicitly approximate (e.g., ~14 or 10+) to avoid future staleness.
Other Locations
README.md:1466
🤖 Was this useful? React with 👍 or 👎
The validator now recognizes the dynamic GitHub release badge (img.shields.io/github/v/release) as the preferred approach over hardcoded version badges that go stale. This aligns with README maintainability guidelines that recommend avoiding hardcoded counts and versions.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
README.md (2)
462-473: Architecture section improvements are good, but hardcoded counts remain.The structural changes improve clarity:
- Clear separation between dev guidance (root AGENTS.md) and user guide (.agent/AGENTS.md)
- Explicit organization: scripts/, tools/, services/, workflows/
However, the hardcoded counts at lines 465-466 ("14 main agents", "130+ helper scripts") have the same staleness issue noted in the AI-CONTEXT block review.
Additionally, removing the "+" from "14+ domain-focused agents" → "14 main agents" makes the value more brittle (exact count requires updates for any new agent).
1-1: Update the version validation script to accept dynamic GitHub release badges.The validation script at
.agent/scripts/validate-version-consistency.sh(lines 54-67) is checking for a hardcodedVersion-X.Y.Z-bluebadge pattern that was intentionally removed from README.md. The README now uses the dynamic GitHub release badge instead:[]Update the badge validation logic to either:
- Check for the dynamic GitHub release badge URL pattern instead of hardcoded version strings
- Remove the README badge validation entirely (since shields.io badges are self-updating)
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 77-98: The README's AI-CONTEXT block currently embeds hardcoded
counts (e.g., "14 main agents", "200+ subagent markdown files", "130+ helper
scripts") which will get stale; update the README to remove these fixed numbers
by replacing them with qualitative descriptors (e.g., "multiple main agents",
"extensive subagent library", "many helper scripts") or with placeholders that
are populated by a CI-updated script, and add a small note about the update
cadence; implement a helper script (suggested name:
.agent/scripts/update-readme-counts.sh) that counts actual files (main agents,
subagent markdowns, scripts) and updates the AI-CONTEXT and the Architecture
section so counts are generated dynamically during CI/release, and ensure
references to the AI-CONTEXT block and the Architecture section are updated to
use the non-hardcoded values.
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 21 00:28:33 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
Address CodeRabbit review feedback: - Change '14 main agents' to '~15 main agents' (approximate) - Change '130+ helper scripts' to '100+ helper scripts' (round number) This ensures counts remain accurate longer without frequent updates.
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 21 00:32:40 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
Address Gemini Code Assist feedback: - Change 'Key Commands' from bold to ### heading - Change 'Agent Structure' from bold to ### heading This improves machine readability and semantic consistency.
Missed one hardcoded '14 domain agents' at line 892. Changed to '~15 domain agents' for consistency.
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 21 00:40:24 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Wed Jan 21 00:41:43 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
- Update validate-version-consistency.sh with aidevops.sh, package.json, marketplace.json checks - Refactor version-manager.sh to call standalone validator instead of duplicate logic - Add validation after marketplace.json sed update to catch silent failures - Update auto-version-bump.sh with complete file list Fixes issue where version-manager.sh had its own validation logic that drifted from validate-version-consistency.sh (used by CI), causing release v2.67.0 to fail initially when PR #130 updated only the standalone script.
- Update validate-version-consistency.sh with aidevops.sh, package.json, marketplace.json checks - Refactor version-manager.sh to call standalone validator instead of duplicate logic - Add validation after marketplace.json sed update to catch silent failures - Update auto-version-bump.sh with complete file list Fixes issue where version-manager.sh had its own validation logic that drifted from validate-version-consistency.sh (used by CI), causing release v2.67.0 to fail initially when PR #130 updated only the standalone script.
- Update validate-version-consistency.sh with aidevops.sh, package.json, marketplace.json checks - Refactor version-manager.sh to call standalone validator instead of duplicate logic - Add validation after marketplace.json sed update to catch silent failures - Update auto-version-bump.sh with complete file list Fixes issue where version-manager.sh had its own validation logic that drifted from validate-version-consistency.sh (used by CI), causing release v2.67.0 to fail initially when PR #130 updated only the standalone script.
* docs: improve README maintainability and add AI-CONTEXT block - Remove hardcoded version badge (2.66.0) - use dynamic GitHub release badge - Remove hardcoded lines of code badge - goes stale quickly - Add AI-CONTEXT block with quick reference for AI assistants - Fix Architecture section: remove duplicates, add proper structure - Update MCP badge to 20+ (approximate count) These changes follow maintainability guidelines from workflows/readme-create-update.md * fix: update version validator to accept dynamic GitHub release badge The validator now recognizes the dynamic GitHub release badge (img.shields.io/github/v/release) as the preferred approach over hardcoded version badges that go stale. This aligns with README maintainability guidelines that recommend avoiding hardcoded counts and versions. * fix: use approximate counts in AI-CONTEXT and Architecture sections Address CodeRabbit review feedback: - Change '14 main agents' to '~15 main agents' (approximate) - Change '130+ helper scripts' to '100+ helper scripts' (round number) This ensures counts remain accurate longer without frequent updates. * style: use h3 headings in AI-CONTEXT block for better semantic structure Address Gemini Code Assist feedback: - Change 'Key Commands' from bold to ### heading - Change 'Agent Structure' from bold to ### heading This improves machine readability and semantic consistency. * fix: make remaining agent count approximate Missed one hardcoded '14 domain agents' at line 892. Changed to '~15 domain agents' for consistency. * 🤖 AUTO-FIX: Apply code quality improvements ✅ AUTOMATED FIXES: - Applied Qlty auto-formatting - Fixed common shellcheck issues - Updated code quality standards 🔍 ANALYSIS: - SonarCloud: 323 code smells - Codacy: Analysis completed - Qlty: Auto-formatting applied Generated by: GitHub Actions Code Review Monitoring * feat(plan-plus): add agent design subagents for planning discussions (#132) Add build-agent and agent-review to Plan+ subagents list so users can discuss agent design patterns during planning mode before implementation. * feat: add readme-helper.sh for dynamic count management (#131) * feat: add readme-helper.sh for dynamic count management - New script: readme-helper.sh with commands: - counts: Show current agent/script counts - check: Verify if README counts are stale - update: Update README counts (with --apply flag) - Updated full-loop.md: Added README check step for aidevops repo - Updated readme-create-update.md: Added dynamic counts guidance - Updated readme.md command: Added helper script reference This enables automated README maintenance and prevents count staleness. * fix: address review feedback for readme-helper.sh - Remove unnecessary SC2034 shellcheck disable (Gemini feedback) - Add caching for count functions to avoid repeated find calls (Gemini) - Guard for missing directories, return 0 instead of failing (Augment) - Align rounding logic between check and update commands (Augment) - Both now use round_scripts() and round_subagents() functions - Consistent output: 150+ subagents, 130+ scripts * style: add blank lines before fenced code blocks Fix Codacy markdown linting issues in full-loop.md and readme-create-update.md * 🤖 AUTO-FIX: Apply code quality improvements ✅ AUTOMATED FIXES: - Applied Qlty auto-formatting - Fixed common shellcheck issues - Updated code quality standards 🔍 ANALYSIS: - SonarCloud: 324 code smells - Codacy: Analysis completed - Qlty: Auto-formatting applied Generated by: GitHub Actions Code Review Monitoring * chore(release): bump version to 2.67.0 - feat: add readme-helper.sh for dynamic count management (#131) - feat(plan-plus): add agent design subagents for planning discussions (#132) - docs: improve README maintainability and add AI-CONTEXT block (#130) Also fixes version-manager.sh to accept dynamic GitHub release badges. * 🤖 AUTO-FIX: Apply code quality improvements ✅ AUTOMATED FIXES: - Applied Qlty auto-formatting - Fixed common shellcheck issues - Updated code quality standards 🔍 ANALYSIS: - SonarCloud: 328 code smells - Codacy: Analysis completed - Qlty: Auto-formatting applied Generated by: GitHub Actions Code Review Monitoring * fix: consolidate version validation to single source of truth (#133) - Update validate-version-consistency.sh with aidevops.sh, package.json, marketplace.json checks - Refactor version-manager.sh to call standalone validator instead of duplicate logic - Add validation after marketplace.json sed update to catch silent failures - Update auto-version-bump.sh with complete file list Fixes issue where version-manager.sh had its own validation logic that drifted from validate-version-consistency.sh (used by CI), causing release v2.67.0 to fail initially when PR #130 updated only the standalone script. * docs: add changelog entry for version validation fix * chore(release): bump version to 2.67.1 * 🤖 AUTO-FIX: Apply code quality improvements ✅ AUTOMATED FIXES: - Applied Qlty auto-formatting - Fixed common shellcheck issues - Updated code quality standards 🔍 ANALYSIS: - SonarCloud: 328 code smells - Codacy: Analysis completed - Qlty: Auto-formatting applied Generated by: GitHub Actions Code Review Monitoring * fix: handle dynamic GitHub release badge in version-manager.sh (#134) The README.md now uses a dynamic GitHub release badge instead of a hardcoded version badge. The version-manager.sh was still trying to update the hardcoded badge and failing when it wasn't found, which caused it to return early before updating marketplace.json. Changes: - Check for dynamic badge (img.shields.io/github/v/release) first - Skip README update if dynamic badge is used (GitHub handles it) - Only update hardcoded badge if present - Warn if no version badge found (non-fatal) This fixes the issue where marketplace.json wasn't being updated during releases because the README validation failed first. * docs: add changelog entry for dynamic badge fix * chore(release): bump version to 2.67.2 * docs: add /add-skill command to README - Add /add-skill to Meta/Improvement slash commands table - Add 'Importing External Skills' section under Cross-Tool Compatibility - Document supported formats (SKILL.md, AGENTS.md, .cursorrules) - Document features (conflict detection, version tracking, symlinks) * style: add blank line before heading in CHANGELOG (MD022) --------- Co-authored-by: GitHub Action <action@github.com>
1 participant
Summary
Changes
These changes follow maintainability guidelines from
workflows/readme-create-update.md:Version-2.66.0badgeLines of Code-18,000+badge.agent/entries20+Testing
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.