oma-search · diff
git:20260909.0c00b0b to git:20260909.093aa3d
43 added, 138 removed. Audit A to A.
---
name: oma-search
description: Intent-based search router with trust scoring. Routes queries to
optimal channels (Context7 docs, native web search, gh/glab code search,
configured local code intelligence) and attaches domain trust labels. Use for
search, find, lookup, reference, docs, code search, and web research.
---
- # Search Agent - Intent-Based Search Router
+ # Search Router
## Scheduling
### Goal
- Classify information-seeking requests, route them to the best search channel, attach trust labels, and return source-grounded results.
+ Route an information request to the appropriate channel and return relevant sources with trust labels.
### 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.
+ - Search, find, look up, reference docs, inspect official APIs, or search remote code.
+ - Another skill requests docs, web, code, or local search with a query and constraints.
### 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)
+ - Library documentation, web research, GitHub/GitLab implementation patterns, or unclear search channels.
### When NOT to use
- - Local codebase exploration only -> use the configured code-intelligence provider or native search
- - Git history or blame analysis -> use SCM Agent
- - Full architecture research -> use Architecture Agent (may invoke this skill internally)
+ - Pure local code exploration -> use configured code intelligence under the shared contract.
+ - Git history/blame -> `oma-scm`; architecture analysis -> `oma-architecture`.
### 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
+ Query, optional route hint (`docs`, `web`, `code`, `local`), source/recency constraints, and flags. Explicit `--docs`, `--code`, or `--web` selects the route; `--strict` filters trust, `--wide` retains labeled results, and `--gitlab` selects the remote code host.
### 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
+ Ranked sources with URL or file reference, route, relevance, trust level/score, and material fallback limits. Do not invent sources when no reliable result is found.
### Dependencies
- - Context7 MCP for docs, runtime-native web search, `gh`/`glab` for code, configured code intelligence or native tools 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
+ Context7 for docs, runtime web search, `oma search`/`gh`/`glab` for remote code, and configured code intelligence or native local search.
## 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 configured code intelligence or native search instead of web.
+ ### Routes
+ | Route | Primary | Fallback | Use for |
+ |---|---|---|---|
+ | `docs` | Context7 `resolve-library-id` → `query-docs` | Web search | Official API/framework documentation |
+ | `web` | Runtime web search | `oma search fetch <url>` for known result URLs | Web sources |
+ | `code` | `oma search code` | Report unavailable host/auth | Remote repository patterns |
+ | `local` | Configured code-intelligence provider | Native search and scoped reads | Current project files and symbols |
### 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.
+ - Missing/empty documentation lookup: use web search and state the fallback.
+ - A known URL cannot be fetched: use the fetch strategies in the route reference; retain authentication/blocking errors if all strategies fail.
+ - Configured local tools unavailable or timed out: follow `../_shared/core/code-intelligence.md`.
+ - Unknown trust: retain the result as `unknown` with score `—`; do not imply verification.
+ - No result satisfies `--strict`: report that outcome and offer a wider or narrower query.
### Exit
- - Success: results are routed, trust-scored, and source-grounded.
- - Partial success: route failures or trust limitations are explicit.
+ Return evidence-backed results and disclose failed routes or source limitations. A domain score alone does not verify an individual claim.
## 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`
- - Configured code intelligence or native tools for local project search
+ ### Canonical workflow path
+ 1. Parse the query and explicit flags. Use `resources/intent-rules.md` only when classification is needed; select one route unless ambiguity requires more.
+ 2. Dispatch using Routes. Load `resources/execution-protocol.md` for the selected channel's command flags, fetch strategies, or normalization details.
+ 3. Collect source references and deduplicate by URL. For non-local results, resolve domain trust using `resources/trust-registry.md`; reuse the current session cache. Apply `--strict` after scoring.
+ 4. Rank by relevance, using trust as a tiebreaker. Return the requested answer or source list with supporting references and fallback limitations.
- ### Canonical command path
+ ### CLI entry points
```bash
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.
+ The CLI also exposes `api`, `api:search`, `meta`, `rss`, `rss:google`, `media`, `archive`, and `doctor`; use a primitive only when the selected route needs it.
### 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 via `oma search trust <domain>` (single source: `cli/commands/search/trust.ts`)
- 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, configured code intelligence or native tools 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
-
- | 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` | Configured code-intelligence provider | Native search and scoped reads | Current project files, symbols |
-
- ### 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"
- ```
+ - Explicit route/source constraints take precedence over automatic classification.
+ - Score at domain level, not URL-path or page level. Use the CLI registry and the documented Context7/official-site exceptions; do not invent scores.
+ - Do not duplicate successful routes or search locally via the web.
+ - Use available runtime web tools and the configured local provider; do not install or track a repository automatically.
- #### 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
+ ### Resource scope and effects
+ Search may contact external services or inspect local code and spawn `gh`/`glab` processes. Query constraints, selected sources, and trust metadata are session context; persistent caches belong in generated state, not skill definitions.
## References
- Follow `../_shared/core/code-intelligence.md`: discover the configured provider’s available tools; use native search and scoped reads when unavailable. Do not install or track repositories automatically.
-
- 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`
+ - Intent classifier: `resources/intent-rules.md` (no explicit route or ambiguous query)
+ - Route execution detail: `resources/execution-protocol.md` (selected channel only)
+ - Trust resolution and cache rules: `resources/trust-registry.md` (non-local sources)
+ - Recovery detail: `resources/error-playbook.md` (route failures)
+ - Result checklist: `resources/checklist.md` (applicable route checks)
+ - Examples: `resources/examples.md` (unfamiliar input/output contracts)
+ - Local code-intelligence contract: `../_shared/core/code-intelligence.md`