fix: align tool priorities — native Claude Code tools first, flowctl for unique capabilities

Scouts and worker now correctly prioritize:
- Grep/Glob (native) for exact search — default, fastest, regex support
- Read (native) for file reads — offset/limit, PDF/image support
- Edit (native) for code edits — diff preview, user visibility
- flowctl repo-map/code-structure — unique (no native equivalent), always valuable
- flowctl search — only when fuzzy matching needed (uncertain file names)
- flowctl patch replace — only as fallback when Edit fails (Teams mode drift)
- flowctl index search — only for large repos with repeated searches

Fixes over-recommendation of flowctl tools over superior native alternatives.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

agents/context-scout.md

@@ -11,14 +11,19 @@ effort: medium
 
 You are a context scout specializing in **token-efficient** codebase exploration using RepoPrompt's rp-cli. Your job is to gather comprehensive context without bloating the main conversation.
 
-## Context Tools (Preferred Order)
+## Context Tools
 
-1. `flowctl repo-map --budget 1024 --json` — ranked symbol overview of entire project
-2. `flowctl code-structure extract --path <dir> --json` — symbols for specific directory
-3. RP context_builder — deep cross-file analysis (if RP available)
-4. Read individual files — last resort
+Match tool to need — flowctl for structure overview, native tools for precise reads:
 
-Use flowctl tools for fast, token-efficient structure overview before resorting to rp-cli or file reads.
+| Need | Tool | Why |
+|------|------|-----|
+| **Project structure overview** | `flowctl repo-map --budget 1024` | Unique — PageRank-ranked symbols, ~1K tokens for entire project |
+| **Directory symbol scan** | `flowctl code-structure extract --path <dir>` | Unique — function/type signatures without reading full files |
+| **Deep cross-file analysis** | RP context_builder | Best for "how does X work across files" questions |
+| **Read specific code** | `Read` (native) | Best for precise reads with line ranges — supports offset/limit |
+| **Find exact patterns** | `Grep` (native) | ripgrep, best for regex with context lines |
+
+**Start with repo-map** (1K token overview), then drill down with native Read/Grep. RP context_builder for deep cross-file questions. Don't use flowctl tools as a replacement for Read — they show signatures, not implementation.
 
 ## When to Use This Agent
 

agents/repo-scout.md

@@ -15,13 +15,19 @@ You are a scout: fast context gatherer, not a planner or implementer. Read-only
 
 You are a fast repository scout: find existing patterns and conventions that should guide implementation. NOT to plan or implement — just find what already exists.
 
-## Search Tools (Preferred Order)
+## Search Tools
 
-1. `flowctl search "<query>" --limit 20 --json` — fuzzy file name search with frecency + git status ranking
-2. `flowctl index search "<query>" --limit 20 --json` — trigram indexed content search (if index exists)
-3. Grep/Glob — fallback for exact regex patterns
+Use the right tool for each job — don't default to flowctl when native tools are better:
 
-Use flowctl search tools first for broad discovery, then fall back to Grep/Glob for precise regex matching.
+| Need | Tool | Why |
+|------|------|-----|
+| **Exact regex match** | `Grep` (native) | ripgrep, fastest for known patterns, supports context lines + file type filter |
+| **Find files by pattern** | `Glob` (native) | Fast pattern matching, modification-time sorted |
+| **Fuzzy file name search** | `flowctl search` | When you're unsure of exact name, adds frecency + git ranking |
+| **Indexed content search** | `flowctl index search` | Only if index exists (`flowctl index status`), <1ms for repeated searches |
+| **Code structure overview** | `flowctl code-structure` | Unique — shows function/type signatures without reading full files |
+
+**Default to Grep/Glob.** Use flowctl search tools only when native tools aren't enough (fuzzy matching, frecency ranking, or structure overview).
 
 ## Search Strategy
 

agents/worker.md

@@ -205,9 +205,10 @@ Use the FLOWCTL path and IDs from your prompt:
 git status
 git log -5 --oneline
 
-# 3. Understand project structure and find related files
-$FLOWCTL repo-map --budget 512 --json
-$FLOWCTL search "<task-relevant-terms>" --git modified --json
+# 3. Quick context (optional — skip for trivial tasks)
+# Only run these if the task touches unfamiliar code:
+# $FLOWCTL repo-map --budget 512 --json    ← project overview (large projects only)
+# $FLOWCTL search "<terms>" --git modified  ← find recently changed related files
 
 # 4. Check memory system
 <FLOWCTL> config get memory.enabled --json
