Oma Search

Search Agent - Intent-Based Search Router

Scheduling

Goal

Classify information-seeking requests, route them to the best search channel, attach trust labels, and return source-grounded results.

Intent signature

• User asks to search, find, look up, reference docs, inspect official documentation, search GitHub/GitLab code, or gather web research.
• Another skill needs reusable search infrastructure with trust scoring.

When to use

• Finding official library/framework documentation
• Web research for tutorials, examples, comparisons, and solutions
• Searching GitHub/GitLab code for implementation patterns
• Any query where the search channel is unclear (auto-routing)
• Other skills needing search infrastructure (shared invocation)

When NOT to use

• Local codebase exploration only -> use Serena MCP directly
• Git history or blame analysis -> use SCM Agent
• Full architecture research -> use Architecture Agent (may invoke this skill internally)

Expected inputs

• Query string, intent hint, or explicit flags such as --docs, --code, --web, --strict, --wide, --gitlab
• Optional required source type, recency, domain, or trust constraints

Expected outputs

• Ranked search results with route, source, trust label, and concise relevance summary
• Fallback explanation when primary route fails
• Source links or references suitable for the calling skill

Dependencies

• Context7 MCP for docs, runtime-native web search, gh/glab for code, Serena for local search
• resources/intent-rules.md, resources/trust-registry.md, execution protocol, examples, and checklist

Control-flow features

• Branches by classified intent, user flags, route success/failure, and trust constraints
• May call web/docs/code/local tools
• Scores domains at domain level only

Structural Flow

Entry

1. Parse the query and flags. 2. Classify the search intent. 3. Select one best route unless ambiguity or flags justify more.

Scenes

1. PREPARE: Parse query and classify route. 2. ACT: Dispatch to docs, web, code, or local search. 3. ACQUIRE: Collect search results and source metadata. 4. VERIFY: Apply trust scoring and route-specific quality checks. 5. FINALIZE: Present ranked results or fallback status.

Transitions

• If --docs, --code, --web, --strict, --wide, or --gitlab is provided, flags override classifier.
• If docs route fails, fall back to web.
• If web search needs fetch escalation, use oma search fetch strategies.
• If query is purely local, use Serena MCP instead of web.

Failure and recovery

• If primary route fails, fall forward to the next appropriate route.
• If trust score is weak, label it instead of hiding uncertainty.
• If no reliable results exist, report that and suggest a narrower query.

Exit

• Success: results are routed, trust-scored, and source-grounded.
• Partial success: route failures or trust limitations are explicit.

Logical Operations

Actions

Tools and instruments

• Context7 docs tools
• Runtime-native web search
• gh search code or glab api
• Serena MCP for local project search

Canonical command path

gh search code "<query>"
glab api "/search?scope=blobs&search=<query>"

For docs and web routes, use the runtime's available official-docs or web-search tools after classifying intent; do not duplicate routes unless the intent is ambiguous.

Resource scope

Preconditions

• Query and route constraints are clear enough to classify.
• Required search tools are available or fallback is possible.

Effects and side effects

• Performs external searches or local code searches.
• Produces ranked references that may influence downstream implementation or research.

Guardrails

1. Classify intent before searching: every query goes through IntentClassifier first 2. One query, one best route: avoid redundant multi-route unless intent is ambiguous 3. Trust score every result: all non-local results get domain trust labels from the registry 4. Flags override classifier: user-provided flags (--docs, --code, --web, --strict, --wide, --gitlab) always take precedence 5. Fail forward: if primary route fails, fall back gracefully (docs->web, web->oma search fetch strategies) 6. No additional MCP required: Context7 for docs, runtime native for web, CLI for code, Serena for local 7. Vendor-agnostic web search: use whatever the current runtime provides (WebSearch, Google, Bing) 8. Domain-level trust only: do not attempt sub-path or page-level scoring

Routes

Default Workflow

