docs: improve AGENTS.md progressive disclosure with descriptive hints

[marcusquinn]

Summary

Improve the progressive disclosure in main AGENTS.md with better descriptive hints for subagent folders.

Changes

• Reorganize AGENTS.md structure for better readability
• Add descriptive hints to subagent folder references
• Improve navigation for users discovering the framework

[coderabbitai]

Warning

Rate limit exceeded

@marcusquinn has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 14 minutes and 12 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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.

📥 Commits

Reviewing files that changed from the base of the PR and between a361dc6 and 38b427a.

📒 Files selected for processing (1)

• .agent/AGENTS.md

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello @marcusquinn, I'm Gemini Code Assist¹! 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 AGENTS.md documentation by restructuring its content and providing more detailed, context-driven guidance for subagent folders. The changes aim to enhance the progressive disclosure of information, making it easier for users to navigate and understand the framework's specialized capabilities without being overwhelmed by unnecessary details.

Highlights

• Documentation Structure Improvement: The AGENTS.md file has been reorganized to enhance readability and user navigation, particularly in the 'Subagent Folders' section.
• Enhanced Subagent Descriptions: The 'Subagent Folders' table now includes 'Purpose' and 'Key Subagents' columns, offering more descriptive hints and specific examples for each folder's content.
• Refined Progressive Disclosure Guidance: The section on progressive disclosure has been updated with a clearer strategy and explicit instructions on when and how to use subagents, including a new table format for specific recommendations.
• New Subagent Entry: A new scripts/commands/ entry has been added to the subagent folders list, detailing its purpose for interactive slash commands.

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the AGENTS.md documentation. The reorganization of the "Subagent Folders" section into a more descriptive three-column table and the restructuring of the "Progressive Disclosure" section with clearer instructions and a table-based guide are excellent changes. These modifications enhance readability and make it easier for users to navigate and understand the framework's subagents.

[gemini-code-assist]

For consistency with the other entries in the "Key Subagents" column, consider removing the parentheses around "templates for memory files". This will make the table formatting uniform across all rows.

Suggested change

	| `memory/` | Cross-session patterns - learning from past interactions, user preferences | (templates for memory files) |
	| `memory/` | Cross-session patterns - learning from past interactions, user preferences | templates for memory files |

[gemini-code-assist]

The new table under "When to read subagents" is a great improvement in structure and clarity. However, it seems a couple of items from the previous list were removed. Consider if it would be beneficial to add entries for "Service operations" and "Oh-My-OpenCode integration" to this table for completeness, as they were present in the previous version of this guide.

For example:

| Task Domain                | Read These                         |
|----------------------------|------------------------------------|
| ...                        | ...                                |
| Service operations         | `services/[type]/[provider].md`    |
| Oh-My-OpenCode integration | `tools/opencode/oh-my-opencode.md` |

[augmentcode]

🤖 Augment PR Summary

Summary: Updates .agent/AGENTS.md to make subagent discovery and “progressive disclosure” clearer, so users/assistants can pull in the right domain docs without overloading context.

Changes:

• Replaces the Subagent Folders list with a 3-column table (Folder/Purpose/Key Subagents) and adds descriptive hints.
• Adds a scripts/commands/ entry to document slash-command subagents.
• Rewrites the Progressive Disclosure section into an explicit strategy plus “how to use subagents” steps.
• Adds a task-domain → recommended subagent files table for faster navigation.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.

[marcusquinn]

Closing: changes already included in main