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

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

Scenes

• PREPARE: Parse query and classify route.
• ACT: Dispatch to docs, web, code, or local search.
• ACQUIRE: Collect search results and source metadata.
• VERIFY: Apply trust scoring and route-specific quality checks.
• 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

| Action | SSL primitive | Evidence |

|--------|---------------|----------|

| Parse query and flags | READ | User request |

| Classify intent | SELECT | Intent rules |

| Dispatch search route | CALL_TOOL | Docs, web, code, local tools |

| Collect results | READ | Search outputs |

| Score trust | VALIDATE | Trust registry |

| Rank and format | INFER | Relevance and trust |

| Report results | NOTIFY | Final answer |

Tools and instruments

• Context7 docs tools
• Runtime-native web search
• oma search CLI primitives: fetch, code, trust, api, api:search, meta, rss, rss:google, media, archive, doctor
• Serena MCP for local project search

Canonical command path

oma search code "<query>" [--host gitlab] [--language <lang>] [--repo <owner/repo>]
oma search trust <domain>
oma search fetch <url>

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

| Scope | Resource target |

|-------|-----------------|

| NETWORK | Web/docs/source-code search targets |

| CODEBASE | Local files when local search is selected |

| PROCESS | gh, glab, and CLI search commands |

| MEMORY | Query classification, trust labels, selected results |

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

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

Routes

| Route | Primary Tool | Fallback | Trigger |

|-------|-------------|----------|---------|

| docs | Context7 MCP (resolve-library-id → query-docs) | web route | Official docs, API reference |

| web | Runtime native search | oma search fetch (api/probe/impersonate/browser) | Tutorials, examples, solutions |

| code | oma search code (wraps gh / glab) | (none) | Implementation patterns, repos |

| local | Serena MCP (delegate) | (none) | Current project files, symbols |

Default Workflow

• Parse: Extract query, detect flags, classify intent
• Route: Dispatch to the appropriate search channel(s)
• Collect: Gather results from dispatched routes
• Score: Attach trust labels to each result domain
• 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:

• State intent: docs | web | code | local
• Pass query string
• 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