1. Parse: Extract query, detect flags, classify intent 2. Route: Dispatch to the appropriate search channel(s) 3. Collect: Gather results from dispatched routes 4. Score: Attach trust labels to each result domain 5. Present: Format and rank results for the user

Invocation

Standalone

/oma-search "React Server Components streaming"
/oma-search --docs "Next.js middleware"
/oma-search --code "PKCE implementation"
/oma-search --strict "JWT refresh token rotation"

Shared Infrastructure (from other skills)

Other skills reference oma-search by specifying intent and query: 1. State intent: docs | web | code | local 2. Pass query string 3. Use Trust Score in results to weigh source reliability

References

Follow resources/execution-protocol.md step by step. See resources/examples.md for input/output examples. Use resources/intent-rules.md for intent classification reference. Use resources/trust-registry.md for domain trust scoring reference. Before submitting, run resources/checklist.md. Vendor-specific execution protocols are injected automatically by oma agent:spawn. Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.

• Execution steps: resources/execution-protocol.md
• Intent classification: resources/intent-rules.md
• Trust registry: resources/trust-registry.md
• Examples: resources/examples.md
• Checklist: resources/checklist.md
• Error recovery: resources/error-playbook.md
• Context loading: ../_shared/core/context-loading.md
• Context budget: ../_shared/core/context-budget.md
• Lessons learned: ../_shared/core/lessons-learned.md

Search Agent - Verification Checklist

Run this checklist before presenting results to the user.

Intent Classification

• [ ] Query was classified into a valid mode (docs/web/code/local)
• [ ] Override flags were respected if provided
• [ ] Classification reasoning is logged in output header ("Mode: X (auto|flag)")

Route Execution

• [ ] Correct route(s) dispatched based on classified intent
• [ ] docs route: Context7 library resolved, or fallback triggered with notice
• [ ] web route: native search attempted first, oma search fetch only on failure
• [ ] code route: platform detected from URL or default to gh
• [ ] local route: delegated to Serena without duplication

Result Quality

• [ ] Results are relevant to the original query
• [ ] No duplicate URLs in final output
• [ ] Results are sorted by relevance, trust score as tiebreaker
• [ ] Each result has: source label, title, domain, trust info

Trust Scoring

• [ ] Every non-local result has a trust label attached
• [ ] Unknown domains labeled as —, not excluded
• [ ] --strict mode correctly filters below 0.85
• [ ] --strict with 0 results shows rerun suggestion

Error Handling

• [ ] Failures reported transparently (no silent drops)
• [ ] Fallback chain followed (docs->web, web->oma search fetch)
• [ ] Rate limits reported without retry loops

Output Format

• [ ] Header shows query and mode
• [ ] Results numbered with route prefix (DOCS/WEB/CODE)
• [ ] Trust tags and scores shown in brackets
• [ ] Filtered count shown in --strict mode

Search Agent - Error Playbook

docs Route Errors

Context7 library not found

Symptom: resolve-library-id returns no match Recovery: 1. Try alternative library name spellings (e.g., "nextjs" vs "next.js") 2. If still not found: auto-fallback to web route 3. Inform user: "Could not find official docs via Context7. Falling back to web search."

Context7 returns empty/irrelevant docs

Symptom: query-docs returns content that doesn't match the query topic Recovery: 1. Try broader or narrower topic parameter 2. Fall back to web route with the original query 3. Present web results with note about docs miss

web Route Errors

Native search returns empty

Symptom: Runtime search tool returns 0 results Recovery: 1. Simplify query (remove qualifiers, keep core terms) 2. Retry with simplified query 3. If still empty: run oma search fetch <url> on candidate URLs

Native search blocked (402/403)

Symptom: Target site returns access denied Recovery: 1. Run oma search fetch <url>; this auto-escalates api → probe → impersonate → browser 2. Each strategy tries progressively more aggressive access methods 3. If all strategies fail: report "Unable to access this source"; rerun with --include-archive to try caches (AMP / archive.today / Wayback)

