agent-kitchen 0.4.0 → 0.5.0

package/README.md

@@ -17,14 +17,15 @@ 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í. La excepción es una línea de `AGENTS.md`, que escribe él mismo.
+- 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` |
@@ -57,7 +58,7 @@ npx agent-kitchen doctor                       # revisa cada pieza con su propio
 - **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`. 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 (`✗`).
+**`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/commands/doctor.d.ts

@@ -1,6 +1,7 @@
 /**
  * @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, and so is
  * a missing rule in AGENTS.md.

package/dist/commands/doctor.js

@@ -3,6 +3,7 @@ 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: "·" };
@@ -16,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), agentsMdChecks(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", "agents-md"]
+ * @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,13 +1,14 @@
 /**
  * @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
+ * 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.
@@ -20,14 +21,15 @@ 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, AGENTS_MD];
+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", "agents-md"]
+ * @example pieceNames() // ["skills-manager", "issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
  */
 export function pieceNames() {
     return [...PIECES];
@@ -41,13 +43,14 @@ export function pieceNames() {
  * @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 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]);
+    const all = await Promise.all([skillsManager, flow, cloud, guard, skills, agentsMd]);
     return all.flatMap((status) => status ?? []);
 }
 /**

package/dist/piece.d.ts

@@ -1,10 +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, 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 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,10 +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, 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 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/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.
@@ -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.
@@ -129,6 +177,7 @@ export async function issueFlowChecks(root) {
         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 apply para actualizarlo` }];
+    const labelsRead = missingLabels(root, installed);
     const result = await captureNpx(root, [`${FLOW_PACKAGE}@${installed}`, "doctor", "--json"]);
     let found;
     try {
@@ -147,5 +196,13 @@ export async function issueFlowChecks(root) {
         : 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 apply` };
-    return [...own, skills];
+    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/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,6 +1,6 @@
 {
   "name": "agent-kitchen",
-  "version": "0.4.0",
+  "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",