feat: Claude Code plugin for becwright (AI-agent integration, phase A)

.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"
+    }
+  ]
+}

README.es.md

@@ -80,6 +80,19 @@ Comandos disponibles:
 | `becwright export <id>` | Exporta una BEC a un archivo `.bec.yaml` |
 | `becwright import <archivo\|URL>` | 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

README.md

@@ -79,6 +79,19 @@ Available commands:
 | `becwright export <id>` | Exports a BEC to a `.bec.yaml` file |
 | `becwright import <file\|URL>` | 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

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"
+  ]
+}

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 <regex-or-catalog-url>` — 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`.

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 <pattern-or-catalog-url> | 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 <thing>`** — If `<thing>` is an http(s) URL or a `.bec.yaml` path, run
+  `becwright import <thing>`. 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`.

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 <url-or-file>` | Add a BEC from the catalog (shows code, asks before installing) |
+| `becwright export <rule-id>` | 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 <built-in> [args]` (see `becwright list`), a custom
+  `.bec/checks/<name>.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 <regex>`),
+`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`.