oma search fetch all strategies fail

Symptom: Non-zero exit code after api/probe/impersonate/browser exhausted. Recovery: 1. Read the attempts array in JSON output: strategies, elapsedMs, HTTP status, detected signals. 2. Rerun with --include-archive for cached fallbacks. 3. paywall signal → content gated; report auth requirement. 4. js-essential + browser failed → site blocks headless Chrome; suggest manual fetch or alternative source. 5. Exit code 6 (timeout) → rerun with --timeout 30 or larger.

Browser strategy cannot find Chrome

Symptom: "Chrome/Chromium not found ... or set OMA_CHROME_PATH." Recovery: 1. oma search doctor to see detection state. 2. Install Chrome / Edge / Brave / Chromium, or set OMA_CHROME_PATH. 3. Or --skip browser to rely on api/probe/impersonate only.

curl_cffi not installed (impersonate strategy)

Symptom: "curl_cffi is not installed. Run: pip install curl_cffi". Recovery: pip install curl_cffi, or --skip impersonate.

code Route Errors

gh search code rate limit

Symptom: HTTP 403 or "rate limit exceeded" from GitHub API Recovery: 1. Inform user: "GitHub API rate limit reached (30 req/min). Wait briefly or narrow your query." 2. Suggest adding language/repo qualifiers to reduce result set 3. Do NOT retry automatically in a loop

glab api authentication missing

Symptom: glab not installed or not authenticated Recovery: 1. Check if glab is available: which glab 2. If not installed: "GitLab CLI is not installed. Using GitHub search as default." 3. If not authenticated: "GitLab CLI requires authentication. Run glab auth login first." 4. Fall back to gh search code with notice

gh/glab returns 0 results

Symptom: No code matches found Recovery: 1. Suggest broader query terms 2. Suggest removing language filter if one was applied 3. Offer to try web route instead: "No code results found. Search web for examples?"

Trust Scoring Errors

Domain not in registry

Symptom: URL domain has no entry in trust-registry.md Recovery: Label as unknown with score —. Do NOT exclude from results.

--strict mode returns 0 results

Symptom: All results filtered out by trust score threshold Recovery: 1. Inform user: "No results meet the strict trust threshold (verified+)." 2. Suggest: "Rerun with --wide to see all results with trust labels."

Intent Classification Errors

Misclassified intent

Symptom: User reports results are from wrong source type Recovery: 1. Suggest explicit flag: "Try --docs or --web to specify the search type." 2. Results footer always shows: "Mode: {mode} ({auto|flag})" for transparency

docs mode returns 0, user wanted docs

Symptom: docs classified correctly but Context7 has no match Recovery: 1. Auto-add web search in parallel 2. Merge results, clearly label which came from web vs docs 3. Inform: "Official docs not found in Context7. Showing web results."

Multi-Vendor Errors

Runtime has no web search tool

Symptom: Current vendor doesn't expose a search tool Recovery: 1. Skip native search, go directly to oma search fetch <url> 2. The probe strategy (Jina Reader + curl variants) works without vendor-specific tools

Tool name mismatch across vendors

Symptom: Expected tool name doesn't exist in current runtime Recovery: Follow vendor-detection protocol to identify correct tool names. Execution protocol references generic capabilities, not specific tool names.

Search Agent - Input/Output Examples

Example 1: docs route (auto-detected)

Input:

/oma-search "React useEffect official docs"

Intent Classification:

• Keyword "official docs" detected -> docs mode

Output:

Query: "React useEffect official docs"
Mode: docs (auto)

DOCS #1  useEffect — react.dev                  [verified,lang-docs 0.95]
DOCS #2  Synchronizing with Effects — react.dev  [verified,lang-docs 0.95]
DOCS #3  useEffect API Reference — react.dev     [verified,lang-docs 0.95]

Example 2: web route (auto-detected)

