AutoGineer
Generated banner for OpenLore
Generated logo for OpenLore

OpenLore

Memory server

Created by Clay Good

Published in clay-good/OpenLore. Publisher page

362 GitHub stars

What it is

Persistent architectural memory and structural cognition for AI coding agents.
— the description by Clay Good

AutoGineer overview, from the brain’s own files

OpenLore is a memory system designed to solve the amnesia and lack of governance in AI coding agents. By performing a one-time static analysis of a repository, it builds a persistent knowledge graph that encompasses application code, infrastructure-as-code, and architectural decisions. Unlike standard RAG systems, OpenLore operates deterministically without an LLM in the hot path, ensuring consistent answers and providing agents with an 'Epistemic Lease' to warn them when facts have become stale. It serves as both a memory layer for agent orientation and a governance engine that certifies changes, flags breaking API surface modifications, and validates sensitive boundary crossings before they are committed.

How it works

Memory model: Hybrid

AutoGineer overview, from the brain’s own files

OpenLore functions as an MCP server that indexes your repository into a local knowledge graph. Upon installation, it maps code structures, dependencies, and architectural specs. During agent sessions, it injects a compact architecture digest into the agent's context. The agent then uses MCP tools to query this graph for tasks like orienting to a codebase, tracing execution paths, or verifying claims. Governance tools analyze diffs against the graph to provide deterministic verdicts on breaking changes or boundary violations without requiring an LLM.

Folders
FolderRoleFiles
.claudeagent-config1
.githubagent-config12
docsdocs62
examplesexamples95
scriptsscripts27
skillsagent-instructions25
srcsource-code1284
benchfolder15
benchmarksfolder1
openspecfolder1261
packagingfolder2
schemasfolder2
stubsfolder1

The agent reads

The agent writes

Requirements

Runtimes: Node.js ^22.22.0 || >=23.5.0

Databases: LanceDB

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. This brain runs code automatically: 1 script. Review package.json before opening the folder in Claude Code. No step below turns a hook on for you.

    • package.json: node scripts/postinstall.mjs
  2. Not scanned by AutoGineerAutoGineer could not scan everything it runs. https://www.npmjs.com/package/openlore

  3. Created by Clay Good. Published in clay-good/OpenLore. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

  • Orienting an agent to a new codebase at the start of a task.
  • Validating that a proposed code change does not break public API contracts.
  • Checking if a diff introduces a path into a sensitive architectural boundary.
  • Verifying claims about code safety or dead code before refactoring.
  • Maintaining architectural specifications that stay synchronized with code changes.
  • Selecting relevant tests to run based on the specific impact of a code modification.
“Orient me to the user authentication flow in this repository.”
The agent calls orient() and receives a summary of relevant functions, callers, and specs, allowing it to start the task immediately without manual file exploration.
“Review my current changes for breaking API surface modifications.”
The agent uses certify_public_surface to identify changed exports and lists the specific consumers that would be affected by the proposed changes.
“Verify if the function 'deleteUser' is safe to remove.”
The agent uses find_dead_code or verify_claim to determine if the function has any remaining callers or dependencies, providing a deterministic verdict.
“Check if this diff opens a path into the sensitive 'payment-gateway' module.”
The agent uses change_impact_certificate to confirm whether the new code creates a reachable path into the protected boundary.

Documentation by Clay Good

<h1 align="center">OpenLore</h1>

<p align="center"> <strong>Deterministic, local-first memory and guardrails for AI coding agents — no LLM in the hot path.</strong><br> Install once. From then on it runs in the background, keeping your agent oriented and its changes safe.<br> No API key. Same answer every time. </p>

<p align="center"> <a href="https://www.npmjs.com/package/openlore"><img src="https://img.shields.io/npm/v/openlore?color=2563eb&label=npm&logo=npm&logoColor=white" alt="npm version"></a> <a href="https://github.com/clay-good/OpenLore/actions/workflows/ci.yml"><img src="https://github.com/clay-good/OpenLore/actions/workflows/ci.yml/badge.svg" alt="CI status"></a> <a href="LICENSE"><img src="https://img.shields.io/npm/l/openlore?color=22c55e" alt="MIT License"></a> <img src="https://img.shields.io/node/v/openlore?color=339933&logo=node.js&logoColor=white" alt="Node >=22.22"> <br> <img src="https://img.shields.io/badge/MCP-ready-7c3aed?logo=anthropic&logoColor=white" alt="MCP ready"> <img src="https://img.shields.io/badge/languages-21%20%2B%2013%20IaC-f97316" alt="21 languages + 13 IaC ecosystems"> <img src="https://img.shields.io/badge/tests-5500%2B-success" alt="5500+ tests"> <img src="https://img.shields.io/badge/API_key-not_required-0ea5e9" alt="No API key required"> <a href="https://github.com/clay-good/OpenLore/stargazers"><img src="https://img.shields.io/github/stars/clay-good/OpenLore?style=social" alt="GitHub stars"></a> </p>

<p align="center"> <code>install</code> wires your agent and indexes the repo → <code>orient</code> returns the code a task touches → <code>review</code> catches the change that breaks a contract. All local, no API key. </p>

<p align="center"> <strong><a href="#install-once-then-forget-it">Install</a> · <a href="#what-you-get">What you get</a> · <a href="#value-scorecard--does-it-pay-for-itself">Benchmarks</a> · <a href="#openlore-vs-alternatives">vs. Alternatives</a> · <a href="#documentation">Docs</a></strong> </p>

AI coding agents are amnesiac and ungoverned. Every task restarts by re-reading the same files, long sessions drift onto stale assumptions, and nothing warns the agent when a change is about to break a contract or cross a boundary.

OpenLore fixes both halves, and then gets out of your way. A one-time static analysis builds a live knowledge graph of your repo — call structure, types, tests, decisions, IaC. From then on your agent is already oriented at the start of every task and its changes are certified before they land — automatically, deterministically, with no LLM in the hot path, so the same question returns the same grounded answer and the agent is told when a fact goes stale instead of served a confident guess.

Install once, then forget it

npm install -g openlore && openlore install

That is the only command most people ever run. It auto-detects your agent (Claude Code, Cursor, Cline, Continue, Pi, AGENTS.md), wires it, registers the MCP server, and builds the index — no API key, no config, no prompts. After that, it's on in the background and you don't think about it:

  • 🔄 Every task starts oriented, automatically — a compact architecture digest is injected into your agent's context at the start of each session, and your agent calls orient() and the other tools itself over MCP. You don't type anything.

  • 🌱 Every repo, not just this one — install wires your user account too, so each new git repo you open indexes itself in the background on first touch. "Install once" is literal.

  • 🩹 Always fresh — a file watcher re-indexes as you edit and converges to a full analysis; anything it can't recompute in time is marked explicitly stale, never silently wrong.

  • 🛡️ Changes get checked before they land — the governance tools (and openlore review on a PR) run deterministically with no API key.

The CLI below exists for humans and CI — prove, review, doctor, features. The everyday path is: install, then let your agent use it.

Zero config. Run openlore features to see every opt-in capability (embeddings, the commit gate, the spec store…), whether it's on, and the one command to enable it. openlore doctor verifies the wiring.

What you get

Two things, both deterministic and local:

🧠 Memory — your agent starts every task already oriented

  • Orient in one call — orient(task) returns the relevant functions, callers, specs, tests, and insertion points (~430µs p50 on a 15k-node graph) instead of a dozen exploratory file reads.

  • Survives refactors — anchored notes and decisions carry forward when a symbol is renamed or moved, instead of orphaning.

  • One graph for everything — application code, Infrastructure-as-Code, and architectural decisions share one graph, so a single query spans all three.

  • Told when a fact is stale — every response carries a brief, factual freshness note (the Epistemic Lease) once a cached fact has aged or the repo moved, so a long session can't drift onto a confident guess.

🛡️ Governance — guardrails on what the agent changes

  • Breaking-change verdict — certify_public_surface classifies every changed export breaking / non-breaking / potentially-breaking and names the consumers each break hits. Never silently "safe."

  • Sensitive-boundary check — change_impact_certificate flags when a diff opens a new path into a boundary you declared (reachable after the change, not before).

  • Grounded claims — verify_claim returns confirmed / refuted / unverifiable with a citation, before an agent asserts "X is dead" or "Y is safe to change."

  • One commit gate — openlore enforce blocks on findings you mark blocking. Advisory by default, no API key.

