Agent workflow

Use this guide when an AI agent needs repository evidence. Pick the scenario first, use the narrowest suitable tool, and finish with a source read before answering or editing.

Probe the live surface

For each new client session or subagent, verify Frigg on the live MCP tools/list or make one successful Frigg call. A parent session’s tool list and host schema files do not prove that a child received the server.

If Frigg is missing for that spawn, use the host’s shell/read fallback and report a harness registration gap. That is different from a Frigg search, ranking, or index failure. Shared HTTP lets registered clients share one runtime; it cannot register Frigg in a child that did not receive the MCP server.

Pick a scenario

Need	Start with	Follow with
Exact string or regex	`search_text`	`read_match`
Known API, type, function, or method	`search_symbol`	copied `target_ref`, navigation, then `read_match`
Vague “where is this?” question	`search_hybrid`	exact `search_text` or `search_symbol`, then proof
Several independent guesses	`search_batch`	inspect probe evidence, select a result, then proof
Files or a file outline	`list_files` or `document_symbols`	`read_file`
Usages, callers, or blast radius	`impact_bundle` with a copied target	section proof actions, then reads
AST-shaped evidence	`inspect_syntax_tree` then `search_structural`	`read_match`
Wrong repository, surprising zero, or post-edit uncertainty	`workspace`	follow its freshness or recovery action

Do not answer from a hybrid rank alone. Hybrid search is ranked discovery, so pivot to an exact tool before treating a candidate as proof.

Follow the evidence loop

Omit repository_id in normal single-repository work. Call workspace only when adoption, scope, freshness, or a surprising result changes trust.
Run the scenario’s search or listing tool.
Read completeness before interpreting a short or empty collection. Continue only with the returned opaque continuation, keeping the normalized request unchanged.
Execute authoritative next_actions by calling the named existing MCP tool with the exact arguments. Respect action order and dependencies. suggested_next is a deprecated compatibility projection.
Copy a selected row’s target_ref unchanged into navigation or impact_bundle. Do not reconstruct the target or mix target with direct symbol/location inputs.
Use read_match with the result_handle and match_id from the same producer response. Use read_file when the current path is already known.
After edits, check workspace.freshness before reusing indexed results or old proof handles.

Replace source-code shell habits

Shell habit	Frigg tool
`rg --files`	`list_files`
`rg -n "text"`	`search_text`
`rg -n "foo\|bar"`	`search_text` with `pattern_type=regex`
`rg -l "text"`	`search_text` with `files_with_matches=true`
`rg -c "text"`	`search_text` with `count_only=true`; read `total_matches`
identifier, API, type, class, or function lookup	`search_symbol`
`cat path`	`read_file`
`sed -n '10,80p' path`	`read_file` with `start_line` and `end_line`
definitions, references, implementations, or calls	navigation tools or `impact_bundle`

Use shell tools for git state and diffs, non-code files, build/test output, generated or unindexed files, explicit live-disk verification, unsupported ripgrep flags, or when Frigg is unavailable.

Done criteria

After search: read the selected source before answering or editing.
After hybrid: confirm with exact text or symbol search.
After impact analysis: inspect section trust and completeness, then read its proof targets.
After a surprising zero: use structured recovery and workspace state before leaving Frigg.
After an edit: use Work after edits and re-run a producer before reading a touched-path proof.

Source Anchors

../frigg/README.md
../frigg/skills/frigg-first-code-search/SKILL.md
../frigg/skills/frigg-first-code-search/references/discovery-and-evidence.md
../frigg/skills/frigg-first-code-search/references/navigation-and-structure.md
../frigg/skills/frigg-first-code-search/references/workspace-and-runtime.md
../frigg/crates/cli/src/mcp/guidance.rs
../frigg/crates/cli/src/mcp/types/completeness.rs
../frigg/crates/cli/src/mcp/types/next_action.rs
../frigg/crates/cli/src/mcp/types/target.rs