Input:

/oma-search "Redis pub/sub use cases"

Intent Classification:

• Keyword "use cases" detected -> web mode

Output:

Query: "Redis pub/sub use cases"
Mode: web (auto)

WEB  #1  Redis Pub/Sub Guide — redis.io/docs     [verified,vendor-docs 0.90]
WEB  #2  Real-time Chat with Redis — dev.to      [external,blog 0.40]
WEB  #3  Redis Pub/Sub Patterns — stackoverflow   [community,qa 0.65]
WEB  #4  Redis Event-Driven Architecture — medium [external,blog 0.35]

Example 3: code route (flag override)

Input:

/oma-search --code "OAuth PKCE implementation TypeScript"

Intent Classification:

• --code flag -> skip classification, forced code mode

Output:

Query: "OAuth PKCE implementation TypeScript"
Mode: code (flag)

CODE #1  src/auth/pkce.ts — panva/oauth4webapi         [github]
CODE #2  lib/pkce.ts — auth0/nextjs-auth0               [github]
CODE #3  packages/oauth/src/pkce.ts — lucia-auth/lucia   [github]

Example 4: Ambiguous query (fallback parallel)

Input:

/oma-search "Next.js middleware"

Intent Classification:

• No clear keyword signal -> fallback web + docs parallel

Output:

Query: "Next.js middleware"
Mode: docs + web (auto)

DOCS #1  Middleware — nextjs.org/docs             [verified,lang-docs 0.95]
DOCS #2  next.config.js — nextjs.org/docs         [verified,lang-docs 0.95]
WEB  #3  Middleware Deep Dive — vercel.com/blog    [verified,vendor 0.90]
WEB  #4  Next.js Middleware Guide — freecodecamp   [external,tutorial 0.45]

Example 5: --strict mode

Input:

/oma-search --strict "JWT refresh token rotation"

Intent Classification:

• --strict modifier -> filter to verified+ (>= 0.85)
• No route flag -> fallback web + docs

Output:

Query: "JWT refresh token rotation"
Mode: docs + web (auto, strict)

DOCS #1  JWT Best Practices — datatracker.ietf.org  [verified,standards 0.95]
WEB  #2  Token Rotation — auth0.com/docs             [verified,vendor-docs 0.90]
WEB  #3  Refresh Token Rotation — auth0.com/docs       [verified,vendor-docs 0.90]

Filtered: 4 results below trust threshold (0.85). Use --wide to see all.

Example 6: GitLab code search

Input:

/oma-search --code --gitlab "CI pipeline caching strategy"

Output:

Query: "CI pipeline caching strategy"
Mode: code (flag, gitlab)

CODE #1  .gitlab-ci.yml — gitlab-org/gitlab          [gitlab]
CODE #2  ci/cache.yml — gitlab-org/omnibus-gitlab     [gitlab]
CODE #3  .gitlab-ci.yml — getsentry/sentry            [gitlab]

Example 7: Shared infrastructure call (from oma-debug)

Context: oma-debug encounters an unfamiliar error message

Internal call:

Intent: web
Query: "TypeError: Cannot read properties of undefined (reading 'map') React"

Output returned to oma-debug:

Query: "TypeError: Cannot read properties of undefined (reading 'map') React"
Mode: web (explicit)

WEB  #1  Common React Error Fix — stackoverflow      [community,qa 0.65]
WEB  #2  Handling Undefined in React — react.dev      [verified,lang-docs 0.95]
WEB  #3  TypeError Debugging — dev.to                 [external,blog 0.40]

Example 8: docs fallback to web

Input:

/oma-search --docs "htmx form validation"

Context7 fails to resolve "htmx" library.

Output:

Query: "htmx form validation"
Mode: docs -> web (fallback)

Could not find official docs via Context7. Showing web results.