The one line to remember: an agent's expensive failure mode isn't ignorance — it's confidence. A model that doesn't know a function exists will go look. A model that "knows" a stale fact builds on it, and you pay at review time. OpenLore is built so the agent can be told "that fact is stale" and "this change opens a path you said was sensitive" — deterministically, with no second model guessing about the first.

Value Scorecard — does it pay for itself?

OpenLore only earns its place if an agent with it reaches a correct answer for less total cost than the same agent without it. We measure that and publish it — wins and losses. Numbers from the Spec 14 benchmark (claude -p, sonnet, N=4 medians, pinned SHAs), measured 2026-06-01.

ScenarioCost ΔRound-trips ΔVerdict
Large/unfamiliar repo · deep "how does X flow through Y" (its target)−7% to −21%−26%✅ helps — and the win grows with repo size
Small/familiar repo · shallow "who calls X"task-dependent (Round 1: +43%)+38%❌ often adds overhead — measure first

The win scales with codebase size (round-trips without → with):

Repo (size)Cost ΔRound-trips
excalidraw (~640 files)−21%25 → 16
tokio (~790 files)−21%17 → 13
okhttp−13%13 → 11
django (~3k files)−7%21 → 15
gin (110 files, smallest)+4% (≈even)10 → 9

Re-confirmed live 2026-06-03: the deep-task win reproduces (okhttp −13%); the small/familiar case is task-dependent, not a flat loss (chalk −32% win vs. express +59% loss). Don't guess from our repos — run openlore prove --estimate on yours (seconds, no API key).

Honesty contract. We never publish a savings number the benchmark didn't produce, we always show the losses next to the wins, and every claim traces to a command you can run. Methodology: docs/AGENT-BENCHMARKS.md.

Is OpenLore for you?

✅ Strong fitA codebase too big to hold in your head — and the model's. Private or niche code the model never memorized. Long sessions where stale assumptions compound. Polyglot repos, or code plus the IaC that deploys it.
🤔 Try it, measureMid-size repos and mixed workloads. Run openlore prove --estimate (seconds, no key) before you commit.
❌ Probably notA small repo the model already knows, answering shallow questions — your agent's built-in search is cheaper, and we publish the measurement that says so. Also: OpenLore locates and certifies, it never edits your code.

What your agent reaches for (you rarely type these)

Once wired, your agent calls these over MCP on its own. The default surface is the substrate preset — 15 tools: the navigation core, the highest-value governance reads (recall, verify_claim, blast_radius), and the spec composites. The lean navigation preset (10 tools) and the full 83 tools (--preset full) are one flag away.

When the agent needs to…Tool
Start any taskorient(task) — functions, callers, specs, insertion points in one call
Find which file/function handles Xsearch_code
Know the blast radius of a changeanalyze_impact — risk + up/downstream chain + governing decisions
Trace how request X reaches function Ytrace_execution_path
Pick the tests a change should runselect_tests — backward reachability to the reaching tests
Find dead code / what dies if X is deletedfind_dead_code — cross-language reachability
Check a whole diff before commitblast_radius — callers, tests, specs that drift
Tell if a diff opens a sensitive boundarychange_impact_certificate
Tell if a change breaks a consumer's APIcertify_public_surface — verdict, consumers named
Verify a fact before asserting itverify_claim — deterministic verdict + citation
Record an architectural choicerecord_decision before writing the code

Full reference — all 83 tools: docs/mcp-tools.md. Ships as a Claude Code Skill at skills/openlore-orient/.

OpenLore vs. alternatives

Everyone in this category answers the same first question: how does the agent see the codebase without reading it file by file? LSP toolkits answer with symbols, graph MCP servers with a parsed graph, search platforms with an index. OpenLore answers it too — then keeps going into the second question almost nobody answers: what happens when the agent starts writing? A retrieval layer makes an agent informed; it doesn't make it safe. That second half — governance on the same graph, no LLM in the loop — is what OpenLore is for.

Agent built-insLSP toolkitsGraph MCPSearch platformsOpenLore
Structural context instead of file reads❌ grep✓ symbols✓ graph✓ index✓ call graph + IaC + decisions on one graph
Local, no API key, deterministicPartial✓✓❌ hosted✓ no LLM in the hot path
Cross-session memory anchored to code❌Partial✓ notes❌✓ carried across renames
Told when a cached fact goes stale❌❌❌❌✓ Epistemic Lease
Breaking-change verdict over a diff❌❌Partial❌✓ per export, consumers named
"Did this diff open a sensitive path?"❌❌❌❌✓ differential, pre-commit
Cost effect published with the losses❌❌❌❌✓ −26% round-trips on deep tasks

Use the other tool when it's the right one: symbol-level edits (rename across files) are an LSP toolkit's home turf — OpenLore is deliberately read-only, and the two compose. Org-wide search across hundreds of repos is a search platform. Just-fast-graph-retrieval is a smaller graph MCP server. And a small, familiar repo with shallow questions is cheaper with your agent's built-in search. OpenLore also exports SCIP, so it sits alongside these tools, not against them.

Comparisons reflect each project's publicly documented capabilities as of July 2026; a correction PR is always welcome.

What it costs

Measured on a fresh clone of ripgrep with published [email protected]:

What it costsOn ripgrep (232 files)
One-time index build13.6 s, entirely local — no API key, no network
Disk27 MB under .openlore/ (gitignorable; rebuildable from source)
Per-query latency~430 µs p50 in-process via the MCP server
Your source codenever leaves the machine — no account, no telemetry (opt-in only)
Lock-innone — delete .openlore/ and nothing about your repo has changed

Large monorepos take minutes rather than seconds, stated plainly in Known limitations. Platform: Linux and Windows are exercised in CI; macOS is supported.

Fully local — nothing phones home. No account, no network call; your source, the index, and every query stay on your machine. The only diagnostics that exist are opt-in and local-only, off by default and never transmitted: OPENLORE_TELEMETRY=1 records tool calls, agent identity, latency, error messages, decision titles, and lease events to the gitignored .openlore/telemetry/ directory, and OPENLORE_LLM_LOGS=1 stores prompts and responses (after secret redaction) in the gitignored .openlore/logs/ directory. → docs/configuration.md

Languages, Infrastructure-as-Code & contracts

Languages: TypeScript · JavaScript · Python · Go · Rust · Ruby · Java · C++ · Swift · C# · Kotlin · PHP · C · Scala · Dart · Lua · Elixir · Bash — call graphs ride the same primitives for every language. → docs/language-support.md

Infrastructure-as-Code: Terraform/HCL · Kubernetes · Helm · CloudFormation · Ansible · Pulumi · AWS CDK · CDKTF · Dockerfile · Docker Compose · GitHub Actions · Azure Bicep · Serverless Framework — IaC resources project onto the same graph as application code, so orient, search_code, and analyze_impact answer "what's the blast radius of changing this security group / IAM role / base image / CI job?" with zero new tooling. → docs/iac.md

Interface contracts: OpenAPI 3.x · Swagger 2.0 — each declared operation projects onto the same graph, bound to the route handler that serves it and the function that calls it, so orient and analyze_impact cross the API boundary. Matching is literal, and everything unbound is disclosed. → docs/contracts.md

Known limitations

We'd rather you know these up front.

  • Static analysis only. Polymorphic dispatch, event channels, and route→handler bindings are recovered (provenance-labeled synthesized). What isn't: reflective invocation with a non-literal target (getattr(o, name)()), eval, and DI/plugin registries with no visible binding — silently absent from the graph.

  • LLM spec quality varies. Generated spec prose reflects the model's understanding — review complex business logic. Structure, format, coverage, and drift are checked deterministically.

  • Keyword (BM25) search answers first; local semantic follows in the background. orient/search_code work immediately with no key. Background builds then add on-device vectors (CPU-only, ~23 MB model) when the optional package is installed; opt out with "embedding": { "provider": "none" }.

  • Large monorepos analyze one package at a time after the first full build (openlore analyze --shard <name>); the initial index is still a full analysis.

  • Incremental updates converge or flag, never silently diverge. When a change exceeds the per-save budget, the rest is marked explicitly stale and self-heals on later edits or a background re-analyze.

Documentation

Start here: the documentation index maps every task to the one canonical page that answers it. The essentials:

I want to…Doc
Install & wire my agent (one command)install.md
Understand why wiring an agent helpsagent-setup.md
See all 83 MCP tools + parametersmcp-tools.md
Run the full CLI referencecli-reference.md
Configure .openlore/config.json (incl. enforcement.policy)configuration.md
Choose / configure an LLM provider (optional)providers.md
Fix a setup problemTROUBLESHOOTING.md
Read the benchmark methodology + per-task numbersAGENT-BENCHMARKS.md
Search code by meaning (semantic / GraphRAG)semantic-search.md
Pick the tests a change should runtest-impact-selection.md
Find dead code / coverage gapsreachability-dead-code.md · coverage-gaps.md
Detect spec ↔ code driftdrift-detection.md
Enforce architecture / import rulesarchitecture-invariants.md
Gate commits / wire CI & PR reviewci-cd.md · preflight.md
Understand IaC & cross-domain impactiac.md · cross-domain-impact.md
See declared API contracts in the graphcontracts.md
Query across repos (federation)federation.md
Share the index as a bundleshareable-bundle.md
Export to Sourcegraph / SCIP toolsscip-export.md
Read the internalsARCHITECTURE.md · ALGORITHMS.md · PHILOSOPHY.md

Development

npm install
npm run build
npm run test:run  # 5500+ unit tests, one-shot (npm test is watch mode)
npm run typecheck

New contributor? See CONTRIBUTING.md for setup, MCP wiring, and the commit gate. Please also read our Code of Conduct; to report a vulnerability, see SECURITY.md.

Community

If OpenLore saves your agents from re-reading the same files — or catches one risky change before it lands — star the repo. It's the signal that tells us to keep building, and it helps other engineers find it.

Links

  • OpenSpec — spec-driven development framework

  • AGENTS.md — system prompt for direct LLM prompting

  • Examples — BMAD, Vibe, GSD, drift-demo, spec-kit integrations

docs/install.md

openlore install

Auto-configure popular AI coding agents to call OpenLore's orient() automatically.

Quick start

npm i -g openlore
cd your-project
openlore install

Once, ever. That auto-detects which agent surfaces are present (Claude Code, Cursor, Cline, Continue, Pi, Codex, plus the universal AGENTS.md fallback) and writes the minimal config needed for each agent to call orient() before reading source files — for this repository and for your user account. Every git repository you open afterwards with a user-scope-wired agent reaches the OpenLore MCP server and builds its own index in the background, with no further command.

Use --repo-only if you want per-repository scope control instead.

Confirm it worked with openlore doctor — it reports your config, index freshness, MCP wiring, and LLM/embedding setup, and prints the exact command to fix anything that is missing.

Onboarding onto an already-analyzed repo? Instead of cold-indexing, import a committed graph bundle: openlore import .openlore/index-bundle.olbundle — an integrity-checked index in seconds (or a transparent rebuild if it is stale). Producer provenance is verified only for a trusted signature. See shareable-bundle.md.

Scopes: user and repository

ScopeFiles (Claude Code, Codex)Effect
user (default)Claude: ~/.claude.json (mcpServers.openlore), ~/.claude/settings.json (hooks + status line + Bash(openlore:*)), ~/.claude/CLAUDE.md; Codex: ~/.codex/config.toml, ~/.codex/hooks.jsonevery repository you open reaches OpenLore
repo (always, when you run install inside one)Claude: .mcp.json, .claude/settings.json (hooks), .claude/settings.local.json, CLAUDE.md; Codex: .codex/config.toml, .codex/hooks.jsonthis repository, wired and indexed immediately

The user scope is written for every adapter that has one, not only for adapters detected in the current directory — that is what makes "install once" true in a repository whose markers belong to some other agent. The practical consequence: a bare openlore install creates ~/.claude/ even if you do not use Claude Code. --repo-only, or --agent <name>, avoids that.

OPENLORE_HOME and OPENLORE_SETTINGS_RUNTIME_DIR relocate the user scope and its lock/journal directory respectively.

Adapters with no user-scope surface (cursor, cline, continue, pi, agents-md) are wired per repository and named as such in the summary — an honest note, never a failure. openlore connect list shows both scopes; openlore install --uninstall removes OpenLore-managed entries from both, and never deletes ~/.claude.json or ~/.claude/settings.json themselves. Because it removes the user scope, running it inside one repository unwires every repository on the machine; it names the absolute path it stripped and says so. Use --repo-only to clean one repository and leave the user scope in place. An explicit --agent narrows both scopes, on install and on uninstall alike, and only a whole-install removal takes out the commit gate. openlore connect remove <agent> is repository-scoped by default — pass --user-scope to remove the machine-wide entries too.

Both scopes wired means both scopes active. Claude Code resolves MCP servers by name, so one server runs. It does not do that for hooks or instructions: user-level and project-level SessionStart / UserPromptSubmit hooks both fire, and ~/.claude/CLAUDE.md and the project CLAUDE.md are both loaded. A repository wired at both scopes therefore runs orient twice per session and orient --inject twice per prompt, and carries the instruction block twice. If that matters to you, wire one scope: openlore install --repo-only for per-repository control, or openlore install --agent claude-code from outside a repository for user scope alone.

OPENLORE_HOME overrides where the user scope is written (sandboxes, CI images, containers whose $HOME is not the profile you mean to configure).

Claude Code status line

When openlore install wires Claude Code's user scope, it also sets Claude's custom status line (~/.claude/settings.json statusLine) to run openlore statusline --installed-by-openlore. The command reports the search-index state of the session's project directory: green when current, yellow when missing, stale, or unknown, and red when degraded. It is never written to a repository's shared .claude/settings.json, which would override every teammate's own status line. If statusLine is already set, install keeps it and prints a hint instead; call the unmarked openlore statusline from your own status-line script to show both. Re-running install refreshes the OpenLore status line, and uninstall removes only that one (identified by --installed-by-openlore).

Claude Code documents custom shell-command status lines and ANSI color output in its status-line guide. Codex CLI's /statusline command currently selects and orders built-in footer fields; it does not expose a custom command or text item, so OpenLore cannot add a dynamic readiness indicator there.

Background auto-init, and its guardrails

Because user-scope wiring reaches repositories you never ran a command in, the background build is consent-guarded:

  • Git work trees only. A directory that is not inside a git work tree is never indexed.

  • Disclosed once per repository. The first background build in a repository adds one line to the tool response naming what was built, where it landed, that the call was not blocked, and both opt-outs.

  • Opt out per repository with "autoInit": false in .openlore/config.json, or per environment with OPENLORE_NO_AUTO_ANALYZE=1. An index-absent answer in an opted-out repository names the opt-out rather than reading as a broken install. openlore features shows the current state.

  • Degrades on large trees. Above the file-count ceiling (AUTO_INIT_DEGRADED_FILE_CEILING, currently 5,000 files) the background build sheds its semantic-embedding pass and builds signatures plus the keyword (BM25) index only, and says so. An explicit openlore analyze is never degraded — you asked for it.

  • Writes no git hook. Auto-init runs init and analyze, nothing else. The commit gate below is wired only by an explicit openlore install in that repository.

Zero-interaction onboarding

The happy path needs no flags and never touches your repo on npm install:

  • Post-install hint. Installing the package prints a single next-step line (cd your-project && openlore install) — no analysis, no config writes, no API key. It is silent in CI, non-TTY, and dependency/in-tree installs, and always exits 0. Suppress it with OPENLORE_SKIP_POSTINSTALL=1.

  • Non-interactive wiring. openlore connect --yes (alias -y) skips the interactive agent picker and wires every detected surface, exactly like a bare openlore install.

  • Cold-start self-bootstrap. If an agent wires the MCP server without ever running openlore install, the server builds the full index once in the background on first run — non-blocking, fail-soft, and with no API key. Opt out with OPENLORE_NO_AUTO_ANALYZE=1.

  • Staying current. A passive, cached, fail-silent banner notes when a newer version is published (human-facing commands only; silenced by OPENLORE_NO_UPDATE_NOTIFIER=1). Upgrade explicitly with openlore update, which detects npm-global / Homebrew / npx and runs the right command (--check / --dry-run to preview).

Flags