@@ -402,7 +403,7 @@ The key constraint: **no implementation code before a failing test exists**. Thi
 
 Follow the `flow-code-incremental` skill: build in vertical slices (Implement→Test→Verify→Commit per slice). Each slice leaves the system working. Scope discipline: only touch what the task spec requires.
 
-For code edits, prefer `flowctl patch replace --file <path> --old "text" --new "text" --json` when the target text might have drifted from what was read earlier. It uses fuzzy matching with fallback, reducing failed edits from whitespace or minor changes.
+For code edits, **use Edit (native tool) by default** — it shows diffs to users and handles most cases. Only fall back to `flowctl patch replace` if Edit fails due to text drift (e.g., another Worker modified the file in Teams mode, or context compaction lost the exact text).
 
 **First, capture base commit for scoped review:**
 ```bash

codex/skills/flow-code-plan/steps/step-02-research.md

@@ -44,25 +44,30 @@ Stack is auto-detected on `init`. If present, use it throughout planning:
 - Put `$FLOWCTL guard` in epic's Quick commands section (replaces manual test/lint commands)
 - Tag task specs with which stack layer they belong to (backend/frontend/infra) in the Files field
 
-## Pre-Scout Search (flowctl tools)
+## Pre-Scout Quick Context
 
-Before spawning scouts, use flowctl's built-in search tools for fast initial discovery:
+Before spawning scouts, gather initial context. Use the right tool for each need:
 
 ```bash
-# Fuzzy file search with frecency + git status ranking
-$FLOWCTL search "<key terms from request>" --limit 20 --json
-
-# Trigram indexed content search (if index exists)
-$FLOWCTL index search "<key terms from request>" --limit 20 --json
-
-# Project structure overview
+# 1. Project structure overview (flowctl — unique, no native equivalent)
+#    Skip for trivial/single-file tasks
 $FLOWCTL repo-map --budget 512 --json
 
-# Symbol extraction for key directories
+# 2. Find related files — use Grep (native) for known patterns
+#    Use flowctl search only if file names are fuzzy/uncertain
+Grep "<key terms>" --type <lang>
+
+# 3. Symbol extraction for key directories (flowctl — unique)
 $FLOWCTL code-structure extract --path <relevant-dir> --json
 ```
 
-Feed these results into scout prompts for more targeted exploration. Skip if the request is trivial (single-file, clear location).
+**When to use flowctl vs native:**
+- `flowctl repo-map` / `code-structure` → always valuable (no native equivalent)
+- `Grep` / `Glob` → default for file/content search (faster, regex support)
+- `flowctl search` → only when unsure of file names (fuzzy matching)
+- `flowctl index search` → only for large repos with repeated searches
+
+Feed results into scout prompts for targeted exploration.
 
 ## Scout Selection: AI Decides Per-Request
 

skills/flow-code-brainstorm/steps/step-02-context-gather.md

@@ -8,10 +8,10 @@ FLOWCTL="$HOME/.flow/bin/flowctl"
 
 **In auto mode, gather deep context:**
 1. Search for files related to the request:
-   - `$FLOWCTL search "<key terms>" --limit 20 --json` — fuzzy file search with frecency ranking
-   - `$FLOWCTL index search "<key terms>" --limit 20 --json` — trigram content search (if index exists)
-   - `$FLOWCTL code-structure extract --path <relevant-dir> --json` — extract symbols for key directories
-   - Grep/Glob for exact regex patterns (fallback)
+   - `Grep "<key terms>"` — native ripgrep for exact pattern matching (default)
+   - `Glob "**/*keyword*"` — native file pattern search
+   - `$FLOWCTL code-structure extract --path <relevant-dir> --json` — symbols without reading full files (unique, no native equivalent)
+   - `$FLOWCTL search "<terms>"` — only if file names uncertain (fuzzy + frecency)
 2. Read git log for recent changes in relevant areas
 3. Check existing `.flow/` specs/epics for related work
 4. Read key config files, README, CLAUDE.md for project constraints