WEB  #1  Form Validation — htmx.org                  [verified,lang-docs 0.90]
WEB  #2  htmx Validation Guide — dev.to              [external,blog 0.40]
WEB  #3  htmx Form Patterns — reddit.com/r/htmx      [community,forum 0.50]

Search Agent - Execution Protocol

Step 0: Parse Query

1. Extract flags from the query string:

• --docs, --code, --web: force specific route
• --strict: only verified+ sources (trust score >= 0.85)
• --wide: all sources with trust labels
• --gitlab: force glab api for code route

2. Classify intent using resources/intent-rules.md:

• If flag is present: skip classification, use flag
• If no flag: apply keyword pattern matching
• If ambiguous: use web + docs parallel (default fallback)

3. Log selected mode and route(s) for transparency

Step 1: Route Dispatch

docs route

1. Call Context7 resolve-library-id with the library/framework name 2. If resolved: call query-docs with the library ID and query topic 3. If NOT resolved: fall back to web route with notice to user

web route

1. Use runtime native search tool (WebSearch, Google Search, Bing, etc.) 2. If native search fails or returns blocked/empty:

• Enter the bypass fallback (see below)

3. Collect top results with URLs

Bypass Fallback (on native search failure)

Delegate to the native CLI: oma search fetch <url>. The pipeline auto-escalates through four strategies and stops on the first success:

• api: platform-specific handlers (Twitter syndication, Reddit JSON,

HN Firebase, arXiv Atom, SE v2.3, Bluesky AT Protocol, Mastodon, Wikipedia, CrossRef, OpenLibrary, Lobste.rs, dev.to, V2EX, npm, PyPI, Naver blog/finance).

• probe: parallel Jina Reader + WebFetch + curl UA variants (first-wins).
• impersonate: Python curl_cffi subprocess (safari→chrome→firefox;

Korean hosts prefer safari). Auto-skips remaining TLS targets on JS-essential markers.

• browser: puppeteer-core + system Chrome via CDP. No MCP runtime

dependency. Install Chrome or set OMA_CHROME_PATH.

Sidecar: add --include-archive to try AMP → archive.today → Wayback Machine when all primary strategies fail. Archive hits tag provenance so consumers can deprioritize cached content.

Flags: --only <list>, --skip <list>, --timeout <sec>, --locale <v>, --pretty. Exit codes: 0=ok, 2=blocked, 3=not-found, 4=invalid-input, 5=auth-required, 6=timeout, 1=error.

code route

1. Detect platform from user-provided URL or context:

• URL contains github.com -> use gh search code "query"
• URL contains gitlab.com -> use glab api "/search?scope=blobs&search=query"
• No URL (keyword only) -> use gh search code (default, largest OSS coverage)
• --gitlab flag -> force glab api

2. Parse CLI output into structured results 3. Include repo name, file path, and match context

local route

Delegate entirely to Serena MCP:

• find_symbol for named code entities
• search_for_pattern for arbitrary text patterns
• get_symbols_overview for structural exploration

Do NOT duplicate Serena's functionality. Simply pass through.

Step 2: Collect Results

1. Gather results from all dispatched routes 2. Normalize into uniform format:

   { source: "docs|web|code|local", title, url, domain, snippet }

3. Deduplicate by URL

Step 3: Trust Scoring

1. For each result with a URL, extract the domain 2. Resolve trust score (see resources/trust-registry.md): a. Check Serena memory cache (trust-registry-cache) b. If cache miss: apply heuristic pattern matching (domain patterns → category + score) c. If heuristic returns unknown: call Tranco API (siterank.redirect2.me) for validation 3. Attach trust level, tags, and score:

• Resolved: use level and score
• Unresolved: label as unknown with score —

4. Write newly resolved scores to Serena memory cache 5. If --strict mode: filter out results below verified (< 0.85)

• If 0 results remain: suggest --wide rerun

6. Sort by: relevance first, trust score as tiebreaker

Step 4: Present Results

Format output as:

Query: "{query}"
Mode: {mode} ({auto|flag})

