GitHub stars
296

Install

/plugin install enola@enola

Run it inside Claude Code after adding the marketplace with /plugin marketplace add enola-labs/enola.

Contents

Discovered from source

Skills 6

Enola: architecture before and after a change

Enola serves a deterministic map of the codebase over MCP: modules, symbols, routes, storage, and how they depend on each other. Ask it instead of reconstructing structure from file searches; a text search finds where a name is written and misses a package that reaches it through another, a call through an interface, and a function passed as a value.

Which tool answers what

QuestionTool
What depends on X, and what breaks if it changes?impact_analysis
Who calls X? What does X call?traverse
How does A reach B?find_path
How is this area wired?explore, query_facts, show_symbol
What does nothing use?find_orphans
What is already wrong here: cycles, layer violations, hotspots, unused routes?query_insights
Which rules govern this file?constraints_for, plan_check
What does changing this endpoint reach?endpoint_impact
Which functions do fixes keep changing?touched
Which symbol holds this line, and did a remembered one change?locate
Packaging or performance decisionspackage_metrics, analyze_performance

Before and after a change

Before editing code whose blast radius is not obvious, run impact_analysis on it, and pin a baseline with set_baseline once, if the session hook has not pinned one.

After a structural change, generate_snapshot then diff_snapshot shows what moved: findings introduced or resolved, coupling added, symbols added or removed. A layer crossed the wrong way, or coupling nobody asked for, is a reason to fix the change before presenting it.

The gate: enola check

enola check is the CLI and CI form of the same comparison, with a stable exit code. Run it after structural changes and before reporting the work complete:

enola check

A bare enola check reports the delta and fails nothing. A repository that wants enforcement names its policy, for example enola check --fail-on=layers. Use the policy the repository already declares; do not add or change --fail-on on the user's behalf.

enola reports movement from a pinned baseline, not every existing problem. A finding no policy enforced is evidence to show the user, not authorization to revert or refactor unrelated code. Do not call a change architecturally clean when the check could not run or its baseline was not comparable.

Task skills

For a whole task, load the matching skill instead of improvising the workflow: the review skill for reviewing a change or pull request, the test-plan skill for what to test, the intent skill for writing or maintaining architecture rules, and the memory skill for memories about code.

When the executable is missing

If enola is not on PATH, say that the Enola CLI is required, point the user to the repository's installation instructions, and verify with enola doctor once it is installed. Never install or upgrade the executable without the user's approval.

Architecture intent with enola

enola measures what the architecture is. Intent is what it was meant to be, written down so every snapshot compares the two. A rule nobody declared cannot fail, and a rule declared wrong fails forever, so this skill is mostly about getting the user's decisions onto the page accurately.

Intent lives in three places, and the first two use one schema:

  • enola-intent.yaml at the repository root: layers, components, rules, and the repository's seams (consumes, serves) and dependencies.
  • Files under enola/constraints/, for components and rules split by domain.
  • An enola_intent block in a markdown page's frontmatter: knowledge pages, seams, layers and claims declared where the decision was made. Never components or rules.

Ground rules

  1. The user decides what becomes law. Mined candidates, recipe bindings and your own ideas are proposals. Present them, and write only what the user accepts.
  2. Every rule needs a because: in the user's words. It is printed on every finding the rule produces. If you do not know why a rule exists, ask; do not invent a reason.
  3. Never turn on enforcement yourself. Adding --fail-on, setting a rule's mode to strict, adding an exempt: entry or a suppression are the user's calls. Exemptions and suppressions name an owner: that is a person, never you.
  4. A selector that matches nothing is the failure to watch for. It is valid, lints clean and can never be violated. Do not stop until every component and layer resolves to members.
  5. A proposal is a complete, valid declaration. When you present rules for the user to accept, every component a rule names is declared, every rule uses a real rule form, and it lints clean (see "Checking a draft" below). Accepting it should take one step.
  6. Leave generated pages alone. If a wiki's enola_intent blocks are produced by the user's own tooling, change the tooling or ask, not the generated output.

