Prefer FFF for search guidance (#532)

The managed Codex/Claude instructions already mentioned fff, but the RTK guidance could still read as if RTK should wrap file search first. This records fff MCP as the first-choice search surface whenever it is available, with RTK and rg as fallbacks only.

Constraint: fff is client-provided MCP capability and is not always available.

Rejected: Require fff-mcp as a global Guardex dependency | current status tests intentionally keep fff-mcp out of global service requirements.

Confidence: high

Scope-risk: narrow

Directive: Keep file-search ordering fff MCP first, RTK shell wrappers second.

Tested: rtk test node --test test/prompt.test.js

Tested: rtk test node --test test/setup.test.js

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

AGENTS.md

@@ -373,6 +373,7 @@ GUARDEX_ON=1
 - Work from an `agent/*` branch and worktree, never directly on the protected base branch.
 - Claim files before edits.
 - Use Colony for coordination before falling back to OMX state/notepad.
+- Prefer fff MCP tools for file search whenever available; do not route file search through RTK when fff can answer it.
 - Use OpenSpec for durable behavior contracts and change-driven work.
 - Keep outputs compact: less word, same proof.
 - Commit, push, and open/update a PR for completed work unless the user explicitly says to keep it local.
@@ -480,6 +481,12 @@ Default: less word, same proof.
 - Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases.
 - Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
 
+### FFF file search
+
+Use the fff MCP tools for all file search operations instead of default tools, including RTK shell wrappers.
+
+If fff MCP tools are unavailable in the current client, fall back to `rtk grep`, `rtk find`, `rtk ls`, or `rg` and keep output compact.
+
 ### Caveman style
 
 Commentary and progress updates use smart-caveman `ultra` by default:

templates/AGENTS.multiagent-safety.md

@@ -27,7 +27,7 @@ GUARDEX_ON=1
 - Work from an `agent/*` branch and worktree, never directly on the protected base branch.
 - Claim files before edits.
 - Use Colony for coordination before falling back to OMX state/notepad.
-- Use the fff MCP tools for all file search operations instead of default tools.
+- Prefer fff MCP tools for file search whenever available; do not route file search through RTK when fff can answer it.
 - Use OpenSpec for durable behavior contracts and change-driven work.
 - Keep outputs compact: less word, same proof.
 - Commit, push, and open/update a PR for completed work unless the user explicitly says to keep it local.
@@ -137,7 +137,7 @@ Default: less word, same proof.
 
 ### RTK command compression
 
-When `rtk` is available, prefer it for noisy shell discovery and verification.
+When `rtk` is available, prefer it for noisy shell discovery and verification. For file search, fff MCP takes precedence whenever available.
 
 - Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.
 - Git and GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.
@@ -150,9 +150,9 @@ When `rtk` is available, prefer it for noisy shell discovery and verification.
 
 ### FFF file search
 
-Use the fff MCP tools for all file search operations instead of default tools.
+Use the fff MCP tools for all file search operations instead of default tools, including RTK shell wrappers.
 
-If fff MCP tools are unavailable in the current client, fall back to `rtk grep`, `rtk ls`, or `rg` and keep output compact.
+If fff MCP tools are unavailable in the current client, fall back to `rtk grep`, `rtk find`, `rtk ls`, or `rg` and keep output compact.
 
 ### Caveman style
 

test/prompt.test.js

@@ -165,7 +165,8 @@ test('prompt --snippet prints the managed AGENTS template with token budget and
   assert.match(result.stdout, /rtk git status/);
   assert.match(result.stdout, /Do not wrap machine-readable commands with RTK/);
   assert.match(result.stdout, /### FFF file search/);
-  assert.match(result.stdout, /Use the fff MCP tools for all file search operations instead of default tools\./);
+  assert.match(result.stdout, /For file search, fff MCP takes precedence whenever available\./);
+  assert.match(result.stdout, /Use the fff MCP tools for all file search operations instead of default tools, including RTK shell wrappers\./);
   assert.match(result.stdout, /If fff MCP tools are unavailable in the current client/);
   assert.match(result.stdout, /### Caveman style/);
   assert.match(result.stdout, /Answer order stays fixed: answer first, cause next, fix or next step last\./);