{ROUTE} #{n}  {title} — {source}     [{tags} {stars} {score}]

Example:

Query: "Next.js middleware authentication"
Mode: docs + web (auto)

DOCS #1  Next.js Middleware — next.js docs     [verified,lang-docs 0.95]
DOCS #2  Authentication — next-auth.js docs    [verified,lib-docs 0.90]
WEB  #3  Middleware Auth Guide — vercel.com     [verified,vendor 0.90]
WEB  #4  Next.js Auth Tutorial — dev.to        [external,blog 0.35]
CODE #5  middleware.ts — vercel/next.js         [github]

On Error

See resources/error-playbook.md for recovery steps.

Intent Classification Rules

Classification Priority

1. Override flags: always win, skip classification entirely 2. Keyword pattern matching: scan query for mode-specific keywords 3. Signal detection: contextual clues (library name + version, error message, etc.) 4. Fallback: web + docs parallel when no clear signal

Override Flags

Keyword Patterns

docs mode

Keywords: official, docs, documentation, API ref, reference, spec, specification

Signals:

• Library/framework name + version mentioned (e.g., "React 19 docs")
• Specific API or method name + "how to use"

web mode

Keywords: example, tutorial, how to, guide, blog, comparison, vs, use case, best practice

Signals:

• Opinion/comparison queries ("X vs Y", "best way to")
• Error messages or stack traces (solution search)
• Trend or news queries

code mode

Keywords: implementation, pattern, repo, repository, source code, code search, codebase

Signals:

• Language/framework + "how is it implemented"
• Specific algorithm or pattern name
• URL containing github.com or gitlab.com

local mode

Keywords: this project, here, this file, function, class, method, variable, our code

Signals:

• References to current codebase context
• Relative file paths mentioned
• "Where is X defined" type queries

Multi-language activation (Korean, Japanese, etc.) is owned by .agents/hooks/core/triggers.json §oma-search.keywords. This file documents English mode classifiers only.

Fallback Rule

When no clear intent is detected:

• Dispatch web + docs in parallel
• Merge results with trust scoring
• Present combined ranked output

Ambiguity Resolution Examples

Trust Registry Reference

Domain trust scoring strategy for search results. Uses heuristic pattern matching + Tranco domain ranking for validation.

Trust Levels

Scoring Rules

1. Domain-level only: score applies to the entire domain, not sub-paths 2. Unknown domains are NOT excluded: they appear with — label 3. `--strict` filter: only shows results with score >= 0.85 (verified+) 4. Sort tiebreaker: when relevance is equal, higher trust score ranks first

Score Resolution

Step 1: Classify domain by pattern (category)

First match wins.

verified patterns

community patterns

external patterns

unknown

Everything not matching above patterns.

Step 2: Validate with Tranco ranking (optional)

Use the Tranco siterank API to verify domain legitimacy:

curl -s "https://siterank.redirect2.me/api/rank.json?domain={domain}"

Response:

{ "success": true, "domain": "react.dev", "rank": 12301 }
{ "success": false, "domain": "sketchy.xyz", "rank": 0 }

Tranco determines popularity, NOT content quality. Use it as a validator, not a scorer:

Rate limit: free for light non-commercial use. Do NOT call for every result. Call only when heuristic returns unknown and you need validation.

Step 3: Cache in Serena memory

Cache resolved scores to avoid re-evaluation:

write_memory("trust-registry-cache", resolved_scores)
read_memory("trust-registry-cache")

Cache is project-scoped and survives skill updates.

Lookup Algorithm

1. Extract domain from result URL (strip protocol, path, query)
2. Check Serena memory cache (trust-registry-cache)
3. If cache miss → apply heuristic pattern matching (Step 1)
4. If heuristic returns unknown → call Tranco API for validation (Step 2)
5. Attach [level, tags, score] to result
6. Write newly resolved scores to cache (Step 3)

Data Sources