Starting from nothing

  1. Make sure a snapshot exists (generate_snapshot), so lint can resolve selectors.

  2. See what enola already infers: query_insights(explainer='layers') reports the layer pattern it recognised. enola constraints init --dry-run shows which shipped recipes bind to directories this repository has. "Nothing to bind" is a normal answer: ask whether the repository follows one of those patterns under other directory names.

  3. Propose rules the code already almost follows: enola constraints mine. Each candidate carries its regularity (for example 47/48) and names its exceptions. Show the user the strongest few, with the exceptions, and let them pick. Use --min-confidence 0.98 --top 0 when there are too many. On a small repository it often proposes nothing and counts what fell under its support floor of 10; lowering --min-support shows those, but a regularity over a handful of facts is weak evidence, so say so when you present one.

  4. Write the layer order first. It is the single most useful declaration: a declared order is graded at confidence 1.00, an inferred one caps at 0.80, so only a declared one can gate. Outermost first; each layer may depend on itself and on layers below:

    layers:
      - {name: handlers, paths: ["app/handlers/**"]}
      - {name: domain,   paths: ["app/domain/**"]}
      - {name: storage,  paths: ["app/storage/**"]}
    

    A paths entry is an exact module path or a prefix/** subtree, nothing else. An order between packages belongs here, not in one forbid rule per pair of packages. Group by role, not by directory tree, and keep a comment beside each boundary saying why it is there.

  5. Then components and rules for what layers cannot say:

    components:
      - name: storage
        match: ["storage/**"]
      - name: notify
        match: ["notify/**"]
    rules:
      - id: storage-sends-nothing
        forbid: storage
        to: notify
        via: imports
        because: "persistence must not decide what the buyer is told"
    

    match takes an exact path, a prefix/** subtree or a **/name basename glob. via is one of calls, depends_on, implements, imports. For the other rule forms (allow, protect, private, cap, require, forbid_cycles and the rest), read enola help constraints and the reference linked at the end.

  6. Validate: enola constraints lint. Repeat until it reports no problems and no component or layer with 0 members.

  7. Regenerate the snapshot and show what the declaration says about today's code: query_insights(explainer='constraints'), query_insights(explainer='layers'). Explain the default mode, ratchet: breaches that already exist stay silent, and only new ones fail. Declaring a rule does not break the build that declares it.

  8. Offer enforcement and stop. Show the command the user would put in CI, for example enola check --fail-on=layers,constraints, and leave the decision to them.

Checking a draft without adopting it

Until the user accepts it, a draft stays out of the repository. Lint it in place of the repository's declaration, with its selectors resolved against the snapshot:

enola constraints lint --declaration /tmp/draft.yaml .

Fix it until it passes and every component and layer has members. Nothing is written; files under enola/constraints/ are still read beside the draft. Make sure a snapshot exists first (generate_snapshot), or lint can only validate, not resolve.

Before editing code that rules govern

  • plan_check (or enola plan --paths <files>) lists the rules governing the files you are about to touch and their blast radius. A path that does not exist yet still answers.
  • enola plan --patch change.diff evaluates a diff on a scratch copy and names the rule any new edge would breach, before the edit lands.
  • constraints_for gives one file's or fact's components, the rules binding them, and the violations already naming it.
  • governing_intent names the decision pages whose anchors cover the code, and the code a page governs.

Shape the change to satisfy the rules. If a rule is in the way, say so; do not edit the rule to make your change pass.

When a breach is reported

Present it with its because: and help the user choose, strongest first:

  1. Fix the code. The rule stands and the change was wrong.
  2. Exempt it with an exempt: entry on the rule, naming the exact witness, an owner, a because: and a since: date. For carve-outs decided to be out of scope for good.
  3. Suppress it in .enola/suppressions.yaml with owner, reason and date. Temporary: the violation is real but must not block a strict rule while it is worked off.
  4. Leave it to the ratchet. Only for breaches that predate the rule. Nobody decided anything, which is why anything decided deserves 2 or 3.

enola constraints explain <file> answers "why does this file belong to that component": the selector that admitted it, its edges, and what would change if it moved.

Keeping the law honest

enola constraints ledger lists every rule beside its breaches and the exemptions and suppressions excusing them, with each excuse's owner and age. Bring three things to the user:

  • a rule whose breaches are mostly excused, which is a rule to reconsider;
  • old excuses, whose reasons have probably stopped being true;
  • excuses that matched nothing, which can be deleted today.