FlagEffect
--agent <name>Install only for one surface. Names: claude-code, cursor, cline, continue, pi, agents-md.
--preset <name>Wire the MCP server to a tool preset: substrate (the default — the navigation core, governance reads recall + verify_claim + blast_radius, and prepare_spec_generation + prepare_spec_repair; the write face remember/record_decision stays opt-in), navigation (the lean navigate-only escape), minimal, memory, verify, federation, coordination, or full. Omit it for the substrate default; pass --preset navigation for the lean core, or --preset full to wire all 83 tools.
--repo-onlyWire this repository only — write no user-scope entries.
--dry-runPrint the planned changes; write nothing. Previews show only the changed hunks, in a bounded context window, with secrets redacted — an untouched key in your private configuration is never printed.
--forceOverwrite OpenLore-managed blocks even when hand-edited.
--uninstallRemove every OpenLore-managed block / entry, in both scopes. Files OpenLore created (and never had non-OpenLore content) are deleted. Each reported change names its absolute path and scope, and a user-scope removal states that it affects all repositories — add --repo-only to uninstall this repository only.

Default tool surface. A plain openlore install wires the read-only substrate preset: 15 tools comprising the navigation core, the highest-value governance reads, and the 2 spec preparation composites. Use --preset navigation for the lean 10-tool escape or --preset full for all 83 tools. The decision-write and commit-gate tools remain opt-in through a preset that includes them.

What it actually writes

Every file we touch gets a managed block delimited by:

<!-- BEGIN OPENLORE (managed — edits inside this block will be overwritten) -->
<!-- openlore-fingerprint: <16-hex> -->
...content...
<!-- END OPENLORE -->

JSON config files get a top-level _openlore key carrying a fingerprint of the values we wrote. Re-running openlore install is a no-op when the fingerprint matches; if you hand-edited inside the block we refuse to overwrite unless you pass --force.

SurfaceMarkerFiles written
claude-code.claude/ or CLAUDE.mdrepo: append block to CLAUDE.md; mcpServers.openlore in .mcp.json; SessionStart + UserPromptSubmit hooks in .claude/settings.json. user: the same entries in ~/.claude/CLAUDE.md, ~/.claude.json, ~/.claude/settings.json
cursor.cursor/ or .cursorrulesappend block to .cursorrules; write .cursor/rules/openlore.mdc; mcpServers.openlore in .cursor/mcp.json
cline.clinerules or .vscode/settings.json (cline.*)append block to .clinerules
continue.continue/add /orient entry to .continue/config.json (MCP server registration is TODO — see below)
pi.pi/ (or ~/.pi/ when the tree has no marker at all)write .pi/extensions/openlore.js — a fingerprinted re-export shim pointing at the extension inside the openlore package. No markdown block or MCP entry; the extension starts openlore serve on demand. See Pi.
codex.codex/add OpenLore MCP server to .codex/config.toml and proposal hook to .codex/hooks.json (or config.toml when it already defines hooks); in repository scope, the agent-loop moments in .codex/hooks.json; user scope uses ~/.codex/. See Codex.
agents-mdalways appliesappend block to AGENTS.md (creates if absent)

Plus, in any git repository, openlore install writes .git/hooks/pre-commit (the decisions gate, non-blocking — see below) and .git/hooks/post-commit (its --no-verify bypass detector). Both are marker-delimited blocks appended to whatever is already there, and --uninstall removes exactly those blocks.

Codex

openlore install --agent codex adds the OpenLore MCP server to Codex's config.toml and a proposal-preparation command hook to its hooks configuration. The hook emits context only for a recognized OpenSpec propose invocation; it does not parse the conversation or run structural analysis. Codex's UserPromptSubmit matcher is currently ignored, so the lightweight command is invoked on each submitted prompt and emits nothing for unrelated prompts. The agent then summarizes the conversation and calls openlore_orient with that brief.

Codex requires users to review and trust non-managed hooks before they run. Project-level hooks also require the repository's .codex/ layer to be trusted. See Codex hooks.

Pi (pi.dev)

Pi loads JavaScript extensions rather than MCP servers, so its footprint is a single file. Three equivalent routes, pick one:

openlore install --agent pi          # .pi/extensions/openlore.js (this project)
pi install npm:openlore              # Pi's own package route — reads the "pi" field in package.json
openlore setup --tools pi --global   # ~/.pi/agent/extensions/openlore.js (every project)

The extension registers the navigation tools (openlore_orient, openlore_search_code, openlore_get_subgraph, …) and talks to a warm openlore serve daemon over loopback so calls hit warm caches. By default it does not repeat the repository digest and spec index in each turn; the agent calls openlore_orient when it has a task. Set "pi": { "contextMode": "full" } in .openlore/config.json to restore the standing digest and index. Requires Pi ≥ 0.78.1 and one openlore analyze beforehand. Full detail in examples/pi/README.md.

A Pi session starts with the lean tool set Claude Code gets by default (the substrate preset), plus openlore_configure and openlore_activate_tools. When Pi's native tool_search is already enabled by the user, OpenLore keeps only openlore_orient and openlore_search_code directly visible and exposes specialist tools through Pi's deferred tool search. Enable it in Pi yourself (for example, add "+tool_search" to defaultTools in ~/.pi/agent/settings.json); OpenLore does not change Pi settings. Without tool_search, the existing lean surface and openlore_activate_tools groups remain in use. To keep every tool active from the start, set:

{ "pi": { "toolSurface": "all" } }

in .openlore/config.json.

Pi configuration is opt-in: an unconfigured project receives a non-blocking hint once per cwd within the extension instance. Use /openlore configure for project settings or /openlore configure --global for defaults shared by Pi, the CLI and MCP in ~/.openlore/config.json (%USERPROFILE%\.openlore\config.json on Windows). Project object fields override global fields; arrays replace inherited arrays. A project block that sets its own endpoint (baseUrl, apiBase, openaiCompatBaseUrl) does not inherit the user apiKey or a TLS opt-out for it: a repository may not choose where your key is sent. OpenLore prints a warning when this happens. The user file ignores OPENLORE_HOME; set OPENLORE_GLOBAL_CONFIG to move it. An explicit CLI --config uses that file alone. See Pi configuration for details.

What the file contains. .pi/extensions/openlore.js is a four-line re-export shim, not a copy of the extension. The shipped extension is plain tsc output whose relative imports only resolve inside the openlore package, so a copy fails to load. The shim's target path is absolute: re-run openlore install --agent pi after moving or reinstalling openlore, and prefer pi install npm:openlore when .pi/ is committed and shared across machines. The file carries an openlore-fingerprint marker — hand-edit it and install refuses to overwrite it without --force.

Pre-commit hooks

openlore install wires one gate: the decisions commit gate, in non-blocking autopilot mode (governance.autopilot: true). Verified architectural decisions are recorded and synced to specs at commit time, and no commit is ever blocked by it. That is what makes one command yield structural navigation and a decision trail.

Install sets that mode only when it wires a gate for the first time in a repository. A repository that already carries an OpenLore commit gate keeps the mode it was configured with — in a configuration that exists, an absent governance.autopilot means blocking review, and install will not flip it — and an explicit governance.autopilot: false is never flipped either.

A repository with no .openlore/config.json at all gets a non-blocking gate. That is the openlore install --no-analyze and openlore setup case: neither runs init, so there is nowhere to record the mode — and blocking is a setting, so the absence of the file that would record it is not a choice to block. Install does not create a configuration there either, because that is the init you declined. To require blocking review in such a repository, run openlore init and set { "governance": { "autopilot": false } }.

Whichever mode is installed, install reports that mode: the summary is printed from the same resolver the gate itself reads, so it cannot tell you "no commit is blocked" over a gate that blocks.

openlore install also skips the gate entirely when OpenLore resolves inside the repository (a local devDependency), because a commit gate must not execute code the repository can change.

Every other git hook below is installed explicitly and is advisory by default. All of them coexist in a single .git/hooks/pre-commit. Each installer inserts its own marked block directly after the shebang and changes nothing else in the script, so a hook of your own that ends in exit 0 keeps working exactly as written and still reaches every OpenLore block:

HookInstallBlocks when
Enforcement gate (recommended, unified)openlore enforce --install-hooka governance finding resolves to blocking under enforcement.policy — the single posture over all findings
Agent-loop enforcement (opt-in, Claude Code + Codex)openlore setup --agent-enforcement-hook alla finding resolves to blocking; remediation is fed back through each agent's Stop hook
Decisions gatewired by openlore install in autopilot mode (never blocks); openlore decisions --install-hook for the explicit routeonly in blocking review mode (governance.autopilot: false), when verified decisions await review/sync
Blast-radius guardopenlore blast-radius --install-hookthe diff triggers a configured blastRadius.block pattern
Change-impact certificateopenlore impact-certificate --install-hookthe diff opens a new path into a impactCertificate.block surface severity

