agent-kitchen 0.3.0 → 0.4.0

package/README.md

@@ -3,10 +3,12 @@
 Un solo comando para instalar, actualizar y revisar lo que un repo usa para trabajar con agentes: el flujo de issues con sus skills, las skills generales, las sesiones de Claude en la nube y las barandas de seguridad.
 
 ```sh
-npx agent-kitchen          # muestra qué hay, qué falta y qué está atrasado, y pregunta
+npx agent-kitchen apply    # muestra qué hay, qué falta y qué está atrasado, y pregunta
 npx agent-kitchen doctor   # revisa que todo funcione, sin cambiar nada
 ```
 
+Qué hace cada herramienta y cada skill, y dónde están: [docs/README.md](docs/README.md) para personas y [docs/agent-guide.md](docs/agent-guide.md) para agentes.
+
 Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay, corre esa con los mismos argumentos, así que `npx` nunca usa una copia vieja de su caché.
 
 ## En simple
@@ -15,7 +17,7 @@ Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay,
 - Pregunta una vez: **todo lo sugerido** (Enter), **elegir** los pasos y las skills, o **salir**. Todas las preguntas van antes de instalar; después corre solo.
 - Cada paso es una línea con ✓ o ✗. La salida de cada herramienta solo aparece si falla, o con `--verbose`.
 - Es rápido: las versiones se consultan todas a la vez y las herramientas se descargan mientras respondes.
-- Cada pieza la instala su propia herramienta. `agent-kitchen` solo sabe cuáles hay, en qué versión están y cómo se conectan entre sí.
+- Cada pieza la instala su propia herramienta. `agent-kitchen` solo sabe cuáles hay, en qué versión están y cómo se conectan entre sí. La excepción es una línea de `AGENTS.md`, que escribe él mismo.
 - Correrlo de nuevo no rompe nada: si todo está al día, lo dice y termina.
 
 ## Las piezas
