enola-guides

Shows a team how to work this way, with decisions anchored to code, laws in CI, and agents that read before they write.

Set this up in your team Source on GitHub rubygems.org

Role: Author and maintainer
What: A Ruby gem: 12 guides, 26 laws to copy, worked examples, 9 agent skills, 4 hooks
For: Ruby and Rails teams adopting enola
Releases: 8 on rubygems.org since August 2026; 0.3.1 is the latest
License: Apache-2.0

templates/hooks/intent-first-gate.sh · an agent's first edit in app/billing

intent-first gate (shop): first write for this piece of work.

Before app/billing/charge.rb moves, read what governs it and check the intended change
against it. If the change deviates from what the governing page records,
amend the page first; if nothing governs this work, say so and ask
whether it should be shaped.

Plan report for shop
Snapshot: no snapshot at /tmp/shop/.enola — governance answers from the declarations alone; blast radius is unmeasured

Target app/billing/charge.rb (path)
  No measured fact lives at this path — governance below covers code about to be written.
  Component billing (declared in enola/constraints/billing-is-documented.rb)
    rule billing-is-documented [ratchet]: every file of billing must be governed by a compiled page
      because: code under a decision needs the page that decided it
    rule billing-keeps-to-its-own-tables [ratchet]: billing must reach only the tables it owns
      because: a part that writes another part's table owns a bug it cannot see

A report, never a gate: these verdicts are for the caller to weigh before editing.

Retrying proceeds. This gate re-arms on every user message; within one
piece of work it will not fire again for shop.

Real output from the gem's intent-first hook, run on a copy of its rails-shop example. The agent's first write is held once, with the laws that govern the file; the retry goes through.

Agents write fast. They don't know what you decided.

A coding agent sees the files in front of it, not the decisions behind them. Nothing in the code tells it that billing must not write another part’s tables, or that a background job never calls a controller. So teams write longer prompts and longer reviews, and the knowledge that matters stays in people’s heads.

enola-guides is how I close that gap with enola: write the decisions down, anchor them to the code they govern, check them in CI, and have the agent read them at the moment it is about to change that code.

What it does.

Architecture rules your team can read, checked in CI.

Each rule is a law, written as a sentence in a Ruby DSL, one file each, with the reason beside it. The gem ships a catalogue of 26 laws to copy, from foreign keys on a tenant column to parts that may not cycle. The CI check reports first and only fails the build once the team decides it should.
examples/rails-shop/enola/constraints/billing-is-documented.rb
```
Enola.architecture "shop" do
  part :billing, files: ["app/billing/**", "app/models/invoice.rb"]

  law "billing is documented" do
    billing.must_be_governed
    since "2026-09-01"
    why "code under a decision needs the page that decided it"
    mode :ratchet
  end
end
```
Decisions anchored to the code they govern.

A decision page in the knowledge base names the files it governs, so any file can answer which decision applies to it, and a law can require that code under a decision has its page. A number in the prose cites a receipt (the commit, the enola version, a fingerprint), so a script can check it again. As guide 9 puts it: “A claim nobody can re-check is a sentence, not a fact.”
examples/knowledge-base/wiki/shop/permanent/architecture.md
```
---
title: Shop architecture
enola_intent:
  governs:
    - app/jobs/**
    - app/models/**
  decisions:
    - jobs enqueue, models decide; a job never calls back into a job
---

# Shop architecture

Orders are written by `OrderService` only; the two other writers the
graph reported in 2026-08 were folded into it. `Order` has 41 dependents
(receipt shop@3f2a9c1, fingerprint 8d1e…c40a).
```
Hooks and skills that fire at the right moment.

Four hooks for agent sessions. The intent-first gate holds the first edit in a repository once and shows what governs the file, as above. The turn record notes what moved. Stop-time debt holds once when code under a decision changed and the decision did not. Session refresh rebuilds the graph when the code has moved on.

Nine skills ask the graph at a fixed moment: before planning, while taking in a new source, on a schedule, before a push. They report; the people decide.
templates/ · what a team copies into its repository
```
hooks/
  intent-first-gate.sh   record.sh
  stop-debt.sh           session-refresh.sh
skills/
  enola                  enola-laws
  enola-intent-first     enola-grade-before-push
  enola-deepdive         enola-ingest-check
  enola-drift            enola-citation-hygiene
  enola-zoom-out
enola-check.sh           enola-findings.rb
enola-cluster.yaml       constraints-starter/
```

From install to a first law in ten minutes.

Twelve guides, in reading order: start here, a Rails app, an Ember app, writing laws, constraints in CI, hooks and agents, providers, beyond one repository, and four on running a knowledge base with enola. The rails-shop example declares thirteen laws, and one command validates them all.

$ enola constraints lint . (shortened)

enola constraints lint: repo /tmp/shop (built-in default config)

shop: declared by constraints files under enola/constraints/.
  enola/constraints/a-mutating-action-is-authorized.rb: 11 component(s), 1 rule(s), 0 exemption(s)
  enola/constraints/background-jobs-never-invoke-controller-code.rb: 10 component(s), 1 rule(s), 0 exemption(s)
  enola/constraints/billing-is-documented.rb: 1 component(s), 1 rule(s), 0 exemption(s)
  enola/constraints/billing-keeps-to-its-own-tables.rb: 1 component(s), 1 rule(s), 0 exemption(s)
  enola/constraints/the-public-api-stays-small.rb: 1 component(s), 1 rule(s), 0 exemption(s)
  … eight more laws, and enola's built-in recipes

OK — every declaration is valid.

How I work with knowledge bases.

This is the method I run my own work on: one knowledge base across all the repositories of a system, decisions written down before structural changes, and agents that read them before they write. This site runs the same way, on pi-brain, and brain is where it started.

The guides are that practice written down, so a team can adopt it, pin it as a gem, and keep it after I leave. When I help a team become AI-native, this is what I set up.

The AI-native offer

Source on GitHubmisabegovic/enola-guides, the original
rubygems.orggem install enola-guides
enolathe tool the guides are for
How I work with knowledge basesthe practice, across all my tools

enola-guides

Agents write fast. They don't know what you decided.

What it does.

Architecture rules your team can read, checked in CI.

Decisions anchored to the code they govern.

Hooks and skills that fire at the right moment.

From install to a first law in ten minutes.

How I work with knowledge bases.

Want this in your team?

Want a second opinion?