openlore enforce is the recommended single gate: it resolves every governance finding through one enforcement.policy, and the per-surface blastRadius.block / impactCertificate.block configs lower onto it. All hooks are advisory by default — nothing blocks until you opt a finding into blocking. Use claude or codex instead of all to install only one agent host; use none to remove OpenLore's entries from both without changing user-authored hooks. See cli-reference.md.

Task-scoped context injection

Beyond the whole-repo SessionStart primer, openlore install wires a per-task injection hook (Claude Code UserPromptSubmit) that runs openlore orient --inject against your submitted prompt and places a compact orientation block in context before the agent's first turn. The orientation the agent would otherwise spend a tool round-trip to fetch is simply already there — the round-trip is amortized to zero, which is the cost OpenLore's Value Scorecard attributes the small/familiar/shallow loss case to.

The injected block:

  • reuses lean orient output (Spec 27) — there is no second orientation code path;

  • is deterministic (no LLM) and bounded by a token budget (default ~600 tokens), so it can never dominate the context it economizes;

  • is clearly attributed to OpenLore and opens with a one-line "informational; act on it or ignore it" framing — facts, not instructions;

  • is gated: exact identifier mentions, matched-function count, fan-in / hub centrality, and retrieval-mode evidence decide whether the task warrants a full block; below the threshold it degrades to a single pointer line, so injection stays out of the small/familiar arena it would otherwise tax. Without embeddings, the default keyword/BM25 path uses scale-free top-match identifier overlap and never compares the corpus-relative BM25 score to a fixed threshold. Run openlore embed --local — a one-command, on-device, no-API-key upgrade — or set EMBED_* for a remote endpoint to add the bounded semantic-score path.

  • never breaks your turn: any failure (no graph, parse error, empty/weak match) degrades to the pointer line and exits 0.

Per-adapter support
SurfacePre-turn injection channel
claude-code✅ UserPromptSubmit hook running openlore orient --inject
cursor, cline, continue, agents-md❌ no pre-turn hook mechanism — these fall back to the instruction block + SessionStart-style guidance; no behavior change
Turning it off

Task-scoped injection is on by default. To disable it (while leaving the MCP server and the SessionStart primer intact), set in .openlore/config.json:

{
  "contextInjection": {
    "mode": "off",            // "task-scoped" (default) | "off"
    "tokenBudget": 600,        // hard cap in estimated tokens; positive values below 68 clamp to 68
    "relevanceMinMatches": 2,  // gate: minimum match count unless an identifier is exact
    "relevanceMinFanIn": 2,    // gate: centrality; exact/ranked identifier evidence also clears it
    "relevanceMinScore": 0.3   // gate: minimum top score (semantic/hybrid scale only)
  }
}

With mode: "off", openlore orient --inject emits nothing and exits 0.

Performance and activation notes

  • It runs on every prompt and blocks the turn until it returns, so it is built to be fast: orient is a local, deterministic lookup (~300 ms for the work itself; the npx wrapper that resolves the package adds ~200 ms). That is well under Claude Code's 30 s UserPromptSubmit timeout. On a weak match it short-circuits to the one-line pointer, so the slow path is the rare strong-match case.

  • Activation tracks the installed version. The wired command is npx --yes openlore orient --inject, which resolves the openlore your environment already has. If that is an older published version without --inject, the hook is a clean no-op (it prints nothing to stdout, writes a short notice to stderr, and exits non-zero — which does not block your prompt) until an openlore carrying --inject is what npx resolves. Run openlore --version to check.

Agent-loop hooks

In a repository install, openlore install also wires six moments of the agent loop into .claude/settings.json, so the agent gets OpenLore's receipts without calling a tool. Each runs openlore hook <moment>, reads the hook payload, and prints at most one short receipt as the event's additionalContext — or nothing, when there is nothing new.

MomentClaude Code eventWhat the agent is told
before-editPreToolUse on Edit|Write|MultiEdit|NotebookEditthe target is a generated file (its source and regenerate command), vendored code, or a lockfile; an import or symbol the pending Write/Edit/MultiEdit text would add that does not resolve (phantom references, graded in memory before the write)
after-toolsPostToolUse, same tools and Bash; PostToolUseFailure on Bash (a failing command)a shell command is counted, and a test run is recorded (below); an edit is recorded for the session ledger, which can then name background changes; new ledger facts; for the edited file: check weakening, phantom references, and generated files; a live peer on the board that changed a symbol this worktree declared reading (declare_footprint readSet) or that orient/recall served here in the last 30 minutes
before-stopStopthe verify_change receipt for the session's diff, plus the symbols edited after the last test run and the tests that reach them, shown to you (a systemMessage): context for the agent at Stop would make it keep working
after-compactSessionStart (matcher compact)the handoff briefing of the in-flight change, so the agent resumes from computed state, not only the compaction summary (stated after every compaction)
before-subagentPreToolUse on Agent|Tasknothing: it queues the sub-agent's task (credentials redacted, kept in .openlore/session-ledger/ for at most 2 minutes), because SubagentStart does not carry it; nothing is stored when subagent-start or contextInjection is off
subagent-startSubagentStartthe sub-agent itself gets the task-scoped orient briefing for its own task, when that task is the only one queued for its session and agent type (two parallel calls of one type, or a sub-agent no Agent call started, get no task briefing rather than a wrong one), and the live peers of other worktrees on the board (declare_footprint)

