Run okf-prompt-lookup before answering knowledge-touching prompts
Run okf-prompt-lookup before answering knowledge-touching prompts
The problem: knowledge/ has 700+ concept files but agents don't grep before answering. Knowledge that's invisible to the agent is the same as knowledge that doesn't exist.
The fix: a stdlib-only TypeScript script (scripts/okf-prompt-lookup.ts, v3 2026-07-03) that scores every .md under knowledge/ by TF-IDF-weighted body + title tokens against the user prompt, with slug/phrase bonuses and synonym expansion. Returns top-N matching concept-file paths. Cache is warmed on first run and invalidated by mtime.
How each agent runs it
Claude Code
Automatic. Wired into ~/.claude/settings.json UserPromptSubmit hook. Fires on every user prompt, prepends top-3 hits as a system message. Zero agent effort.
OpenCode, MiMoCode, Antigravity, ZCode
These agents have no UserPromptSubmit equivalent (audited 2026-06-29 — see decisions/architecture/agent-tooling/okf-auto-lookup-hook-2026-06-29). They MUST run the script themselves at the start of any non-trivial task:
npx tsx C:/D/oriz/scripts/okf-prompt-lookup.ts "<the user's prompt>" --limit 3
Read the top-3 returned files before deciding the approach. Same rigor as Claude Code's automatic surfacing.
Kilo Code
Plugin route (chat.message hook) exists but requires a TypeScript/Bun plugin — deferred. Until built, Kilo follows the OpenCode pattern: run the script manually at task start.
When to skip
- Pure conversational turn ("thanks", "yes continue", "ok") — script exits 1 on short prompts anyway
- Follow-up turn where the previous turn already surfaced and read relevant knowledge
- Trivial mechanical edits (rename, typo fix) where no decision is being made
When NOT to skip
- Any architectural choice
- Any "how do I X" question
- Any prompt mentioning a domain term (auth, hosting, DNS, secrets, deploy, scaffold, env, MCP, package, etc.)
- Any prompt where you're about to answer from memory rather than from
knowledge/
Why this isn't just a soft suggestion
The auto-grep hook on CC has measured value (this session: user prompt about parallelism surfaced parallel-fan-out-by-default automatically; agent didn't have to think to grep). Fleet parity demands equivalent rigor everywhere — the harness limitation is no excuse for stale answers on personal-machine agents.
Cross-refs
- [[agent-fleet-parity]] — same rules across all agents
- [[agent-minimum-context]] — read minimum, surfaced via this hook
- [[keep-knowledge-fresh]] — read knowledge before acting, this is the mechanism