openlore-orient
/openlore-orient
Pobiera z OpenLore funkcje, wywołania, sekcje specyfikacji i punkty wstawienia kodu, zanim zacznie czytać pliki źródłowe.
- Autor
- clay-good ↗
- Repozytorium
- openlore ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 7
- Skrypty
- 3
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/orient-via-mcp.mjs, scripts/orient.ps1, scripts/orient.sh
Co robi i kiedy
Pobiera z OpenLore funkcje, wywołania, sekcje specyfikacji i punkty wstawienia kodu, zanim zacznie czytać pliki źródłowe.
Oryginalny opis (EN)
Retrieve relevant functions, callers, spec sections, and insertion points from OpenLore before reading source files. Use when starting work that needs structural orientation in an existing codebase.
Jak działa
- When to use this skill
- How to use it
- What NOT to do
- Failure modes
Podgląd SKILL.md
--- name: openlore-orient description: Retrieve relevant functions, callers, spec sections, and insertion points from OpenLore before reading source files. Use when starting work that needs structural orientation in an existing codebase. --- # OpenLore — orient before you read This project uses **OpenLore** to maintain a deterministic, graph-native model of the codebase: every function, every caller, every spec section, every file. The `orient` tool collapses what would otherwise be a chain of `analyze_codebase → search_code → search_specs → suggest_insertion_points` into a single call. The single most important habit when working in this repo: **call `orient` before opening source files for any non-trivial task.** ## When to use this skill Call `orient` at the start of any of these: - **New task in the repo** — even ones that feel small. The graph knows things the file tree doesn't. - **Unknown function or symbol** — instead of grepping blind, ask `orient` and let it return the function, its callers, and the spec section that owns it. - **Planning a cross-module change** — `orient` returns insertion points ranked by structural fit, so you start at the right boundary instead of the most-recently-viewed file. - **After an Epistemic Lease prefix appears** — when a tool response says you're stale, re-orient before continuing. Acting on stale context is the most common failure mode. If you are reading source files without having called `orient` first, you are probably wasting tokens. ## How to use it ### Preferred: via the OpenLore MCP server If `openlore` is registered as an MCP server in this project (look for `.mcp.json` → `mcpServers.openlore` — the project-scope file Claude Code reads; **not** `.claude/settings.json`, which it ignores for MCP), call the `orient` tool directly through the MCP interface. This is the lowest-latency path and gives the model access to whatever tool surface the server was wired with — the lean 10-tool `navigation` preset by default (`openlore install --preset full` wires all 62), not just `orient`. ### Fallback: via the shell wrapper ```sh bash scripts/orient.sh "<task description>" ``` (On Windows: `powershell -File scripts/orient.ps1 "<task description>"`) The wrapper tries the direct CLI subcommand first (`npx --yes openlore orient --json --task "<task>"`) and falls back to driving the `openlore mcp` server over stdio JSON-RPC via the sibling `orient-via-mcp.mjs` helper on older openlore versions that predate the CLI subcommand. Either path produces real orient JSON on stdout. Parse these arrays from the result: The result fields are **camelCase** (matching `orient --json`): - **`relevantFunctions`** — top scored functions for the task, each with `name`/`file`/`line`, role classification, and a short reason. - **`callPaths`** — caller/callee neighbourhood for the top functions. This is where "who breaks if I change this" lives. - **`specDomains`** — OpenSpec domains that own the relevant files, including the requirements they encode. Read these before reading code. - **`insertionPoints`** — ranked candidate locations to make the change, with structural justification. - **`relevantFiles`**, **`provenance`**, **`changeCoupling`**, **`suggestedTools`**, **`nextSteps`** — supporting context. **`searchMode`** is `semantic` when embeddings are built or `bm25_fallback` otherwise. Always start by reading **`specDomains`**, then **`callPaths`**, then jump into source only at the **`insertionPoints`** you actually plan to edit. ### Lean mode for shallow lookups (cheaper) For a quick "who calls X" / "where is Y defined" lookup, pass **`lean: true`** (or `orient --lean`): it returns just the navigation core (`relevantFunctions` with `expand` handles, `callPaths`, `specDomains`) — ~40% smaller — and drops the provenance / change-coupling / insertion-points / specs / decisions enrichment, each still one `expand` handle or dedicated tool call away. Omit `lean` when you actually need that enrichment (planning an edit, checking specs/decisions). Caveat (measured, Spec 27): on a *trivial* lookup in a small/familiar repo, even a lean orient call can cost more than just grepping — `orient` earns its keep on unfamiliar or multi-hop work, not one-line facts you could find in 2 reads. > **Note:** the `openlore orient --json --task` CLI subcommand is available, so the wrappers use it directly. The MCP fallback in the wrappers only kicks in on older openlore versions that predate the subcommand. > **Want to measure it on your own repo?** Pass `--metrics` (off by default) to have `orient` report its wall time and output size to stderr. Nothing is measured or printed unless you ask for it. ## What NOT to do - **Do not open source files before `orient` has returned.** This is the single most expensive mistake — you'll re-derive what the graph already knows. - **Do not call `orient` on every edit.** It's a session-start and re-orient-on-staleness tool, not a per-call helper. Respect the Epistemic Lease signal — if no prefix appears, your context is still fresh. - **Do not paraphrase the task** when passing it to `orient`. Use the user's words. The semantic search matches better when the query language matches the eventual prompt. - **Do not ignore `specDomains`.** Reading specs first is faster and more accurate than reading code first, in this repo. ## Failure modes If `orient` returns an empty result or errors: 1. **Empty `relevantFunctions` array** — the task description didn't match the graph. Try rephrasing using a known module name, function name, or domain word from the spec. Do not fall back silently — tell the user that `orient` didn't match and you're going to grep. 2. **Wrapper output contains `"error": "No analysis found"`** — the codebase hasn't been analyzed yet. Run `npx openlore analyze` once to seed the graph, then retry. The wrapper itself is healthy in this case; the underlying tool is telling you what's missing. 3. **Graph is stale (mtime older than recent edits)** — the JSON output will still come back, but the insertion points may be wrong. Re-run `npx openlore analyze` to rebuild. In all failure cases, the correct fallback is a *targeted* `grep`/file read scoped to a single module — not opening the whole repo. And **always tell the user the skill silently degraded** so they can rebuild the graph if needed.
Pliki w paczce (7)
- README.md 4 KB
- SKILL.md 6 KB
- examples/example-orient-output.json 4 KB
- examples/example-task-prompt.md 2 KB
- scripts/orient-via-mcp.mjs 5 KB
- scripts/orient.ps1 1 KB
- scripts/orient.sh 1 KB
Wersje
W bazie nie ma innych skilli o nazwie openlore-orient.
Migawka bazy z 13.11.2026 · wersja paczki 231381a82df9 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 82openlore-generate
Tworzy nową specyfikację domeny OpenSpec dla istniejącego kodu na podstawie dowodów z serwera OpenLore MCP. - 100openlore-implement-story
Wdraża historyjkę w istniejącym kodzie: orientacja w strukturze, sprawdzenie ryzyk, walidacja specyfikacji, testy i wykrywanie dryfu. - 90duck-orient
Generuje lub odświeża plik orientacji w repozytorium z ćwiczeniami interaktywnymi, gdy wraca się do kodu po przerwie. - 100technical-orientation
Wyjaśnia projekty techniczne lub bazy kodu osobie spoza inżynierii, na prośby „orient me” lub „explain this repo”. - 100orient
Generuje dla skilla learning-opportunities plik orientation.md specyficzny dla repozytorium, na bezpośrednią prośbę o orientację w repo. - 90orient
Przygotowuje wstępną orientację w sprawie na prośbę użytkownika.