feat(plugin): add genesis-tools:explore agent#84
Conversation
… reports Adds a custom agent that replicates the built-in Explore agent's fast codebase exploration but writes a persistent markdown report to .claude/explore/. Reports survive after the subagent exits, unlike the built-in Explore agent.
Summary of ChangesHello, 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 introduces a significant enhancement to the codebase exploration capabilities by providing a new agent that not only performs deep dives into the code but also ensures that all findings are durably recorded. This addresses the limitation of the existing built-in exploration tools, which do not retain their output, thereby improving the long-term utility and referenceability of exploration results for developers. Highlights
Changelog
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
|
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughA new documentation file introduces the "Explore & Document" agent, detailing its initialization process, multi-wave exploration approach (Orient, Read Key Files, Deep Dive), persistent report storage under .claude/explore/, and formatting guidelines for generated Markdown documentation. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![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 a new genesis-tools:explore agent, defined in a markdown file. This agent is designed for in-depth codebase exploration and generates a persistent markdown report of its findings. The prompt for the agent is well-structured and provides clear, detailed instructions. My review includes one suggestion to improve the consistency of placeholders in the agent's instructions, which will help ensure its output is accurate.
Note: Security Review has been skipped due to the limited scope of the PR.
| After writing the report, return a brief summary to the caller: | ||
|
|
||
| ``` | ||
| Exploration complete. Report saved to `.claude/explore/YYYY-MM-DD-<name>.md` |
There was a problem hiding this comment.
For consistency, it's better to use the same placeholder for the report topic throughout the instructions. On line 62, you use <kebab-case-topic>, but here you use <name>. Using <kebab-case-topic> in both places will make the instructions clearer for the agent and ensure the file path in the summary message is consistent with the actual file created.
| Exploration complete. Report saved to `.claude/explore/YYYY-MM-DD-<name>.md` | |
| Exploration complete. Report saved to `.claude/explore/YYYY-MM-DD-<kebab-case-topic>.md` |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/genesis-tools/agents/explore.md`:
- Around line 121-132: Update the code block in the "Return Your Findings"
snippet so it includes a language specifier (e.g., change the opening fence to
```text) to ensure proper markdown formatting; locate the snippet under the "###
4. Return Your Findings" section (the block that starts with "Exploration
complete. Report saved to `.claude/explore/YYYY-MM-DD-<name>.md`") and change
the triple-backtick fence accordingly.
- Around line 68-113: In the "Architecture / Flow" section of
plugins/genesis-tools/agents/explore.md the inline diagram code fence needs
blank lines before and after and should declare a language for proper rendering;
update the diagram block under "Architecture / Flow" so there is an empty line
before the opening ``` and an empty line after the closing ```, and change the
opening fence to include a language token such as ```text to improve readability
and markdown rendering.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 85825182-9904-4743-a7fc-4db98431408a
📒 Files selected for processing (1)
plugins/genesis-tools/agents/explore.md
📜 Review details
⏰ 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: Agent
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2026-02-25T23:00:07.620Z
Learnt from: genesiscz
Repo: genesiscz/GenesisTools PR: 56
File: plugins/genesis-tools/commands/github-pr.md:131-131
Timestamp: 2026-02-25T23:00:07.620Z
Learning: Adopt the style: use lowercase 'markdown' (not 'Markdown') in the GenesisTools documentation. Apply this consistently across all Markdown files in the repository (any .md file), including generated docs and READMEs.
Applied to files:
plugins/genesis-tools/agents/explore.md
🪛 markdownlint-cli2 (0.21.0)
plugins/genesis-tools/agents/explore.md
[warning] 91-91: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 96-96: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 96-96: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 125-125: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (4)
plugins/genesis-tools/agents/explore.md (4)
1-12: LGTM! Clear agent metadata.The frontmatter correctly defines the agent with appropriate tools for codebase exploration and persistent documentation. The description clearly differentiates this agent from the built-in Explore agent.
14-22: LGTM! Clear introduction and differentiation.The introduction clearly establishes the agent's purpose and the first action ensures the output directory exists. The differentiation from the built-in agent is helpful context.
24-58: LGTM! Excellent structured exploration approach.The three-wave exploration strategy (Orient → Read Key Files → Deep Dive) provides a clear, efficient framework. The efficiency rules are specific and actionable, preventing exhaustive reads while ensuring thorough investigation.
115-120: LGTM! Excellent practical guidelines.The four guidelines (specific, concise, show-don't-tell, scannable) provide clear quality criteria. The emphasis on file:line references ensures reports are actionable and traceable.
| ```markdown | ||
| # [Topic Title] | ||
|
|
||
| > Explored on YYYY-MM-DD | Scope: [which directories/modules were examined] | ||
|
|
||
| ## Summary | ||
|
|
||
| [2-4 sentences answering the core question. A reader should get the gist here.] | ||
|
|
||
| ## Key Findings | ||
|
|
||
| ### [Finding 1 Title] | ||
|
|
||
| [Explanation with file references like `src/foo/bar.ts:42`] | ||
|
|
||
| ### [Finding 2 Title] | ||
|
|
||
| ... | ||
|
|
||
| ## Architecture / Flow | ||
|
|
||
| [If applicable — describe how components connect. Use a text diagram if it helps:] | ||
|
|
||
| ``` | ||
| ComponentA ──calls──▶ ComponentB ──emits──▶ EventBus | ||
| │ | ||
| ▼ | ||
| Database | ||
| ``` | ||
|
|
||
| ## File Map | ||
|
|
||
| | File | Role | | ||
| |------|------| | ||
| | `src/path/to/file.ts` | Brief description | | ||
| | `src/path/to/other.ts` | Brief description | | ||
|
|
||
| ## Code Excerpts | ||
|
|
||
| [Include only the most important/illustrative snippets — not entire files. | ||
| Use line references so the reader can jump to the source.] | ||
|
|
||
| ## Open Questions | ||
|
|
||
| [Anything unresolved or worth further investigation. Skip this section if everything is clear.] | ||
| ``` |
There was a problem hiding this comment.
Fix markdown formatting for nested code blocks.
The nested code block showing the diagram example (lines 91-96) needs formatting improvements for better readability:
- Add a blank line before the code block (after line 90)
- Add a blank line after the code block (before line 97)
- Specify a language for the code block (e.g.,
textor leave as is but add blank lines)
📝 Proposed formatting fix
[If applicable — describe how components connect. Use a text diagram if it helps:]
+
-```
+```text
ComponentA ──calls──▶ ComponentB ──emits──▶ EventBus
│
▼
DatabaseFile Map
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 91-91: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 96-96: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 96-96: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/genesis-tools/agents/explore.md` around lines 68 - 113, In the
"Architecture / Flow" section of plugins/genesis-tools/agents/explore.md the
inline diagram code fence needs blank lines before and after and should declare
a language for proper rendering; update the diagram block under "Architecture /
Flow" so there is an empty line before the opening ``` and an empty line after
the closing ```, and change the opening fence to include a language token such
as ```text to improve readability and markdown rendering.
There was a problem hiding this comment.
Pull request overview
Adds a new explore agent prompt intended to perform fast codebase exploration and write persistent Markdown reports under .claude/explore/.
Changes:
- Introduces
plugins/genesis-tools/agents/explore.mdwith frontmatter metadata, tool list, and a structured exploration/report-writing workflow - Defines a report template (summary, findings, architecture diagram, file map, excerpts) and a short “return to caller” summary format
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Use 4-backtick fence for outer template block so inner diagram fence doesn't break markdown rendering. Add language specifiers to code blocks.
Summary
genesis-tools:exploreagent that replicates the built-in Explore agent's fast codebase exploration capabilities.claude/explore/<date>-<topic>.mdHow it works
Tasktool withsubagent_type: "genesis-tools:explore"Test plan
.claude/explore/Summary by CodeRabbit