The ledger reads the snapshot, so regenerate first if the declaration changed.

Reference

Memory anchored to code

A memory about code ("this function retries twice because the API rate-limits", "the bug in X came from Y") is only as good as its link to that code. Kept as text, it is found by words and goes stale silently. Anchored with enola, it is keyed by the symbol it describes, found through the graph, and checked against the code before it is trusted.

enola does not store memories. It supplies the key (a stamp) and the check. The memory stays wherever the user keeps memories.

The stamp

locate with the place the memory is about returns the symbol holding it:

locate(locations=["src/billing/retry.ts:42"])

or enola locate src/billing/retry.ts:42 on the command line (--json for the fields). Keep these fields from the symbol, plus the cited fields when one line was named: id, repo, name, symbol_kind, body_hash, inner_hash, decl_hash when present, and cited_hash with cited_lines.

Cite the narrowest place the memory is about: one line for a bug or a gotcha, the declaration line for a memory about the whole function. A line outside every symbol (an import, a package-level block) gets no stamp; record the file path instead.

The stamp names the innermost symbol enola holds at that line, which can be smaller than what a reader would call a declaration: a method of an object literal that a function returns, a function named inside another function, a default export written as a call. Every status below is about that symbol, not the function around it. Do not overrule a status because the symbol is not a declaration by some other definition.

Saving a memory

  1. Write the memory as the user's memory system expects.
  2. If it is about specific code, stamp each place it is about and store the stamps with it: in the store's metadata or frontmatter if it has any, otherwise in a block at the end of the memory, otherwise in a JSONL sidecar keyed by the memory's id. Keep file:line beside the stamp for a human reader.
  3. Do not stamp memories that are not about code: preferences, people, decisions with no code location. They are recalled the usual way.

If the memory system already calls enola (cognee, for example, stores locate stamps), reuse its stamps rather than adding a second set.

Recalling what is relevant

Relevance comes from the graph, not from words in the memory.

  1. Name the task's symbols: locate on the lines you are about to change, or the symbols the user named.
  2. Widen by one or two hops: impact_analysis(target=<symbol>, max_depth=2, include_forward=true, output_mode='compact') lists what depends on it and what it depends on.
  3. The relevant memories are the ones whose stamp name is among those symbols. Rank them: the symbol itself first, then one hop away, then two, then memories recorded only by file path in the same files.
  4. Check only those stamps, as below. Checking every memory in the store on every task is cost without benefit.

Checking before use

Pass the candidates' stamps to locate(stamps=[...]) in one call, or enola locate --stamps stamps.jsonl. Act on each status as follows, and do not re-derive a status by reading code: enola already compared the versions.

StatusWhat it meansWhat to do
currentSame symbol, same codeUse the memory as it is
rewrittenSame symbol, its code changed. change: signature means only the signature did; change: body means the body didFor signature, a memory about behaviour still holds; one about how to call it needs a look. For body, re-check the claim against the code (show_symbol) before relying on it, then re-stamp it or update it. cited: intact means the cited lines are still in the symbol
movedSame code under a new id, in another file or packageReplace the stamp with the returned symbol's fields. Nothing to re-check
presentSame symbol, but a version is missing on one sideTreat as unverified
gone, no candidatesThe symbol is not in the graphThe code it described was deleted. Mark the memory stale and ask the user before removing it
gone, with candidatesSame name with other code, or a copy elsewhereProbably moved and rewritten at once. If the memory matters for the task now, look at the best candidate once; otherwise mark it unresolved and move on
ambiguousMore than one symbol fitsKeep the memory and show the candidates; do not pick one

Stamps are checked against the current snapshot. Refresh it first (generate_snapshot) if the code changed since. To check against a recorded revision instead of the working tree, use the CLI: enola locate --at <commit> --stamps stamps.jsonl.

Keeping memory clean

When the user asks to tidy memories, check every stamped memory in one batch and report counts per status, then the gone and rewritten ones by name. Update moved stamps without asking. Changes to or removal of a memory's content are the user's call.

Structural review with enola

