fix(#475): make code-reading sub-agents MCP-first by atlas-apex · Pull Request #477 · me2resh/apexyard

atlas-apex · 2026-06-01T12:36:20Z

Summary

Makes the 7 code-reading sub-agents MCP-first ([Task] MCP-first rule doesn't reach sub-agents — they grep instead of search_code #475). The standing "use MCP search before grep" rule only reached the main loop — via suggest-mcp-search.sh (which observes the main agent's Bash calls) + operator feedback memory. A spawned sub-agent runs its own loop with its own tools, so neither lever reached it. Confirmed 2026-06-01: the tech-lead sub-agent authored a curios-dog migration design entirely via grep/Read — zero search_code calls in activity.jsonl.
Adds the MCP search tools (mcp__apexyard-search__search_code + search_docs) to the tools/allowed-tools line of tech-lead, backend-engineer, frontend-engineer, data-engineer, platform-engineer, qa-engineer, security-reviewer. (code-reviewer already had search_docs; solution-architect already had both + the instruction — it's the reference implementation.)
Adds a consistent ## MCP-first code search block to each agent body: prefer search_code/search_docs over grep+Read; fall back to grep only when MCP returns nothing (e.g. project not indexed). Graceful degradation preserved — adopters without MCP see unchanged behaviour.
AgDR-0056 records the decision and why the hook route was rejected for now: extending suggest-mcp-search.sh into sub-agent contexts needs harness-level tool-call interception the current PreToolUse plumbing can't do. Prompt-level (self-discipline) matches how the main-loop rule already works.
No model-line changes — the unrelated local sonnet→opus overrides on backend/frontend-engineer were explicitly excluded (restored to dev before editing); the diff is tools-line + MCP-block only.

Testing

markdownlint-cli2 (CI ruleset) — 0 errors on the 7 agents + AgDR-0056 (only MD060 from a newer-than-CI local linter, already firing repo-wide on pre-existing tables).
Diff verified to contain no model: line changes (contamination check) — only allowed-tools/tools additions + the MCP-first prose block.
No agent-count change (edits to existing agents) → test_site_counts.sh unaffected.
Manual follow-up to verify behaviour: a spawned agent reviewing a managed project should now emit search_code entries in activity.jsonl (companion staleness gap noted below).

Note — companion gap (separate follow-up)

This PR fixes whether sub-agents use MCP. It does not address index staleness — nothing reindexes a workspace clone after git pull/merge, so search_code can return not_indexed or stale results even once agents prefer it. Filing a separate ticket for a post-pull reindex trigger; the two are companions (no point being MCP-first against a stale index).

Glossary

Term	Definition
MCP-first	Prefer `mcp__apexyard-search__search_code` / `search_docs` over `grep` + `Read`, falling back to grep only when MCP returns nothing.
Sub-agent inheritance	Whether a behaviour enforced on the main agent loop carries into agents spawned via the Agent tool — it does not for tool-call-observing hooks, which is the gap this closes at the prompt level.
activity.jsonl	The apexyard-search MCP server's query log; zero `search_code` entries for a code-reading run is the symptom this fixes.

Closes #475

The "use MCP search before grep" rule only reached the main loop (via suggest-mcp-search.sh + feedback memory); spawned sub-agents read managed-project code with grep+Read instead. Confirmed 2026-06-01: the tech-lead sub-agent authored a curios-dog design with zero search_code calls in activity.jsonl. - Add mcp__apexyard-search__search_code + search_docs to the tools/allowed-tools of the 7 code-reading agents: tech-lead, backend/frontend/data/platform-engineer, qa-engineer, security-reviewer (code-reviewer already had search_docs; solution-architect already had both — the reference implementation) - Add a consistent "## MCP-first code search" block to each agent body: prefer search_code/search_docs over grep+Read; fall back to grep only when MCP returns nothing (project not indexed). Preserves graceful degradation. - AgDR-0056 records the decision + why the hook route (extend suggest-mcp-search into sub-agent contexts) was rejected for now (harness-level, can't see sub-agent tool calls). Prompt-level (self-discipline), mirroring how the main-loop rule already works. No agent-count change; site-counts unaffected. Closes #475 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

atlas-apex

Code Review: PR #477

Commit: 9ed71963a136a61c8a3b96e1583d6c1a8d277d8c

Summary

Makes the 7 code-reading sub-agents MCP-first (#475). Each agent definition gains mcp__apexyard-search__search_code + mcp__apexyard-search__search_docs on its tools/allowed-tools line, plus a consistent ## MCP-first code search prose block in its body. Adds docs/agdr/AgDR-0056-subagent-mcp-first.md recording the decision (prompt-level over hook-level, with the hook route explicitly rejected-for-now). No application code; docs/config only.

Checklist Results

✅ Architecture & Design: Pass — purely additive agent-metadata + prose; no layering concerns.
✅ Code Quality: Pass — no code; frontmatter well-formed.
✅ Testing: N/A — agent-definition docs; site-counts unaffected (no agent count change).
✅ Security: Pass — security-reviewer keeps disallowedTools: Write, Edit; only read-class MCP tools added.
✅ Performance: Pass — the change reduces token cost (semantic search over grep+Read).
✅ PR Description & Glossary: Pass — Summary, Testing, Glossary, Closes #475, and AgDR marker all present.
✅ Summary Bullet Narrative: Pass — every bullet is a bold-lead narrative sentence with verb + rationale.
✅ Technical Decisions (AgDR):Pass — AgDR-0056 included and referenced via .
✅ Adopter Handbooks: N/A — diff is .md-only (agents + AgDR); no language handbooks load, and the always-load handbooks (clean-architecture, migration-safety, commit-quality) target application code, not framework docs.

Issues Found

None.

Verifications performed:

Contamination check (model: lines): grep -E '^[+-]\s*model:' against the full diff returns NOTHING. The unrelated local sonnet→opus overrides on backend/frontend-engineer were correctly excluded. ✅ Clean.
Frontmatter validity: each addition matches the file's existing key — backend/frontend/data/platform/qa extend allowed-tools:; security-reviewer extends tools: (and keeps disallowedTools: Write, Edit untouched). All remain valid comma-separated single-line lists; no YAML breakage. ✅
MCP-first block consistency: identical wording across all 7, with two intentional role-specific tailorings — tech-lead adds "(e.g. authoring a technical design against an existing service)" and security-reviewer adds "during a review". Both are appropriate, not drift. ✅
Agent count: edits to existing agents only; no new/removed agent files → test_site_counts.sh unaffected. ✅
AgDR-0056: follows the template (context / options / decision / consequences / artifacts), correctly documents why the hook route was rejected so a future maintainer doesn't re-investigate. ✅

CI Note (merge-time, not a code-review blocker)

lychee is currently red, but the failure is an unrelated external flake:

[500] https://claude.com/claude-code in docs/getting-started.md — a file not touched by this PR, and a server-side 500 (transient), not a broken link introduced here.
markdownlint-cli2 ✅ pass, Verify Ticket ID ✅ pass.

This does NOT affect the code-review verdict. However, per .claude/rules/pr-quality.md § "No Red CI Before Merge", the merge gate will still block until CI is green. Before merge: re-run the lychee job (or wait for claude.com to recover) so all checks are green. Do not merge on red CI even though this failure is pre-existing and unrelated.

Verdict

APPROVED (code-review side). Re-run the flaky lychee check to green before merging.

🤖 Reviewed by Rex (Code Reviewer Agent)
📌 Reviewed commit: 9ed71963a136a61c8a3b96e1583d6c1a8d277d8c

The "use MCP search before grep" rule only reached the main loop (via suggest-mcp-search.sh + feedback memory); spawned sub-agents read managed-project code with grep+Read instead. Confirmed 2026-06-01: the tech-lead sub-agent authored a curios-dog design with zero search_code calls in activity.jsonl. - Add mcp__apexyard-search__search_code + search_docs to the tools/allowed-tools of the 7 code-reading agents: tech-lead, backend/frontend/data/platform-engineer, qa-engineer, security-reviewer (code-reviewer already had search_docs; solution-architect already had both — the reference implementation) - Add a consistent "## MCP-first code search" block to each agent body: prefer search_code/search_docs over grep+Read; fall back to grep only when MCP returns nothing (project not indexed). Preserves graceful degradation. - AgDR-0056 records the decision + why the hook route (extend suggest-mcp-search into sub-agent contexts) was rejected for now (harness-level, can't see sub-agent tool calls). Prompt-level (self-discipline), mirroring how the main-loop rule already works. No agent-count change; site-counts unaffected. Closes #475 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

atlas-apex commented Jun 1, 2026

View reviewed changes

atlas-apex merged commit 9f92f07 into me2resh:dev Jun 1, 2026
3 of 4 checks passed

atlas-apex mentioned this pull request Jun 1, 2026

[Task] MCP-first rule doesn't reach sub-agents — they grep instead of search_code #475

Closed

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(#475): make code-reading sub-agents MCP-first#477

fix(#475): make code-reading sub-agents MCP-first#477
atlas-apex merged 1 commit into
me2resh:devfrom
atlas-apex:fix/GH-475-subagent-mcp-first

atlas-apex commented Jun 1, 2026

Uh oh!

atlas-apex left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

atlas-apex commented Jun 1, 2026

Summary

Testing

Note — companion gap (separate follow-up)

Glossary

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Code Review: PR #477

Summary

Checklist Results

Issues Found

CI Note (merge-time, not a code-review blocker)

Verdict

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants