agentleFS
clay-goodclay-good/spec-gen/skills/openlore-orient/SKILL.md

openlore-orient

Skill359 starsChanged 6 months agoMITView on GitHub

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.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Call orient at the start of any of these:

    line 14
  2. Very specific:

    If you are reading source files without having called orient first, you are probably wasting tokens.

    line 21
  3. Very specific:

    Always start by reading specDomains, then callPaths, then jump into source only at the insertionPoints you actually plan to edit.

    line 47
  4. Very specific:

    Do not paraphrase the task: when passing it to orient.

    line 61
  5. Very specific:

    If orient returns an empty result or errors:

    line 66

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.