Related Pages

Related topics: ParselFire Core Engine, Host Integrations

Overview and Installation

Project Identity and Scope

Boffin is distributed as a single npm package, boffinit, currently at version 0.3.2. The package is the canonical entry point for users and bundles three concrete delivery surfaces:

• an installer used to set up Boffin in a target environment
• one or more packs that ship the project's rule/knowledge content
• host integrations that adapt those packs to specific applications or runtimes

According to the release notes for v0.3.2, none of these three surfaces changed behavior in the latest release; v0.3.2 is strictly a documentation and metadata refresh. Source: README.md:1-20, package.json:1-30

The README positions Boffin against the baseline of "static rules files," arguing that Boffin offers a more structured alternative, and leads with case studies (including a DuckDB-focused case study) to demonstrate the trade-offs. Source: README.md:1-40

Installation

The recommended installation is through npm, using the published package name boffinit:

npm install boffinit

This installs the full distribution: installer, packs, and host integration glue. From there, the installer (invoked from the installed boffinit binary or programmatic entry point) is responsible for placing packs into the correct locations for the chosen host integration. Source: package.json:1-40

For reference, the project also exposes its identity through the VERSION file at the repository root, which is what the v0.3.2 release notes refer to when describing the latest published artifact. Source: VERSION:1-1

Versioning and Citation

The project uses a plain MAJOR.MINOR.PATCH SemVer scheme; 0.3.2 is a patch-level metadata release. Because the bump only touched documentation and metadata, existing consumers of [email protected] do not need to change their integration code when moving to 0.3.2. Source: README.md:1-20, VERSION:1-1

CITATION.cff is provided at the repository root so that the project can be cited in academic or professional contexts (for example, in the DuckDB case study). It is regenerated as part of the metadata refresh and carries the current version, author, and release information. Source: CITATION.cff:1-30

License and Attribution

The license under which Boffin is distributed is recorded in the LICENSE file at the repository root; any installation via npm inherits the same terms as the published tarball. Source: LICENSE:1-20

Attribution for external material, datasets, or third-party evidence used in Boffin's case studies (including the DuckDB case study mentioned in the v0.3.2 release notes) is consolidated in the CREDITS file. The latest release performed an evidence-credit cleanup specifically for the DuckDB case study, so users reproducing that study should consult CREDITS for the corrected attributions. Source: CREDITS:1-30

Getting Started Workflow

flowchart LR
  A[Read README.md] --> B[npm install boffinit]
  B --> C[Run installer]
  C --> D{Select host integration}
  D --> E[Place packs]
  E --> F[Use Boffin in target app]

For most users, the on-ramp is the three-step path shown above: read the rewritten README to understand the problem statement and review the up-front case studies, install boffinit via npm, and then run the installer with the desired host integration selected so the packs are wired in correctly. Source: README.md:1-60, package.json:1-40

Related Pages

Related topics: Packs and Constraint Routing, Skills, Profiles and Workflows

ParselFire Core Engine

The ParselFire Core Engine is the central processing component of the boffin project, responsible for ingesting, normalizing, and applying AI-generated coding instructions across host environments. It acts as the rule-resolution layer that converts declarative rule packs into enforceable runtime behavior within agentic coding assistants.

Purpose and Scope

ParselFire bridges the gap between static rules files (such as .cursorrules, CLAUDE.md, or similar instruction manifests) and dynamic runtime enforcement. Unlike traditional rules files that are passively read by models, ParselFire actively participates in tool selection, prompt construction, and action validation during AI-assisted coding sessions.

The engine is invoked through the boffinit npm package (published as [email protected]), which serves as the distribution and installation vehicle. The engine itself is host-agnostic: it can be embedded into multiple AI coding assistants without modification, provided the host integration layer conforms to the expected hook contract.

Source: docs/engine.md

Architecture and Component Layout

The engine is decomposed into several collaborating modules, each with a well-defined responsibility:

This separation allows the core engine logic to remain stable while the installer and host adapters evolve independently. The v0.3.2 release explicitly noted that "Installer, packs, and host integrations: no behavior change," indicating that the core engine contract is preserved across minor versions.

Source: lib/installer.js, lib/cli.js

Engine Workflow

The engine follows a deterministic, four-stage pipeline whenever a host environment triggers the runtime hook:

1. Discovery — The runtime hook calls into the engine to enumerate available rule packs on disk using the path resolver.
2. Normalization — Raw rule fragments (parcels) are parsed, scoped, and merged according to precedence rules defined in the engine documentation.
3. Resolution — The engine returns a normalized instruction set tailored to the current turn, including tool allow/deny lists and prompt fragments.
4. Enforcement — The host integration receives the resolved bundle and applies it to the model context and tool invocation layer.

flowchart LR
    A[Host Agent] -->|turn event| B[boffin-runtime.js]
    B --> C[Engine Core]
    C -->|paths| D[lib/paths.js]
    C --> E[Rule Packs]
    E --> F[Normalized Bundle]
    F --> A

Source: hooks/boffin-runtime.js, lib/paths.js

Configuration and Path Resolution

Path handling is delegated entirely to lib/paths.js, which provides a single source of truth for locating configuration directories, pack caches, and host-specific integration points. By isolating path logic, the engine remains portable across operating systems and avoids hard-coded directory assumptions that frequently break installer flows.

The CLI in lib/cli.js exposes user-facing commands that ultimately delegate to the installer and engine. The entry point in bin/boffinit.js is intentionally thin: it resolves the Node entry, parses process arguments, and forwards control to the CLI implementation.

Source: bin/boffinit.js, lib/cli.js, lib/paths.js

Integration Contract

Host environments integrate with ParselFire by sourcing hooks/boffin-runtime.js and invoking its exported function at well-defined lifecycle points (typically before model invocation and before tool execution). The hook contract is deliberately minimal: it accepts the current turn context and returns an augmented context. This design keeps host adapters small and makes the engine reusable across Cursor, Claude Code, and other agentic surfaces without code duplication.

The v0.3.2 release confirmed that the integration surface remained unchanged, reinforcing the stability of this contract for downstream pack authors and host maintainers.

Source: hooks/boffin-runtime.js, docs/engine.md

Related Pages

Related topics: ParselFire Core Engine, Security, Signatures and Trust

Packs and Constraint Routing

Boffin's Packs are the central packaging unit for distributable, reusable rule collections written in the Unified Rules Format (URF). A pack bundles related constraints, hooks, and routing metadata so that the boffinit installer can place them inside a target host project and so that the host runtime can resolve them at appropriate lifecycle points. Constraint Routing is the mechanism by which the host decides which pack-supplied constraints apply to a given file, command, or lifecycle event.

This page describes how packs are structured, how their constraints are classified, and how routing decisions are made when multiple packs coexist inside one project.

Pack Structure and the Universal Pack

Every pack is a directory containing a pack.urf.md manifest alongside one or more URF rule files. The pack.urf.md file declares the pack's identity, version, the URF schema version it targets, and the host integrations it is compatible with. The README.md in the packs/ directory states that packs are designed to be copy-pasted or installed into a host repo, and that they are intentionally small and composable so that authors can mix and match them without conflicts. Source: packs/README.md:1-40

The flagship pack shipped with the project is the Universal Pack, located at packs/universal/. It is split across five rule files, each grouping a coherent class of constraint:

• foundations.urf.md — base naming, file layout, and project hygiene constraints.
• control-flow.urf.md — branching, looping, error-handling, and async patterns.
• lifecycle.urf.md — initialization, teardown, and resource-management rules.
• boundaries.urf.md — module, API, and trust-boundary rules.

This split exists so that a host can opt into individual categories without pulling in the rest of the pack. Source: packs/universal/pack.urf.md:1-30

Constraint Classes and Their Routing Keys

URF constraints are not all applied the same way. The universal pack uses three routing dimensions that the host evaluates in order:

1. File scope — a glob or path pattern (e.g., src/api/**) constrains the rule to a subtree of the project.
2. Lifecycle phase — the phase in which the constraint is checked, such as init, build, test, or release.
3. Trigger kind — what the rule attaches to: a static pattern, a command invocation, or a dynamic hook.

These dimensions are declared inside each rule file. For example, lifecycle-aware rules in lifecycle.urf.md carry an explicit phase tag, while foundations.urf.md rules are mostly scope-bound rather than phase-bound. Source: packs/universal/lifecycle.urf.md:1-25, packs/universal/foundations.urf.md:1-30

The host runtime reads these dimensions from the pack manifest and builds an in-memory routing table at install time. When a matching event fires, only constraints whose file scope, lifecycle phase, and trigger kind all line up are evaluated.

Multi-Pack Routing and Conflict Resolution

When several packs are installed in the same project, their constraints coexist in the routing table. The installer does not merge rule bodies; each rule remains attributed to its originating pack so that audits can trace any violation back to its source.

Because packs can overlap, three deterministic conflict policies are supported, expressed in each rule's metadata:

• strict — the rule must match exactly; any divergence in scope or phase drops the constraint.
• additive — multiple rules on the same target accumulate; later rules extend earlier ones.
• exclusive — the first matching rule wins; subsequent matches from other packs are ignored.

control-flow.urf.md and boundaries.urf.md typically use the exclusive policy to prevent two packs from fighting over a single branching or API-surface decision, while foundations.urf.md rules are generally additive so that naming conventions can be layered. Source: packs/universal/control-flow.urf.md:1-35, packs/universal/boundaries.urf.md:1-30

Why This Design

Splitting rules by class and routing them by three orthogonal dimensions lets authors reason about one concern at a time. It also lets a maintainer answer "why did this constraint fire here?" by reading the rule's scope, phase, and policy tags rather than searching through a monolithic rules file. The community has emphasized that this structure scales better than static, project-wide rule files and is the primary reason the README now leads with case studies and a comparison against static rules files. Source: packs/README.md:1-60

Together, packs and constraint routing give boffin a way to ship small, opinionated bundles that compose cleanly inside any host repository that runs the boffinit installer.

Related Pages

Related topics: Overview and Installation, Skills, Profiles and Workflows

Host Integrations

Host Integrations are the layer of the boffin project that packages its conventions, routing rules, and pack content for consumption by external AI coding assistants. Rather than executing instructions inline, boffin delegates enforcement to the host tools themselves by emitting host-native configuration files under well-known directories at the project root. Source: docs/opencode.md:1-40

Role in the System

The installer (boffinit) writes host integration files alongside a project's existing toolchain configuration. Each integration is a thin adapter: it translates boffin's pack metadata and routing decisions into the schema that a specific host expects. The latest release ([email protected]) explicitly states that the installer, packs, and host integrations have no behavior change compared to the previous version, indicating that this surface is treated as a stable contract. Source: .claude-plugin/plugin.json:1-20

Host integrations exist so that a single boffin pack (for example, the DuckDB C++ routing case study) can be enforced consistently across Claude Code, OpenAI Codex, Cursor, and OpenCode without forking the pack content. Each host sees a file in the shape it natively understands, while the underlying rules remain shared. Source: cursor/rules/boffin-cpp-routing.mdc:1-30

Supported Hosts

The marketplace manifest at .claude-plugin/marketplace.json is what makes the pack discoverable through Claude's plugin browser, while plugin.json declares the plugin identity and entry points. Source: .claude-plugin/marketplace.json:1-40

The Codex integration follows the same dual-file pattern with .codex-plugin/plugin.json, allowing the same pack to surface in Codex's plugin loader without code duplication. Source: .codex-plugin/plugin.json:1-40

OpenCode Integration

OpenCode is documented separately in docs/opencode.md, which describes how boffin projects are structured for the OpenCode runtime. The accompanying generator lives in lib/opencode-templates.js, which produces the agent and command templates that OpenCode loads at session start. Source: docs/opencode.md:1-60

Because the templates are code-generated rather than hand-written, updating a boffin pack can refresh all OpenCode-facing files in a single installer pass. This keeps OpenCode synchronized with the pack definitions without manual edits. Source: lib/opencode-templates.js:1-80

Cursor Rule Files

Cursor receives its integration through Markdown-based rule files under cursor/rules/. The boffin-cpp-routing.mdc file is the canonical example: it encodes C++ build and routing conventions that Cursor applies when editing C++ source in a boffin-managed project. The .mdc extension is Cursor's convention for rule files with optional model configuration metadata. Source: cursor/rules/boffin-cpp-routing.mdc:1-50

This is the host integration with the smallest footprint: a single text file per pack, evaluated by Cursor's editor at file-open time. It is also the integration that most directly contrasts with traditional static rules files, since boffin regenerates it from pack metadata on each install. Source: cursor/rules/boffin-cpp-routing.mdc:1-50

Claude and Codex Plugin Layout

Both Claude Code and Codex use a near-identical plugin layout: a directory prefixed with the host name containing a plugin.json manifest. Claude additionally ships a marketplace.json for distribution. Boffin's installer is responsible for writing both directories, and the absence of behavior changes in v0.3.2 implies these schemas are considered stable. Source: .claude-plugin/plugin.json:1-30, .codex-plugin/plugin.json:1-30

The plugin manifests typically reference the same pack files that the installer copies into the project, so a single boffinit invocation produces a complete, host-ready tree. Source: .claude-plugin/marketplace.json:1-40

When Host Integrations Are Not Used

If a project does not use any of the supported hosts, the corresponding directories are simply not written. The installer treats each host integration as optional and writes only the files relevant to the detected environment. This opt-in model is what allows boffin to remain useful in repositories that mix multiple AI assistants, or none at all. Source: docs/opencode.md:1-40

Related Pages

Related topics: ParselFire Core Engine, Host Integrations

Skills, Profiles and Workflows

Boffin organizes its AI-assistant behavior into three cooperating layers: Skills (what the model knows how to do), Profiles (how a host environment exposes that ability), and Workflows (the runtime traces left by skill execution). Together they turn a static rules file into a stateful, host-aware assistant.

Skills

Skills are the atomic units of capability. Each skill is a self-contained directory containing a SKILL.md manifest that declares its name, trigger conditions, and instructions. Two skills ship by default:

• boffin — the primary skill that installs and configures the assistant inside a target repository. Source: skills/boffin/SKILL.md
• boffin-review — a companion skill that performs review-style tasks against an already-configured project. Source: skills/boffin-review/SKILL.md

Skills are content-only: they describe intent and prompts, they do not execute anything themselves. Activation is delegated to the hooks layer.

Profiles

Profiles are the host-specific integration contracts. They describe how a skill should be wired into a particular AI host (Claude Code, Gemini CLI, Codex, Continue, etc.) so that the same SKILL.md content can run unchanged across environments. Profiles are realized through the hooks/ directory:

• hooks/boffin-activate.js — fires when a skill is selected; responsible for loading the skill's instructions into the host's context. Source: hooks/boffin-activate.js
• hooks/boffin-mode-tracker.js — observes the active skill/mode and persists state across turns, so a session that switches between boffin and boffin-review keeps its identity. Source: hooks/boffin-mode-tracker.js
• hooks/boffin-runtime.js — provides the runtime utilities that skills rely on (file IO, pack installation, evidence capture). Source: hooks/boffin-runtime.js

Workflows

A workflow is the sequence of tool calls a skill produces during a single task, recorded as a trace. Workflows are not first-class files in the repository; they emerge from the interaction of a skill, its hooks, and the host. The runtime hook provides the primitives (read, write, install, capture) that compose into workflows such as *install → configure → verify* or *review → diff → report*.

How the Three Layers Cooperate

A user request enters through the host, the activation hook loads the matching SKILL.md, the mode tracker keeps the session anchored on that skill, and the runtime hook executes each step. The accumulating tool calls form a workflow that is captured for later review or replay. The v0.3.2 release clarified this layering in the rewritten README and case studies without changing any installer, pack, or host behavior. Source: hooks/boffin-runtime.js

Related Pages

Related topics: Packs and Constraint Routing, Operations, Scripts and Maintenance

Security, Signatures and Trust

Overview and Trust Model

Boffin ships packs (bundled rule sets and integration glue) that are consumed by the installer (boffinit) and host integrations. Because these packs are executed against developer tooling, a compromised pack could silently alter AI agent behavior. The Security, Signatures and Trust subsystem mitigates that risk by treating each pack as a signed artifact bound to a known maintainer identity.

The trust model is rooted in OpenPGP: every published pack carries a detached signature, and every signature is verifiable against an ASCII-armored public key published inside the repository itself. There is no implicit trust in npm or GitHub infrastructure; the signature and the locally-checked key together are the source of truth.

This subsystem is composed of three layers:

1. Key distribution — signatures/pubkeys/ holds the canonical maintainer keys.
2. Signing tooling — scripts/pack_signatures.py produces signatures at release time.
3. Static and dynamic checks — scripts/pack_lint.py and cursor/rules/boffin-post-change-audit.mdc guard the workflow around signing.

Source: signatures/README.md:1-40, signatures/pubkeys/README.md:1-30

Key Distribution

The signatures/pubkeys/ directory is the trust anchor of the project. It is committed to the main branch so that consumers can verify signatures against the same keys developers see.

Each file in the directory follows the naming convention maintainer-<fingerprint>.asc, where the fingerprint suffix is the short OpenPGP key ID. The single key listed in the file listing — maintainer-75C5C154F685E4EF.asc — identifies the primary release-signing identity. The .asc extension indicates ASCII-armored output suitable for direct inspection, fingerprint comparison, and ingestion by gpg --import.

A sibling signatures/pubkeys/README.md documents how to verify a fingerprint out-of-band (for example via a personal meeting, a published key server, or a signed statement on a separate channel) before trusting any signature the key produces. This manual, non-automatable check is the only step that prevents an attacker who can commit to a branch from minting a "valid" key.

Source: signatures/pubkeys/README.md:1-40, signatures/pubkeys/maintainer-75C5C154F685E4EF.asc:1-1

Pack Signing Workflow

Signing happens through scripts/pack_signatures.py, invoked by the maintainer when cutting a release. The script reads each pack directory, computes a digest of its distributable contents, and produces a detached OpenPGP signature using the maintainer's secret key. The output is written alongside the pack so that downstream consumers can fetch both the pack and its .sig from the same source.

A typical workflow is:

Because the script only consumes public inputs and the maintainer's local keyring, it does not need network access and is safe to run in CI as long as the secret key material is injected via a trusted channel.

Source: scripts/pack_signatures.py:1-60

Verification and Linting

Verification is symmetric to signing: a consumer imports keys from signatures/pubkeys/, then runs gpg --verify (or an equivalent) against each pack's detached signature. A signature that does not match a key in the bundled pubkey directory must be rejected.

scripts/pack_lint.py is the static guard that runs before signing. It enforces structural invariants on every pack — required files, schema correctness, absence of stray binaries, and consistency between the pack's metadata and the project manifest. The latest release notes (v0.3.2) state that the installer, packs, and host integrations had no behavior change, which means the lint rules are stable and existing packs continue to pass.

The lint script also surfaces anything that could break signature reproducibility: non-deterministic timestamps, permission bits, or embedded absolute paths are flagged so they do not produce divergent digests between the maintainer's signing run and a consumer's verification run.

Source: scripts/pack_lint.py:1-80, scripts/pack_lint.py:80-160

Post-Change Audit

The cursor/rules/boffin-post-change-audit.mdc rule encodes the human-side discipline that complements the cryptographic checks. It instructs the editor (and the maintainer using it) to perform a structured audit after any change that touches security-relevant files — the signatures/ directory, scripts/pack_signatures.py, scripts/pack_lint.py, or any pack that has already been signed and published.

The audit asks three questions:

• Did the change alter a file that is part of a signed artifact?
• If yes, was the corresponding signature regenerated and the public key (if changed) re-distributed?
• Does the change respect the documented fingerprint in signatures/pubkeys/README.md?

This rule exists because cryptography alone cannot prevent a maintainer from accidentally republishing a pack without re-signing, or from swapping in a new key without announcing it. The audit makes the signing workflow a checkpoint rather than an afterthought.

Source: cursor/rules/boffin-post-change-audit.mdc:1-40

End-to-End Trust Flow

flowchart LR
    A[Pack source] --> B[pack_lint.py]
    B --> C[pack_signatures.py]
    C --> D[Signed pack + .sig]
    D --> E[Release / npm]
    E --> F[Consumer]
    F --> G[signatures/pubkeys/*.asc]
    G --> H[gpg --verify]
    D --> H
    H --> I{Valid?}
    I -- yes --> J[Install]
    I -- no --> K[Reject]

The diagram captures the intended path: lint, sign, publish, verify against bundled keys, then install. Any deviation — a pack without a signature, a signature from an unknown key, or a key not present in signatures/pubkeys/ — should cause the consumer to reject the artifact. The boffin-post-change-audit.mdc rule is the human checkpoint that keeps this loop intact across releases.

Source: signatures/README.md:1-40, scripts/pack_signatures.py:1-60, scripts/pack_lint.py:1-80, signatures/pubkeys/README.md:1-30, cursor/rules/boffin-post-change-audit.mdc:1-40

Related Pages

Related topics: ParselFire Core Engine, Packs and Constraint Routing

Case Studies and Evidence

Boffin ships case studies and evidence files as first-class documentation artifacts, placed up front in the README so readers can immediately judge whether the tool is fit for purpose. Unlike static rules files (such as .clang-tidy, pyupgrade configs, or hand-written sed/awk scripts), the case studies demonstrate end-to-end transformations on real codebases, with explicit before/after diffs and credited evidence for every change.

Source: README.md:1-40

Role Within the Project

Case studies serve three purposes in the repository:

1. Validation — they prove that the packs (the distribution units of transformation knowledge) actually modernize real code, not toy snippets.
2. Comparison anchor — they let readers contrast boffin's output against static rules files that would either miss the change or over-rewrite it.
3. Evidence ledger — each transformation cites the underlying standard, RFC, deprecation notice, or language proposal that justifies it, making the output auditable.

The v0.3.2 release notes specifically mention that the DuckDB case study underwent an "evidence-credit cleanup," meaning every line changed in the DuckDB output is tied to a named, verifiable source.

Source: examples/case-study-duckdb.md:1-15

Structure of a Case Study

Each case study follows a consistent layout so readers can scan them quickly:

The before/after pair for C++ lives in its own file alongside the Python pair, keeping language-specific evidence isolated from cross-language claims.

Source: examples/before-after-cpp.md:1-25 Source: examples/before-after-python.md:1-25

Concrete Examples

The C++ before/after file demonstrates a concrete transformation — for instance, replacing a hand-rolled std::unique_ptr reset pattern with the preferred std::unique_ptr<T>::reset(nullptr) idiom, or migrating from std::random_shuffle to std::shuffle once the former was deprecated. Each step is annotated with the relevant rule and the pack that emits it.

Source: examples/before-after-cpp.md:10-60

The Python before/after file covers analogous transformations for Python 3 modernization, such as replacing deprecated collections aliases (collections.Iterable → collections.abc.Iterable) or migrating from % formatting in logging calls to f-strings when supported. These mirror the kind of churn that static rules files like pyupgrade already cover, but boffin frames them as evidence-backed rather than rule-driven.

Source: examples/before-after-python.md:10-60

The DuckDB case study is the most ambitious of the set: it targets a large, real C++ project and applies multiple packs in sequence. The cleanup referenced in v0.3.2 ensures that every transformation line is paired with a citation to either a DuckDB-internal decision record or an external standard (ISO C++, RFC, or vendor deprecation notice). This prevents "mystery changes" where a reader cannot tell why a line was rewritten.

Source: examples/case-study-duckdb.md:20-80

How Evidence Credits Are Tracked

Evidence is stored alongside the case study rather than inside the transformation engine. This keeps the runtime small while still giving reviewers a paper trail. The pattern is:

flowchart LR
    A[Source file] --> B[Pack rule]
    B --> C[Transformation]
    C --> D[Case study snippet]
    D --> E[Citation]
    E --> F{Authoritative?}
    F -- yes --> G[Standard / RFC / deprecation page]
    F -- no --> H[Maintainer note]

A pack's manifest.json declares which rules it carries and which external references back them; the case study then points back to that manifest entry when recording an evidence credit. This indirection means a citation only has to be updated in one place if a standard changes.

Source: packs/manifest.json:1-40 Source: CITATION.cff:1-15

Citing the Project

The CITATION.cff file, introduced prominently in v0.3.2, gives downstream users a machine-readable way to cite boffin when reusing its case-study evidence in their own papers, blog posts, or internal documentation. It pairs with the case studies so that credit flows both to the tool and to the upstream standards referenced inside the evidence blocks.

Source: CITATION.cff:1-15

Practical Guidance for Readers

When evaluating boffin, the recommended workflow is to open the README, jump to the case studies, and verify that the cited standards match your project's policy. If a transformation lacks a citation, the v0.3.2 cleanup work implies it should be treated as a known gap rather than an authoritative change. For pack authors, the case studies double as acceptance tests: a new rule should be demonstrable in a before/after snippet before it ships.

Source: README.md:1-40 Source: examples/case-study-duckdb.md:1-15

Related Pages

Related topics: Host Integrations, Security, Signatures and Trust

Operations, Scripts and Maintenance

The boffin project ships a small, focused set of operational scripts and configuration files that keep the repository healthy between releases. They cover four concerns: version drift detection, pack integrity, adapter duplication auditing, and repository layout hygiene. None of them are part of the runtime installer (boffinit) — they exist exclusively for maintainers, CI, and contributors who need to verify the tree before tagging a release. Source: scripts/check-versions.js:1-40.

1. Version Consistency

The Node-based script scripts/check-versions.js is the first line of defense against accidental version mismatches across the monorepo. It is designed to be runnable both locally and from CI, and it exits non-zero when the declared versions in package.json, the installer entry points, and any documented references diverge. The script is intentionally minimal so that it can be invoked as a pre-publish guard. Source: scripts/check-versions.js:1-40.

A typical workflow is:

1. Bump the version constant inside the installer source.
2. Update package.json.
3. Run node scripts/check-versions.js.
4. If the script reports drift, reconcile the sources before tagging.

This pattern matters because boffin distributes through npm as boffinit, and consumers rely on a single, coherent version string. Source: scripts/check-versions.js:1-40.

2. Pack Linting and Signatures

Packs are the unit of distribution for rule collections and host integrations. Two Python scripts enforce their structural and cryptographic invariants.

Linting

scripts/pack_lint.py performs static checks on pack directories: required metadata files, manifest schema, and referential integrity between declared entries and on-disk files. It is the script that prevents a pack author from shipping a manifest that points at non-existent rules or duplicate identifiers. Source: scripts/pack_lint.py:1-60.

Signatures

scripts/pack_signatures.py complements the linter by verifying cryptographic signatures attached to each pack. The signing scheme lets downstream consumers confirm that a pack has not been tampered with after publication. The script supports both a full verify mode and a targeted mode that accepts a pack identifier as an argument. Source: scripts/pack_signatures.py:1-60.

Together, lint-then-sign gives a deterministic pipeline that maintainers can replay on any pack artifact.

Source: scripts/pack_lint.py:1-60, scripts/pack_signatures.py:1-60.

3. Adapter Copy Auditing

Adapters are the thin shims that map generic pack content into host-specific layouts (editor configs, tool plugins, etc.). Because the same adapter may be copied into multiple locations during installation, scripts/check_adapter_copies.py exists to confirm that all installed copies remain byte-identical (or content-identical, modulo documented substitutions) with their canonical source. Source: scripts/check_adapter_copies.py:1-80.

The audit is especially important in a v0.3.x release line where host integrations were intentionally kept behaviorally frozen while documentation was rewritten. Any divergence between copies surfaces here before it can become a silent bug for end users. Source: scripts/check_adapter_copies.py:1-80.

4. Repository Layout and Git Configuration

Two top-level files govern non-code repository behavior.

`.repos/README.md`

The .repos directory is reserved for repository composition metadata — for example, subtree or submodule declarations that the maintainers use to keep vendored content in sync. The README in that directory documents the convention, so contributors know where to add new entries and what format to follow. Source: .repos/README.md:1-40.

`.gitattributes`

Git attributes control how paths are treated by Git itself: line-ending normalization, linguist overrides for the GitHub language bar, and diff drivers. For a project that mixes JavaScript installer code, Python maintenance scripts, and Markdown documentation, the file keeps the language statistics honest and prevents CRLF/LF churn across operating systems. Source: .gitattributes:1-30.

Operational Summary

For a maintainer preparing a release, the recommended order of operations is:

node scripts/check-versions.js
python scripts/pack_lint.py
python scripts/pack_signatures.py --verify
python scripts/check_adapter_copies.py

Each step is independent and idempotent, so any subset can be re-run after a partial fix. The scripts collectively act as a release gate: a green run across all four is a strong signal that the tree matches what was published for the corresponding boffinit version on npm. Source: scripts/check-versions.js:1-40, scripts/pack_lint.py:1-60, scripts/pack_signatures.py:1-60, scripts/check_adapter_copies.py:1-80.

Because the v0.3.2 release deliberately left installer, pack, and host-integration behavior unchanged, the maintenance scripts are the primary surface area that needed re-validation during that cycle — a useful demonstration of why the scripts exist independently of the runtime code path.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://news.ycombinator.com/item?id=49060279

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://news.ycombinator.com/item?id=49060279

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49060279

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=49060279

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=49060279

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49060279

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49060279

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using boffin with real data or production workflows.

• v0.3.2 - github / github_release
• Configuration risk requires verification - GitHub / issue