john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

fix: research agents prefer native tools over shell for repo exploration

Browse Source 
Research agents (repo-research-analyst, git-history-analyzer,
best-practices-researcher, framework-docs-researcher) were using
shell commands like find, rg, cat, and chained pipelines for routine
codebase exploration. This triggers permission prompts in Claude Code
and degrades the user experience when these agents run as sub-agents.

Updated all research agents with platform-agnostic tool selection
guidance that prefers native file-search/glob, content-search/grep,
and file-read tools over shell equivalents. Shell is now reserved for
commands with no native equivalent (ast-grep, bundle show, git).
Git-history-analyzer additionally limits shell to one simple git
command per call with no chaining or piping.

Added tool selection rules to AGENTS.md so future agents follow
the same pattern by default.
This commit is contained in:
Trevin Chow
2026-03-16 20:22:55 -07:00
parent 30c06e5122
commit b290690655
6 changed files with 37 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
plugins/compound-engineering/AGENTS.md
View File

@@ -94,6 +94,18 @@ This plugin is authored once, then converted for other agent platforms. Commands
- [ ] When one skill refers to another skill, prefer semantic wording such as "load the `document-review` skill" rather than slash syntax.
- [ ] Use slash syntax only when referring to an actual published command or workflow such as `/ce:work` or `/deepen-plan`.
### Tool Selection in Agents and Skills
Agents and skills that explore codebases must prefer native tools over shell commands.
Why: shell-heavy exploration causes avoidable permission prompts in sub-agent workflows; native file-search, content-search, and file-read tools avoid that.
- [ ] Never instruct agents to use `find`, `ls`, `cat`, `head`, `tail`, `grep`, `rg`, `wc`, or `tree` through a shell for routine file discovery, content search, or file reading
- [ ] Describe tools by capability class with platform hints — e.g., "Use the native file-search/glob tool (e.g., Glob in Claude Code)" — not by Claude Code-specific tool names alone
- [ ] When shell is the only option (e.g., `ast-grep`, `bundle show`, git commands), instruct one simple command at a time — no chaining (`&&`, `||`, `;`), pipes, or redirects
- [ ] Do not encode shell recipes for routine exploration when native tools can do the job; encode intent and preferred tool classes instead
- [ ] For shell-only workflows (e.g., `gh`, `git`, `bundle show`, project CLIs), explicit command examples are acceptable when they are simple, task-scoped, and not chained together
### Quick Validation Command
```bash