dazzer-plugin

Imported from dazzer-io/dazzer-plugin (AGENTS.md). Install upstream with npx skills add dazzer-io/dazzer-plugin. Copyright stays with the author.

Dazzer plugin

Purpose

What people install so their AI actually uses their Dazzer memory. It adds three nudges: check the memory before answering, save what settled once enough has accumulated, and get re-oriented after a context reset.

It never talks to Dazzer. It has no credentials and no reliable moment at which a connection is up. All it does is tap the model at the right instant; the model then acts through the connection it already owns and reads the current rules from the Brain at the moment it acts. That is why the shipped script is near-static: change the rules in the Brain, not here.

Layout

Key patterns

• Checks are Node, never shell. A check that validates a structured message must parse it. Writing checks in the same language as the thing they guard is how the first defect happened - a shell pattern mistaken for a parse.
• No package manifest, no dependencies. Nothing here is built or published to a package registry; it is installed by copying files. Keep it that way.
• Every tunable value is named and lives outside the code. A number written into the script is a number nobody can find or change.
• Changing an install step means changing it twice. The README is what a person reads; tools.manifest.json is what a screen renders. Edit one without the other and install-parity refuses the run, naming both files. Adding a tool means a README block and a manifest entry, together.
• The reminders' wording is not cosmetic. Onboarding proves the reminders are installed by looking for one of those sentences in what the AI could see — nothing else puts them there. Reword one without updating spokenSentences and reminder-parity refuses. The direction that matters is the quiet one: words declared that nothing says would report every correctly installed person as not set up.

Where work happens

The main checkout is read-only: file-tool writes into it are refused (.claude/hooks/reference-copy-guard.sh) — shell redirection is not intercepted, so the guard is a floor, not a seal. All work happens in a linked worktree under ../dazzer-plugin-worktrees/<what-it-does>, created by node scripts/git-health.mjs new <kind>/<what-it-does> so its folder name matches its branch. status reports every worktree, what is unsaved, what is unpushed, what has gone cold, and where two branches touch the same files; open work is snapshotted each turn and untouched branches retire to archive/<name> after 14 days (scripts/git-health.mjs). Some tools place their own worktrees inside this checkout — those are judged by what they hold, never by where they sit. Proven by gate git-health.

Testing

node scripts/baseline.mjs runs everything. It stays green while listed defects fail, and prints what is still outstanding by name.

The ledger is shrink-only in both directions: an unlisted failure fails the run, and a listed entry that starts passing also fails it. That second rule is deliberate — it makes a fix prove itself to the runner instead of being announced in a commit message. When you fix something, delete its line.

The suite takes its interpreter from SHELL_UNDER_TEST. Never name a shell inside the suite: the system shell is bash-in-posix-mode on a Mac and dash on a Linux runner, and they disagree on exactly the comparison one defect lives on.

Critical rules

Violating either of these means the work is not done. Both exist because something already broke for real people, and both are machine-enforced, so arguing around them fails the run.

1. plugins/dazzer MUST NOT contain a connection of any kind, at any depth, in any file — not even "just for telemetry". A bundled connection carries its own sign-in, so installing the behaviour replaced a working, signed-in connection with an unauthenticated one and people's memory went dark until they noticed. Someone who already connected must never have to sign in again just to get a few reminders. Enforced by connection-isolation. Origin: commit 3c6fe7a.

2. A shipped connection MUST point at an address we own. The first release shipped the hostname the hosting platform generated. Every install would have baked in one provider, one project and one region, and any move would have broken every copy in the field with no way to reach them. Enforced by connection-address. Origin: commit a33a129.

Boundaries

• The rules the model follows live in the Brain and are served live. This repository holds triggers, not teaching. If you find yourself writing the rulebook in here, stop — a second copy will silently diverge from the real one.
• The checkpoint script is the only thing with real reach: it runs on every reply on someone else's machine and can hold their session open. It fails open by construction — the decision defaults to staying quiet, and only a comparison that actually succeeded can turn it on. Never restructure it so that "do nothing" is the branch you have to remember to take.
• Anything the incoming message says is untrusted input. Read named fields, check their shape, and confine anything that becomes a filename to the folder this plugin owns.