agent-kitchen 0.3.1 → 0.5.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,17 +17,19 @@ 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í. Las excepciones son una línea de `AGENTS.md` y la versión de `skills-manager` en `package.json`, que escribe él mismo.
 - Correrlo de nuevo no rompe nada: si todo está al día, lo dice y termina.
 
 ## Las piezas
 
 | Pieza | Qué es | Versión del repo | Última | Instalar | Actualizar |
 |---|---|---|---|---|---|
-| `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 |
+| `skills-manager` | La versión de [`@ramon-sg/skills-manager`](https://github.com/ramon-sg/skills-manager) que corre `agent-kitchen`: como mínimo 1.2.0. Si falta la agrega y si es menor la sube; nunca la baja. Un rango o `workspace:` no se toca, y avisa si la versión que corre queda bajo el mínimo. Solo en repos con `package.json` que usan skills | `package.json` | — | La agrega `agent-kitchen` | La sube `agent-kitchen` |
+| `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. Desde 0.2.6, si a GitHub le faltan labels del flujo (`spike`, `P1`–`P4`…), `issue-flow labels sync` los crea |
 | `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 | `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 +44,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 `skills-manager` esté al menos en 1.2.0, que las skills del flujo estén en la tag de su CLI, qué labels del flujo le faltan a GitHub (con `·`), 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

@@ -1,8 +1,10 @@
 /**
  * @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),
+ * tool at the repo's own version: the version of skills-manager agent-kitchen needs, 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,7 +1,9 @@
+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";
 import { skillsChecks } from "../pieces/skills.js";
+import { skillsManagerChecks } from "../pieces/skills-manager.js";
 import { mainCheckout } from "../repo.js";
 /** The mark of each check's status. */
 const MARKS = { ok: "✓", fail: "✗", info: "·" };