Codex. A repository install also writes four of these moments into .codex/hooks.json (Codex's hooks follow the same protocol): before-edit on PreToolUse and after-tools on PostToolUse for apply_patch (every file the patch touches) and Bash, before-stop on Stop, and after-compact on SessionStart (compact). Codex runs a new hook only after you review and trust it. A patch's paths are read from Codex's working directory. A shell result's exit code is read from the Exit code: line Codex puts at the head of its output; without one, a test run's outcome is not known. The pending-edit check and the sub-agent moments are Claude Code only.

Pi. OpenLore's Pi extension appends the after-tools receipt to the result of Pi's edit, write, bash, and powershell tools, so the agent reads it with the tool's own output (the tool's machine-readable result is kept). In an OpenLore project only, it runs openlore hook after-tools in a node child process (about a second and a half; at most two at once, 20 s each, stopped on Esc), so no analyzer loads in the Pi process. A shell result's exit code is Pi's own; an aborted or timed-out command is an interrupted run. Calls a codemode script makes are skipped. After Pi compacts a session, the extension computes the handoff briefing (openlore hook after-compact) in the background, without holding the compaction open, and adds the latest one to the next prompt as a hidden conversation message (a turn waits at most 2 s for it; a briefing not ready yet goes with a later turn). An overflow retry runs before it. Pi has no before-edit or before-stop moment, so test runs recorded there are not yet stated at stop.

  • This session's changes. Facts compare with the commit HEAD was at when the session's first hook ran, so work committed earlier is not raised again in every session.

  • Once each. A fact is stated once per Claude Code session (keyed by the payload's session_id; without one, nothing is deduplicated). A fact cut by the size budget is stated on a later call.

  • Found from a subdirectory. The hook uses the nearest directory at or above the session's working directory that has .openlore/.

  • Bounded. Each receipt has a size budget (the most severe facts first, the rest counted) and a time limit (8 s, 15 s, 50 s, 30 s, 5 s, 10 s); past it the hook prints nothing.

  • Advisory. Hooks exit 0 and never block, with one exception: when your enforcement.policy makes a finding code blocking, the before-stop hook blocks the stop and lists those findings for the agent. It does not block twice in a row.

  • Repository scope only. The moments run on every edit, so a user-scope install does not wire them (they would run in every repository). Run openlore install in the repository to get them.

  • Edits after the last test run. A shell command that is a test run — a runner in command position from a closed list (vitest, jest, pytest, go test, cargo test, npm test, make test, …) or a test script the repository declares in package.json (test, test:*, e2e) — is recorded with its time, exit status (a failing command arrives as a tool failure), and the hash of every symbol in the files the session edited. cat jest.config.js or vitest --version is not a run; an interrupted run does not count. At stop, the symbols whose hash changed since the last completed run are named (deleted ones as removed) with the tests that reach them, or "not computed" with the reason; a file with no record of its symbols at the run is named as not determined; a failed last run with no later edit is named too. Edits made through shell commands are not tracked. OpenLore runs no test. When no shell command ever reached the hook, the fact is withheld with that reason. Leading VAR=value assignments are dropped and secrets redacted before a command is stored. Other shell commands are only counted, and print nothing.

  • Turning one off: "hooks": { "before-edit": false } in .openlore/config.json. openlore status lists the wired moments and marks the ones turned off.

  • A Write payload over 8 MB is not read; the hook prints nothing for it.

  • Uninstall removes only these groups (each carries _openloreHook: <moment>); your own hooks, and the opt-in openlore check-edit --hook, are left as they are.

Codex and Pi, and the sub-agent and task-created moments, follow in a later change.

Known follow-ups

  • Continue MCP registration: Continue's MCP config path varies across recent versions, so we currently only register the /orient slash command and leave a warning. See TODO(openlore-spec-01) in src/cli/install/adapters/continue.ts.

512 files · 450 not served here

Advantages

  • Deterministic, local-first operation with no LLM in the hot path ensures consistent, grounded answers. evidence: README.md
  • Provides governance guardrails that flag breaking changes and sensitive boundary violations before code is committed. evidence: README.md
  • Maintains persistent memory across sessions that survives code renames and refactors. evidence: README.md
  • Reduces agent round-trips and costs by providing structural context instead of relying on exploratory file reads. evidence: README.md

Limitations

  • Static analysis cannot recover reflective invocations, eval, or dynamic DI/plugin registries with no visible bindings. evidence: README.md
  • Small, familiar repositories may experience overhead compared to native agent search. evidence: README.md
  • Large monorepos require incremental analysis strategies after the initial full build. evidence: README.md

Security

Risk level: Low risk

This brain runs

Agent instructions that run or fetch something (169)

  • .claude/commands/first-run-hardening.md: Your job: find and fix the bugs that break a NEW USER's first-run experience — the way earlier passes found "unknown command 'orient'", "--no-embed kills BM25", "watcher EMFILE on target/", and "install never builds the index".
  • .claude/commands/first-run-hardening.md: BUILD FIRST so you test current code, not the published version: `npm run build` → drive `node dist/cli/index.js`, never bare `openlore`/`npx openlore` (those resolve the OLD published version).
  • .claude/commands/first-run-hardening.md: When comparing to published behavior, do it explicitly with `npx --yes openlore@latest` and label it.
  • .claude/commands/first-run-hardening.md: Run the REAL first-run flow as a user would, end to end, checking exit codes AND actual output of each step: openlore install # the one-command path
  • .claude/commands/first-run-hardening.md: Also exercise: init → analyze → analyze --no-embed → analyze --force → orient (no task / with task / bad --limit) → install --no-analyze → install --dry-run → install --uninstall → mcp server over stdio (initialize → tools/call orient).
  • .claude/commands/first-run-hardening.md: Idempotency / re-runs: running install or analyze twice must be a clean no-op, not a duplicate or a clobber.
  • .claude/commands/first-run-hardening.md: Treat other people's repos as READ-ONLY fixtures: after each dogfood run, remove ALL openlore artifacts (.openlore, openspec/, CLAUDE.md, ARCHITECTURE.md) and `git checkout` any modified .gitignore / settings.json.
  • .claude/commands/first-run-hardening.md: Verify the repo is clean (`git status`) before moving on.
  • .claude/commands/first-run-hardening.md: Verify honestly: run `npm run typecheck` and `npm run test:run` and report the REAL counts.
  • .claude/commands/first-run-hardening.md: confirm with `git rev-list --left-right --count origin/main...main` (want `0 0`) before and after.
  • .claude/commands/first-run-hardening.md: Branch pruning: only delete branches already merged into origin/main (verify with `git branch -r --merged origin/main`);
  • AGENTS.md: Before committing code (pre-commit hook via `openlore drift --install-hook`)
  • AGENTS.md: openlore drift --install-hook # Install as git pre-commit hook
  • AGENTS.md: [ ] No spec drift — run `openlore drift` to verify specs match code
  • AGENTS.md: - Run `openspec validate --all` to verify structure
  • AGENTS.md: - Run `openlore drift --install-hook` to catch future drift
  • AGENTS.md: Always run `openlore analyze` first.
  • AGENTS.md: Or install the Vibe skill (creates `.vibe/skills/openlore.md` as a `/openlore` slash command):
  • AGENTS.md: Because the output limit is 4 096 tokens (vs 16 000 for Claude), generation produces **shorter specs per run**.
  • AGENTS.md: **One domain at a time** — run `openlore generate` with `--domain <name>` so each invocation focuses on a single domain and stays within the output budget.
  • AGENTS.md: **Use the analysis artifacts** — always run `openlore analyze` first;
  • AGENTS.md: **Expect multi-pass generation** — large codebases may require multiple `generate` runs (one per domain) rather than a single all-domains run.
  • AGENTS.md: Then run `openlore decisions --sync` and retry `git commit`.
  • AGENTS.md: **`reason: "approved_not_synced"` — decisions approved but not written to specs:** Run `openlore decisions --sync` then retry `git commit`.
  • AGENTS.md: If yes: run `openlore decisions --consolidate --gate` and handle the result.
  • AGENTS.md: If no: retry with `git commit --no-verify` to skip the gate.
  • AGENTS.md: If yes: run `openlore decisions --consolidate --gate` and handle the result.
  • AGENTS.md: If no: retry with `git commit --no-verify` to skip the gate.
  • CLAUDE.md: CLI: `openlore coverage-gaps` | | "What's the blast radius of my diff before I commit?" | `blast_radius` — one advisory briefing: callers/layers, tests to run, anchored memories/decisions that will drift, stale specs | | "Post a deterministic structural review on a PR" (CLI, no MCP/agen …[+99 chars]
  • CLAUDE.md: Call `orient "<task description>"` (via the openlore MCP server, or `npx openlore orient --json`) **before touching a module you have not yet read in this session**, and when a task spans several modules.
  • CLAUDE.md: re-run `openlore install --preset <name>` to change it and regenerate these instructions.
  • examples/mistral-vibe/skills/openlore-analyze-codebase/SKILL.md: Suggest running `/openlore-plan-refactor` once the user has enough context to act, then `/openlore-execute-refactor` to apply the plan
  • examples/mistral-vibe/skills/openlore-analyze-codebase/SKILL.md: To activate `search_specs`, run `openlore analyze --embed` or `openlore analyze --reindex-specs`.
  • examples/mistral-vibe/skills/openlore-brainstorm/SKILL.md: Using Domain Sketch — structural analysis will be available after `openlore analyze` is run on the first implementation."
  • examples/mistral-vibe/skills/openlore-brainstorm/SKILL.md: - First implementation — run `openlore analyze && openlore generate` after
  • examples/mistral-vibe/skills/openlore-debug/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • examples/mistral-vibe/skills/openlore-debug/SKILL.md: If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
  • examples/mistral-vibe/skills/openlore-debug/SKILL.md: Run it.
  • examples/mistral-vibe/skills/openlore-debug/SKILL.md: **Apply the fix**, then run the test again.
  • examples/mistral-vibe/skills/openlore-debug/SKILL.md: Run the full test suite.
  • examples/mistral-vibe/skills/openlore-debug/SKILL.md: If the domain spec does not exist yet (`uncovered` from Step 8), note the invariant in the story/issue instead and flag it for the next `openlore generate` run.
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: "execute the planned refactoring"
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: explicit command `/openlore-execute-refactor`
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: **Prerequisite**: the `openlore-plan-refactor` skill must have been run and the plan confirmed.
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: If a coverage tool is available, run it on the target file and compare against the coverage baseline in the plan.
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: git status # must show: nothing to commit, working tree clean
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: git log --oneline -1 # note this commit hash — your restore point
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: For **each change** in the plan, execute the full mini-development cycle below.
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: **4 — TEST** Run the test gate from the plan entry.
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: Run the full test suite one final time to confirm the refactored state is clean.
  • examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md: Apply renames one file at a time, run tests after each, and respect the ≤ 50-line edit constraint.**
  • examples/mistral-vibe/skills/openlore-generate/SKILL.md: OpenLore does not validate OpenSpec structure, so run the `openspec validate` follow-up the receipt names.
  • examples/mistral-vibe/skills/openlore-generate/SKILL.md: **If validation cannot run — the CLI is missing, broken, or fails for any reason — say so explicitly and report the spec as NOT validated.** Never present an unvalidated spec as complete;
  • examples/mistral-vibe/skills/openlore-generate/SKILL.md: Finalize: after validation, run `openlore mapping refresh` when shell access is available so the persisted link index matches the spec you wrote.
  • examples/mistral-vibe/skills/openlore-generate/SKILL.md: If you cannot run it, say so explicitly — correctness is unaffected, because audit and Repair re-derive the index in memory, and only the cache is stale.
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: | Situation | Approach | |---|---| | `risk_context` present, risk 🟢 < 40 | Skip to Step 3 — use insertion point from context | | `risk_context` present, risk 🟡 40–69 | Run Step 2 impact check, then proceed | | `risk_context` present, risk 🔴 ≥ 70 | Stop — a blocking refactor story mus …[+81 chars]
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: Run `/openlore-execute-refactor` on the blocking function first, or create a blocking refactor task and return to this story once the risk is resolved.
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: Run the `openlore-repair` host skill before implementing.
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: Only run once tests are green.
  • examples/mistral-vibe/skills/openlore-implement-story/SKILL.md: | Drift type | Resolution | |---|---| | `uncovered` on new files | Note it — propose `openlore generate` post-sprint | | `gap` on existing domain | Run the `openlore-repair` host skill | | `stale` | Fix the reference | | No drift | Done |
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: To apply the plan, use the `openlore-execute-refactor` skill.
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: Each change = one atomic edit → one diff verification → one full test run → ✅ or rollback.
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: If a recent analysis already exists, skip unless the user explicitly requests a fresh run.
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: | Ecosystem | Command | |---|---| | Node.js | `npm test -- --coverage --collectCoverageFrom="<files>"` | | Python | `pytest --cov=<module> --cov-report=term-missing` | | Rust | `cargo tarpaulin --include-files <files>` | | Go | `go test -cover ./...` |
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: **Test gate**: exact test command to run after this change
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: Workflow: /openlore-plan-refactor → /openlore-execute-refactor
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: - `git diff --stat` shows only the expected files
  • examples/mistral-vibe/skills/openlore-plan-refactor/SKILL.md: Hash: <to be filled by the execute workflow>
  • examples/mistral-vibe/skills/openlore-write-tests/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • examples/mistral-vibe/skills/openlore-write-tests/SKILL.md: If `orient` returns `"error": "no cache"` → run `openlore analyze` first, then retry.
  • examples/mistral-vibe/skills/openlore-write-tests/SKILL.md: | File found | Framework | |---|---| | `vitest.config.*`, `vitest.config.ts` | Vitest — runner: `npx vitest run <file>` | | `jest.config.*` | Jest — runner: `npx jest <file>` | | `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` | pytest — runner: `pytest <file> -v` | …[+147 chars]
  • examples/mistral-vibe/skills/openlore-write-tests/SKILL.md: Run the test file with `$TEST_RUNNER`.
  • examples/opencode-skills/openlore-analyze-codebase/SKILL.md: Suggest running `/openlore-plan-refactor` once the user has enough context to act, then `/openlore-execute-refactor` to apply the plan
  • examples/opencode-skills/openlore-analyze-codebase/SKILL.md: To activate `search_specs`, run `openlore analyze --embed` or `openlore analyze --reindex-specs`.
  • examples/opencode-skills/openlore-brainstorm/SKILL.md: Using Domain Sketch — structural analysis will be available after `openlore analyze` is run on the first implementation."
  • examples/opencode-skills/openlore-brainstorm/SKILL.md: - First implementation — run `openlore analyze && openlore generate` after
  • examples/opencode-skills/openlore-debug/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • examples/opencode-skills/openlore-debug/SKILL.md: If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
  • examples/opencode-skills/openlore-debug/SKILL.md: Run it.
  • examples/opencode-skills/openlore-debug/SKILL.md: **Apply the fix**, then run the test again.
  • examples/opencode-skills/openlore-debug/SKILL.md: Run the full test suite.
  • examples/opencode-skills/openlore-debug/SKILL.md: If the domain spec does not exist yet (`uncovered` from Step 8), note the invariant in the story/issue instead and flag it for the next `openlore generate` run.
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: "execute the planned refactoring"
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: explicit command `/openlore-execute-refactor`
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: **Prerequisite**: the `openlore-plan-refactor` skill must have been run and the plan confirmed.
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: If a coverage tool is available, run it on the target file and compare against the coverage baseline in the plan.
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: git status # must show: nothing to commit, working tree clean
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: git log --oneline -1 # note this commit hash — your restore point
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: For **each change** in the plan, execute the full mini-development cycle below.
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: **4 — TEST** Run the test gate from the plan entry.
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: Run the full test suite one final time to confirm the refactored state is clean.
  • examples/opencode-skills/openlore-execute-refactor/SKILL.md: Apply renames one file at a time, run tests after each, and respect the ≤ 50-line edit constraint.**
  • examples/opencode-skills/openlore-generate/SKILL.md: OpenLore does not validate OpenSpec structure, so run the `openspec validate` follow-up the receipt names.
  • examples/opencode-skills/openlore-generate/SKILL.md: **If validation cannot run — the CLI is missing, broken, or fails for any reason — say so explicitly and report the spec as NOT validated.** Never present an unvalidated spec as complete;
  • examples/opencode-skills/openlore-generate/SKILL.md: Finalize: after validation, run `openlore mapping refresh` when shell access is available so the persisted link index matches the spec you wrote.
  • examples/opencode-skills/openlore-generate/SKILL.md: If you cannot run it, say so explicitly — correctness is unaffected, because audit and Repair re-derive the index in memory, and only the cache is stale.
  • examples/opencode-skills/openlore-implement-story/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • examples/opencode-skills/openlore-implement-story/SKILL.md: If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
  • examples/opencode-skills/openlore-implement-story/SKILL.md: | Situation | Approach | |---|---| | `risk_context` present, risk 🟢 < 40 | Skip to Step 3 — use insertion point from context | | `risk_context` present, risk 🟡 40–69 | Run Step 2 impact check, then proceed | | `risk_context` present, risk 🔴 ≥ 70 | Stop — a blocking refactor story mus …[+81 chars]
  • examples/opencode-skills/openlore-implement-story/SKILL.md: Run `/openlore-execute-refactor` on the blocking function first, or create a blocking refactor task and return to this story once the risk is resolved.
  • examples/opencode-skills/openlore-implement-story/SKILL.md: Run the `openlore-repair` host skill before implementing.
  • examples/opencode-skills/openlore-implement-story/SKILL.md: Only run once tests are green.
  • examples/opencode-skills/openlore-implement-story/SKILL.md: | Drift type | Resolution | |---|---| | `uncovered` on new files | Note it — propose `openlore generate` post-sprint | | `gap` on existing domain | Run the `openlore-repair` host skill | | `stale` | Fix the reference | | No drift | Done |
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: To apply the plan, use the `openlore-execute-refactor` skill.
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: Each change = one atomic edit → one diff verification → one full test run → ✅ or rollback.
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: If a recent analysis already exists, skip unless the user explicitly requests a fresh run.
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: | Ecosystem | Command | |---|---| | Node.js | `npm test -- --coverage --collectCoverageFrom="<files>"` | | Python | `pytest --cov=<module> --cov-report=term-missing` | | Rust | `cargo tarpaulin --include-files <files>` | | Go | `go test -cover ./...` |
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: **Test gate**: exact test command to run after this change
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: Workflow: /openlore-plan-refactor → /openlore-execute-refactor
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: - `git diff --stat` shows only the expected files
  • examples/opencode-skills/openlore-plan-refactor/SKILL.md: Hash: <to be filled by the execute workflow>
  • examples/opencode-skills/openlore-write-tests/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • examples/opencode-skills/openlore-write-tests/SKILL.md: If `orient` returns `"error": "no cache"` → run `openlore analyze` first, then retry.
  • examples/opencode-skills/openlore-write-tests/SKILL.md: | File found | Framework | |---|---| | `vitest.config.*`, `vitest.config.ts` | Vitest — runner: `npx vitest run <file>` | | `jest.config.*` | Jest — runner: `npx jest <file>` | | `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` | pytest — runner: `pytest <file> -v` | …[+147 chars]
  • examples/opencode-skills/openlore-write-tests/SKILL.md: Run the test file with `$TEST_RUNNER`.
  • skills/openlore-analyze-codebase/SKILL.md: Suggest running `/openlore-plan-refactor` once the user has enough context to act, then `/openlore-execute-refactor` to apply the plan
  • skills/openlore-analyze-codebase/SKILL.md: To activate `search_specs`, run `openlore analyze --embed` or `openlore analyze --reindex-specs`.
  • skills/openlore-brainstorm/SKILL.md: Using Domain Sketch — structural analysis will be available after `openlore analyze` is run on the first implementation."
  • skills/openlore-brainstorm/SKILL.md: - First implementation — run `openlore analyze && openlore generate` after
  • skills/openlore-debug/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • skills/openlore-debug/SKILL.md: If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
  • skills/openlore-debug/SKILL.md: Run it.
  • skills/openlore-debug/SKILL.md: **Apply the fix**, then run the test again.
  • skills/openlore-debug/SKILL.md: Run the full test suite.
  • skills/openlore-debug/SKILL.md: If the domain spec does not exist yet (`uncovered` from Step 8), note the invariant in the story/issue instead and flag it for the next `openlore generate` run.
  • skills/openlore-execute-refactor/SKILL.md: "execute the planned refactoring"
  • skills/openlore-execute-refactor/SKILL.md: explicit command `/openlore-execute-refactor`
  • skills/openlore-execute-refactor/SKILL.md: **Prerequisite**: the `openlore-plan-refactor` skill must have been run and the plan confirmed.
  • skills/openlore-execute-refactor/SKILL.md: If a coverage tool is available, run it on the target file and compare against the coverage baseline in the plan.
  • skills/openlore-execute-refactor/SKILL.md: git status # must show: nothing to commit, working tree clean
  • skills/openlore-execute-refactor/SKILL.md: git log --oneline -1 # note this commit hash — your restore point
  • skills/openlore-execute-refactor/SKILL.md: For **each change** in the plan, execute the full mini-development cycle below.
  • skills/openlore-execute-refactor/SKILL.md: **4 — TEST** Run the test gate from the plan entry.
  • skills/openlore-execute-refactor/SKILL.md: Run the full test suite one final time to confirm the refactored state is clean.
  • skills/openlore-execute-refactor/SKILL.md: Apply renames one file at a time, run tests after each, and respect the ≤ 50-line edit constraint.**
  • skills/openlore-generate/SKILL.md: OpenLore does not validate OpenSpec structure, so run the `openspec validate` follow-up the receipt names.
  • skills/openlore-generate/SKILL.md: **If validation cannot run — the CLI is missing, broken, or fails for any reason — say so explicitly and report the spec as NOT validated.** Never present an unvalidated spec as complete;
  • skills/openlore-generate/SKILL.md: Finalize: after validation, run `openlore mapping refresh` when shell access is available so the persisted link index matches the spec you wrote.
  • skills/openlore-generate/SKILL.md: If you cannot run it, say so explicitly — correctness is unaffected, because audit and Repair re-derive the index in memory, and only the cache is stale.
  • skills/openlore-implement-story/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • skills/openlore-implement-story/SKILL.md: If `orient` returns `"error": "no cache"` → run `analyze_codebase` first, then retry.
  • skills/openlore-implement-story/SKILL.md: | Situation | Approach | |---|---| | `risk_context` present, risk 🟢 < 40 | Skip to Step 3 — use insertion point from context | | `risk_context` present, risk 🟡 40–69 | Run Step 2 impact check, then proceed | | `risk_context` present, risk 🔴 ≥ 70 | Stop — a blocking refactor story mus …[+81 chars]
  • skills/openlore-implement-story/SKILL.md: Run `/openlore-execute-refactor` on the blocking function first, or create a blocking refactor task and return to this story once the risk is resolved.
  • skills/openlore-implement-story/SKILL.md: Run the `openlore-repair` host skill before implementing.
  • skills/openlore-implement-story/SKILL.md: Only run once tests are green.
  • skills/openlore-implement-story/SKILL.md: | Drift type | Resolution | |---|---| | `uncovered` on new files | Note it — propose `openlore generate` post-sprint | | `gap` on existing domain | Run the `openlore-repair` host skill | | `stale` | Fix the reference | | No drift | Done |
  • skills/openlore-orient/SKILL.md: 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`.
  • skills/openlore-orient/SKILL.md: bash scripts/orient.sh "<task description>"
  • skills/openlore-orient/SKILL.md: 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.
  • skills/openlore-orient/SKILL.md: Run `npx openlore analyze` once to seed the graph, then retry.
  • skills/openlore-orient/SKILL.md: Re-run `npx openlore analyze` to rebuild.
  • skills/openlore-plan-refactor/SKILL.md: To apply the plan, use the `openlore-execute-refactor` skill.
  • skills/openlore-plan-refactor/SKILL.md: Each change = one atomic edit → one diff verification → one full test run → ✅ or rollback.
  • skills/openlore-plan-refactor/SKILL.md: If a recent analysis already exists, skip unless the user explicitly requests a fresh run.
  • skills/openlore-plan-refactor/SKILL.md: | Ecosystem | Command | |---|---| | Node.js | `npm test -- --coverage --collectCoverageFrom="<files>"` | | Python | `pytest --cov=<module> --cov-report=term-missing` | | Rust | `cargo tarpaulin --include-files <files>` | | Go | `go test -cover ./...` |
  • skills/openlore-plan-refactor/SKILL.md: **Test gate**: exact test command to run after this change
  • skills/openlore-plan-refactor/SKILL.md: Workflow: /openlore-plan-refactor → /openlore-execute-refactor
  • skills/openlore-plan-refactor/SKILL.md: - `git diff --stat` shows only the expected files
  • skills/openlore-plan-refactor/SKILL.md: Hash: <to be filled by the execute workflow>
  • skills/openlore-repair/SKILL.md: OpenLore does not validate OpenSpec structure, so run the `openspec validate` follow-up the receipt names.
  • skills/openlore-repair/SKILL.md: **If validation cannot run — the CLI is missing, broken, or fails for any reason — say so explicitly and report the spec as NOT validated.** Never present an unvalidated edit as complete;
  • skills/openlore-repair/SKILL.md: Finalize: after validation, run `openlore mapping refresh` when shell access is available so the persisted link index matches the spec you edited.
  • skills/openlore-repair/SKILL.md: If you cannot run it, say so explicitly — correctness is unaffected, because audit and Repair re-derive the index in memory, and only the cache is stale.
  • skills/openlore-write-tests/SKILL.md: **Prerequisite**: openlore analysis must exist (`openlore analyze` has been run).
  • skills/openlore-write-tests/SKILL.md: If `orient` returns `"error": "no cache"` → run `openlore analyze` first, then retry.
  • skills/openlore-write-tests/SKILL.md: | File found | Framework | |---|---| | `vitest.config.*`, `vitest.config.ts` | Vitest — runner: `npx vitest run <file>` | | `jest.config.*` | Jest — runner: `npx jest <file>` | | `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` | pytest — runner: `pytest <file> -v` | …[+147 chars]
  • skills/openlore-write-tests/SKILL.md: Run the test file with `$TEST_RUNNER`.

Package scripts (1)

  • package.json (postinstall): node scripts/postinstall.mjs
  • Low risk: network-instructions (.claude/commands/first-run-hardening.md:21)
  • Low risk: scripts-present (bench/retrieval/run.ts)
  • Low risk: scripts-present (bench/run.ts)
  • Low risk: autonomy-phrase (examples/mistral-vibe/skills/openlore-execute-refactor/SKILL.md:240)
  • Low risk: autonomy-phrase (examples/opencode-skills/openlore-execute-refactor/SKILL.md:240)
  • Low risk: scripts-present (scripts/api-consumer-smoke.mjs)
  • Low risk: scripts-present (scripts/copy-assets.mjs)
  • Low risk: scripts-present (scripts/postinstall.mjs)
  • Low risk: autonomy-phrase (skills/openlore-execute-refactor/SKILL.md:240)
  • Low risk: network-instructions (skills/openlore-orient/SKILL.md:37)
  • Low risk: scripts-present (skills/openlore-orient/scripts/orient.sh)

Attribution and licence

Created by
Clay Good
Declared authors
  • Clay Good (declared in package.json)
Publisher
Clay Good (Community)
Source
clay-good/OpenLore · commit c45c2ca
Licence
MIT License (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Clay Good.

Install from source

450 of its files are not served here, so there is no ZIP. clay-good/OpenLore at c45c2ca