@@ -24,8 +26,9 @@ Al arrancar revisa si npm tiene una versión más nueva de sí mismo. Si la hay,
 |---|---|---|---|---|---|
 | `issue-flow` | Flujo de issues ([`@ramon-sg/issue-flow`](https://github.com/ramon-sg/issue-flow)): rama, worktree y PR en draft por issue, y sus 5 skills | `package.json` | npm | `issue-flow init` | `issue-flow upgrade` en la versión nueva, y sus skills a la misma tag |
 | `claude-cloud` | Sesiones en la nube ([`@ramon-sg/claude-cloud`](https://github.com/ramon-sg/claude-cloud)): herramientas, Docker y el clone completo | `.claude/cloud.json` | npm | `claude-cloud init` | Cambia la versión que fija `.claude/cloud.json` |
-| `claude-repo-guard` | Barandas ([`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard)): modo auto con sandbox, escribe solo en su worktree | `.claude/repo-guard.manifest.json` | Tags `vX.Y.Z` de GitHub | `install` en esa tag | `install` en la tag nueva |
+| `claude-repo-guard` | Barandas ([`claude-repo-guard`](https://github.com/ramon-sg/claude-repo-guard)): modo auto con sandbox, escribe solo en su worktree | `.claude/repo-guard.manifest.json` | Tags `vX.Y.Z` de GitHub | `apply` en esa tag (`install` antes de 0.5.0) | `apply` en la tag nueva |
 | `skills` | Skills con [`skills-manager`](https://github.com/ramon-sg/skills-manager): las del flujo y las de [`agent-skills`](https://github.com/ramon-sg/agent-skills) (planes, auditoría de código y de tests) | `.agents/skills.lock.json` | Tags del catálogo | `skills-manager init --select` con las elegidas | `skills-manager update` |
+| `agents-md` | Una línea en `AGENTS.md` que le pide al agente mirar la versión instalada de una biblioteca antes de usarla. Si el repo tiene `CLAUDE.md`, le agrega `@AGENTS.md`, porque si no Claude Code no lee `AGENTS.md`. Solo en repos con `package.json` | `AGENTS.md` | — | La escribe `agent-kitchen` | — |
 
 Si npm o GitHub no responden, la pieza se muestra pero no se ofrece actualizarla. Si un paso falla, los demás siguen y el comando dice cómo reintentarlo.
 
@@ -40,19 +43,21 @@ Si npm o GitHub no responden, la pieza se muestra pero no se ofrece actualizarla
 ## Uso
 
 ```sh
-npx agent-kitchen                        # pregunta, en una terminal (Enter: todo lo sugerido)
-npx agent-kitchen --dry-run              # solo muestra qué haría
-npx agent-kitchen --yes                  # hace lo sugerido sin preguntar
-npx agent-kitchen --verbose              # muestra la salida de cada herramienta
-npx agent-kitchen --skip claude-cloud    # deja fuera una pieza (o varias, con comas)
-npx agent-kitchen doctor                 # revisa cada pieza con su propio doctor
+npx agent-kitchen apply                        # pregunta, en una terminal (Enter: todo lo sugerido)
+npx agent-kitchen apply --dry-run              # solo muestra qué haría
+npx agent-kitchen apply --yes                  # hace lo sugerido sin preguntar
+npx agent-kitchen apply --verbose              # muestra la salida de cada herramienta
+npx agent-kitchen apply --skip claude-cloud    # deja fuera una pieza (o varias, con comas)
+npx agent-kitchen doctor                       # revisa cada pieza con su propio doctor
 ```
 
+- **Sin subcomando** (`npx agent-kitchen`) hace lo mismo que `apply`, por ahora, y avisa que se use `apply`. En una versión mayor pasará a solo mostrar el estado.
+
 - **Sin terminal y sin `--yes`** (por ejemplo, desde un agente), solo muestra lo que ofrecería.
 - **Corre en el checkout principal,** no en un worktree, y desde tu terminal. Dentro de una sesión de Claude, el sandbox de `claude-repo-guard` no deja escribir `.claude/settings.json`.
 - **Al terminar,** corre el `install` de tu gestor de paquetes, revisa el diff y haz commit.
 
-**`doctor`** corre el doctor de cada herramienta en la versión del repo: `issue-flow doctor --json`, `skills-manager check` y `claude-repo-guard doctor --json`. Además revisa que las skills del flujo estén en la tag de su CLI, que `.claude/cloud.json` fije una versión exacta y, en macOS, `weakerNetworkIsolation`. Lo que no está instalado o tiene una versión nueva solo se anota con `·`. Sale con 1 si algo falla (`✗`).
+**`doctor`** corre el doctor de cada herramienta en la versión del repo: `issue-flow doctor --json`, `skills-manager check` y `claude-repo-guard doctor --json`. Además revisa que las skills del flujo estén en la tag de su CLI, que `.claude/cloud.json` fije una versión exacta y, en macOS, `weakerNetworkIsolation`. En un repo con `package.json`, también la línea de `AGENTS.md` y, si hay `CLAUDE.md`, su `@AGENTS.md`. Lo que no está instalado o tiene una versión nueva solo se anota con `·`. Sale con 1 si algo falla (`✗`).
 
 ## Sumar una pieza
 

package/dist/cli.js

@@ -21,15 +21,15 @@ const PACKAGE = "agent-kitchen";
 const HANDED_OVER = "AGENT_KITCHEN_HANDED_OVER";
 /** Usage text. */
 const USAGE = `Uso:
-  agent-kitchen [--yes | --dry-run] [--verbose] [--skip <pieza>,...]
+  agent-kitchen apply [--yes | --dry-run] [--verbose] [--skip <pieza>,...]
   agent-kitchen doctor
 
 agent-kitchen revisa cada pieza de las herramientas de agentes del repo (${pieceNames().join(", ")}),
-muestra qué tiene el repo y la última versión de cada una, y ofrece instalar lo que falta y
-actualizar lo que está atrasado. En una terminal pregunta una vez: hacer todo lo sugerido,
+muestra qué tiene el repo y la última versión de cada una, y apply ofrece instalar lo que falta
+y actualizar lo que está atrasado. En una terminal pregunta una vez: hacer todo lo sugerido,
 o elegir los pasos y las skills. --yes hace lo sugerido sin preguntar; sin terminal solo lo
 muestra. --verbose muestra la salida de cada herramienta. Córrelo en la copia principal del
-repo, desde tu terminal.
+repo, desde tu terminal. Sin subcomando hace lo mismo que apply, por ahora.
 
 doctor corre las revisiones de cada pieza en la versión del repo, sin cambiar nada.`;
 /**
@@ -92,13 +92,15 @@ async function main(argv) {
     if (handed !== null)
         return handed;
     const [command, ...rest] = positionals;
-    if (rest.length > 0 || (command !== undefined && command !== "doctor"))
+    if (rest.length > 0 || (command !== undefined && command !== "doctor" && command !== "apply"))
         throw new UsageError(`no existe el comando ${positionals.join(" ")}.`);
     if (command === "doctor") {
         if (values.yes !== undefined || values["dry-run"] !== undefined || values.skip !== undefined || values.verbose !== undefined)
             throw new UsageError("doctor no lleva opciones.");
         return doctor(process.cwd(), out);
     }
+    if (command === undefined)
+        out.stderr("agent-kitchen: usa 'agent-kitchen apply'; sin subcomando dejará de instalar en una versión mayor.\n");
     const skip = (values.skip ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
     return sync({ cwd: process.cwd(), yes: values.yes ?? false, dryRun: values["dry-run"] ?? false, verbose: values.verbose ?? false, skip }, out);
 }

package/dist/commands/doctor.d.ts

@@ -2,7 +2,8 @@
  * @file `agent-kitchen doctor`: whether each piece the repo has works, with the doctor of each
  * tool at the repo's own version: the issue flow (and its skills at its tag),
  * `skills-manager check`, the version `.claude/cloud.json` pins, and claude-repo-guard. It
- * changes nothing. A piece the repo does not have, or a newer release, is only noted.
+ * changes nothing. A piece the repo does not have, or a newer release, is only noted, and so is
+ * a missing rule in AGENTS.md.
  */
 import type { Output } from "../output.js";
 /**

package/dist/commands/doctor.js

@@ -1,3 +1,4 @@
+import { agentsMdChecks } from "../pieces/agents-md.js";
 import { cloudChecks } from "../pieces/cloud.js";
 import { guardChecks } from "../pieces/guard.js";
 import { issueFlowChecks } from "../pieces/issue-flow.js";
@@ -15,7 +16,7 @@ const MARKS = { ok: "✓", fail: "✗", info: "·" };
  */
 export async function doctor(cwd, out) {
     const root = mainCheckout(cwd, "agent-kitchen doctor");
-    const checks = (await Promise.all([issueFlowChecks(root), skillsChecks(root), cloudChecks(root), guardChecks(root)])).flat();
+    const checks = (await Promise.all([issueFlowChecks(root), skillsChecks(root), cloudChecks(root), guardChecks(root), agentsMdChecks(root)])).flat();
     for (const check of checks)
         out.stdout(`${MARKS[check.status]} ${check.name}: ${check.detail}\n`);
     return checks.some((check) => check.status === "fail") ? 1 : 0;

package/dist/commands/sync.d.ts

@@ -10,7 +10,7 @@ export interface SyncOptions {
 /**
  * The names `--skip` takes.
  * @returns The pieces' names.
- * @example pieceNames() // ["issue-flow", "claude-cloud", "claude-repo-guard", "skills"]
+ * @example pieceNames() // ["issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
  */
 export declare function pieceNames(): string[];
 /**

package/dist/commands/sync.js

@@ -1,6 +1,8 @@
 /**
- * @file `agent-kitchen [--yes] [--dry-run] [--verbose] [--skip <piece>,...]`: the one command.
- * It looks at each piece (the issue flow, claude-cloud, claude-repo-guard, the skills) with
+ * @file `agent-kitchen apply [--yes] [--dry-run] [--verbose] [--skip <piece>,...]`: the one command
+ * that changes the repo (and, for now, also the bare `agent-kitchen`).
+ * It looks at each piece (the issue flow, claude-cloud, claude-repo-guard, the skills, the
+ * rule in AGENTS.md) with
  * every lookup at once, shows what the repo has, and offers the steps that install what is
  * missing or update what is behind. In a terminal it asks first, all in one go: everything
  * suggested, or pick the steps and the skills; whether to replace the repo's own skills.
@@ -17,21 +19,23 @@ import { cloudStatus, NAME as CLOUD } from "../pieces/cloud.js";
 import { guardStatus, NAME as GUARD } from "../pieces/guard.js";
 import { issueFlowStatus, NAME as FLOW } from "../pieces/issue-flow.js";
 import { keepOwn, NAME as SKILLS, ownInPick, skillsStatus } from "../pieces/skills.js";
+import { agentsMdStatus, NAME as AGENTS_MD } from "../pieces/agents-md.js";
 import { mainCheckout, packageManager } from "../repo.js";
 import { download, failedOutput, setVerbose } from "../tools.js";
 /** Every piece, in the order its steps run. */
-const PIECES = [FLOW, CLOUD, GUARD, SKILLS];
+const PIECES = [FLOW, CLOUD, GUARD, SKILLS, AGENTS_MD];
 /**
  * The names `--skip` takes.
  * @returns The pieces' names.
- * @example pieceNames() // ["issue-flow", "claude-cloud", "claude-repo-guard", "skills"]
+ * @example pieceNames() // ["issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
  */
 export function pieceNames() {
     return [...PIECES];
 }
 /**
- * Each piece's status, with every lookup at once. The guard's step depends on whether the
- * flow is about to be installed, so it waits for the flow's status.
+ * Each piece's status, with every lookup at once. The guard's step and the rule in AGENTS.md
+ * depend on whether the flow is about to be installed (it writes package.json), so they wait
+ * for the flow's status.
  * @param root - The repo.
  * @param skip - The pieces left out.
  * @returns The statuses, in the pieces' order.
@@ -40,8 +44,10 @@ async function statusesOf(root, skip) {
     const flow = skip.includes(FLOW) ? null : issueFlowStatus(root);
     const cloud = skip.includes(CLOUD) ? null : cloudStatus(root);
     const skills = skip.includes(SKILLS) ? null : skillsStatus(root, !skip.includes(FLOW));
-    const guard = skip.includes(GUARD) ? null : (flow ?? Promise.resolve(null)).then((status) => guardStatus(root, status !== null && !status.installed && status.steps.length > 0));
-    const all = await Promise.all([flow, cloud, guard, skills]);
+    const flowComing = (flow ?? Promise.resolve(null)).then((status) => status !== null && !status.installed && status.steps.length > 0);
+    const guard = skip.includes(GUARD) ? null : flowComing.then((coming) => guardStatus(root, coming));
+    const agentsMd = skip.includes(AGENTS_MD) ? null : flowComing.then((coming) => agentsMdStatus(root, coming));
+    const all = await Promise.all([flow, cloud, guard, skills, agentsMd]);
     return all.flatMap((status) => status ?? []);
 }
 /**
@@ -70,7 +76,7 @@ function keepOwnSkills(root, step, out) {
     if (own.length === 0)
         return;
     Object.assign(step.skills, keepOwn(step.skills, own));
-    out.stdout(`Se dejan fuera las skills que el repo ya tiene como propias: ${own.join(", ")}. Para reemplazarlas, corre agent-kitchen en una terminal.\n`);
+    out.stdout(`Se dejan fuera las skills que el repo ya tiene como propias: ${own.join(", ")}. Para reemplazarlas, corre agent-kitchen apply en una terminal.\n`);
 }
 /**
  * Asks, for a step that installs skills, which ones, and whether to replace the repo's own.
@@ -120,7 +126,7 @@ async function chooseSteps(root, steps, options, out) {
         return suggested;
     }
     if (options.dryRun || !out.interactive) {
-        const hint = options.dryRun ? "" : " (para hacerlos, corre agent-kitchen en una terminal, o con --yes)";
+        const hint = options.dryRun ? "" : " (para hacerlos, corre agent-kitchen apply en una terminal, o con --yes)";
         out.stdout(`Pasos sugeridos${hint}:\n${steps.map((step) => `  [${step.checked ? "x" : " "}] ${step.label}\n`).join("")}`);
         return null;
     }
@@ -205,7 +211,7 @@ export async function sync(options, out) {
         throw new UsageError(`no existe la pieza ${unknown}; son ${pieceNames().join(", ")}.`);
     if (options.yes && options.dryRun)
         throw new UsageError("usa --yes o --dry-run, no los dos.");
-    const root = mainCheckout(options.cwd, "agent-kitchen");
+    const root = mainCheckout(options.cwd, "agent-kitchen apply");
     setVerbose(options.verbose);
     if (out.interactive)
         out.stdout("Revisando el repo y las últimas versiones…\n");

package/dist/piece.d.ts

@@ -1,9 +1,10 @@
 /**
  * @file What agent-kitchen knows of each piece it manages, and the names they share. A piece
- * (the issue flow, claude-cloud, claude-repo-guard, the skills) tells what the repo has and
- * the steps that would install or update it; agent-kitchen shows them, lets the person pick,
- * and runs the picked ones in order. Every step runs the piece's own tool, which owns its
- * files: agent-kitchen only writes the few lines that join two pieces.
+ * (the issue flow, claude-cloud, claude-repo-guard, the skills, the rule in AGENTS.md) tells
+ * what the repo has and the steps that would install or update it; agent-kitchen shows them,
+ * lets the person pick, and runs the picked ones in order. Every step runs the piece's own
+ * tool, which owns its files: agent-kitchen only writes the few lines that join two pieces,
+ * and the one line of AGENTS.md, which has no tool.
  */
 /** The issue flow on npm. */
 export declare const FLOW_PACKAGE = "@ramon-sg/issue-flow";

package/dist/piece.js

@@ -1,9 +1,10 @@
 /**
  * @file What agent-kitchen knows of each piece it manages, and the names they share. A piece
- * (the issue flow, claude-cloud, claude-repo-guard, the skills) tells what the repo has and
- * the steps that would install or update it; agent-kitchen shows them, lets the person pick,
- * and runs the picked ones in order. Every step runs the piece's own tool, which owns its
- * files: agent-kitchen only writes the few lines that join two pieces.
+ * (the issue flow, claude-cloud, claude-repo-guard, the skills, the rule in AGENTS.md) tells
+ * what the repo has and the steps that would install or update it; agent-kitchen shows them,
+ * lets the person pick, and runs the picked ones in order. Every step runs the piece's own
+ * tool, which owns its files: agent-kitchen only writes the few lines that join two pieces,
+ * and the one line of AGENTS.md, which has no tool.
  */
 /** The issue flow on npm. */
 export const FLOW_PACKAGE = "@ramon-sg/issue-flow";

package/dist/pieces/agents-md.d.ts

@@ -0,0 +1,20 @@
+import type { Check, PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "agents-md";
+/** The line, as AGENTS.md has it. */
+export declare const VERSION_RULE = "Antes de usar una biblioteca, mira su versi\u00F3n instalada en `node_modules/<biblioteca>/package.json` y lee sus tipos o su documentaci\u00F3n ah\u00ED. Si no alcanza, busca la documentaci\u00F3n de esa versi\u00F3n, no la \u00FAltima.";
+/**
+ * What the repo has of the rule, and the step that adds it.
+ * @param root - The repo.
+ * @param flowComing - Whether this run installs the flow, which writes package.json.
+ * @returns The piece's status, or null if the repo has no package.json and gets none.
+ * @example (await agentsMdStatus(root, false))?.state // "falta la regla"
+ */
+export declare function agentsMdStatus(root: string, flowComing: boolean): Promise<PieceStatus | null>;
+/**
+ * Whether AGENTS.md has the rule and CLAUDE.md, if there is one, imports it. Only noted.
+ * @param root - The repo.
+ * @returns The checks; none without package.json.
+ * @example (await agentsMdChecks(root))[0].status // "ok"
+ */
+export declare function agentsMdChecks(root: string): Promise<Check[]>;

package/dist/pieces/agents-md.js

@@ -0,0 +1,124 @@
+/**
+ * @file The rule in AGENTS.md that makes the agent check the installed version of a library
+ * before using it, instead of the one it remembers. It is one fixed line, so AGENTS.md stays
+ * small: it loads in every session. This piece has no tool of its own: agent-kitchen writes
+ * the line, as it writes the guard's options. Claude Code does not read AGENTS.md when the
+ * repo has a CLAUDE.md, so that file gets `@AGENTS.md` too. Only for repos with package.json.
+ */
+import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "agents-md";
+/** The line, as AGENTS.md has it. */
+export const VERSION_RULE = "Antes de usar una biblioteca, mira su versión instalada en `node_modules/<biblioteca>/package.json` y lee sus tipos o su documentación ahí. Si no alcanza, busca la documentación de esa versión, no la última.";
+/** The line that makes Claude Code read AGENTS.md from CLAUDE.md. */
+const IMPORT = "@AGENTS.md";
+/**
+ * A file's text, or null if it does not exist.
+ * @param root - The repo.
+ * @param name - The file.
+ * @returns Its text, or null.
+ */
+function readText(root, name) {
+    const path = join(root, name);
+    return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+/**
+ * Whether a text has a line, exactly.
+ * @param text - The text, or null.
+ * @param line - The line.
+ * @returns Whether it has it.
+ */
+function hasLine(text, line) {
+    return text !== null && text.split("\n").some((each) => each.trim() === line);
+}
+/**
+ * Whether CLAUDE.md and AGENTS.md are one file through a link (`ln -s AGENTS.md CLAUDE.md`):
+ * then Claude Code already reads the rule, and an import would make AGENTS.md import itself.
+ * @param root - The repo.
+ * @returns Whether they are the same file.
+ */
+function sameFile(root) {
+    try {
+        return realpathSync(join(root, "CLAUDE.md")) === realpathSync(join(root, "AGENTS.md"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What the repo lacks: the rule in AGENTS.md, and the import in a CLAUDE.md that exists and
+ * is not AGENTS.md itself.
+ * @param root - The repo.
+ * @returns Whether each one is missing.
+ */
+function missing(root) {
+    const claude = readText(root, "CLAUDE.md");
+    return { rule: !hasLine(readText(root, "AGENTS.md"), VERSION_RULE), import: claude !== null && !hasLine(claude, IMPORT) && !sameFile(root) };
+}
+/**
+ * Adds a line at the end of a file, after a blank line, with the file's own line endings, or
+ * creates the file with it. Nothing the file had is lost but its trailing blank lines.
+ * @param root - The repo.
+ * @param name - The file.
+ * @param line - The line.
+ */
+function append(root, name, line) {
+    const text = readText(root, name) ?? "";
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const kept = text.replace(/(?:\r?\n)+$/, "");
+    writeFileSync(join(root, name), `${kept.trim() === "" ? "" : `${kept}${eol}${eol}`}${line}${eol}`);
+}
+/**
+ * Writes what is missing, if the repo has package.json by now.
+ * @param context - Where it runs.
+ * @returns Always true: a repo without package.json gets nothing, and that is no failure.
+ */
+function write(context) {
+    if (!existsSync(join(context.root, "package.json"))) {
+        context.note("sin package.json: no se agregó nada");
+        return true;
+    }
+    const lack = missing(context.root);
+    if (lack.rule)
+        append(context.root, "AGENTS.md", VERSION_RULE);
+    if (lack.import)
+        append(context.root, "CLAUDE.md", IMPORT);
+    return true;
+}
+/**
+ * What the repo has of the rule, and the step that adds it.
+ * @param root - The repo.
+ * @param flowComing - Whether this run installs the flow, which writes package.json.
+ * @returns The piece's status, or null if the repo has no package.json and gets none.
+ * @example (await agentsMdStatus(root, false))?.state // "falta la regla"
+ */
+export async function agentsMdStatus(root, flowComing) {
+    if (!existsSync(join(root, "package.json")) && !flowComing)
+        return null;
+    const lack = missing(root);
+    const summary = "regla de versiones instaladas en AGENTS.md";
+    if (!lack.rule && !lack.import)
+        return { name: NAME, summary, installed: true, state: "al día", steps: [] };
+    const files = [...(lack.rule ? ["AGENTS.md"] : []), ...(lack.import ? ["CLAUDE.md"] : [])];
+    const label = lack.rule ? `Agregar a AGENTS.md la regla de versiones instaladas${lack.import ? " (y @AGENTS.md en CLAUDE.md)" : ""}` : "Agregar @AGENTS.md a CLAUDE.md, para que Claude Code lea AGENTS.md";
+    const state = lack.rule ? "falta la regla" : "CLAUDE.md no importa AGENTS.md";
+    return { name: NAME, summary, installed: !lack.rule, state, steps: [{ piece: NAME, checked: true, downloads: [], label: `${label}: ${files.join(", ")}`, run: async (context) => write(context) }] };
+}
+/**
+ * Whether AGENTS.md has the rule and CLAUDE.md, if there is one, imports it. Only noted.
+ * @param root - The repo.
+ * @returns The checks; none without package.json.
+ * @example (await agentsMdChecks(root))[0].status // "ok"
+ */
+export async function agentsMdChecks(root) {
+    if (!existsSync(join(root, "package.json")))
+        return [];
+    const lack = missing(root);
+    const checks = [];
+    if (lack.rule)
+        checks.push({ name: NAME, status: "info", detail: "falta la regla de versiones en AGENTS.md; corre npx agent-kitchen apply" });
+    if (lack.import)
+        checks.push({ name: NAME, status: "info", detail: "CLAUDE.md no importa AGENTS.md, así que Claude Code no lo lee; corre npx agent-kitchen apply" });
+    return checks.length > 0 ? checks : [{ name: NAME, status: "ok", detail: "regla de versiones en AGENTS.md" }];
+}

package/dist/pieces/cloud.js

@@ -83,6 +83,6 @@ export async function cloudChecks(root) {
     if (version === null)
         return [{ name: NAME, status: "fail", detail: `${CONFIG} no fija una versión exacta: pon en "version" la que se usa, como "${latest ?? "1.0.0"}"` }];
     if (latest !== null && compareVersions(latest, version) > 0)
-        return [{ name: NAME, status: "info", detail: `${version}, hay ${latest}: corre npx agent-kitchen` }];
+        return [{ name: NAME, status: "info", detail: `${version}, hay ${latest}: corre npx agent-kitchen apply` }];
     return [{ name: NAME, status: "ok", detail: version }];
 }

package/dist/pieces/guard.d.ts

@@ -7,6 +7,11 @@
  * macOS `weakerNetworkIsolation` lets `gh` work inside the sandbox (the guard's own default
  * is false, so false counts as missing; the step can be unticked). When the flow is
  * installed in the same run, the guard gets those options in that run too.
+ *
+ * Its command that installs or updates is `apply` since 0.5.0 and `install` before, so the
+ * command follows the version being run. If it fails, its own output is shown; the hint about
+ * Claude's sandbox is added only when that output is a permission error, which is how the
+ * sandbox's block on `.claude/settings.json` shows up.
  */
 import { type Check, type PieceStatus } from "../piece.js";
 /** The piece's name, as `--skip` takes it. */
@@ -24,6 +29,21 @@ export declare const WEAKER_NETWORK = "weakerNetworkIsolation";
  * @example guardSpec("0.2.0") // "github:ramon-sg/claude-repo-guard#v0.2.0"
  */
 export declare function guardSpec(version: string | null): string;
+/**
+ * The guard's command that installs or updates, at a version.
+ * @param version - The version, or null for the default branch.
+ * @returns `apply` from 0.5.0 on and on the default branch, `install` before.
+ * @example guardCommand("0.4.1") // "install"
+ */
+export declare function guardCommand(version: string | null): string;
+/**
+ * What to say when the guard did not install.
+ * @param version - The version it ran.
+ * @param output - What it printed.
+ * @returns One line: the command to run by hand, and the sandbox hint only if the output is a permission error.
+ * @example guardFailure("0.5.1", "Error: EPERM: operation not permitted") // "…sandbox…"
+ */
+export declare function guardFailure(version: string | null, output: string): string;
 /**
  * The guard's options with what the flow needs added; what the repo set stays.
  * @param root - The repo.

package/dist/pieces/guard.js

@@ -7,6 +7,11 @@
  * macOS `weakerNetworkIsolation` lets `gh` work inside the sandbox (the guard's own default
  * is false, so false counts as missing; the step can be unticked). When the flow is
  * installed in the same run, the guard gets those options in that run too.
+ *
+ * Its command that installs or updates is `apply` since 0.5.0 and `install` before, so the
+ * command follows the version being run. If it fails, its own output is shown; the hint about
+ * Claude's sandbox is added only when that output is a permission error, which is how the
+ * sandbox's block on `.claude/settings.json` shows up.
  */
 import { FLOW_CONFIG } from "../piece.js";
 import { readJson, writeJson } from "../repo.js";
@@ -32,6 +37,32 @@ export const WEAKER_NETWORK = "weakerNetworkIsolation";
 export function guardSpec(version) {
     return version === null ? `github:${REPO}` : `github:${REPO}#v${version}`;
 }
+/** The first version whose install command is `apply`. */
+const APPLY_SINCE = "0.5.0";
+/** What a write blocked by a sandbox or by the file's permissions prints. */
+const PERMISSION_ERROR = /\b(EPERM|EACCES|EROFS)\b|operation not permitted|permission denied|read-only file system/i;
+/**
+ * The guard's command that installs or updates, at a version.
+ * @param version - The version, or null for the default branch.
+ * @returns `apply` from 0.5.0 on and on the default branch, `install` before.
+ * @example guardCommand("0.4.1") // "install"
+ */
+export function guardCommand(version) {
+    return version === null || compareVersions(version, APPLY_SINCE) >= 0 ? "apply" : "install";
+}
+/**
+ * What to say when the guard did not install.
+ * @param version - The version it ran.
+ * @param output - What it printed.
+ * @returns One line: the command to run by hand, and the sandbox hint only if the output is a permission error.
+ * @example guardFailure("0.5.1", "Error: EPERM: operation not permitted") // "…sandbox…"
+ */
+export function guardFailure(version, output) {
+    const command = `npx ${guardSpec(version)} ${guardCommand(version)}`;
+    if (PERMISSION_ERROR.test(output))
+        return `claude-repo-guard no se instaló: no tuvo permiso para escribir en el repo. Si corres agent-kitchen dentro de una sesión de Claude, su sandbox bloquea .claude/settings.json; corre '${command}' desde tu terminal.`;
+    return `claude-repo-guard no se instaló; su error está abajo. Para reintentar a mano: '${command}'.`;
+}
 /**
  * The guard's options with what the flow needs added; what the repo set stays.
  * @param root - The repo.
@@ -71,10 +102,10 @@ async function install(context, version) {
         writeJson(context.root, CONFIG, options);
     for (const change of changes)
         context.note(change);
-    const run = await runNpx(context.root, [guardSpec(version), "install", "--yes"]);
+    const run = await runNpx(context.root, [guardSpec(version), guardCommand(version), "--yes"]);
     if (run.ok)
         return true;
-    context.fail(`claude-repo-guard no se instaló; corre 'npx ${guardSpec(version)} install' desde tu terminal (dentro de una sesión de Claude su sandbox bloquea .claude/settings.json).`, run.output);
+    context.fail(guardFailure(version, run.output), run.output);
     return false;
 }
 /**
@@ -144,7 +175,7 @@ export async function guardChecks(root) {
         return [{ name: NAME, status: "info", detail: "no instalado (Claude se abre con tus propios permisos)" }];
     const checks = [];
     if (process.platform === "darwin" && readJson(root, CONFIG)?.[WEAKER_NETWORK] !== true)
-        checks.push({ name: `${NAME}: ${WEAKER_NETWORK}`, status: "fail", detail: `no está activado en ${CONFIG}, así que gh falla en el sandbox de macOS: corre npx agent-kitchen` });
+        checks.push({ name: `${NAME}: ${WEAKER_NETWORK}`, status: "fail", detail: `no está activado en ${CONFIG}, así que gh falla en el sandbox de macOS: corre npx agent-kitchen apply` });
     const result = await captureNpx(root, [guardSpec(installed), "doctor", "--json"]);
     let found;
     try {

package/dist/pieces/issue-flow.js

@@ -63,7 +63,7 @@ async function moveSkills(context, version) {
         context.note(`skills del flujo en v${version}: ${names.join(", ")}`);
         return true;
     }
-    context.fail(`skills-manager no actualizó las skills del flujo; corre '${failed.command}' y luego agent-kitchen otra vez.`, failed.run.output);
+    context.fail(`skills-manager no actualizó las skills del flujo; corre '${failed.command}' y luego agent-kitchen apply otra vez.`, failed.run.output);
     return false;
 }
 /**
@@ -128,7 +128,7 @@ export async function issueFlowChecks(root) {
     if (installed === null)
         return [{ name: NAME, status: "info", detail: `package.json tiene ${spec}, no una versión exacta` }];
     if (compareVersions(installed, JSON_DOCTOR) < 0)
-        return [{ name: NAME, status: "info", detail: `${installed} no tiene doctor --json: corre npx agent-kitchen para actualizarlo` }];
+        return [{ name: NAME, status: "info", detail: `${installed} no tiene doctor --json: corre npx agent-kitchen apply para actualizarlo` }];
     const result = await captureNpx(root, [`${FLOW_PACKAGE}@${installed}`, "doctor", "--json"]);
     let found;
     try {
@@ -146,6 +146,6 @@ export async function issueFlowChecks(root) {
         ? { name: `${NAME}: skills`, status: "info", detail: "ninguna instalada" }
         : off.length === 0
             ? { name: `${NAME}: skills`, status: "ok", detail: `${count} en v${installed}` }
-            : { name: `${NAME}: skills`, status: "fail", detail: `${off.join(", ")}; issue-flow está en ${installed}: corre npx agent-kitchen` };
+            : { name: `${NAME}: skills`, status: "fail", detail: `${off.join(", ")}; issue-flow está en ${installed}: corre npx agent-kitchen apply` };
     return [...own, skills];
 }

package/dist/pieces/skills.js

@@ -181,7 +181,7 @@ async function updateStep(root, catalog, ref) {
             const failed = await updateSkills(context.root, behind.map((skill) => skill.name));
             if (failed === null)
                 return true;
-            context.fail(`skills-manager no actualizó ${catalog}; corre '${failed.command}' y luego agent-kitchen otra vez.`, failed.run.output);
+            context.fail(`skills-manager no actualizó ${catalog}; corre '${failed.command}' y luego agent-kitchen apply otra vez.`, failed.run.output);
             return false;
         },
     };

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "agent-kitchen",
-  "version": "0.3.0",
-  "description": "One command to install, update and check a repo's agent tooling: the issue flow and its skills, the general skills, Claude cloud sessions and claude-repo-guard.",
+  "version": "0.4.0",
+  "description": "One command to install, update and check a repo's agent tooling: the issue flow and its skills, the general skills, Claude cloud sessions, claude-repo-guard and the installed-versions rule in AGENTS.md.",
   "license": "MIT",
   "type": "module",
-  "bin": { "agent-kitchen": "dist/cli.js" },
-  "files": ["dist"],
-  "engines": { "node": ">=20" },
-  "publishConfig": { "access": "public", "provenance": true },
+  "bin": {
+    "agent-kitchen": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ramon-sg/agent-kitchen.git"
@@ -17,6 +26,11 @@
     "test": "tsc && node --test test/*.test.mjs",
     "prepublishOnly": "npm test"
   },
-  "dependencies": { "@clack/prompts": "1.8.1" },
-  "devDependencies": { "@types/node": "^24.0.0", "typescript": "^5.9.3" }
+  "dependencies": {
+    "@clack/prompts": "1.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
 }