@@ -15,7 +17,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([skillsManagerChecks(root), 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() // ["skills-manager", "issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
  */
 export declare function pieceNames(): string[];
 /**

package/dist/commands/sync.js

@@ -1,11 +1,14 @@
 /**
- * @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 version of skills-manager, 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.
- * While the person answers, the tools download. Then the steps run in order (the flow
- * first, the skills last, since they follow the flow's version), one line each, with the
+ * While the person answers, the tools download. Then the steps run in order (skills-manager
+ * first, since the flow moves its skills with it; the skills last, since they follow the
+ * flow's version), one line each, with the
  * tools' output only when one fails; one that fails does not stop the rest. With `--yes`
  * it does what is suggested without asking (and keeps the repo's own skills); without a
  * terminal it only shows the steps.
@@ -17,31 +20,37 @@ 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 { NAME as SKILLS_MANAGER, skillsManagerStatus } from "../pieces/skills-manager.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 = [SKILLS_MANAGER, 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() // ["skills-manager", "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.
  */
 async function statusesOf(root, skip) {
+    const skillsManager = skip.includes(SKILLS_MANAGER) ? null : skillsManagerStatus(root, !skip.includes(SKILLS));
     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([skillsManager, flow, cloud, guard, skills, agentsMd]);
     return all.flatMap((status) => status ?? []);
 }
 /**
@@ -70,7 +79,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 +129,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 +214,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,11 @@
 /**
  * @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 version of skills-manager, 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, the one line of AGENTS.md, which has no tool,
+ * and the version of skills-manager in package.json, which agent-kitchen is the one to run.
  */
 /** The issue flow on npm. */
 export declare const FLOW_PACKAGE = "@ramon-sg/issue-flow";

package/dist/piece.js

@@ -1,9 +1,11 @@
 /**
  * @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 version of skills-manager, 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, the one line of AGENTS.md, which has no tool,
+ * and the version of skills-manager in package.json, which agent-kitchen is the one to run.
  */
 /** 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.js

@@ -175,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.d.ts

@@ -3,6 +3,8 @@
  * The repo's version is the one in package.json. Installing runs its `init` at the latest
  * version; updating runs its `upgrade` at the new one and then moves its skills to the same
  * tag, because the skills call the CLI. If only the skills are off, it moves them alone.
+ * From 0.2.6 it also offers `labels sync`, after the install or update, when GitHub lacks
+ * some of the labels the flow expects.
  * `init` runs with `--yes`: the person answered agent-kitchen's questions before the steps.
  */
 import { type Check, type PieceStatus } from "../piece.js";

package/dist/pieces/issue-flow.js

@@ -3,10 +3,12 @@
  * The repo's version is the one in package.json. Installing runs its `init` at the latest
  * version; updating runs its `upgrade` at the new one and then moves its skills to the same
  * tag, because the skills call the CLI. If only the skills are off, it moves them alone.
+ * From 0.2.6 it also offers `labels sync`, after the install or update, when GitHub lacks
+ * some of the labels the flow expects.
  * `init` runs with `--yes`: the person answered agent-kitchen's questions before the steps.
  */
 import { FLOW_CATALOG, FLOW_PACKAGE } from "../piece.js";
-import { dependencyVersion, readJson } from "../repo.js";
+import { dependencyVersion, isObject, readJson } from "../repo.js";
 import { catalogSkills, manifestCatalogs, pinCatalog, updateSkills } from "../skills-files.js";
 import { captureNpx, compareVersions, isRelease, npmLatest, runNpx } from "../tools.js";
 /** The piece's name, as `--skip` takes it. */
@@ -15,6 +17,8 @@ export const NAME = "issue-flow";
 const SKILLS_CATALOG_LABEL = "el catálogo";
 /** The first version whose `doctor` prints `--json`. */
 const JSON_DOCTOR = "0.2.0";
+/** The first version with `labels sync`. */
+const LABELS_SINCE = "0.2.6";
 /**
  * The issue flow's version in the repo, as package.json has it: an exact release when the
  * flow set it up, or anything else (a range, a `file:` link) someone wrote by hand.
@@ -63,7 +67,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;
 }
 /**
@@ -80,6 +84,46 @@ async function runFlow(context, version, args) {
     context.fail(`issue-flow ${args[0] ?? ""} falló; corre 'npx ${FLOW_PACKAGE}@${version} ${args.join(" ")}'.`, run.output);
     return false;
 }
+/**
+ * The labels the flow expects that GitHub lacks, as `labels sync --dry-run --json` of a
+ * version tells (a label that only differs in color or description does not count).
+ * @param root - The repo.
+ * @param version - The flow's version.
+ * @returns Their names, none for a version without `labels sync`, or null if it could not tell.
+ * @example await missingLabels(root, "0.2.6") // ["spike"]
+ */
+async function missingLabels(root, version) {
+    if (compareVersions(version, LABELS_SINCE) < 0)
+        return [];
+    const result = await captureNpx(root, [`${FLOW_PACKAGE}@${version}`, "labels", "sync", "--dry-run", "--json"], true);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        return null;
+    }
+    if (!isObject(found) || !Array.isArray(found.labels))
+        return null;
+    return found.labels.filter((label) => isObject(label) && label.status === "to-create").map((label) => String(label.name));
+}
+/**
+ * The step that makes in GitHub the labels the flow lacks, with its own command. It only
+ * runs if the repo has that version of the flow by then: not when its install or update
+ * was left out or failed.
+ * @param version - The flow's version.
+ * @param missing - The labels.
+ * @returns The step.
+ */
+function labelsStep(version, missing) {
+    return { piece: NAME, checked: true, downloads: [`${FLOW_PACKAGE}@${version}`], label: `Crear en GitHub los labels que faltan: ${missing.join(", ")}`, run: async (context) => {
+            if (flowVersion(context.root) !== version) {
+                context.note(`no se crearon: el repo no tiene issue-flow ${version}`);
+                return true;
+            }
+            return runFlow(context, version, ["labels", "sync"]);
+        } };
+}
 /**
  * The step the repo needs, if any.
  * @param installed - The repo's version, or null.
@@ -110,9 +154,13 @@ export async function issueFlowStatus(root) {
     const installed = flowVersion(root);
     const latest = await npmLatest(FLOW_PACKAGE);
     const step = stepFor(installed, latest, root);
-    const known = latest === null ? " (npm no responde)" : "";
-    const state = installed === null ? `no instalado${known}` : latest !== null && compareVersions(latest, installed) > 0 ? `${installed}, hay ${latest}` : `${installed}, al día${known}`;
-    return { name: NAME, summary, installed: installed !== null, state, steps: step === null ? [] : [step] };
+    const behind = installed !== null && latest !== null && compareVersions(latest, installed) > 0;
+    const target = installed === null || behind ? latest : installed;
+    const missing = target === null ? [] : await missingLabels(root, target);
+    const known = `${latest === null ? " (npm no responde)" : ""}${missing === null ? " (no se pudieron leer los labels de GitHub)" : ""}`;
+    const state = installed === null ? `no instalado${known}` : behind ? `${installed}, hay ${latest}${known}` : `${installed}, al día${known}`;
+    const steps = [...(step === null ? [] : [step]), ...(target !== null && missing !== null && missing.length > 0 ? [labelsStep(target, missing)] : [])];
+    return { name: NAME, summary, installed: installed !== null, state, steps };
 }
 /**
  * The flow's own doctor at the repo's version, and whether its skills are at that tag.
@@ -128,7 +176,8 @@ 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 labelsRead = missingLabels(root, installed);
     const result = await captureNpx(root, [`${FLOW_PACKAGE}@${installed}`, "doctor", "--json"]);
     let found;
     try {
@@ -146,6 +195,14 @@ 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` };
-    return [...own, skills];
+            : { name: `${NAME}: skills`, status: "fail", detail: `${off.join(", ")}; issue-flow está en ${installed}: corre npx agent-kitchen apply` };
+    const missing = await labelsRead;
+    const labels = compareVersions(installed, LABELS_SINCE) < 0
+        ? []
+        : missing === null
+            ? [{ name: `${NAME}: labels`, status: "info", detail: "no se pudieron leer de GitHub" }]
+            : missing.length > 0
+                ? [{ name: `${NAME}: labels`, status: "info", detail: `faltan ${missing.join(", ")} en GitHub; corre npx agent-kitchen apply` }]
+                : [{ name: `${NAME}: labels`, status: "ok", detail: "GitHub tiene los que espera el flujo" }];
+    return [...own, skills, ...labels];
 }

package/dist/pieces/skills-manager.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file The version of `skills-manager` in the repo's package.json. agent-kitchen runs it to
+ * install and move the skills, so agent-kitchen is the one that knows the oldest version it
+ * works with: it adds it when missing and raises an exact version below it, never lowers
+ * one. A range or `workspace:` is the repo's own choice: it is left alone, with a warning if
+ * the version it runs is too old. Only in a repo with package.json that uses skills.
+ */
+import { type Check, type PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "skills-manager";
+/** The oldest `skills-manager` agent-kitchen works with: the first with `--replace`. */
+export declare const MIN_VERSION = "1.2.0";
+/**
+ * What the repo has of skills-manager, and the step that raises it, if any. The step reads
+ * package.json again when it runs.
+ * @param root - The repo.
+ * @param withSkills - Whether this run may install skills.
+ * @returns The piece's status, or null where the piece does not apply.
+ * @example skillsManagerStatus(root, true)?.state // "1.1.0, bajo 1.2.0"
+ */
+export declare function skillsManagerStatus(root: string, withSkills: boolean): PieceStatus | null;
+/**
+ * Whether the version of skills-manager the repo runs is the one agent-kitchen needs.
+ * @param root - The repo.
+ * @returns The checks; none where the piece does not apply.
+ * @example skillsManagerChecks(root)[0]?.status // "ok"
+ */
+export declare function skillsManagerChecks(root: string): Check[];

package/dist/pieces/skills-manager.js

@@ -0,0 +1,106 @@
+/**
+ * @file The version of `skills-manager` in the repo's package.json. agent-kitchen runs it to
+ * install and move the skills, so agent-kitchen is the one that knows the oldest version it
+ * works with: it adds it when missing and raises an exact version below it, never lowers
+ * one. A range or `workspace:` is the repo's own choice: it is left alone, with a warning if
+ * the version it runs is too old. Only in a repo with package.json that uses skills.
+ */
+import { SKILLS_MANAGER, SKILLS_MANIFEST } from "../piece.js";
+import { dependencyVersion, installedVersion, readJson, setDependency } from "../repo.js";
+import { compareVersions, isRelease } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "skills-manager";
+/** The oldest `skills-manager` agent-kitchen works with: the first with `--replace`. */
+export const MIN_VERSION = "1.2.0";
+/**
+ * What package.json has of skills-manager and, for a range, the version that runs: the one
+ * in node_modules, or the first x.y.z of the range.
+ * @param root - The repo.
+ * @returns What it has.
+ */
+function pinned(root) {
+    const spec = dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER);
+    if (spec === null)
+        return { kind: "missing" };
+    if (isRelease(spec))
+        return { kind: "exact", version: spec };
+    const floor = spec.startsWith("workspace:") ? null : (/\d+\.\d+\.\d+/.exec(spec)?.[0] ?? null);
+    return { kind: "other", spec, runs: installedVersion(root, SKILLS_MANAGER) ?? floor };
+}
+/**
+ * Whether a version is older than the one agent-kitchen needs.
+ * @param version - The version.
+ * @returns True if it is below the minimum.
+ */
+function below(version) {
+    return compareVersions(version, MIN_VERSION) < 0;
+}
+/**
+ * Whether the piece applies: the repo has package.json and uses skills, or this run may
+ * install them.
+ * @param root - The repo.
+ * @param withSkills - Whether this run may install skills (`skills` is not left out).
+ * @returns True if it applies.
+ */
+function applies(root, withSkills) {
+    return readJson(root, "package.json") !== null && (withSkills || readJson(root, SKILLS_MANIFEST) !== null);
+}
+/**
+ * What the repo has of skills-manager, and the step that raises it, if any. The step reads
+ * package.json again when it runs.
+ * @param root - The repo.
+ * @param withSkills - Whether this run may install skills.
+ * @returns The piece's status, or null where the piece does not apply.
+ * @example skillsManagerStatus(root, true)?.state // "1.1.0, bajo 1.2.0"
+ */
+export function skillsManagerStatus(root, withSkills) {
+    if (!applies(root, withSkills))
+        return null;
+    const summary = "el CLI de las skills, que corre agent-kitchen";
+    const now = pinned(root);
+    if (now.kind === "other") {
+        const old = now.runs !== null && below(now.runs) ? `; corre ${now.runs}, bajo ${MIN_VERSION}` : "";
+        return { name: NAME, summary, installed: true, state: `package.json tiene ${now.spec}, no una versión exacta; no se toca${old}`, steps: [] };
+    }
+    if (now.kind === "exact" && !below(now.version))
+        return { name: NAME, summary, installed: true, state: `${now.version}, al día`, steps: [] };
+    const label = now.kind === "missing" ? `Agregar skills-manager ${MIN_VERSION} a package.json` : `Subir skills-manager ${now.version} → ${MIN_VERSION}, el mínimo de agent-kitchen`;
+    const state = now.kind === "missing" ? "no está en package.json" : `${now.version}, bajo ${MIN_VERSION}`;
+    const step = {
+        piece: NAME,
+        checked: true,
+        downloads: [`${SKILLS_MANAGER}@${MIN_VERSION}`],
+        label,
+        run: async (context) => {
+            const current = pinned(context.root);
+            if (current.kind === "missing" || (current.kind === "exact" && below(current.version))) {
+                setDependency(context.root, SKILLS_MANAGER, MIN_VERSION);
+                context.note(`${SKILLS_MANAGER} ${MIN_VERSION} en package.json`);
+            }
+            else
+                context.note("package.json ya tenía una versión que sirve");
+            return true;
+        },
+    };
+    return { name: NAME, summary, installed: now.kind !== "missing", state, steps: [step] };
+}
+/**
+ * Whether the version of skills-manager the repo runs is the one agent-kitchen needs.
+ * @param root - The repo.
+ * @returns The checks; none where the piece does not apply.
+ * @example skillsManagerChecks(root)[0]?.status // "ok"
+ */
+export function skillsManagerChecks(root) {
+    if (!applies(root, false))
+        return [];
+    const now = pinned(root);
+    if (now.kind === "missing")
+        return [{ name: NAME, status: "info", detail: `no está en package.json; corre npx agent-kitchen apply para fijar ${MIN_VERSION}` }];
+    if (now.kind === "exact")
+        return below(now.version)
+            ? [{ name: NAME, status: "fail", detail: `${now.version}, bajo ${MIN_VERSION}, el mínimo de agent-kitchen: corre npx agent-kitchen apply` }]
+            : [{ name: NAME, status: "ok", detail: `${now.version} (mínimo ${MIN_VERSION})` }];
+    if (now.runs !== null && below(now.runs))
+        return [{ name: NAME, status: "fail", detail: `${now.spec} corre ${now.runs}, bajo ${MIN_VERSION}, el mínimo de agent-kitchen: sube el rango` }];
+    return [{ name: NAME, status: "ok", detail: `${now.spec}${now.runs === null ? "" : `, corre ${now.runs}`}` }];
+}

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/dist/repo.d.ts

@@ -46,3 +46,23 @@ export declare function dependencyVersion(pkg: Record<string, unknown> | null, n
  * @example packageManager(root) // "pnpm"
  */
 export declare function packageManager(root: string): string;
+/**
+ * The version of a package installed in the repo's `node_modules`.
+ * @param root - The repo.
+ * @param name - The package.
+ * @returns Its version, or null if it is not installed.
+ * @example installedVersion(root, "@ramon-sg/skills-manager") // "1.3.0"
+ */
+export declare function installedVersion(root: string, name: string): string | null;
+/**
+ * Sets the version of a dependency in package.json, changing nothing else: the file keeps
+ * its indentation, line endings and key order. It changes the entry `dependencyVersion`
+ * reads (`devDependencies` first, then `dependencies`); a new one goes into
+ * `devDependencies`, in alphabetical order, as npm adds it.
+ * @param root - The repo.
+ * @param name - The package.
+ * @param version - The version.
+ * @throws KitError if package.json is missing or not a JSON object.
+ * @example setDependency(root, "@ramon-sg/skills-manager", "1.2.0")
+ */
+export declare function setDependency(root: string, name: string, version: string): void;

package/dist/repo.js

@@ -115,3 +115,54 @@ export function packageManager(root) {
         return field;
     return LOCKFILES.find(([file]) => existsSync(join(root, file)))?.[1] ?? "npm";
 }
+/**
+ * The version of a package installed in the repo's `node_modules`.
+ * @param root - The repo.
+ * @param name - The package.
+ * @returns Its version, or null if it is not installed.
+ * @example installedVersion(root, "@ramon-sg/skills-manager") // "1.3.0"
+ */
+export function installedVersion(root, name) {
+    const file = join(root, "node_modules", name, "package.json");
+    if (!existsSync(file))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(file, "utf8"));
+        return isObject(pkg) && typeof pkg.version === "string" ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sets the version of a dependency in package.json, changing nothing else: the file keeps
+ * its indentation, line endings and key order. It changes the entry `dependencyVersion`
+ * reads (`devDependencies` first, then `dependencies`); a new one goes into
+ * `devDependencies`, in alphabetical order, as npm adds it.
+ * @param root - The repo.
+ * @param name - The package.
+ * @param version - The version.
+ * @throws KitError if package.json is missing or not a JSON object.
+ * @example setDependency(root, "@ramon-sg/skills-manager", "1.2.0")
+ */
+export function setDependency(root, name, version) {
+    const pkg = readJson(root, "package.json");
+    if (pkg === null)
+        throw new KitError("no hay package.json.");
+    const text = readFileSync(join(root, "package.json"), "utf8");
+    const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? "  ";
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const [deps, dev] = [pkg.dependencies, pkg.devDependencies];
+    if (isObject(dev) && typeof dev[name] === "string")
+        dev[name] = version;
+    else if (isObject(deps) && typeof deps[name] === "string")
+        deps[name] = version;
+    else {
+        const entries = Object.entries(isObject(dev) ? dev : {});
+        const at = entries.findIndex(([key]) => key > name);
+        entries.splice(at === -1 ? entries.length : at, 0, [name, version]);
+        pkg.devDependencies = Object.fromEntries(entries);
+    }
+    const json = JSON.stringify(pkg, null, indent).replace(/\n/g, eol);
+    writeFileSync(join(root, "package.json"), /\r?\n$/.test(text) || text === "" ? `${json}${eol}` : json);
+}

package/dist/skills-files.d.ts

@@ -66,10 +66,12 @@ export declare function manifestCatalogs(root: string): {
  */
 export declare function pinCatalog(root: string, catalog: string, tag: string): boolean;
 /**
- * The `skills-manager` to run: the version the repo pins in package.json, so the lock is
- * written by the same version every time, or the latest 1.x.
+ * The `skills-manager` to run, so the lock is written by the same version every time: the
+ * exact version package.json pins (the one its install leaves, even before it runs), else
+ * the one in node_modules, else the range package.json has (npx cannot take `workspace:`),
+ * else the latest 1.x.
  * @param root - The repo.
  * @returns The npx spec.
- * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.1.0"
+ * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.2.0"
  */
 export declare function skillsManagerSpec(root: string): string;

package/dist/skills-files.js

@@ -1,15 +1,15 @@
 /**
  * @file What agent-kitchen reads of the files of `skills-manager`: which skills of a catalog
  * the lock has and at which tag (the lock is where the manifest's `paths.lock` says), the
- * catalog's source in the manifest, which `skills-manager` to run (the one the repo pins,
- * or the latest 1.x), the repo's own skills (folders the lock does not know), and updating
- * skills one by one, because `skills-manager update` takes a single name.
+ * catalog's source in the manifest, which `skills-manager` to run (the one the repo pins or
+ * has installed, or the latest 1.x), the repo's own skills (folders the lock does not know),
+ * and updating skills one by one, because `skills-manager update` takes a single name.
  */
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { dependencyVersion, isObject, readJson, writeJson } from "./repo.js";
+import { dependencyVersion, installedVersion, isObject, readJson, writeJson } from "./repo.js";
 import { SKILLS_LOCK, SKILLS_MANAGER, SKILLS_MANIFEST } from "./piece.js";
-import { runNpx } from "./tools.js";
+import { isRelease, runNpx } from "./tools.js";
 /** Where `skills-manager` puts the skills when the manifest does not say. */
 const SKILLS_DIR = ".agents/skills";
 /**
@@ -105,12 +105,18 @@ export function pinCatalog(root, catalog, tag) {
     return true;
 }
 /**
- * The `skills-manager` to run: the version the repo pins in package.json, so the lock is
- * written by the same version every time, or the latest 1.x.
+ * The `skills-manager` to run, so the lock is written by the same version every time: the
+ * exact version package.json pins (the one its install leaves, even before it runs), else
+ * the one in node_modules, else the range package.json has (npx cannot take `workspace:`),
+ * else the latest 1.x.
  * @param root - The repo.
  * @returns The npx spec.
- * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.1.0"
+ * @example skillsManagerSpec(root) // "@ramon-sg/skills-manager@1.2.0"
  */
 export function skillsManagerSpec(root) {
-    return `${SKILLS_MANAGER}@${dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER) ?? "1"}`;
+    const pinned = dependencyVersion(readJson(root, "package.json"), SKILLS_MANAGER);
+    if (pinned !== null && isRelease(pinned))
+        return `${SKILLS_MANAGER}@${pinned}`;
+    const range = pinned === null || pinned.startsWith("workspace:") ? null : pinned;
+    return `${SKILLS_MANAGER}@${installedVersion(root, SKILLS_MANAGER) ?? range ?? "1"}`;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-kitchen",
-  "version": "0.3.1",
-  "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.5.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": {