rulebookguard 0.11.0 → 0.12.0

package/README.md

@@ -43,7 +43,7 @@ Requires Node.js 22 or later.
 rulebookguard does not need to be a dependency of your project. Nothing in your code imports it, so you can run it with `npx`, pinning the version so that every machine and CI run the same one:
 
 ```sh
-npx rulebookguard@0.11.0 lint
+npx rulebookguard@0.12.0 lint
 ```
 
 Each release locks its own dependencies for npm and `npx`, so a pinned version keeps running the same code. Other package managers, such as `pnpm dlx`, ignore that lock and resolve the dependency ranges. Your `package.json` and lockfile stay untouched.
@@ -56,10 +56,10 @@ npm install --save-dev rulebookguard
 
 A first rule in four steps:
 
-1. Set up the rulebook: `npx rulebookguard@0.11.0 init clients --ci` writes `rulebookguard.config.yaml`, the `clients` context and a CI workflow (see [Configuration](#configuration) to adjust `testGlobs`).
-2. Scaffold a rule: `npx rulebookguard@0.11.0 new clients` creates `docs/rules/clients/R-CLI-001.md` as `proposed`.
+1. Set up the rulebook: `npx rulebookguard@0.12.0 init clients --ci` writes `rulebookguard.config.yaml`, the `clients` context and a CI workflow (see [Configuration](#configuration) to adjust `testGlobs`).
+2. Scaffold a rule: `npx rulebookguard@0.12.0 new clients` creates `docs/rules/clients/R-CLI-001.md` as `proposed`.
 3. Write the rule, add its `anchors`, set `status: active`, and wrap the test that proves it with `@rule R-CLI-001` and `@endrule R-CLI-001`.
-4. Run `npx rulebookguard@0.11.0 lint`, and add it to CI with the [CI recipe](#ci-recipe).
+4. Run `npx rulebookguard@0.12.0 lint`, and add it to CI with the [CI recipe](#ci-recipe).
 
 ## Configuration
 
@@ -250,6 +250,7 @@ func validateDocument(country, number string) error {
 | [`export gherkin`](#export-gherkin---out-dir)                         | writes the rules' scenarios as Cucumber `.feature` files     |
 | [`export cursor\|copilot\|kiro`](#export-cursorcopilotkiro---out-dir) | writes the active rules as rule files of other AI tools      |
 | [`export agents-md`](#export-agents-md---out-dir)                     | keeps an index of the active rules in `AGENTS.md`            |
+| [`export kiro-agents`](#export-kiro-agents---out-dir)                 | writes the `rule-author` and `rule-miner` agents for Kiro    |
 | [`hook`](#hook)                                                       | Claude Code hook that injects the rules of a file            |
 | [`mcp`](#mcp---project-dir)                                           | MCP server for AI agents                                     |
 | [`site:generate`](#sitegenerate---out-dir---base-path)                | builds a static site of the rulebook                         |
@@ -488,6 +489,10 @@ Run it again after changing rules, for example in CI or before committing: it ov
 
 Keeps an index of the active rules in `AGENTS.md`, at the rulebook root or in `--out`. `AGENTS.md` has no path scoping and is always read, so it holds each rule's id, anchors (or `no anchors`), summary and rule file, not the full text. The index lives between `<!-- rulebookguard:start -->` and `<!-- rulebookguard:end -->`: the rest of the file is kept, the block is appended the first time and replaced after that, and it is removed when no rule is active, along with the file if nothing else is left (printing `removed AGENTS.md`). Anything other than one start marker followed by one end marker, or neither, fails with exit code 1 and leaves the file untouched.
 
+### `export kiro-agents [--out <dir>]`
+
+Writes `rule-author` and `rule-miner` as [Kiro custom agents](https://kiro.dev/docs/custom-agents/) in `.kiro/agents/rulebookguard-<name>.md`, under the rulebook root or directly in `--out`. Each file carries its own MCP server, pinned to the version of the CLI that wrote it, and the rule writing guide, so it works without the [Kiro power](#kiro). Run it again after upgrading. Other files in the directory are left alone, and if `rulebookguard-rule-author.md` or `rulebookguard-rule-miner.md` lacks the generated line, the command fails with exit code 1 before writing anything.
+
 ### `hook`
 
 A Claude Code hook for `PreToolUse` and `PostToolUse` events of tools that take a `file_path` (the [Claude Code plugin](#claude-code-plugin) wires it up). It reads the hook event as JSON on stdin, takes `tool_input.file_path` (relative paths resolve against the event's `cwd`), finds `rulebookguard.config.yaml` by walking up from that file, and prints the active rules anchored to it as additional context for Claude, under the same `hookEventName`:
@@ -528,7 +533,7 @@ The rulebook is found from `--project` (default: the current directory). A comma
 > npm install --save-dev rulebookguard @rulebookguard/site
 > ```
 
-Without it, the site commands fail, exit 1, with `The site commands need the @rulebookguard/site package. Install it next to rulebookguard: npm install --save-dev @rulebookguard/site`. One-off, without installing: `npx -p rulebookguard@0.11.0 -p @rulebookguard/site@0.11.0 rulebookguard site:run`.
+Without it, the site commands fail, exit 1, with `The site commands need the @rulebookguard/site package. Install it next to rulebookguard: npm install --save-dev @rulebookguard/site`. One-off, without installing: `npx -p rulebookguard@0.12.0 -p @rulebookguard/site@0.12.0 rulebookguard site:run`.
 
 Builds a read-only static site of the rulebook with [Astro Starlight](https://starlight.astro.build) into `--out` (default `site`, relative to the current directory) and prints that path. Open it from disk or publish it as is, for example on GitHub Pages; pass `--base` when it is served from a sub-path (`--base /rules`).
 
@@ -581,7 +586,7 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 22
-      - run: npx --yes rulebookguard@0.11.0 lint --base origin/${{ github.base_ref }}
+      - run: npx --yes rulebookguard@0.12.0 lint --base origin/${{ github.base_ref }}
 ```
 
 > [!TIP]
@@ -608,3 +613,20 @@ claude plugin install rulebookguard@rulebookguard
 Or, inside Claude Code 2.1.275 or later: `/plugin install rulebookguard --marketplace JuanCJR/rulebookguard`.
 
 The plugin runs the project's own rulebookguard (`node_modules/rulebookguard`, in the project directory or a parent) when its version is at least the plugin's; otherwise it runs `npx rulebookguard@<plugin version>`, which needs Node.js and network access the first time. In a checkout of rulebookguard itself it runs the checkout's own built CLI (`dist/cli.mjs`, from `vp pack`), whatever its version. The hooks never block a tool: any failure, including a timeout, lets it go ahead without rules.
+
+## Kiro
+
+Kiro gets the same rules through three pieces:
+
+| Piece                                                 | What it gives Kiro                                       | How to get it                      |
+| ----------------------------------------------------- | -------------------------------------------------------- | ---------------------------------- |
+| [Steering files](#export-cursorcopilotkiro---out-dir) | the active rules of the files it works on                | `rulebookguard export kiro`        |
+| Power in [`plugin/`](plugin)                          | the `rules` and `rule-writing` skills and the MCP server | import the `plugin` folder         |
+| [Custom agents](#export-kiro-agents---out-dir)        | `rule-author` and `rule-miner`                           | `rulebookguard export kiro-agents` |
+
+To install the power, open the Powers panel in Kiro, choose **Add Custom Power**, then **Import power from a folder** with a clone of this repository's `plugin` folder. Its MCP server runs `npx --yes rulebookguard@0.12.0 mcp` from the directory Kiro starts it in, and needs Node.js and network access the first time.
+
+Keep `rulebookguard.config.yaml` at the root of the Kiro workspace: Kiro reads `.kiro/` from there, and the steering patterns are relative to the rulebook root. There is no hook for Kiro, because steering files already deliver the rules of a matching file.
+
+> [!NOTE]
+> Kiro limits what these pieces reach. Kiro CLI V1 and V2 do not load `fileMatch` steering files automatically, so `rulebookguard export agents-md` is the way to reach them, and powers are listed for CLI V3. A custom agent does not read steering files unless its `resources` include `file://.kiro/steering/**/*.md`.

package/dist/{anchors-jf2bKfyg.mjs → anchors-JxhjEzRN.mjs}

@@ -1,4 +1,4 @@
-import { S as toRepoPath, y as createGlobMatcher } from "./lint-BPdk6XxH.mjs";
+import { S as toRepoPath, y as createGlobMatcher } from "./lint-HEXtuztv.mjs";
 // src/catalog/anchors.ts
 function rulesForPath(rules, path) {
 	const target = toRepoPath(path);

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { B as FormatError, I as CONFIG_FILE_NAME, M as CONTEXT_FILE_NAME, S as toRepoPath, V as formatIssue, _ as loadCatalog, b as expandGlobs, c as gitFallbackWarning, d as writeJson, f as writeLines, g as findRulebookRoot, h as scanTestTags, i as lintCommand, k as isRuleId, l as openCatalog, o as CliError, p as scanImplementations, s as findRule, t as changedFiles, u as shownPath, z as messages } from "./lint-BPdk6XxH.mjs";
-import { t as rulesForPath } from "./anchors-jf2bKfyg.mjs";
+import { B as FormatError, F as splitFrontmatter, I as CONFIG_FILE_NAME, M as CONTEXT_FILE_NAME, S as toRepoPath, V as formatIssue, _ as loadCatalog, b as expandGlobs, c as gitFallbackWarning, d as writeJson, f as writeLines, g as findRulebookRoot, h as scanTestTags, i as lintCommand, k as isRuleId, l as openCatalog, o as CliError, p as scanImplementations, s as findRule, t as changedFiles, u as shownPath, z as messages } from "./lint-HEXtuztv.mjs";
+import { t as rulesForPath } from "./anchors-JxhjEzRN.mjs";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
@@ -85,7 +85,7 @@ async function handWrittenFiles(dir, format, names) {
 }
 async function staleRuleFiles(dir, format, target, current) {
 	const stale = [];
-	for (const name of await listNames(dir)) if (!current.has(name) && name.startsWith(RULE_FILE_PREFIX) && name.endsWith(target.extension) && isRuleId(name.slice(14, -target.extension.length)) && hasGeneratedLine(await readFile(join(dir, name), "utf8"), format)) stale.push(name);
+	for (const name of await listNames(dir)) if (!current.has(name) && name.startsWith("rulebookguard-") && name.endsWith(target.extension) && isRuleId(name.slice(14, -target.extension.length)) && hasGeneratedLine(await readFile(join(dir, name), "utf8"), format)) stale.push(name);
 	return stale.sort();
 }
 function hasGeneratedLine(content, format) {
@@ -172,6 +172,78 @@ function expandBraces(glob) {
 function normalizedBody(rule) {
 	return rule.body.replaceAll("\r\n", "\n").trim();
 }
+// src/commands/export-kiro-agents.ts
+const KIRO_AGENTS_FORMAT = "kiro-agents";
+const AGENTS_DIR = ".kiro/agents";
+const AGENT_NAMES = ["rule-author", "rule-miner"];
+const WRITING_GUIDE = "skills/rule-writing/SKILL.md";
+const KIRO_TOOLS = [
+	"read",
+	"write",
+	"shell",
+	"@rulebookguard"
+];
+const PRELOADED_GUIDE = "the preloaded `rulebookguard:rule-writing` skill says";
+const INLINE_GUIDE = "the writing guide at the end of these instructions says";
+const LAUNCHER_NEW = "`rulebookguard.mjs new <context>` (on PATH while the plugin is enabled; if the command is not found, `npx rulebookguard new <context>`)";
+async function exportKiroAgents(catalog, io, out) {
+	const text = messages(catalog.config.language);
+	const dir = out === void 0 ? join(catalog.root, AGENTS_DIR) : resolve(io.cwd, out);
+	const fileName = (name) => `${RULE_FILE_PREFIX}${name}.md`;
+	const handWritten = await handWrittenFiles(dir, KIRO_AGENTS_FORMAT, AGENT_NAMES.map(fileName));
+	if (handWritten.length > 0) throw new CliError(handWritten.map((name) => text.handWrittenExport(toRepoPath(shownPath(io.cwd, join(dir, name))), KIRO_AGENTS_FORMAT)).join("\n"));
+	const { version } = JSON.parse(await readPluginFile("plugin.json"));
+	const guide = bodyOf(await readPluginFile(WRITING_GUIDE), WRITING_GUIDE);
+	const lines = [];
+	await mkdir(dir, { recursive: true });
+	for (const name of AGENT_NAMES) {
+		const file = join(dir, fileName(name));
+		await writeFile(file, await kiroAgent(name, guide, version, text));
+		lines.push(toRepoPath(shownPath(io.cwd, file)));
+	}
+	writeLines(io, lines);
+}
+async function kiroAgent(name, guide, version, text) {
+	const source = `agents/${name}.md`;
+	const { data, body } = splitFrontmatter(await readPluginFile(source), source);
+	const { description } = data;
+	const instructions = normalized(body).replaceAll(PRELOADED_GUIDE, INLINE_GUIDE).replaceAll(LAUNCHER_NEW, `\`npx --yes rulebookguard@${version} new <context>\``);
+	return [
+		"---",
+		`name: ${name}`,
+		`description: ${JSON.stringify(description)}`,
+		`tools: ${JSON.stringify(KIRO_TOOLS)}`,
+		"mcpServers:",
+		"  rulebookguard:",
+		"    command: npx",
+		`    args: ${JSON.stringify([
+			"--yes",
+			`rulebookguard@${version}`,
+			"mcp"
+		])}`,
+		"---",
+		"",
+		`<!-- ${text.generatedKiroAgent(KIRO_AGENTS_FORMAT, version)} -->`,
+		"",
+		instructions,
+		"",
+		`${guide}\n`
+	].join("\n");
+}
+function bodyOf(source, file) {
+	return normalized(splitFrontmatter(source, file).body);
+}
+function normalized(text) {
+	return text.replaceAll("\r\n", "\n").trim();
+}
+async function readPluginFile(path) {
+	try {
+		return await readFile(new URL(`../plugin/${path}`, import.meta.url), "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		return readFile(new URL(`../../plugin/${path}`, import.meta.url), "utf8");
+	}
+}
 // src/commands/export.ts
 const EXPORT_USAGE = "rulebookguard export <format> [--out <dir>]";
 const GHERKIN_BLOCK = /^```gherkin[^\n]*\n([\s\S]*?)^```/gm;
@@ -181,8 +253,16 @@ async function exportCommand(catalog, io, format, out) {
 		await exportAgentRules(catalog, io, format, out);
 		return;
 	}
+	if (format === "kiro-agents") {
+		await exportKiroAgents(catalog, io, out);
+		return;
+	}
 	if (format !== "gherkin") {
-		const supported = ["gherkin", ...AGENT_FORMATS].join(", ");
+		const supported = [
+			"gherkin",
+			...AGENT_FORMATS,
+			KIRO_AGENTS_FORMAT
+		].join(", ");
 		throw new CliError(`Unknown export format "${format}"; supported: ${supported}.\nUsage: ${EXPORT_USAGE}`, 2);
 	}
 	const language = catalog.config.language ?? "en";
@@ -495,7 +575,7 @@ function render(path, rules, regions, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.11.0";
+var version = "0.12.0";
 // src/commands/new.ts
 const MAX_NUMBER = 999;
 const CONTEXT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
@@ -791,6 +871,8 @@ Commands:
                                                      active; --out: output directory
   export agents-md [--out <dir>]                     keep an index of the active rules in a marked block of
                                                      AGENTS.md; --out: its directory (default: rulebook root)
+  export kiro-agents [--out <dir>]                   write the rule-author and rule-miner agents for Kiro in
+                                                     .kiro/agents; --out: output directory
   hook                                               Claude Code hook for PreToolUse and PostToolUse: reads
                                                      the event on stdin and prints the rules anchored to
                                                      the file of the tool (Read, Edit, Write...)
@@ -935,7 +1017,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-B7g8lbjx.mjs");
+		const { siteCommand } = await import("./site-COuF4ib4.mjs");
 		await siteCommand(io, {
 			out: values.out,
 			base: values.base,

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as loadRule, B as FormatError, D as findRuleRegions, E as RULE_TAG_PATTERN, F as splitFrontmatter, I as CONFIG_FILE_NAME, L as loadConfig, M as CONTEXT_FILE_NAME, N as loadContext, O as findRuleTags, P as parseContext, R as parseConfig, S as toRepoPath, T as RULE_MARKER_PATTERN, V as formatIssue, _ as loadCatalog, a as pendingImplementation, b as expandGlobs, g as findRulebookRoot, h as scanTestTags, j as parseRule, k as isRuleId, m as scanTestRegions, n as formatFinding, p as scanImplementations, r as lintCatalog, v as relativeToRoot, w as IMPLEMENTS_MARKER_PATTERN, x as listRepoFiles, y as createGlobMatcher } from "./lint-BPdk6XxH.mjs";
-import { t as rulesForPath } from "./anchors-jf2bKfyg.mjs";
+import { A as loadRule, B as FormatError, D as findRuleRegions, E as RULE_TAG_PATTERN, F as splitFrontmatter, I as CONFIG_FILE_NAME, L as loadConfig, M as CONTEXT_FILE_NAME, N as loadContext, O as findRuleTags, P as parseContext, R as parseConfig, S as toRepoPath, T as RULE_MARKER_PATTERN, V as formatIssue, _ as loadCatalog, a as pendingImplementation, b as expandGlobs, g as findRulebookRoot, h as scanTestTags, j as parseRule, k as isRuleId, m as scanTestRegions, n as formatFinding, p as scanImplementations, r as lintCatalog, v as relativeToRoot, w as IMPLEMENTS_MARKER_PATTERN, x as listRepoFiles, y as createGlobMatcher } from "./lint-HEXtuztv.mjs";
+import { t as rulesForPath } from "./anchors-JxhjEzRN.mjs";
 export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, IMPLEMENTS_MARKER_PATTERN, RULE_MARKER_PATTERN, RULE_TAG_PATTERN, createGlobMatcher, expandGlobs, findRuleRegions, findRuleTags, findRulebookRoot, formatFinding, formatIssue, isRuleId, lintCatalog, listRepoFiles, loadCatalog, loadConfig, loadContext, loadRule, parseConfig, parseContext, parseRule, pendingImplementation, relativeToRoot, rulesForPath, scanImplementations, scanTestRegions, scanTestTags, splitFrontmatter, toRepoPath };

package/dist/{lint-BPdk6XxH.mjs → lint-HEXtuztv.mjs}

@@ -227,6 +227,7 @@ const MESSAGES = {
 		removedExport: (path) => `removed ${path}`,
 		handWrittenExport: (path, format) => `${path} was not generated by "rulebookguard export ${format}"; move it away and run the export again.`,
 		generatedRule: (format, file) => `Generated by "rulebookguard export ${format}" from ${file}; edit the rule instead.`,
+		generatedKiroAgent: (format, version) => `Generated by "rulebookguard export ${format}" from rulebookguard ${version}; run it again to update.`,
 		generatedAgentsMd: "Generated by \"rulebookguard export agents-md\"; edit the rules instead.",
 		agentsMdHeading: "Business rules",
 		agentsMdIntro: "Before changing a file, follow the active rules anchored to it:",
@@ -335,6 +336,7 @@ const MESSAGES = {
 		removedExport: (path) => `eliminado ${path}`,
 		handWrittenExport: (path, format) => `${path} no fue generado por "rulebookguard export ${format}"; muévelo y vuelve a exportar.`,
 		generatedRule: (format, file) => `Generado por "rulebookguard export ${format}" desde ${file}; edita la regla en su lugar.`,
+		generatedKiroAgent: (format, version) => `Generado por "rulebookguard export ${format}" desde rulebookguard ${version}; vuelve a ejecutarlo para actualizar.`,
 		generatedAgentsMd: "Generado por \"rulebookguard export agents-md\"; edita las reglas en su lugar.",
 		agentsMdHeading: "Reglas de negocio",
 		agentsMdIntro: "Antes de cambiar un archivo, sigue las reglas activas ancladas a él:",

package/dist/{site-B7g8lbjx.mjs → site-COuF4ib4.mjs}

@@ -1,4 +1,4 @@
-import { C as runGit, S as toRepoPath, b as expandGlobs, c as gitFallbackWarning, f as writeLines, l as openCatalog, m as scanTestRegions, o as CliError, r as lintCatalog } from "./lint-BPdk6XxH.mjs";
+import { C as runGit, S as toRepoPath, b as expandGlobs, c as gitFallbackWarning, f as writeLines, l as openCatalog, m as scanTestRegions, o as CliError, r as lintCatalog } from "./lint-HEXtuztv.mjs";
 import { createRequire } from "node:module";
 import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "rulebookguard",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "rulebookguard",
-      "version": "0.11.0",
+      "version": "0.12.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/server": "2.3.1",
@@ -22,7 +22,7 @@
         "node": ">=22"
       },
       "peerDependencies": {
-        "@rulebookguard/site": "^0.11.0"
+        "@rulebookguard/site": "^0.12.0"
       },
       "peerDependenciesMeta": {
         "@rulebookguard/site": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {
@@ -17,6 +17,9 @@
   "files": [
     "dist",
     "schemas",
+    "plugin/agents",
+    "plugin/skills",
+    "plugin/plugin.json",
     "npm-shrinkwrap.json"
   ],
   "type": "module",
@@ -37,14 +40,14 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
-    "@rulebookguard/site": "0.11.0",
+    "@rulebookguard/site": "0.12.0",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
   "peerDependencies": {
-    "@rulebookguard/site": "^0.11.0"
+    "@rulebookguard/site": "^0.12.0"
   },
   "peerDependenciesMeta": {
     "@rulebookguard/site": {

package/plugin/agents/rule-author.md

@@ -0,0 +1,58 @@
+---
+name: rule-author
+description: Turns a feature, a ticket or a behavior change into a rulebookguard rule change plan (new rules with Gherkin, changed rules as diffs, deprecations, conflicts, test skeletons and open questions) for a person to approve, then writes the approved rules as proposed. Use before implementing a feature that adds or changes business behavior.
+tools: Read, Grep, Glob, Bash, Edit, Write, mcp__plugin_rulebookguard_rulebookguard__contexts, mcp__plugin_rulebookguard_rulebookguard__rules_list, mcp__plugin_rulebookguard_rulebookguard__rules_search, mcp__plugin_rulebookguard_rulebookguard__rules_show, mcp__plugin_rulebookguard_rulebookguard__rules_for, mcp__plugin_rulebookguard_rulebookguard__lint
+skills:
+  - rulebookguard:rule-writing
+---
+
+You design the business rules a feature needs before anyone writes its code. You answer: which rules does this feature add, change or retire, and which existing rules does it collide with? Write every rule as the preloaded `rulebookguard:rule-writing` skill says.
+
+You run in one of two modes:
+
+- **Plan**, the default: you read, but write nothing. You return a rule change plan and stop.
+- **Apply**, only when the request includes a plan a person has approved: you write exactly that plan into the rulebook.
+
+## Hard limits
+
+- Never set a rule `active`, and never write tests or production code. After the rules, the work follows the usual flow: rules, then tests, then code, and `lint --base` holds it to that order.
+- Never read the whole catalog. Read by levels: contexts, then the rule lists of the contexts involved, then only the relevant rules.
+- In plan mode, edit nothing and run no command that writes.
+- In apply mode, write only what the approved plan says. If the plan is ambiguous or no longer matches the rulebook, stop and ask instead of guessing.
+- Never delete rule files, commit or push.
+
+## Plan mode
+
+1. **Understand the feature.** Restate it in one or two sentences of business language. Go through every effect a person could observe: results and exit status, messages and printed output, machine-readable output, stored or written data. If the request does not say what happens to one of them, or in a case the feature obviously raises, record that as an open question; do not invent the answer.
+2. **Find the contexts.** `contexts` (L0) for the map. When the feature names files or code areas, `rules_for` on them shows the active rules that already govern them.
+3. **Read the rules involved.** `rules_list` (L1) for each affected context, then `rules_show` (L2) only for the rules whose summary touches the feature. Run `rules_search` once per key word of the feature, and once per obvious synonym (it matches text, needs every word, and knows no synonyms: "exit code" will not find "exit status"), to catch rules in other contexts. Search results are summaries; open only those that touch the feature.
+4. **Decide, rule by rule:**
+   - a new behavior: a new rule;
+   - an existing rule whose statement or examples change, or a proposed rule the feature contradicts: a change to that rule, shown as a diff. Keep its `origin` and `evidence`; a "Questions for the business" item the feature answers is removed in the diff;
+   - an existing rule the feature replaces: a deprecation, with the new rule naming it in `supersedes`;
+   - an active rule the feature would contradict and the request does not ask to change: a conflict. Do not resolve it; describe it.
+
+   A rule you touch that already breaks the writing guide (for example two behaviors in one rule) is an open question, not something to fix in passing.
+
+5. **Draft each new rule** in full: context (an existing one, or a new one with a proposed prefix), summary, entities, anchors (the files the feature will touch, or `[]` when unknown), `dependsOn` and `conflictsWith` when they apply, `origin: authored`, the rule text, and Gherkin scenarios that cover the cases the rule names.
+6. **Sketch the tests:** for each new or changed rule, one test per scenario: the test file (matched by `testGlobs` in `rulebookguard.config.yaml`), the test name, and the `@rule <ID>` and `@endrule <ID>` comment lines around it. Use `NEW-1`, `NEW-2`… for rules that have no id yet. Give names and structure, not test code.
+
+End plan mode with the plan below and nothing after it:
+
+1. **Feature:** the restatement.
+2. **Rules read:** the ids you read in full.
+3. **New rules:** each as `NEW-n` with its complete draft.
+4. **Changed rules:** each id with a before and after diff of the lines that change, written in full (no shortened lines), and why.
+5. **Deprecated rules:** each id and what replaces it.
+6. **Conflicts:** each active rule the feature contradicts, what it says, what the feature needs, and the options.
+7. **Test skeletons:** per rule.
+8. **Open questions:** what a person must decide before approving.
+9. **Waiting for approval.** Approve, change or reject this plan; to write it, call rule-author again with the approved plan.
+
+## Apply mode
+
+1. Check that every rule the plan changes or deprecates still reads as the plan says (`rules_show`). If one changed since, stop and report it. The approval may answer the plan's open questions: write each answer into the rules it affects (a sentence in the rule text and, when it changes an outcome, a scenario), and list it in the report. An open question left unanswered stops you.
+2. For each `NEW-n`, run `rulebookguard.mjs new <context>` (on PATH while the plugin is enabled; if the command is not found, `npx rulebookguard new <context>`), and fill the file it prints with the approved draft, adding `origin: authored` after `summary`. Map each `NEW-n` to the id `new` printed, and replace `NEW-n` everywhere in the files you write. If `new` created a context, fill its `_context.md`.
+3. Apply each approved diff to the changed rules, and set each deprecated rule to `status: deprecated`. Change no other line.
+4. Run the `lint` tool. Fix every error your writes caused and run it again; you are not done while one remains.
+5. Report: the `NEW-n` to id mapping, the files written, the test skeletons with real ids, and the last `lint` result. The next step is writing those tests, then the code.

package/plugin/agents/rule-miner.md

@@ -0,0 +1,43 @@
+---
+name: rule-miner
+description: Lifts the business rules that existing code already enforces into proposed rulebookguard rules, one context at a time, each with evidence and questions for the business. Use when adopting rulebookguard in an existing project, or when asked to extract, mine or document the rules of a module.
+tools: Read, Grep, Glob, Bash, Edit, Write, mcp__plugin_rulebookguard_rulebookguard__contexts, mcp__plugin_rulebookguard_rulebookguard__rules_list, mcp__plugin_rulebookguard_rulebookguard__rules_search, mcp__plugin_rulebookguard_rulebookguard__rules_show, mcp__plugin_rulebookguard_rulebookguard__rules_for, mcp__plugin_rulebookguard_rulebookguard__lint
+skills:
+  - rulebookguard:rule-writing
+---
+
+You lift the business rules that existing code already enforces into the rulebook of this repository. The code says what it does, not what it should do: you propose, a person decides. Write every rule as the preloaded `rulebookguard:rule-writing` skill says.
+
+## Hard limits
+
+- One context per run. If asked for the whole repository, list the candidate contexts (the `contexts` tool plus the main code areas) and stop, asking which one to start with.
+- Every rule you write has `status: proposed` and `origin: extracted`. Never set `active`.
+- Create rule files only with `rulebookguard.mjs new <context>` (on PATH while the plugin is enabled; if the command is not found, `npx rulebookguard new <context>`). Never write a rule file by hand or pick an id yourself.
+- No evidence, no rule: each rule names at least one place in the code that enforces it.
+- Never edit an existing rule, production code, test logic, the config, or files outside the rulebook, the test tags and the `@implements` markers. Never delete files, commit or push.
+
+## Steps
+
+1. **Scope.** Take the context from the request. Read `rulebookguard.config.yaml` (`rulesDir`, `testGlobs`, and `contextBudget`, 30 when unset). Find the code area: the one the user names, or the anchors of the context's existing rules. If neither tells you, ask. A check the area only passes through from another module belongs to the context that owns that module: skip it and suggest that context. Run the `lint` tool once now and keep its findings as the baseline.
+2. **Read the rulebook by levels.** `contexts`, then `rules_list` for the context, then `rules_show` for the rules close to the area. Never read the whole catalog.
+3. **Mine.** Read the code and its tests. Look for decisions the business would recognize: validations, limits, states and transitions, calculations, permissions, deadlines. Use `git log` on the files for intent (commit messages, ticket keys); treat it as a hint, not proof.
+4. **Sort each candidate** into one of the kinds below. One rule per outcome the business would tell apart: two failures with different consequences are two rules; two causes of the same outcome are one.
+   - a business rule, which you write;
+   - a technical detail (retries, caching, formats, framework behavior), which you skip;
+   - a doubt (it may be a bug or a technical value), which you write with the doubt as a question.
+5. **Deduplicate.** For each candidate run `rules_search` once per key word (it needs every word to match, so one word at a time finds more), and compare with the context's `rules_list`. If a rule already states it, do not write it; report "covered by R-…". If a rule states something different from what the code does, do not touch it; report the difference.
+6. **Stay within budget.** Write at most `contextBudget` minus the rules the context already has. Report the rest as pending, with a suggested split of the context.
+7. **Write.** Run `new` for each rule and fill the file it prints: a `summary` in business language, `entities`, narrow `anchors`, the rule text, at least one Gherkin scenario taken from the code or its tests, and a "Questions for the business" list. The template has no `origin` or `evidence`: add `origin: extracted` and an `evidence` list to the frontmatter, after `summary`, with every place in code and tests as `path symbol` (for example `src/clients/create.ts validateDocument`), never with line numbers. Ask only where a value or branch might be technical or a bug rather than intended, for example "Is the limit of 3 attempts a business rule or a technical value?"; at most three questions per rule, and none when the code and its tests leave no doubt. If `new` created the context, fill its `_context.md` summary and body too.
+8. **Tag existing tests.** When a test in a file matched by `testGlobs` already verifies a rule, add a `@rule <ID>` comment on its own line above the test and an `@endrule <ID>` comment on its own line after it, in that file's comment syntax (a marker after code on the same line does not count). Change nothing else in the test. If you are not sure a test covers the rule, or the test file is not matched by `testGlobs`, list it as a suggestion instead; never edit `testGlobs` or the config.
+9. **Mark the code.** Wrap the code that enforces each rule you wrote between an `@implements <ID>` comment on its own line and an `@endimplements <ID>` comment on its own line, in that file's comment syntax and in a file the rule anchors (widen the rule's `anchors` if needed). Add only those two lines: never change the code itself.
+10. **Lint.** Run the `lint` tool. Fix every error that is not in the baseline and run it again. You are not done while one remains. Report the baseline errors, without fixing them.
+
+## Report
+
+End with this report and nothing after it:
+
+1. **Rules proposed:** one line per rule: id, summary, evidence, `@implements` regions as `path:line-endLine`, tagged tests (or "none"). Then the suggested tags you did not apply, each with its test `path:line` and the reason.
+2. **Skipped:** each candidate you did not write and why (technical detail, covered by R-…, no evidence, over budget).
+3. **Differences with existing rules:** rule id, what it says, what the code does, with `path:line`.
+4. **Questions for the business:** grouped by rule id.
+5. **Lint:** result of the last run.

package/plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "rulebookguard",
+  "version": "0.12.0",
+  "description": "Business rules as the source of truth: follow, look up and write the rules anchored to your code.",
+  "author": {
+    "name": "Juan Carlos Jimenez"
+  },
+  "homepage": "https://github.com/JuanCJR/rulebookguard#kiro",
+  "repository": "https://github.com/JuanCJR/rulebookguard",
+  "license": "MIT",
+  "keywords": ["business rules", "business rule", "rulebook", "rulebookguard"]
+}

package/plugin/skills/rule-writing/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: rule-writing
+description: How to write a rulebookguard business rule so every rule reads the same, whoever writes it. Use when writing, extracting, proposing or reviewing a rule file, or turning a feature, ticket or existing code into rules.
+---
+
+# Writing a business rule (rulebookguard)
+
+Follow these rules for every rule file, whether a person or an agent writes it, and whether it comes from a feature or from existing code.
+
+## One rule, one behavior
+
+- A rule states one business behavior. If its text needs "and also", split it into two rules.
+- Write it in the language of the business: what a client, an invoice or an order may or may not do. No class names, functions, tables or HTTP codes in the summary or the rule statement.
+- It must be verifiable: a person can write a test that passes when the rule holds and fails when it does not. "Fast", "secure" or "user friendly" are not rules.
+
+## The fields
+
+- `summary`: one line, a full sentence, stating the behavior itself ("A client document number is unique per country."), not its topic ("Document numbers").
+- `entities`: the domain nouns the rule talks about, in singular (`Client`, `Invoice`).
+- `anchors`: globs of the files that implement the rule. Point at the narrowest files that decide the behavior, not whole directories by default.
+- `status`: always `proposed`. Only a person sets `active`, after confirming the rule and tagging a test.
+- `supersedes`: the id of the rule this one replaces; set the old one to `deprecated`.
+- `dependsOn`: rules that must hold for this one to make sense. `conflictsWith`: rules that cannot be active together with this one.
+- `origin`: `extracted` when the rule was lifted from existing code, `authored` when written from a feature or a decision.
+- `evidence`: for extracted rules, every place in code or tests where the behavior shows, as `path symbol` (the function, method or constant), never `path:line`: line numbers go stale when the code moves. The exact lines live in `@implements` regions. No evidence, no extracted rule.
+
+## The body
+
+1. A `#` title of a few words.
+2. The full rule in plain sentences: the behavior, its limits and its exceptions.
+3. At least one example as a ` ```gherkin ` scenario (`Given` / `When` / `Then`) with concrete values, or a table. Cover the edge the rule names (the limit, the duplicate, the expired case).
+4. For an extracted rule, a final "Questions for the business" list: what the code does that might be a bug or a technical detail rather than intent, for example "Is the limit of 3 attempts a business rule or a technical value?".
+
+## Before you finish
+
+- Search existing rules first (`rules_search`, or `rulebookguard search <words>`); change or supersede a rule instead of writing a duplicate.
+- Create files only with `rulebookguard new <context>`, then fill them in.
+- Run `rulebookguard lint` (or the `lint` tool). If it reports an error, the rule is not done.

package/plugin/skills/rules/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: rules
+description: Business rules protocol for repositories with a rulebookguard.config.yaml. Use before changing code that may implement a business rule, when a rulebookguard hook injects rules for a file, or when asked to add, change or retire a business rule.
+---
+
+# Business rules (rulebookguard)
+
+In this repository the business rules in the rulebook (`rulesDir` in `rulebookguard.config.yaml`, `docs/rules` by default) are the source of truth. Code implements them and tests verify them. Never infer a business rule from the code alone when a rule file exists.
+
+## Before changing code
+
+1. Before editing a file, a hook or a steering file may add the active rules anchored to it; if neither did, ask the `rules_for` tool (or `rulebookguard for <path>`). When a hook lists rule texts as omitted, read each rule with the `rules_show` tool (or `rulebookguard show <id>`).
+2. For a file you have not edited yet, or a broader change, ask the `rules_for` tool (or `rulebookguard for <path>`).
+   For a change that is not tied to one file, read the rulebook by levels: the `contexts` tool, then `rules_list` for the contexts involved, then `rules_show` for the relevant rules. `rules_search` finds rules by words.
+3. Keep the change consistent with every rule listed. If the change would alter what a rule says, stop and tell the user which rule conflicts and how; do not change the behavior silently.
+
+## Changing a rule
+
+Only when the user asks for the behavior change:
+
+1. Edit the rule file first: its summary, body and examples. A new rule starts with `rulebookguard new <context>` as `proposed`; it becomes `active` only when the user confirms it.
+2. Update or add the tests that verify it. A test links to a rule by sitting between a `@rule <ID>` comment right above it and an `@endrule <ID>` comment right after it; the link lives only in the test.
+3. Change the code until those tests pass. Wrap the code that enforces the rule between an `@implements <ID>` comment line and an `@endimplements <ID>` comment line, in a file the rule anchors, so the rule points at those exact lines.
+4. Run `rulebookguard lint` or the `lint` tool, and `rulebookguard lint --base <base branch>` before opening a pull request. A changed rule whose tagging tests did not change fails as `pending-implementation`.
+
+Retire a rule by setting `status: deprecated` and removing its `@rule`/`@endrule` tags and its `@implements`/`@endimplements` regions; a replacement rule names it in `supersedes`.
+
+A rule that needs another one in force lists it in `dependsOn`; two rules that cannot both be active list each other in `conflictsWith`. `lint` rejects unknown ids, `dependsOn` cycles and two active rules in conflict.