From 43442ea5c2d3c4781090e95674b06e51f2a0541e Mon Sep 17 00:00:00 2001 From: DataDave-Dev <153755137+DataDave-Dev@users.noreply.github.com> Date: Tue, 30 Jun 2026 10:14:58 -0600 Subject: [PATCH] feat: add Claude Code plugin so AI agents can install and use becwright becwright is the deterministic net for what an AI agent lets slip; this makes the integration official. A Claude Code session can now install becwright and drive it. - integrations/claude-code/: the plugin. A 'becwright' skill teaches agents what it is, how to install it (npm/pnpm, no Python; or pipx), how to scaffold rules and read/fix check output; a '/becwright' command exposes init/check/add/status. - .claude-plugin/marketplace.json: makes the repo installable via '/plugin marketplace add DataDave-Dev/becwright'. - The plugin installs the published package, it does not bundle the engine. - Document install in both READMEs. Validated with 'claude plugin validate'. First layer of the planned agent integration; a universal MCP server + check --json is the next step. --- .claude-plugin/marketplace.json | 18 +++ README.es.md | 13 +++ README.md | 13 +++ .../claude-code/.claude-plugin/plugin.json | 18 +++ integrations/claude-code/README.md | 40 +++++++ .../claude-code/commands/becwright.md | 24 ++++ .../claude-code/skills/becwright/SKILL.md | 103 ++++++++++++++++++ 7 files changed, 229 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 integrations/claude-code/.claude-plugin/plugin.json create mode 100644 integrations/claude-code/README.md create mode 100644 integrations/claude-code/commands/becwright.md create mode 100644 integrations/claude-code/skills/becwright/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..0e63438 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,18 @@ +{ + "name": "becwright", + "owner": { + "name": "DataDave-Dev", + "url": "https://github.com/DataDave-Dev" + }, + "metadata": { + "description": "Official marketplace for becwright — deterministic, commit-blocking constraints (BECs) for AI-assisted codebases." + }, + "plugins": [ + { + "name": "becwright", + "source": "./integrations/claude-code", + "description": "Deterministic commit-blocking constraints (BECs). Install and use becwright from any Claude Code session.", + "version": "0.1.0" + } + ] +} diff --git a/README.es.md b/README.es.md index 17e9464..d349283 100644 --- a/README.es.md +++ b/README.es.md @@ -80,6 +80,19 @@ Comandos disponibles: | `becwright export ` | Exporta una BEC a un archivo `.bec.yaml` | | `becwright import ` | Importa una BEC de otro repo | +### Uso con agentes de IA (Claude Code) + +becwright es la red determinista para lo que un agente de IA deja pasar. Hay un +plugin de Claude Code para que un agente lo instale y lo maneje por vos: + +```text +/plugin marketplace add DataDave-Dev/becwright +/plugin install becwright@becwright +``` + +Agrega un skill `becwright` y un comando `/becwright`. Ver +[`integrations/claude-code/`](integrations/claude-code/). + Una regla en `.bec/rules.yaml`: ```yaml diff --git a/README.md b/README.md index 0809a7d..7301b55 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,19 @@ Available commands: | `becwright export ` | Exports a BEC to a `.bec.yaml` file | | `becwright import ` | Imports a BEC from another repo | +### Use with AI agents (Claude Code) + +becwright is the deterministic net for what an AI agent lets slip. There is a +Claude Code plugin so an agent can install and drive it for you: + +```text +/plugin marketplace add DataDave-Dev/becwright +/plugin install becwright@becwright +``` + +It adds a `becwright` skill and a `/becwright` command. See +[`integrations/claude-code/`](integrations/claude-code/). + A rule in `.bec/rules.yaml`: ```yaml diff --git a/integrations/claude-code/.claude-plugin/plugin.json b/integrations/claude-code/.claude-plugin/plugin.json new file mode 100644 index 0000000..9f2822b --- /dev/null +++ b/integrations/claude-code/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "becwright", + "description": "Deterministic, commit-blocking constraints (BECs) on your code. Install and use becwright from any session; the guaranteed safety net that complements CLAUDE.md. No Python required.", + "version": "0.1.0", + "author": { + "name": "Alonso David De Leon Rodarte" + }, + "homepage": "https://github.com/DataDave-Dev/becwright", + "repository": "https://github.com/DataDave-Dev/becwright", + "license": "MIT", + "keywords": [ + "pre-commit", + "git-hooks", + "constraints", + "code-quality", + "guardrails" + ] +} diff --git a/integrations/claude-code/README.md b/integrations/claude-code/README.md new file mode 100644 index 0000000..1a25304 --- /dev/null +++ b/integrations/claude-code/README.md @@ -0,0 +1,40 @@ +# becwright — Claude Code plugin + +A Claude Code plugin so any agent session can install and drive becwright: the +deterministic, commit-blocking safety net that complements `CLAUDE.md`. + +## Install + +```text +/plugin marketplace add DataDave-Dev/becwright +/plugin install becwright@becwright +``` + +The first command registers this repo as a marketplace; the second installs the +plugin from it. + +## What it provides + +- **Skill `becwright`** — teaches the agent what becwright is, how to install it + (via npm/pnpm — no Python needed — or pipx), how to scaffold rules, and how to + read and fix `check` output. The agent invokes it automatically when you ask + for a guardrail, a pre-commit check, or a rule that "can't be ignored". +- **Command `/becwright`** — a direct entry point: + - `/becwright init` — install becwright and scaffold `.bec/rules.yaml` + hook + - `/becwright check` — run the rules and summarize PASS / WARN / BLOCK + - `/becwright add ` — add a `forbid` rule or import a BEC + - `/becwright status` — report install + hook + rule count + +The plugin does not bundle becwright itself; it installs the published package +(`becwright` on npm / PyPI) into your project. + +## Layout + +``` +integrations/claude-code/ +├── .claude-plugin/plugin.json +├── commands/becwright.md +└── skills/becwright/SKILL.md +``` + +The marketplace manifest lives at the repo root: `.claude-plugin/marketplace.json`. diff --git a/integrations/claude-code/commands/becwright.md b/integrations/claude-code/commands/becwright.md new file mode 100644 index 0000000..f463639 --- /dev/null +++ b/integrations/claude-code/commands/becwright.md @@ -0,0 +1,24 @@ +--- +description: Install, set up, or run becwright — deterministic commit-blocking constraints (BECs) on this repo +argument-hint: "[init | check | add | status]" +allowed-tools: Bash, Read, Edit, Write +--- + +Use the **becwright** skill. The user invoked `/becwright` with arguments: +`$ARGUMENTS`. + +Interpret the argument and act: + +- **(empty) or `init`** — Ensure becwright is installed (prefer `npm install + --save-dev becwright`, or `pipx install becwright` in a Python project), run + `becwright init`, then show and briefly explain the generated `.bec/rules.yaml`. +- **`check`** — Run `becwright check --all` and summarize PASS / WARN / BLOCK. For + any BLOCK, point to the offending `file:line` and propose a fix. +- **`add `** — If `` is an http(s) URL or a `.bec.yaml` path, run + `becwright import `. Otherwise treat it as a regex and add a `forbid` + rule to `.bec/rules.yaml` (ask for the target `paths` and `severity` first). +- **`status`** — Report whether becwright is installed, whether the pre-commit + hook exists, and how many rules are in `.bec/rules.yaml`. + +If becwright is not yet installed, install it first. If the current directory is +not a git repository, say so before running `becwright init`. diff --git a/integrations/claude-code/skills/becwright/SKILL.md b/integrations/claude-code/skills/becwright/SKILL.md new file mode 100644 index 0000000..37f292d --- /dev/null +++ b/integrations/claude-code/skills/becwright/SKILL.md @@ -0,0 +1,103 @@ +--- +name: becwright +description: Set up or use becwright — deterministic, commit-blocking constraints (BECs) on a codebase. Use when the user wants to enforce a rule so it CANNOT be ignored (no secrets, no debug leftovers, no console.log, banned APIs, custom patterns), asks to "install becwright", "block this on commit", "add a guardrail/pre-commit check", or wants a deterministic safety net that complements CLAUDE.md / .cursorrules. Works for any language; no Python needed (installs via npm/pnpm). +--- + +# becwright + +becwright enforces **constraints on code deterministically**, blocking commits +that violate them. `CLAUDE.md` / `.cursorrules` *ask* an agent to respect rules +(probabilistic — the agent can ignore them); becwright **verifies the result** by +running a real check against the code on every commit (guaranteed, independent of +the agent). Use both: notes prevent, becwright is the deterministic net for what +slips through. + +A **BEC** (Bound Executable Constraint) ties an intent + why to an executable +check, and is portable between repos. + +## Install (no Python required) + +Prefer npm/pnpm — they ship a self-contained binary: + +```bash +npm install --save-dev becwright # project-local (recommended) +pnpm add -D becwright +# or global: npm install -g becwright +# or, in Python projects: pipx install becwright +``` + +If installed as a local devDependency, prefix commands with the package runner +(`npx becwright …` / `pnpm exec becwright …`) or use the `node_modules/.bin` +binary. A global/pipx install puts `becwright` on PATH directly. + +## Set up in a repo + +```bash +becwright init # detects languages, writes .bec/rules.yaml, installs the pre-commit hook +``` + +This scaffolds starter rules and a native `pre-commit` hook. From then on every +commit runs the checks; a blocking rule that fails stops the commit. + +## Daily use + +| Command | What it does | +|---|---| +| `becwright check` | Run rules over staged files (what the hook runs) | +| `becwright check --all` | Run rules over the whole repo | +| `becwright list` | List the built-in checks | +| `becwright import ` | Add a BEC from the catalog (shows code, asks before installing) | +| `becwright export ` | Export a rule as a portable `.bec.yaml` | + +Catalog of ready-to-use BECs: +https://github.com/DataDave-Dev/becwright/tree/main/becs + +## Writing a rule + +Rules live in `.bec/rules.yaml`. The generic `forbid` check covers any language +via a regex, so most rules need no code: + +```yaml +rules: + - id: no-console-log-ts + intent: > + Avoid console.log(...) in TypeScript. + why_it_matters: > + Debug logs clutter production output and can leak data. + paths: + - "src/**/*.ts" + check: "becwright run forbid --pattern 'console\\.log\\s*\\('" + severity: warning # or: blocking +``` + +- `paths`: glob(s) the rule applies to. +- `check`: `becwright run [args]` (see `becwright list`), a custom + `.bec/checks/.py` script, or any shell command that exits non-zero on + failure. +- `severity`: `blocking` stops the commit; `warning` only reports. + +Built-in checks include: `forbid` (any language, `--pattern `), +`hardcoded_secrets`, `dangerous_eval` (any language), and `no_token_in_logs`, +`debug_remnants`, `wildcard_imports`, `redundant_comments` (Python). + +## Interpreting `becwright check` output + +- `PASS` — rule satisfied. +- `WARN` — a `warning` rule matched; reported, commit still allowed. +- `BLOCK` — a `blocking` rule matched; the commit is stopped. The output lists + the offending `file:line`. + +To fix a `BLOCK`: remove the offending code. If a single line is a genuine false +positive, suppress just that line with a trailing `becwright: ignore` comment. +Only loosen a rule in `.bec/rules.yaml` when the constraint itself is wrong — that +is the deliberate, auditable escape hatch, not a per-commit workaround. + +## When helping a user + +1. If they want a guardrail that an agent cannot bypass, recommend becwright over + only adding a note to CLAUDE.md. +2. Install via npm/pnpm unless it's a Python project (then pipx is also fine). +3. Run `becwright init`, then review the generated `.bec/rules.yaml` and tailor + `paths`/`severity` to the repo. +4. Add specific constraints with the `forbid` check or import a BEC from the + catalog. Verify with `becwright check --all`.