agent-kitchen 0.5.0 → 0.6.0

package/README.md

@@ -17,15 +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í. Las excepciones son una línea de `AGENTS.md` y la versión de `skills-manager` en `package.json`, 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, en `package.json`, la versión de `skills-manager` y la de `github-rest` cuando queda bajo el mínimo de issue-flow, 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 |
 |---|---|---|---|---|---|
-| `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 |
+| `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 que usan skills y tienen `package.json`, o donde issue-flow se instala en la misma corrida: entonces crea el `package.json` | `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 apply` (`init` antes de 0.3.0), y sus skills a la misma tag | `issue-flow apply` en la versión nueva (`upgrade` antes de 0.3.0), y sus skills a la misma tag. Desde 0.3.0, si su doctor ve hooks o el `$schema` atrás, `apply` en la versión del repo. Desde 0.3.0, si `github-rest` es una versión exacta bajo el mínimo que pide esa versión del flujo, la sube. 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` |
@@ -39,6 +39,7 @@ Si npm o GitHub no responden, la pieza se muestra pero no se ofrece actualizarla
 - **Qué skills:** la primera vez vienen todas las de los catálogos. Con "Elegir" aparece un menú agrupado por catálogo, con la descripción de cada una. Si un catálogo trae skills que el repo no tiene, se ofrecen como un paso sin marcar.
 - **Skills propias del repo:** si el repo ya tiene una carpeta con el nombre de una skill del catálogo, pregunta una vez si reemplazarlas. Al reemplazar se conserva su `project.md`. Con `--yes` no se reemplazan: se dejan fuera y lo dice.
 - **Seguridad y flujo:** si el repo tiene el flujo, antes de instalar `claude-repo-guard` se escribe en sus opciones que abrir el PR en draft, asignar la issue y agregar el "Slug de rama" son parte del trabajo normal. También se escribe la rama base del flujo como `integrationBranch`. En macOS se agrega `weakerNetworkIsolation`, que `gh` necesita dentro del sandbox. Si `claude-repo-guard` ya estaba al día pero le faltan esas opciones, se ofrecen como un paso.
+- **Qué piezas usa el repo:** `.agents/kitchen.json` guarda por pieza si el repo la quiere (`{ "pieces": { "claude-repo-guard": false } }`). Se crea en la primera corrida de `apply` en una terminal: lo instalado cuenta como sí y lo que ofreció y no marcaste, como no. `false` deja la pieza fuera del menú y de `--yes`, sin desinstalarla; la tabla lo dice y `doctor` no corre sus revisiones. Una pieza que el archivo no menciona se ofrece una vez, marcada "(nueva)"; con `--yes` o sin terminal se deja fuera, si no está instalada, y lo dice (una ya instalada se actualiza como siempre). `--yes`, `--dry-run`, `--skip` y las corridas sin terminal nunca escriben el archivo. Se cambia con `apply --pieces` o a mano. `skills-manager` no tiene decisión: sus skills siguen en `.agents/skills.json`.
 - **La nube no molesta en local:** el hook de sesión solo actúa en la nube. Un repo que nunca se abre ahí no pierde nada.
 
 ## Uso
@@ -47,8 +48,10 @@ Si npm o GitHub no responden, la pieza se muestra pero no se ofrece actualizarla
 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 --commit               # al final, pregunta si commitear, en una rama o con PR
 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 apply --pieces               # cambia qué piezas usa el repo (solo en una terminal)
 npx agent-kitchen doctor                       # revisa cada pieza con su propio doctor
 ```
 
@@ -56,7 +59,14 @@ npx agent-kitchen doctor                       # revisa cada pieza con su propio
 
 - **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.
