boffin

Boffin: strict routed architectural guardrails for AI coding agents, powered by ParselFire Core.

Open source Open in the app JSON README (API)

About

Boffin: strict routed architectural guardrails for AI coding agents, powered by ParselFire Core.

Details

Kind: Plugins
Topic: No topic detected
Publisher: micsm
Origin: gemini
Category: ferramentas
Version: 1.0.1
Stars: 38
Last push: 2026-08-23T11:24:56Z
Repository state: ativo
Language: JavaScript
License: MIT
Added: 2026-08-30 14:13:39
Updated: 2026-08-30 14:13:39
Origin id: micsm/boffin

README

# Boffin

**Boffin (npm: `boffinit`) is a staff-engineer control layer for AI coding
agents: it feeds the agent the architectural constraints for the exact file it
is editing and makes it verify the result -- [DuckDB case study](examples/before-after-cpp.md):
a guided refactor landed at `+17 / -17` lines with 2,104 assertions passing.**

You ask for a 15-line fix; the agent comes back with a 500-line renovation.
Boffin gives the agent the architectural constraints that apply to the file it
is about to touch, then makes it verify the result.

It is not another `AGENTS.md` and not a prompt pack. Those formats usually ship
one static instructions block for the whole repository; Boffin routes only the
constraints relevant to the current edit. Powered by **ParselFire Core**.

```sh
npx boffinit cursor
```

## What Boffin is not

- Not a static repo-wide rules file (`AGENTS.md`-style one block for everything)
- Not a prompt pack or system-prompt trick
- Not a linter or CI gate -- it acts before and after the edit
- Not a speed tool -- the frame is review-safety

## What Boffin does

- Selects the constraints relevant to the edit in front of the agent
- Requires verification proportional to the change
- Ships for Cursor, Claude Code, Codex, and OpenCode from one npm package
- Delivers signed portable packs powered by ParselFire Core

## How it differs (honest comparison)

| | Static rules file (`AGENTS.md`) | Boffin |
|---|---|---|
| Delivery | Usually one static block for the whole repo | Constraints routed to the current edit |
| Verification | None required by the format | Required, proportional to the change |
| Evidence | Usually none | Recorded case studies with numbers |

## Proof, not promises

The public case studies record these guided refactors on real open-source code:

- **[DuckDB](examples/before-after-cpp.md):** `+17 / -17`; 2,104 assertions
across 8 test files passed; distinct continuation and recovery paths were
preserved.
- **[FastAPI](examples/before-after-python.md):** `+16 / -33`; 49 tests passed;
no public API change.
- **[LangChain](examples/before-after-python.md):** the sync/async boundary was
preserved; 4 tests passed.

These are reproducible case studies, not a controlled A/B benchmark.

## Install

Boffin requires Node.js 18 or newer.

### Cursor

Run from your project:

```sh
npx boffinit cursor
```

### Claude Code

Run these inside Claude Code:

```text
/plugin marketplace add MicSm/boffin
/plugin install boffin@boffin
```

### Codex

Run these from a terminal:

```sh
codex plugin marketplace add MicSm/boffin
codex plugin add boffin@boffin
```

Codex does not trust plugin hooks automatically. Run `/hooks` once inside Codex
to review and trust Boffin's hooks; until then the plugin's skills work but the
automatic per-session activation stays off.

### OpenCode

Run from your project:

```sh
npx boffinit opencode
```

Then open the project in OpenCode. Always-on guidance lands via
`opencode.json` -> `.boffin/AGENTS.md`. On demand: `/boffin`,
`/boffin-review`, or the `boffin` / `boffin-review` skills.

Install details, commands, and troubleshooting:
**[OpenCode delivery](docs/opencode.md)**.

Want the machinery? Read **[how ParselFire Core works](docs/engine.md)**.

## What Boffin is fussy about

Similar code is not always the same code. Boffin gives the agent a reason to
stop before it merges a real special case, blurs a sync/async boundary, moves
state away from its owner, or turns a focused task into a tour of the codebase.

- For a focused change, it keeps the requested scope small and asks for the
narrowest check that proves the edit.
- For an open-ended refactor or review, it requires a read-only audit first,
followed by one verified finding at a time.
- When cleanup conflicts with an earlier correctness rule, correctness wins.

The point is not to make the agent timid. It is to make the expensive details
explicit before they become an interesting afternoon.

## FAQ

### How is Boffin different from AGENTS.md?

`AGENTS.md` is usually one static instructions file for the whole repository.
Boffin routes only the architectural constraints relevant to the file the agent
is about to edit, then requires a check proportional to the change.

### Where do the constraints come from?

Every rule ships in this repository as readable, versioned markdown under
[`packs/`](packs/), and the packs are GPG-signed. Nothing is hidden at install
time: open any pack and read every rule before trusting it. At edit time Boffin
selects which of those rules apply to the file being touched. See
**[how ParselFire Core works](docs/engine.md)** for the routing map.

### Why does my coding agent turn small fixes into huge rewrites?

You ask for a small fix; the agent comes back with a renovation. Boffin
injects the load-bearing constraints for the current file before the edit and
forces verification afterward.

### What do `lite`, `full`, and `max` change?

They tune cleanup ambition, not correctness:

- `lite` keeps cleanup pressure low and favors the smallest useful change.
- `full` is the balanced default.
- `max` applies the strongest cleanup pressure when the task justifies it.

On plugin hosts, select a profile with `/boffin lite`, `/boffin full`, or
`/boffin max`. There is no `off` profile.

### Do profiles change the safety floor?

No. Every profile keeps the same early correctness stages and rejection rules,
including trust-boundary validation, data-loss prevention, security, and
accessibility requirements.

### What are `boffin:` comments in generated code?

`boffin:` marks are machine-readable audit tokens: they let you grep/harvest
which invariants held and which were refused across a codebase. Nothing is
sent anywhere; the payload is the invariant itself. Disable with one line:
create an empty `.boffin-trace-off` file at the repository root.

### Is Boffin a command sandbox or security tool?

No. Boffin does not isolate processes, filter shell commands, or restrict
filesystem or network access. It guides architectural decisions in generated
code. Use command sandboxes and security controls for their own job; Boffin has
a different job.

### How do I uninstall the Cursor or OpenCode integration?

```sh
npx boffinit cursor uninstall
npx boffinit opencode uninstall
```

Each uninstaller removes that host's managed files only. Shared
`.boffin/packs` and `.boffin/VERSION` stay if the other host is still
installed. Unrelated project files are left alone.

### Does Boffin replace tests or code review?

No. It tells the agent which contracts deserve attention and requires external
checks, but your repository's tests and review process remain authoritative.

## Other hosts

Portable adapters cover hosts that read `AGENTS.md`, `CLAUDE.md`, workspace
rules, or repository instructions. See
**[host delivery and adapters](docs/engine.md#host-delivery-and-adapters)** for
the technical map.

## Project

- Repository: <https://github.com/MicSm/boffin>
- Engine documentation: [ParselFire Core](docs/engine.md)
- Evidence: [Python](examples/before-after-python.md) and
[C++](examples/before-after-cpp.md)
- Contributions: [CONTRIBUTING.md](CONTRIBUTING.md)

Boffin is available under the [MIT License](LICENSE). See [credits](CREDITS).

```sh
npx boffinit cursor
```

boffin

About

Details

README

More