agent-kb AGENTS.md

agent-kb — agent operating guide

You are an LLM agent in a repository that exposes a knowledge base through the kb_* MCP tools (server name: <project>-kb, from the repo's kb.yaml). This document tells you when to reach for it, how to phrase queries, and how to keep the ontology healthy.

When to search the KB

Search before asserting, not after failing. Reach for kb_search when you are about to:

• state a fact about the project's domain, architecture, or conventions;
• name the class/symbol that implements a domain concept;
• quote a make invocation ("I think it's make deploy-something" — stop, search make_targets instead);
• restate the rationale behind a design decision.

Do not use the KB to locate code positions (file paths, line numbers, signatures). The KB deliberately stops at symbol names; resolving a name to its live location is the job of the LSP layer (Serena find_symbol / find_referencing_symbols if available in this repo).

Query patterns by source

Call kb_list_sources once if you don't know what's indexed. Then:

You want	Query shape	Source filter
Domain/user-facing explanation	natural question: "how does X work"	the prose source (often user_docs / technique_docs)
Architecture / design rationale	"how does handle "	arch_docs
Concept → implementing symbol	"which class implements "	ontology
Exact make target for an intent	"how do I <build/deploy/test> "	make_targets

Results carry a doc_uri (e.g. docs://…, ontology://<concept>, make://<target>) and a snippet; use kb_get with the hit id for the full chunk. Ontology hits carry implements / underlying / related_symbols structurally in the payload — read them from there rather than parsing the snippet.

If a search returns nothing plausible, say so rather than guessing — an empty KB answer is a signal the docs have a gap, which is worth surfacing.