+- **Al terminar,** corre el `install` de tu gestor de paquetes, revisa el diff y haz commit. O usa `--commit`.
+
+**`--commit`** deja los cambios commiteados sin que lo haga un agente:
+
+- **Antes de cualquier paso,** exige el repo sin cambios (también sin seguimiento; los worktrees de `.claude/worktrees/` no cuentan) y en la rama base: `baseBranch` de `.agents/flow.json`, si no la rama por defecto de `origin`, si no `main`. Con `--dry-run` hace solo esta revisión y lista los pasos.
+- **Al terminar,** si cambió `package.json`, corre el `install` de tu gestor para que el lockfile entre en el commit. Muestra los archivos cambiados y pregunta: dejarlos sin commit (por defecto), commit en la base, commit en una rama nueva `chore/agent-kitchen-apply-<fecha>`, o rama nueva con push y PR (con `@ramon-sg/github-rest`).
+- **Con rama,** la copia principal pasa por la rama solo mientras corre el comando: commitea ahí (los hooks de git corren, y uno que prohíbe commitear en la base no la frena) y vuelve a la base sin los cambios. Si el push o el PR fallan, la rama queda y la salida dice qué correr.
+- **Con `--yes`,** elige la rama con PR. Si algún paso falló, no commitea.
 
 **`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 (`✗`).
 

package/dist/cli.js

@@ -21,14 +21,19 @@ const PACKAGE = "agent-kitchen";
 const HANDED_OVER = "AGENT_KITCHEN_HANDED_OVER";
 /** Usage text. */
 const USAGE = `Uso:
-  agent-kitchen apply [--yes | --dry-run] [--verbose] [--skip <pieza>,...]
+  agent-kitchen apply [--yes | --dry-run] [--commit] [--verbose] [--skip <pieza>,...]
+  agent-kitchen apply --pieces [--commit]
   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 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
