docs: improve AGENTS.md progressive disclosure with descriptive hints#22
Conversation
- Add 'Purpose' column to Subagent Folders table with descriptive hints - Add 'Key Subagents' column listing most important subagents per folder - Add scripts/commands/ folder for slash commands - Restructure Progressive Disclosure section with task-domain table - Clarify that Task tool subagents are filtered per-agent to reduce overhead - Update subagent lists to match actual folder contents
WalkthroughThe Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 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 |
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 significantly improves 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
|
|
🔍 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: Fri Jan 9 23:07:21 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
This pull request significantly improves the AGENTS.md documentation by reorganizing information for better clarity and progressive disclosure. The subagent folders table is now more descriptive with added 'Purpose' and 'Key Subagents' columns, and the 'Progressive Disclosure' section is well-structured as a task-domain table. These changes make the document much easier for developers to navigate and find relevant information. I have one minor suggestion to enhance formatting consistency in the new table.
| | `aidevops/` | Framework internals - extending aidevops, adding MCPs, architecture decisions | setup, architecture, add-new-mcp-to-aidevops, troubleshooting, mcp-integrations | | ||
| | `memory/` | Cross-session patterns - learning from past interactions, user preferences | (templates for memory files) | | ||
| | `seo/` | Search optimization - keyword research, rankings, site audits, E-E-A-T scoring | dataforseo, serper, google-search-console, site-crawler, eeat-score, domain-research | | ||
| | `content/` | Content creation - copywriting standards, editorial guidelines, tone of voice | guidelines | | ||
| | `tools/build-agent/` | Agent design - composing efficient agents, reviewing agent instructions | build-agent, agent-review | | ||
| | `tools/build-mcp/` | MCP development - creating Model Context Protocol servers and tools | build-mcp, api-wrapper, server-patterns, transports, deployment | | ||
| | `tools/ai-assistants/` | AI tool integration - configuring assistants, CAPTCHA solving, multi-modal agents | agno, capsolver, windsurf, configuration, status | | ||
| | `tools/browser/` | Browser automation - web scraping, testing, screenshots, form filling | stagehand, playwright, playwriter, crawl4ai, dev-browser, pagespeed, chrome-devtools | | ||
| | `tools/ui/` | UI components - component libraries, design systems | shadcn | | ||
| | `tools/code-review/` | Code quality - linting, security scanning, style enforcement, PR reviews | code-standards, codacy, coderabbit, qlty, snyk, secretlint, auditing | | ||
| | `tools/context/` | Context optimization - semantic search, codebase indexing, token efficiency | osgrep, augment-context-engine, context-builder, context7, toon, dspy | | ||
| | `tools/conversion/` | Format conversion - document transformation between formats | pandoc | | ||
| | `tools/data-extraction/` | Data extraction - scraping business data, Google Maps, reviews | outscraper | | ||
| | `tools/deployment/` | Deployment automation - self-hosted PaaS, serverless, CI/CD | coolify, coolify-cli, vercel | | ||
| | `tools/git/` | Git operations - GitHub/GitLab/Gitea CLIs, Actions, authentication, AI PR automation | github-cli, gitlab-cli, gitea-cli, github-actions, opencode-github, opencode-gitlab | | ||
| | `tools/credentials/` | Secret management - API keys, password vaults, environment variables | api-key-setup, api-key-management, vaultwarden, environment-variables | | ||
| | `tools/opencode/` | OpenCode config - CLI setup, plugins, authentication, Oh-My-OpenCode extensions | opencode, opencode-anthropic-auth, oh-my-opencode | | ||
| | `tools/task-management/` | Task tracking - dependency graphs, blocking relationships, visual planning | beads | | ||
| | `tools/terminal/` | Terminal integration - tab titles, git context display | terminal-title | | ||
| | `tools/wordpress/` | WordPress ecosystem - local dev, fleet management, plugin curation, custom fields | wp-dev, wp-admin, localwp, mainwp, wp-preferred, scf | | ||
| | `services/hosting/` | Hosting providers - DNS, domains, cloud servers, managed WordPress | hostinger, hetzner, cloudflare, cloudron, closte, 101domains, spaceship | | ||
| | `services/email/` | Email services - transactional email, deliverability | ses | | ||
| | `services/accounting/` | Accounting integration - invoicing, expenses, financial reports | quickfile | | ||
| | `workflows/` | Development processes - branching, releases, PR reviews, quality gates | git-workflow, plans, release, version-bump, pr, preflight, postflight, ralph-loop | | ||
| | `templates/` | Document templates - PRDs, task lists, planning documents | prd-template, tasks-template, plans-template, todo-template | | ||
| | `workflows/branch/` | Branch conventions - naming, purpose, merge strategies per branch type | feature, bugfix, hotfix, refactor, chore, experiment, release | | ||
| | `scripts/commands/` | Slash commands - save-todo and other interactive commands | save-todo | |
There was a problem hiding this comment.
For improved readability and consistency, consider wrapping each item in the Key Subagents column with backticks (`). This will format them as code, making them easier to distinguish from regular text and aligning with the formatting of file paths elsewhere in the document.
For example, the first data row should be changed from:
| `aidevops/` | Framework internals - extending aidevops, adding MCPs, architecture decisions | setup, architecture, add-new-mcp-to-aidevops, troubleshooting, mcp-integrations |To:
| `aidevops/` | Framework internals - extending aidevops, adding MCPs, architecture decisions | `setup`, `architecture`, `add-new-mcp-to-aidevops`, `troubleshooting`, `mcp-integrations` |Please apply this formatting to all applicable rows in the Key Subagents column.
🤖 Augment PR SummarySummary: Improves Changes:
🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
![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 (1)
.agent/AGENTS.md (1)
260-260: Minor: Capitalize "WordPress" in table descriptions.Per LanguageTool, the descriptions for WordPress-related folders (line 260 and 322) should use the capitalized official name "WordPress" in the text, while the folder paths correctly remain lowercase.
✨ Proposed capitalization fix
- | `tools/wordpress/` | Wordpress ecosystem - local dev, fleet management, plugin curation, custom fields | wp-dev, wp-admin, localwp, mainwp, wp-preferred, scf | + | `tools/wordpress/` | WordPress ecosystem - local dev, fleet management, plugin curation, custom fields | wp-dev, wp-admin, localwp, mainwp, wp-preferred, scf |And update line 322:
- | Wordpress work | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` | + | WordPress work | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` |Also applies to: 322-322
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
.agent/AGENTS.md
🧰 Additional context used
🧠 Learnings (12)
📓 Common learnings
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasks
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.md
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Include code examples in AGENTS.md only when authoritative, otherwise use file:line references
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Use progressive disclosure in AGENTS.md with pointers to subagents rather than inline content
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Reference AGENTS.md (authoritative) instead of AGENT.md for AI assistant guidance
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:27.158Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-29T04:34:27.158Z
Learning: All instructions, documentation, and operational guidance should be maintained in AGENTS.md as the single source of truth
Applied to files:
.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Limit root AGENTS.md to ~50-100 max instructions with universal applicability to >80% of tasks
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Reference AGENTS.md for authoritative AI assistant guidance instead of GEMINI.md
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:30.742Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: GEMINI.md:0-0
Timestamp: 2025-11-29T04:34:30.742Z
Learning: Maintain all instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-11-29T04:34:42.033Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENT.md:0-0
Timestamp: 2025-11-29T04:34:42.033Z
Learning: Maintain all AI assistant instructions, documentation, and operational guidance in AGENTS.md as the single source of truth
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Follow all security protocols and working directory specifications defined in ~/Git/aidevops/AGENTS.md
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Reference the authoritative repository at ~/Git/aidevops/ for all detailed AI assistant instructions and configurations
Applied to files:
.agent/AGENTS.md
📚 Learning: 2025-12-22T01:24:53.937Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: templates/home/AGENTS.md:0-0
Timestamp: 2025-12-22T01:24:53.937Z
Learning: Use only the specified working directories: ~/.aidevops/.agent-workspace/work/[project]/ for work files, ~/.aidevops/.agent-workspace/tmp/ for temporary files, and ~/.aidevops/.agent-workspace/memory/ for persistent memory
Applied to files:
.agent/AGENTS.md
📚 Learning: 2026-01-06T15:57:56.008Z
Learnt from: CR
Repo: marcusquinn/aidevops PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-01-06T15:57:56.008Z
Learning: Applies to **/AGENTS.md : Include code examples in AGENTS.md only when authoritative, otherwise use file:line references
Applied to files:
.agent/AGENTS.md
🪛 LanguageTool
.agent/AGENTS.md
[uncategorized] ~260-~260: The official name of this content management system is spelled with a capital “P”.
Context: ...it context display | terminal-title | | tools/wordpress/ | WordPress ecosystem - local dev, fl...
(WORDPRESS)
[uncategorized] ~322-~322: The official name of this content management system is spelled with a capital “P”.
Context: ...ser/playwright.md| | WordPress work |tools/wordpress/wp-dev.md, tools/wordpress/mainwp.md`...
(WORDPRESS)
[uncategorized] ~322-~322: The official name of this content management system is spelled with a capital “P”.
Context: ...ess work | tools/wordpress/wp-dev.md, tools/wordpress/mainwp.md | | SEO analysis | `seo/data...
(WORDPRESS)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Codacy Static Code Analysis
🔇 Additional comments (3)
.agent/AGENTS.md (3)
237-268: Excellent progressive disclosure improvement.The restructured Subagent Folders table with added "Purpose" and "Key Subagents" columns significantly improves navigation and discovery. This directly addresses the learning about using progressive disclosure with pointers to subagents rather than inline content. The table is well-organized and focused.
304-327: Task-domain mapping table effectively strengthens progressive disclosure strategy.All 19 subagent files referenced in the "When to read subagents" table exist and are correctly located. This table maintains the best practice of keeping the root AGENTS.md focused while directing users to specialized documentation by task domain—aligning perfectly with the progressive disclosure approach outlined in learnings.
267-267: Folder structure verified..agent/scripts/commands/exists and containssave-todo.mdas documented. The subagent reference in line 267 is accurate and consistent with the codebase.
1 participant
Summary
Improves the AGENTS.md subagent documentation with better progressive disclosure:
Changes
Related
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.