A diff shows lines. This review answers what the lines did to the system: which findings the change introduced, which coupling it added, which code it reached beyond what it said it was about, and which of the code it changed carries the most risk. It works from two snapshots, before and after, and reports only the difference.

It is not a bug hunt. Read the diff for correctness as well, or pair this with a line-level review.

1. Get the "before"

Pick the first that applies.

  • Your own session's edits, with a baseline pinned at the start (by you with set_baseline, or by enola's session hook): use diff_snapshot after a generate_snapshot, or enola check --detail.

  • A branch or pull request: grade it against where it left the target branch (their merge-base), with no baseline pinned:

    enola check --base origin/main --detail          # the PR's target branch
    

    enola exports the merge-base, snapshots it with the repository's configuration and removes it again; nothing is written to the repository. Use main (or the branch's local name) where there is no origin remote.

  • Both sides already recorded in enola's history (enola log lists revisions): enola diff <base>..<head> compares them without an export.

If enola check declines to grade (exit 3), say so and do not present the change as clean: the reason it gives (configuration, extractor version) is enola's setup, not the change.

2. Read the verdict

From the enola check output, report:

  • New findings. Each with its explainer and confidence. 1.00 is measured exactly; below that it is an estimate against this repository's own norms. A finding no policy enforces is still worth showing; say that nothing enforced it.
  • Resolved findings. Credit what the change fixed.
  • New coupling. Imports and calls the change added between packages. An added edge is normal work; one that crosses into an area the change has no business in is not.
  • Removed symbols. Listed under "Removed", and their callers under "Removed coupling". For each one that was exported, search the current tree for its name: a caller the change did not update is the thing to look at.

enola files a hotspot that only moved in or out of its top-20 list under "Incidental shifts", not as new or resolved. Another ranked or statistical finding about code the diff did not touch is usually the same thing: check its file and line against the diff, and if the change did not touch it, say so in one line and move on.

If the repository declares a policy (CI runs enola check --fail-on=...), run with the same flags so the verdict matches what CI will say. Do not invent a policy.

