Skip to content
Bifrost Docs

Agent Instructions

Bifrost includes a host-neutral AGENTS.md section that tells coding agents to use structured code-intelligence tools before broad refactors or risky changes. Append it to an existing project AGENTS.md when you want agents to gather Bifrost context before planning.

Can My Agent Run RQL?

Section titled “Can My Agent Run RQL?”

This template is instruction text only. Installing or appending it does not start Bifrost MCP and does not expose query_code or any other tool. Configure a query-capable MCP server such as --mcp "symbol|extended", start a fresh agent session, and confirm that query_code is advertised before asking the agent to run a query.

MCP accepts canonical JSON inline and saved workspace .rql through query_file; it does not accept raw inline RQL. See MCP query and RQL availability for setup and validation, then use Agent Result Safety for completeness claims.

MCP-capable clients can retrieve the same guidance from the Bifrost server with resources/list and resources/read using this URI:

bifrost://agent-guidance/agents.md

Template

Section titled “Template”

Keep project-specific, agent-specific, or user-specific guidance in the existing project AGENTS.md. The template below contains only the reusable Bifrost code-intelligence guidance.

# Bifrost Code Intelligence

When planning broad refactors, risky behavior changes, or edits to large classes
or modules, use Bifrost's structured code-intelligence tools before proposing a
plan or modifying code.

- Start with `get_summaries` for the target files, directories, classes, or
  modules so the plan is grounded in the actual API shape and neighboring code.
- Use `search_symbols` to find relevant classes, functions, methods, fields, and
  modules by name before opening files manually.
- Use `get_symbol_sources` when you need the exact body of a known symbol.
- Use the available `scan_usages_by_location` or `scan_usages_by_reference`
  tool before changing existing behavior so callers, references, and related
  tests are considered.
- Use `query_code` when the question starts from a language-neutral structural
  shape rather than a known symbol. MCP accepts canonical JSON inline or a
  saved workspace `.rql` file through the exclusive `query_file` field; it does
  not accept raw inline RQL.
- Prefer analyzer-backed summaries, symbols, definitions, and usages over raw
  grep or repeated file reads for code navigation decisions.
- Trust Bifrost for alias-aware and import-aware resolution. Text search may
  miss references that use aliases, re-exports, imports, or language-specific
  indirection.

Do not claim “all callers,” “all matches,” or “no matches” from `query_code`
until all of these checks pass:

- the tool call succeeded and the active workspace is the intended one;
- `truncated` is false and no capability or execution diagnostic makes the
  requested scope partial;
- proven and unproven reference/call edges are distinguished; and
- no result used for a path-completeness claim has `provenance_truncated: true`.

If a check fails, narrow or split the query, or report the returned rows as a
qualified partial result. An importer-file edge proves a direct file import,
not a concrete symbol usage or callsite.