+muestra. --verbose muestra la salida de cada herramienta. --commit exige el repo sin cambios
+y en la rama base; al final instala si cambió package.json y pregunta si dejar los cambios,
+commitearlos en la base, en una rama nueva, o en una rama nueva con push y PR (con --yes,
+esto último). apply --pieces elige qué piezas usa el repo y lo guarda en .agents/kitchen.json
+(en una terminal, sin --yes ni --dry-run). Córrelo en la copia principal del
 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.`;
@@ -77,7 +82,7 @@ async function main(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { yes: { type: "boolean" }, "dry-run": { type: "boolean" }, verbose: { type: "boolean", short: "v" }, skip: { type: "string" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" } },
+        options: { yes: { type: "boolean" }, "dry-run": { type: "boolean" }, commit: { type: "boolean" }, verbose: { type: "boolean", short: "v" }, skip: { type: "string" }, pieces: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" } },
     });
     if (values.help === true) {
         out.stdout(`${USAGE}\n`);
@@ -95,14 +100,14 @@ async function main(argv) {
     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)
+        if (values.yes !== undefined || values["dry-run"] !== undefined || values.skip !== undefined || values.verbose !== undefined || values.commit !== undefined || values.pieces !== 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);
+    return sync({ cwd: process.cwd(), yes: values.yes ?? false, dryRun: values["dry-run"] ?? false, verbose: values.verbose ?? false, skip, commit: values.commit ?? false, pieces: values.pieces ?? false }, out);
 }
 try {
     process.exitCode = await main(process.argv.slice(2));

package/dist/commands/doctor.d.ts

@@ -1,12 +1,4 @@
-/**
- * @file `agent-kitchen doctor`: whether each piece the repo has works, with the doctor of each
- * 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.
- */
-import type { Output } from "../output.js";
+import { type Output } from "../output.js";
 /**
  * Checks the repo; see the file's header.
  * @param cwd - Where it runs.

package/dist/commands/doctor.js

@@ -1,8 +1,19 @@
-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";
+/**
+ * @file `agent-kitchen doctor`: whether each piece the repo has works, with the doctor of each
+ * 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. A piece the repo decided against (`.agents/kitchen.json`) is
+ * only noted, and its tool is not asked.
+ */
+import { readDecisions } from "../decisions.js";
+import { warn } from "../output.js";
+import { agentsMdChecks, NAME as AGENTS_MD } from "../pieces/agents-md.js";
+import { cloudChecks, NAME as CLOUD } from "../pieces/cloud.js";
+import { guardChecks, NAME as GUARD } from "../pieces/guard.js";
+import { issueFlowChecks, NAME as FLOW } from "../pieces/issue-flow.js";
+import { NAME as SKILLS, skillsChecks } from "../pieces/skills.js";
 import { skillsManagerChecks } from "../pieces/skills-manager.js";
 import { mainCheckout } from "../repo.js";
 /** The mark of each check's status. */
@@ -17,7 +28,12 @@ const MARKS = { ok: "✓", fail: "✗", info: "·" };
  */
 export async function doctor(cwd, out) {
     const root = mainCheckout(cwd, "agent-kitchen doctor");
-    const checks = (await Promise.all([skillsManagerChecks(root), issueFlowChecks(root), skillsChecks(root), cloudChecks(root), guardChecks(root), agentsMdChecks(root)])).flat();
+    const saved = readDecisions(root);
+    for (const warning of saved?.warnings ?? [])
+        warn(out, warning);
+    /** The checks of a piece, or a note if the repo left it out. */
+    const unless = (name, run) => saved?.pieces[name] === false ? Promise.resolve([{ name, status: "info", detail: "fuera por decisión del repo" }]) : run();
+    const checks = (await Promise.all([skillsManagerChecks(root), unless(FLOW, () => issueFlowChecks(root)), unless(SKILLS, () => skillsChecks(root)), unless(CLOUD, () => cloudChecks(root)), unless(GUARD, () => guardChecks(root)), unless(AGENTS_MD, () => 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

@@ -6,6 +6,9 @@ export interface SyncOptions {
     dryRun: boolean;
     verbose: boolean;
     skip: string[];
+    commit: boolean;
+    /** Ask which pieces the repo uses, save the answer, then go on as usual. */
+    pieces: boolean;
 }
 /**
  * The names `--skip` takes.
@@ -13,12 +16,29 @@ export interface SyncOptions {
  * @example pieceNames() // ["skills-manager", "issue-flow", "claude-cloud", "claude-repo-guard", "skills", "agents-md"]
  */
 export declare function pieceNames(): string[];
+/**
+ * The closing line when no step ran, which must not contradict a file written in this run.
+ * @param why - "leave" if the person left without changing anything, "none" if they picked no steps.
+ * @param wrote - Whether the decisions file was written in this run.
+ * @returns The line, with its newline.
+ * @example noStepsMessage("none", true) // "No elegiste pasos; solo guardé qué piezas usa el repo.\n"
+ */
+export declare function noStepsMessage(why: "leave" | "none", wrote: boolean): string;
+/**
+ * What the commit of `--commit` lists: the steps that worked, and the decisions file if this
+ * run wrote it.
+ * @param done - The labels of the steps that worked.
+ * @param wrote - Whether the decisions file was written in this run.
+ * @returns The labels.
+ * @example commitLabels([], true) // ["Guardar qué piezas usa el repo en .agents/kitchen.json"]
+ */
+export declare function commitLabels(done: string[], wrote: boolean): string[];
 /**
  * Runs the command; see the file's header.
  * @param options - The options.
  * @param out - Where to write and ask.
  * @returns 0, or 1 if a step failed or the person cancelled.
  * @throws KitError outside the main checkout or with a broken file; UsageError for an unknown piece.
- * @example await sync({ cwd, yes: false, dryRun: true, verbose: false, skip: [] }, out)
+ * @example await sync({ cwd, yes: false, dryRun: true, verbose: false, skip: [], commit: false, pieces: false }, out)
  */
 export declare function sync(options: SyncOptions, out: Output): Promise<number>;

package/dist/commands/sync.js

@@ -1,5 +1,5 @@
 /**
- * @file `agent-kitchen apply [--yes] [--dry-run] [--verbose] [--skip <piece>,...]`: the one command
+ * @file `agent-kitchen apply [--yes] [--dry-run] [--commit] [--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
@@ -11,10 +11,22 @@
  * 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.
+ * terminal it only shows the steps. With `--commit` it first checks the repo is clean and on
+ * its base branch, and at the end installs if package.json changed and asks what to do with
+ * the changes (see git-finish.ts), also when the only change is the decisions file below;
+ * the steps then show as plain lines, since a spinner before a question leaves it deaf.
+ * What the repo decided of each piece, in `.agents/kitchen.json`, is respected: a piece set to
+ * false is left out as with `--skip`, and one with no decision is marked as new. Without
+ * asking (`--yes` or no terminal), a new piece that is not installed is left out for the run.
+ * In a terminal, once the person has answered, the pieces without a decision get one and the
+ * file is written; `--yes`, `--dry-run` and `--skip` never write it.
+ * `--pieces` (terminal only, not with `--yes` or `--dry-run`) first asks which pieces the repo
+ * uses, writes all of them to the file, and then goes on as usual.
  */
 import { spinner } from "@clack/prompts";
-import { askPath, askReplace, askSkills, askSteps } from "../menu.js";
+import { DECIDABLE, decide, DECISIONS, off, readDecisions, undecided, writeDecisions } from "../decisions.js";
+import { baseBranch, branchName, changedPaths, checkReady, finish } from "../git-finish.js";
+import { askFinish, askPath, askPieces, askReplace, askSkills, askSteps } from "../menu.js";
 import { KitError, UsageError, warn } from "../output.js";
 import { cloudStatus, NAME as CLOUD } from "../pieces/cloud.js";
 import { guardStatus, NAME as GUARD } from "../pieces/guard.js";
@@ -23,7 +35,7 @@ import { keepOwn, NAME as SKILLS, ownInPick, skillsStatus } from "../pieces/skil
 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";
+import { download, failedOutput, runInstall, setVerbose } from "../tools.js";
 /** Every piece, in the order its steps run. */
 const PIECES = [SKILLS_MANAGER, FLOW, CLOUD, GUARD, SKILLS, AGENTS_MD];
 /**
@@ -35,37 +47,119 @@ export function pieceNames() {
     return [...PIECES];
 }
 /**
- * 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.
+ * Each piece's status, with every lookup at once. skills-manager, 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 flowComing = (flow ?? Promise.resolve(null)).then((status) => status !== null && !status.installed && status.steps.length > 0);
+    const skillsManager = skip.includes(SKILLS_MANAGER) ? null : flowComing.then((coming) => skillsManagerStatus(root, !skip.includes(SKILLS), coming));
     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([skillsManager, flow, cloud, guard, skills, agentsMd]);
     return all.flatMap((status) => status ?? []);
 }
 /**
- * Prints what the repo has of each piece.
+ * Prints what the repo has of each piece, in the pieces' order, and the pieces the repo
+ * decided not to have, with how to change that.
  * @param statuses - The pieces' statuses.
+ * @param decidedOff - The pieces left out by the repo's decision.
  * @param out - Where to write.
  */
-function printStatus(statuses, out) {
-    const width = Math.max(...statuses.map((status) => status.name.length));
+function printStatus(statuses, decidedOff, out) {
+    const width = Math.max(...statuses.map((status) => status.name.length), ...decidedOff.map((name) => name.length));
     const stateWidth = Math.max(...statuses.map((status) => status.state.length));
     out.stdout("\nEste repo tiene:\n");
-    for (const status of statuses)
-        out.stdout(`  ${status.name.padEnd(width)}  ${status.state.padEnd(stateWidth)}  · ${status.summary}\n`);
+    for (const name of PIECES) {
+        for (const status of statuses.filter((each) => each.name === name))
+            out.stdout(`  ${status.name.padEnd(width)}  ${status.state.padEnd(stateWidth)}  · ${status.summary}\n`);
+        if (decidedOff.includes(name))
+            out.stdout(`  ${name.padEnd(width)}  fuera por decisión del repo\n`);
+    }
+    if (decidedOff.length > 0)
+        out.stdout(`\nPara cambiar qué piezas usa el repo: agent-kitchen apply --pieces (o edita ${DECISIONS}).\n`);
     out.stdout("\n");
 }
+/**
+ * Settles the pieces without a decision and writes the file, unless nothing changed or
+ * nothing was decided.
+ * @param root - The repo.
+ * @param saved - What was read, or null if there is no file.
+ * @param statuses - What each piece found.
+ * @param chosen - The steps the person picked.
+ * @param commits - Whether `--commit` asks about the changes at the end.
+ * @param out - Where to write.
+ * @returns True if the file was written.
+ */
+function saveDecisions(root, saved, statuses, chosen, commits, out) {
+    const previous = saved?.pieces ?? {};
+    const pieces = decide(statuses, chosen, previous);
+    const same = Object.keys(pieces).length === Object.keys(previous).length && Object.entries(pieces).every(([name, value]) => previous[name] === value);
+    if (Object.keys(pieces).length === 0 || (saved !== null && same))
+        return false;
+    writeDecisions(root, pieces, saved?.raw ?? {});
+    out.stdout(savedMessage(commits));
+    return true;
+}
+/**
+ * The closing line when no step ran, which must not contradict a file written in this run.
+ * @param why - "leave" if the person left without changing anything, "none" if they picked no steps.
+ * @param wrote - Whether the decisions file was written in this run.
+ * @returns The line, with its newline.
+ * @example noStepsMessage("none", true) // "No elegiste pasos; solo guardé qué piezas usa el repo.\n"
+ */
+export function noStepsMessage(why, wrote) {
+    if (why === "leave")
+        return wrote ? "No corrí ningún paso; solo guardé qué piezas usa el repo.\n" : "No se cambió nada.\n";
+    return wrote ? "No elegiste pasos; solo guardé qué piezas usa el repo.\n" : "No elegiste nada; no se cambió nada.\n";
+}
+/**
+ * The line that says the decisions were saved.
+ * @param commits - Whether `--commit` asks about the changes at the end, so the file need not be committed by hand.
+ * @returns The line.
+ */
+function savedMessage(commits) {
+    return `Guardé qué piezas usa el repo en ${DECISIONS}${commits ? "" : "; commitéalo"}.\n`;
+}
+/** The line the commit of `--commit` adds for the decisions file. */
+const DECISIONS_STEP = `Guardar qué piezas usa el repo en ${DECISIONS}`;
+/**
+ * What the commit of `--commit` lists: the steps that worked, and the decisions file if this
+ * run wrote it.
+ * @param done - The labels of the steps that worked.
+ * @param wrote - Whether the decisions file was written in this run.
+ * @returns The labels.
+ * @example commitLabels([], true) // ["Guardar qué piezas usa el repo en .agents/kitchen.json"]
+ */
+export function commitLabels(done, wrote) {
+    return wrote ? [...done, DECISIONS_STEP] : done;
+}
+/**
+ * Asks which pieces the repo uses and writes the answer for every decidable piece.
+ * @param root - The repo.
+ * @param saved - What was read, or null if there is no file.
+ * @param commits - Whether `--commit` asks about the changes at the end.
+ * @param out - Where to write.
+ * @returns False if the person cancelled.
+ */
+async function choosePieces(root, saved, commits, out) {
+    out.stdout("Revisando el repo y las últimas versiones…\n");
+    // No skip here: an installed, undecided piece passed in --skip still starts ticked.
+    const statuses = await statusesOf(root, []);
+    const ticked = DECIDABLE.filter((name) => saved?.pieces[name] === true || (saved?.pieces[name] === undefined && statuses.some((status) => status.name === name && status.installed)));
+    const picked = await askPieces(DECIDABLE, ticked);
+    if (picked === null)
+        return false;
+    writeDecisions(root, Object.fromEntries(DECIDABLE.map((name) => [name, picked.includes(name)])), saved?.raw ?? {});
+    out.stdout(savedMessage(commits));
+    return true;
+}
 /**
  * Leaves the repo's own skills out of a step's pick, saying so.
  * @param root - The repo.
@@ -206,7 +300,7 @@ async function runStep(root, step, progress, out) {
  * @param out - Where to write and ask.
  * @returns 0, or 1 if a step failed or the person cancelled.
  * @throws KitError outside the main checkout or with a broken file; UsageError for an unknown piece.
- * @example await sync({ cwd, yes: false, dryRun: true, verbose: false, skip: [] }, out)
+ * @example await sync({ cwd, yes: false, dryRun: true, verbose: false, skip: [], commit: false, pieces: false }, out)
  */
 export async function sync(options, out) {
     const unknown = options.skip.find((name) => !pieceNames().includes(name));
@@ -214,39 +308,133 @@ 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.");
+    if (options.pieces && (options.yes || options.dryRun))
+        throw new UsageError("usa --pieces solo, sin --yes ni --dry-run.");
+    if (options.pieces && !out.interactive)
+        throw new UsageError("--pieces pregunta qué piezas usa el repo; córrelo en una terminal.");
     const root = mainCheckout(options.cwd, "agent-kitchen apply");
+    const base = options.commit ? baseBranch(root) : null;
+    if (base !== null)
+        checkReady(root, base);
     setVerbose(options.verbose);
+    let saved = readDecisions(root);
+    let wrote = false;
+    for (const warning of saved?.warnings ?? [])
+        warn(out, warning);
+    if (options.pieces) {
+        if (!(await choosePieces(root, saved, base !== null, out))) {
+            out.stdout("No se cambió nada.\n");
+            return 0;
+        }
+        saved = readDecisions(root);
+        wrote = true;
+    }
+    const skip = [...options.skip, ...off(saved)];
+    const asks = out.interactive && !options.yes && !options.dryRun;
+    const saves = asks && options.skip.length === 0;
     if (out.interactive)
         out.stdout("Revisando el repo y las últimas versiones…\n");
-    const statuses = await statusesOf(root, options.skip);
-    printStatus(statuses, out);
+    let statuses = await statusesOf(root, skip);
+    if (saved !== null && !asks && !options.dryRun) {
+        const left = undecided(saved).filter((name) => statuses.some((status) => status.name === name && !status.installed));
+        if (left.length > 0) {
+            skip.push(...left);
+            statuses = await statusesOf(root, skip);
+            out.stdout(`Pieza nueva sin decisión: ${left.join(", ")}. Corre agent-kitchen apply en una terminal para elegir.\n`);
+        }
+    }
+    if (saved !== null) {
+        const fresh = undecided(saved);
+        for (const status of statuses.filter((each) => fresh.includes(each.name))) {
+            status.state += " (nueva)";
+            for (const step of status.steps)
+                step.label += " (nueva)";
+        }
+    }
+    printStatus(statuses, off(saved).filter((name) => !options.skip.includes(name)), out);
     const steps = statuses.flatMap((status) => status.steps);
+    // With --commit, a run that only wrote the decisions file still ends with the question.
+    const endWithoutSteps = async () => (base !== null && wrote ? commitChanges(root, base, commitLabels([], true), [], options, out) : 0);
     if (steps.length === 0) {
+        if (saves)
+            wrote = saveDecisions(root, saved, statuses, [], base !== null, out) || wrote;
         out.stdout("Todo al día: no hay nada que instalar ni actualizar.\n");
-        return 0;
+        return endWithoutSteps();
     }
     const chosen = await chooseSteps(root, steps, options, out);
+    if (saves && Array.isArray(chosen))
+        wrote = saveDecisions(root, saved, statuses, chosen, base !== null, out) || wrote;
     if (chosen === "leave") {
-        out.stdout("No se cambió nada.\n");
-        return 0;
+        out.stdout(noStepsMessage("leave", wrote));
+        return endWithoutSteps();
     }
     if (chosen === null) {
+        if (wrote) {
+            out.stdout(noStepsMessage("leave", wrote));
+            return endWithoutSteps();
+        }
         if (!options.dryRun && out.interactive)
             warn(out, "no se cambió nada.");
         return options.dryRun || !out.interactive ? 0 : 1;
     }
     if (chosen.length === 0) {
         if (!options.yes)
-            out.stdout("No elegiste nada; no se cambió nada.\n");
-        return 0;
+            out.stdout(noStepsMessage("none", wrote));
+        return endWithoutSteps();
     }
-    const progress = progressFor(out, options.verbose);
+    const progress = progressFor(out, options.verbose || base !== null);
     const failed = [];
     for (const step of chosen) {
         if (!(await runStep(root, step, progress, out)))
             failed.push(step.label);
     }
+    if (base !== null)
+        return commitChanges(root, base, commitLabels(chosen.filter((step) => !failed.includes(step.label)).map((step) => step.label), wrote), failed, options, out);
     const next = `Falta: corre '${packageManager(root)} install', revisa el diff y haz commit.`;
     out.stdout(`\n${failed.length === 0 ? "Listo." : `Terminó, pero fallaron: ${failed.join("; ")}.`} ${next}\n`);
     return failed.length === 0 ? 0 : 1;
 }
+/**
+ * The end of `--commit`: the install if package.json changed, the changes, the question (or
+ * the branch with a PR under --yes) and what git did.
+ * @param root - The repo.
+ * @param base - The base branch.
+ * @param done - What the commit lists: the labels of the steps that worked, and the decisions file if written.
+ * @param failed - The labels of the steps that failed.
+ * @param options - The options.
+ * @param out - Where to write and ask.
+ * @returns 0, or 1 if a step, the install or git failed.
+ */
+async function commitChanges(root, base, done, failed, options, out) {
+    const summary = failed.length === 0 ? "Listo." : `Terminó, pero fallaron: ${failed.join("; ")}.`;
+    const changed = changedPaths(root);
+    if (changed.length === 0) {
+        out.stdout(`\n${summary} No cambió ningún archivo: no hay nada que commitear.\n`);
+        return failed.length === 0 ? 0 : 1;
+    }
+    const manager = packageManager(root);
+    const packageChanged = changed.includes("package.json");
+    if (packageChanged) {
+        const label = `Instalar las dependencias con ${manager}`;
+        out.stdout(`→ ${label}\n`);
+        const installed = await runInstall(root, manager);
+        out.stdout(`${installed.ok ? "✓" : "✗"} ${label}\n`);
+        if (!installed.ok) {
+            out.stderr(failedOutput(installed.output));
+            out.stdout(`\n${summary} No commiteé: el install falló y los cambios quedan sin commit.\n`);
+            return 1;
+        }
+    }
+    const paths = changedPaths(root);
+    out.stdout(`\n${summary} Cambios:\n${paths.map((path) => `  ${path}`).join("\n")}\n`);
+    if (failed.length > 0 && options.yes) {
+        out.stdout("No commiteé porque algún paso falló; los cambios quedan sin commit.\n");
+        return 1;
+    }
+    const branch = branchName(root, new Date());
+    const choice = options.yes ? "pr" : await askFinish(base, branch, failed.length > 0);
+    const result = await finish(root, choice, { base, branch, steps: done, paths, manager, packageChanged });
+    for (const line of result.lines)
+        out.stdout(`${line}\n`);
+    return result.ok && failed.length === 0 ? 0 : 1;
+}

package/dist/decisions.d.ts

@@ -0,0 +1,54 @@
+import type { PieceStatus, Step } from "./piece.js";
+/** The file with the decisions, relative to the repo. */
+export declare const DECISIONS = ".agents/kitchen.json";
+/** The pieces a repo can decide on, in the order sync runs them. */
+export declare const DECIDABLE: string[];
+/** What was read from the decisions file. */
+export interface Saved {
+    /** The valid decisions of the decidable pieces. */
+    pieces: Record<string, boolean>;
+    /** The whole file, to write back without losing what is not ours. */
+    raw: Record<string, unknown>;
+    /** What was wrong in the file, in Spanish, for the user. */
+    warnings: string[];
+}
+/**
+ * Reads the decisions of a repo.
+ * @param root - The repo.
+ * @returns The decisions, or null if the file does not exist.
+ * @throws KitError if the file is not valid JSON.
+ * @example readDecisions(root)?.pieces // { "claude-repo-guard": false }
+ */
+export declare function readDecisions(root: string): Saved | null;
+/**
+ * The decidable pieces with no decision yet.
+ * @param saved - What was read, or null if there is no file.
+ * @returns Their names; all of them without a file.
+ * @example undecided(null) // ["issue-flow", "claude-cloud", ...]
+ */
+export declare function undecided(saved: Saved | null): string[];
+/**
+ * The pieces the repo decided not to have.
+ * @param saved - What was read, or null if there is no file.
+ * @returns Their names.
+ * @example off({ pieces: { skills: false }, raw: {}, warnings: [] }) // ["skills"]
+ */
+export declare function off(saved: Saved | null): string[];
+/**
+ * Settles the pieces that have no decision from what the repo has and what was chosen.
+ * @param statuses - What each piece found.
+ * @param chosen - The steps the user picked.
+ * @param previous - The decisions already made; they never change here.
+ * @returns `previous` plus a decision for each decidable piece without one: installed or
+ * with a chosen step is true, offered steps all unchosen is false, no steps leaves it open.
+ * @example decide([{ name: "skills", installed: true, summary: "", state: "", steps: [] }], [], {}) // { skills: true }
+ */
+export declare function decide(statuses: PieceStatus[], chosen: Step[], previous: Record<string, boolean>): Record<string, boolean>;
+/**
+ * Writes the decisions, keeping every other key of the file.
+ * @param root - The repo.
+ * @param pieces - The decisions to write.
+ * @param raw - The whole file as it was read (empty if there was none).
+ * @example writeDecisions(root, { "issue-flow": true }, {})
+ */
+export declare function writeDecisions(root: string, pieces: Record<string, boolean>, raw: Record<string, unknown>): void;