3. Find where to look

  1. Map the diff to symbols. On a diff of a few functions, reading it is enough; on a larger one:

    git diff "$(git merge-base HEAD origin/main)"...HEAD > /tmp/change.diff
    enola locate --diff /tmp/change.diff
    

    It lists every changed function and type with its line span. Lines "outside every symbol" are imports, package-level declarations and the like.

  2. Rank changed symbols by blast radius. Run impact_analysis on each changed symbol (the MCP tool keeps the graph loaded; the CLI enola impact reloads it per call). enola check writes no snapshot, so if the MCP tools answer that no facts are loaded, call generate_snapshot once first. The dependent count, the endpoints reached and the modules holding most dependents are what make a one-line change in a widely used function the riskiest line of the diff.

  3. Check the rules governing the touched files. plan_check or constraints_for per file names the declared rules and their because:. A change that follows the letter of a rule but works around its reason is worth a comment.

  4. Check history. touched(since=..., subject='(?i)^fix\b') (or enola touched --subject '(?i)^fix\b' --since <date> --top 0) ranks the functions fixes changed most. A changed symbol near the top of that list has broken before.

  5. Check scope. If the change says what it is about (a PR title, a ticket, the user's request), pass that as the target: enola check --base origin/main --target=<package> --max-spillover=0. Spillover lists packages the change touched that neither the target nor its dependents explain. It is a question for the author, not a defect.

  6. Suggest reviewers. enola check --base origin/main --reviewers names the main authors of each touched module.

4. Write the review

Keep it short and ordered by what a reviewer should do:

  1. Verdict: regressions introduced, resolved, and whether any policy enforced them.
  2. Where to look: at most five places, each a symbol with file and line, and why: its blast radius, the rule governing it, its fix history, or spillover.
  3. What changed structurally: new packages, new cross-package coupling, removed symbols with dependents.
  4. What enola could not see: the "could not see" line of enola check (ignored files, imports outside the graph). Runtime behaviour, tests and logic are outside what a structural comparison measures.

Do not pad it with structure that did not change. If the change is structurally clean, say so in one line and spend the review on the places it reaches.

Set up Enola

This plugin configures Claude Code to use Enola, but it does not install the Enola executable. The executable must be available on PATH before its MCP server and hooks can run.

First check whether it is already installed:

command -v enola && enola doctor

If enola is missing, explain what the following command does and ask the user before running it. On macOS, Linux, or Windows through Git Bash/WSL, use the official installer:

curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh

Alternatively, where Python and pip are available—including native Windows—use:

pip install enola-cli

The package is named enola-cli, but the installed command is enola.

After installation, run:

enola doctor

If the shell still cannot find it, explain that the installation directory must be on PATH. Do not modify shell startup files without the user's approval. Once enola doctor succeeds, tell the user to restart Claude Code or run /reload-plugins so the MCP server starts with the updated environment.

Never install or upgrade Enola without explicit user approval.

Test plan from the graph

A change is tested by the paths that reach it: the routes, commands and jobs a user or another service enters through, and the tests that call into it. enola knows both from the graph, so the plan comes from what the change actually reaches, not from what its file names suggest.

The output is a plan for a person or an agent to carry out. This skill does not run tests or judge them.

1. Name the changed code

  • For a diff (a branch, a PR, uncommitted work):

    git diff "$(git merge-base HEAD origin/main)"...HEAD > /tmp/change.diff
    enola locate --diff /tmp/change.diff
    

    or locate with the diff text. Every changed function and type comes back with its file and line span.

  • For a planned change: the symbols or files the user names. plan_check with the paths gives their blast radius before any edit.

Make sure the snapshot matches the code you are planning for (generate_snapshot after the change is in the working tree).

2. Entry points to exercise

  • Flows. enola flows --through <symbol> lists the entry points whose calls reach a changed symbol: a served route's handler, a program's main, a subcommand, a framework hook. Each is something to exercise. Flows marked side (examples, scripts, migrations, build tooling) come after the program's own.
  • Endpoints. impact_analysis reports "Endpoints affected" for a symbol. For each affected route, or each route the diff changes, endpoint_impact names the controller, the models and tables behind it, the client call sites that send it, and the app screens that depend on it. Screens and client calls are the end-to-end checks.
  • When nothing reaches it. A library's code is entered by its users, and code injected into a browser or another runtime is entered by that runtime, so no flow or endpoint in the graph leads to it. Its entry points are then its public API and the examples, playgrounds or end-to-end specs that exercise it: search the test and example directories for the feature's names and fixtures.
  • Across services. In a multi-repository snapshot, endpoint_impact includes callers in other repositories. coverage_report says which services have calls enola could not resolve; a change behind such a service may have callers the plan cannot list, so say so.

3. Existing tests that reach the change

impact_analysis(target=<symbol>, max_depth=6, output_mode='compact') lists test files as test_ref dependents, by depth. A test at depth 1 calls the symbol directly; at depth 4 it reaches it through three other functions, and a failure there says less about this symbol. List the tests to run, nearest first, grouped by symbol.

A changed symbol with no test_ref within that depth is untested by any reference enola can see. That is the most useful line in the plan. Call it out with the symbol, file and line, and propose what a test for it would call.

Tests reach code by name. A test that drives the code through an interface, a router, a subprocess, a browser or reflection is invisible here, so "no test_ref" means "no test names a path to it", not "certainly untested". Check such a symbol's package for integration tests before reporting it as uncovered.

4. Where it has broken before

  • touched(since=<a year ago>, subject='(?i)^fix\b') ranks the functions that fixes changed most. A changed symbol in that ranking has regressed before: give it a targeted test, not just a pass through the happy path.
  • The changed symbols with the most dependents (the totals from step 3) carry the most risk per line changed.

5. Write the plan

  1. Run these tests: existing test files, nearest first, with the command if the repository's test runner is obvious.
  2. Exercise these entry points: each flow, route or screen, with what to check there, ordered by how directly it reaches the change.
  3. Untested changed code: symbols no test reaches, with a one-line suggestion each.
  4. Higher risk: symbols with fix history or a large blast radius.
  5. Not covered by this plan: callers enola could not resolve, and anything reached only at runtime (configuration, reflection, message consumers without a contract).

Keep it to what the change reaches. A plan that lists every test in the repository tells the reader nothing.

MCP servers 1

Sponsors

Details

Marketplace
enola-labs/enola
Source
plugins/enola
Category
Community