agent-kitchen 0.0.0-stage → 0.2.0

package/dist/pieces/cloud.js

@@ -0,0 +1,93 @@
+/**
+ * @file Claude cloud sessions (`@ramon-sg/claude-cloud`). The repo's version is the one
+ * `.claude/cloud.json` pins: the cloud machine runs exactly that one. Installing runs its
+ * `init`; updating only moves that version (and a `$schema` pinned to a version), which is
+ * how `claude-cloud` updates. Outside
+ * the cloud its hook does nothing, so a repo nobody opens in the cloud loses nothing.
+ */
+import { warn } from "../output.js";
+import { readJson, writeJson } from "../repo.js";
+import { compareVersions, isRelease, npmLatest, runNpx } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "claude-cloud";
+/** The package on npm. */
+const PACKAGE = "@ramon-sg/claude-cloud";
+/** Its config in the repo, which pins its version. */
+const CONFIG = ".claude/cloud.json";
+/**
+ * The version `.claude/cloud.json` pins.
+ * @param config - The config, or null.
+ * @returns The version, or null if it has none.
+ */
+function pinned(config) {
+    return typeof config?.version === "string" && isRelease(config.version) ? config.version : null;
+}
+/**
+ * The step the repo needs, if any.
+ * @param config - The config, or null.
+ * @param latest - The latest on npm, or null.
+ * @returns The step, or null.
+ */
+function stepFor(config, latest) {
+    const version = pinned(config);
+    if (config === null) {
+        const spec = `${PACKAGE}@${latest ?? "1"}`;
+        return {
+            piece: NAME,
+            checked: true,
+            label: `claude-cloud ${latest ?? "1.x"}: prepares Claude cloud sessions (${CONFIG})`,
+            run: (context) => {
+                if (runNpx(context.root, [spec, "init"]))
+                    return true;
+                warn(context.out, `claude-cloud init failed; run 'npx ${spec} init'.`);
+                return false;
+            },
+        };
+    }
+    if (latest === null || (version !== null && compareVersions(latest, version) <= 0))
+        return null;
+    return {
+        piece: NAME,
+        checked: true,
+        label: `claude-cloud ${version ?? "?"} → ${latest}: the version ${CONFIG} pins`,
+        run: (context) => {
+            const current = readJson(context.root, CONFIG) ?? {};
+            const schema = typeof current.$schema === "string" ? current.$schema.replace(/@ramon-sg\/claude-cloud@[^/]+\//, `${PACKAGE}@${latest}/`) : undefined;
+            writeJson(context.root, CONFIG, { ...current, ...(schema === undefined ? {} : { $schema: schema }), version: latest });
+            return true;
+        },
+    };
+}
+/**
+ * What the repo has of claude-cloud, and the step it needs.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example cloudStatus(root).state // "1.0.0, the latest"
+ */
+export function cloudStatus(root) {
+    const config = readJson(root, CONFIG);
+    const latest = npmLatest(PACKAGE);
+    const version = pinned(config);
+    const step = stepFor(config, latest);
+    const known = latest === null ? " (npm cannot tell the latest)" : "";
+    const state = config === null ? `not installed${known}` : version === null ? `${CONFIG} pins no version` : step === null ? `${version}${known}` : `${version}, ${latest ?? "?"} available`;
+    return { name: NAME, summary: "Claude cloud sessions: tools, Docker and the full clone", installed: config !== null, state, steps: step === null ? [] : [step] };
+}
+/**
+ * Whether `.claude/cloud.json` pins a version, and whether a newer one exists.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example cloudChecks(root)[0].status // "ok"
+ */
+export function cloudChecks(root) {
+    const config = readJson(root, CONFIG);
+    if (config === null)
+        return [{ name: NAME, status: "info", detail: "not installed" }];
+    const version = pinned(config);
+    if (version === null)
+        return [{ name: NAME, status: "fail", detail: `${CONFIG} pins no exact version: set "version" to the one to run, like "${npmLatest(PACKAGE) ?? "1.0.0"}"` }];
+    const latest = npmLatest(PACKAGE);
+    if (latest !== null && compareVersions(latest, version) > 0)
+        return [{ name: NAME, status: "info", detail: `${version}, ${latest} available: run npx agent-kitchen` }];
+    return [{ name: NAME, status: "ok", detail: version }];
+}

package/dist/pieces/guard.d.ts

@@ -0,0 +1,40 @@
+import { type Check, type PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "claude-repo-guard";
+/** What the auto mode is told about the issue flow. */
+export declare const GUARD_ENVIRONMENT = "issue-flow is this repo's issue workflow: making the branch and worktree of an issue, its empty start commit, pushing it, opening its draft PR, assigning the issue and adding its \"Slug de rama\" block are normal steps of the work, not risky actions.";
+/** The option that lets `gh` verify TLS inside the macOS sandbox. */
+export declare const WEAKER_NETWORK = "weakerNetworkIsolation";
+/**
+ * The npx spec of a version.
+ * @param version - The version, or null for the default branch.
+ * @returns The spec.
+ * @example guardSpec("0.2.0") // "github:ramon-sg/claude-repo-guard#v0.2.0"
+ */
+export declare function guardSpec(version: string | null): string;
+/**
+ * The guard's options with what the flow needs added; what the repo set stays.
+ * @param root - The repo.
+ * @param platform - The operating system (`process.platform`).
+ * @returns The new options and what changed.
+ * @example guardOptions(root, "darwin").changes // [".claude/repo-guard.config.json: weakerNetworkIsolation true, …"]
+ */
+export declare function guardOptions(root: string, platform: string): {
+    options: Record<string, unknown>;
+    changes: string[];
+};
+/**
+ * What the repo has of claude-repo-guard, and the step it needs.
+ * @param root - The repo.
+ * @param flowComing - Whether an earlier step of this run installs the issue flow.
+ * @returns The piece's status.
+ * @example guardStatus(root, false).state // "not installed"
+ */
+export declare function guardStatus(root: string, flowComing: boolean): PieceStatus;
+/**
+ * The guard's own doctor at the repo's version and, on macOS, the option `gh` needs.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example guardChecks(root).map((check) => check.status) // ["ok"]
+ */
+export declare function guardChecks(root: string): Check[];

package/dist/pieces/guard.js

@@ -0,0 +1,173 @@
+/**
+ * @file The guardrails (`claude-repo-guard`): auto mode with the sandbox, installed in the
+ * repo. It is not on npm, so it runs from GitHub at its `vX.Y.Z` tag; the repo's version is
+ * the one its manifest records. Before installing or updating, agent-kitchen writes in its
+ * options what the issue flow needs, if the repo has the flow: the auto mode is told that
+ * the flow's writes are normal, the flow's base branch becomes `integrationBranch`, and on
+ * macOS `weakerNetworkIsolation` lets `gh` work inside the sandbox (the guard's own default
+ * is false, so false counts as missing; the step can be unticked). When the flow is
+ * installed in the same run, the guard gets those options in that run too.
+ */
+import { warn } from "../output.js";
+import { FLOW_CONFIG } from "../piece.js";
+import { readJson, writeJson } from "../repo.js";
+import { captureNpx, compareVersions, isRelease, latestTag, runNpx } from "../tools.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "claude-repo-guard";
+/** Its GitHub repo. */
+const REPO = "ramon-sg/claude-repo-guard";
+/** Its options in the repo. */
+const CONFIG = ".claude/repo-guard.config.json";
+/** What its install records, with its version. */
+const MANIFEST = ".claude/repo-guard.manifest.json";
+/** What the auto mode is told about the issue flow. */
+export const GUARD_ENVIRONMENT = "issue-flow is this repo's issue workflow: making the branch and worktree of an issue, its empty start commit, pushing it, opening its draft PR, assigning the issue and adding its \"Slug de rama\" block are normal steps of the work, not risky actions.";
+/** The option that lets `gh` verify TLS inside the macOS sandbox. */
+export const WEAKER_NETWORK = "weakerNetworkIsolation";
+/**
+ * The npx spec of a version.
+ * @param version - The version, or null for the default branch.
+ * @returns The spec.
+ * @example guardSpec("0.2.0") // "github:ramon-sg/claude-repo-guard#v0.2.0"
+ */
+export function guardSpec(version) {
+    return version === null ? `github:${REPO}` : `github:${REPO}#v${version}`;
+}
+/**
+ * The guard's options with what the flow needs added; what the repo set stays.
+ * @param root - The repo.
+ * @param platform - The operating system (`process.platform`).
+ * @returns The new options and what changed.
+ * @example guardOptions(root, "darwin").changes // [".claude/repo-guard.config.json: weakerNetworkIsolation true, …"]
+ */
+export function guardOptions(root, platform) {
+    const options = { ...(readJson(root, CONFIG) ?? {}) };
+    const changes = [];
+    const flow = readJson(root, FLOW_CONFIG);
+    const environment = Array.isArray(options.environment) ? options.environment.map(String) : [];
+    if (flow !== null && !environment.includes(GUARD_ENVIRONMENT)) {
+        options.environment = [...environment, GUARD_ENVIRONMENT];
+        changes.push(`${CONFIG}: tells the auto mode about the issue flow`);
+    }
+    const baseBranch = typeof flow?.baseBranch === "string" ? flow.baseBranch : null;
+    if (baseBranch !== null && (options.integrationBranch === undefined || options.integrationBranch === "")) {
+        options.integrationBranch = baseBranch;
+        changes.push(`${CONFIG}: integrationBranch ${baseBranch}`);
+    }
+    if (platform === "darwin" && options[WEAKER_NETWORK] !== true) {
+        options[WEAKER_NETWORK] = true;
+        changes.push(`${CONFIG}: ${WEAKER_NETWORK} true, so gh works inside the macOS sandbox`);
+    }
+    return { options, changes };
+}
+/**
+ * Writes the flow's options and installs the guard at a version.
+ * @param context - Where it runs.
+ * @param version - The version, or null for the default branch.
+ * @returns Whether it installed.
+ */
+function install(context, version) {
+    const { options, changes } = guardOptions(context.root, process.platform);
+    if (changes.length > 0)
+        writeJson(context.root, CONFIG, options);
+    for (const change of changes)
+        context.out.stdout(`  ${change}\n`);
+    if (runNpx(context.root, [guardSpec(version), "install", "--yes"]))
+        return true;
+    failed(context.out, version);
+    return false;
+}
+/**
+ * Writes the flow's options and reinstalls the guard at its version, if they are missing
+ * by now (the flow may have been installed earlier in this run).
+ * @param context - Where it runs.
+ * @param version - The guard's version, or null.
+ * @returns Whether it worked, or true if nothing was missing.
+ */
+function addOptions(context, version) {
+    if (guardOptions(context.root, process.platform).changes.length > 0)
+        return install(context, version);
+    context.out.stdout("  its options already have what the issue flow needs\n");
+    return true;
+}
+/**
+ * Says how to retry an install that failed.
+ * @param out - Where to write.
+ * @param version - The version it tried.
+ */
+function failed(out, version) {
+    warn(out, `claude-repo-guard did not install; run 'npx ${guardSpec(version)} install' from your terminal (inside a Claude session its sandbox blocks .claude/settings.json).`);
+}
+/**
+ * The version its manifest records.
+ * @param root - The repo.
+ * @returns The version, null if it records none, or undefined if it is not installed.
+ */
+function installedVersion(root) {
+    const manifest = readJson(root, MANIFEST);
+    if (manifest === null)
+        return undefined;
+    return typeof manifest.version === "string" && isRelease(manifest.version) ? manifest.version : null;
+}
+/**
+ * The step the repo needs, if any.
+ * @param root - The repo.
+ * @param installed - The repo's version, null if unknown, undefined if not installed.
+ * @param latest - The latest tag, or null.
+ * @returns The step, or null.
+ */
+function stepFor(root, installed, latest, flowComing) {
+    if (installed === undefined)
+        return { piece: NAME, checked: true, label: `claude-repo-guard ${latest ?? "(main)"}: auto mode with the sandbox, and a doc of what it protects`, run: (context) => install(context, latest) };
+    if (latest !== null && (installed === null || compareVersions(latest, installed) > 0))
+        return { piece: NAME, checked: true, label: `claude-repo-guard ${installed ?? "?"} → ${latest}`, run: (context) => install(context, latest) };
+    if (flowComing || guardOptions(root, process.platform).changes.length > 0)
+        return { piece: NAME, checked: true, label: "claude-repo-guard: what the issue flow needs in its options", run: (context) => addOptions(context, installed) };
+    return null;
+}
+/**
+ * What the repo has of claude-repo-guard, and the step it needs.
+ * @param root - The repo.
+ * @param flowComing - Whether an earlier step of this run installs the issue flow.
+ * @returns The piece's status.
+ * @example guardStatus(root, false).state // "not installed"
+ */
+export function guardStatus(root, flowComing) {
+    const installed = installedVersion(root);
+    const latest = latestTag(REPO);
+    const known = latest === null ? " (GitHub has no release tag)" : "";
+    const state = installed === undefined ? `not installed${known}` : latest !== null && (installed === null || compareVersions(latest, installed) > 0) ? `${installed ?? "unknown version"}, ${latest} available` : `${installed ?? "unknown version"}${known}`;
+    const step = stepFor(root, installed, latest, flowComing);
+    return { name: NAME, summary: "guardrails: auto mode with the sandbox, writes only inside the worktree", installed: installed !== undefined, state, steps: step === null ? [] : [step] };
+}
+/**
+ * The guard's own doctor at the repo's version and, on macOS, the option `gh` needs.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example guardChecks(root).map((check) => check.status) // ["ok"]
+ */
+export function guardChecks(root) {
+    const installed = installedVersion(root);
+    if (installed === undefined)
+        return [{ name: NAME, status: "info", detail: "not installed (Claude opens with your own permissions)" }];
+    const checks = [];
+    if (process.platform === "darwin" && readJson(root, CONFIG)?.[WEAKER_NETWORK] !== true)
+        checks.push({ name: `${NAME}: ${WEAKER_NETWORK}`, status: "fail", detail: `not true in ${CONFIG}, so gh fails inside the macOS sandbox: run npx agent-kitchen` });
+    const result = captureNpx(root, [guardSpec(installed), "doctor", "--json"]);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        found = null;
+    }
+    if (!Array.isArray(found))
+        return [...checks, { name: NAME, status: "fail", detail: `could not run its doctor; run 'npx ${guardSpec(installed)} doctor'` }];
+    const bad = found.filter((check) => typeof check !== "object" || check === null || check.ok !== true);
+    if (bad.length === 0)
+        return [...checks, { name: NAME, status: "ok", detail: `${installed ?? "unknown version"}, its doctor passes` }];
+    return [...checks, ...bad.map((check) => {
+            const entry = typeof check === "object" && check !== null ? check : { name: "?", detail: String(check) };
+            return { name: `${NAME}: ${String(entry.name)}`, status: "fail", detail: String(entry.detail) };
+        })];
+}

package/dist/pieces/issue-flow.d.ts

@@ -0,0 +1,32 @@
+import { type Check, type PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "issue-flow";
+/**
+ * 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.
+ * @param root - The repo.
+ * @returns The version in package.json, or null.
+ * @example flowVersion(root) // "0.2.0"
+ */
+export declare function flowSpec(root: string): string | null;
+/**
+ * The issue flow's release in the repo: what package.json pins, if it is an exact release.
+ * @param root - The repo.
+ * @returns The version, or null if there is none or it is not a release.
+ * @example flowVersion(root) // "0.2.0"
+ */
+export declare function flowVersion(root: string): string | null;
+/**
+ * What the repo has of the issue flow, and the step it needs.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example issueFlowStatus(root).state // "0.1.0, 0.2.0 available"
+ */
+export declare function issueFlowStatus(root: string): PieceStatus;
+/**
+ * The flow's own doctor at the repo's version, and whether its skills are at that tag.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example issueFlowChecks(root)[0].name // "issue-flow: .agents/flow.json"
+ */
+export declare function issueFlowChecks(root: string): Check[];

package/dist/pieces/issue-flow.js

@@ -0,0 +1,147 @@
+/**
+ * @file The issue flow (`@ramon-sg/issue-flow`): its CLI, hooks and config, and its skills.
+ * 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.
+ */
+import { warn } from "../output.js";
+import { FLOW_CATALOG, FLOW_PACKAGE } from "../piece.js";
+import { dependencyVersion, 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. */
+export const NAME = "issue-flow";
+/** How the catalog's ref is named when it is off. */
+const SKILLS_CATALOG_LABEL = "the catalog";
+/** The first version whose `doctor` prints `--json`. */
+const JSON_DOCTOR = "0.2.0";
+/**
+ * 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.
+ * @param root - The repo.
+ * @returns The version in package.json, or null.
+ * @example flowVersion(root) // "0.2.0"
+ */
+export function flowSpec(root) {
+    return dependencyVersion(readJson(root, "package.json"), FLOW_PACKAGE);
+}
+/**
+ * The issue flow's release in the repo: what package.json pins, if it is an exact release.
+ * @param root - The repo.
+ * @returns The version, or null if there is none or it is not a release.
+ * @example flowVersion(root) // "0.2.0"
+ */
+export function flowVersion(root) {
+    const spec = flowSpec(root);
+    return spec !== null && isRelease(spec) ? spec : null;
+}
+/**
+ * The flow's skills that are not at a version's tag, or the catalog pinned elsewhere.
+ * @param root - The repo.
+ * @param version - The flow's version.
+ * @returns Their names; the catalog's ref as well if it is off.
+ */
+function skillsOff(root, version) {
+    const tag = `v${version}`;
+    const off = catalogSkills(root, FLOW_CATALOG).filter((skill) => skill.tag !== tag).map((skill) => `${skill.name} at ${skill.tag ?? "no tag"}`);
+    const source = manifestCatalogs(root).find((item) => item.catalog === FLOW_CATALOG);
+    return source !== undefined && source.ref !== tag ? [...off, `${SKILLS_CATALOG_LABEL} at ${source.ref ?? "the latest"}`] : off;
+}
+/**
+ * Moves the flow's skills to a version's tag: the catalog's ref in the manifest, and then
+ * `skills-manager update` on them.
+ * @param context - Where it runs.
+ * @param version - The flow's version.
+ * @returns Whether it worked, or true if the repo has none of the flow's skills.
+ */
+function moveSkills(context, version) {
+    if (!pinCatalog(context.root, FLOW_CATALOG, `v${version}`))
+        return true;
+    const failed = updateSkills(context.root, catalogSkills(context.root, FLOW_CATALOG).map((skill) => skill.name));
+    if (failed === null)
+        return true;
+    warn(context.out, `skills-manager did not update the flow's skills; run '${failed}' and then agent-kitchen again.`);
+    return false;
+}
+/**
+ * Runs the flow's own command at a version.
+ * @param context - Where it runs.
+ * @param version - The version.
+ * @param args - The command and its flags.
+ * @returns Whether it exited 0.
+ */
+function runFlow(context, version, args) {
+    if (runNpx(context.root, [`${FLOW_PACKAGE}@${version}`, ...args]))
+        return true;
+    warn(context.out, `issue-flow ${args[0] ?? ""} failed; run 'npx ${FLOW_PACKAGE}@${version} ${args.join(" ")}'.`);
+    return false;
+}
+/**
+ * The step the repo needs, if any.
+ * @param installed - The repo's version, or null.
+ * @param latest - The latest on npm, or null.
+ * @param root - The repo.
+ * @returns The step, or null.
+ */
+function stepFor(installed, latest, root) {
+    if (installed === null && latest !== null)
+        return { piece: NAME, checked: true, label: `issue-flow ${latest}: .agents/flow.json with its recipes, the hooks and scripts`, run: (context) => runFlow(context, latest, ["init", ...(context.yes ? ["--yes"] : [])]) };
+    if (installed !== null && latest !== null && compareVersions(latest, installed) > 0)
+        return { piece: NAME, checked: true, label: `issue-flow ${installed} → ${latest}: the CLI, its hooks and its skills`, run: (context) => runFlow(context, latest, ["upgrade"]) && moveSkills(context, latest) };
+    if (installed !== null && skillsOff(root, installed).length > 0)
+        return { piece: NAME, checked: true, label: `issue-flow's skills → v${installed}, the CLI's version`, run: (context) => moveSkills(context, installed) };
+    return null;
+}
+/**
+ * What the repo has of the issue flow, and the step it needs.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example issueFlowStatus(root).state // "0.1.0, 0.2.0 available"
+ */
+export function issueFlowStatus(root) {
+    const summary = "the issue flow: branch, worktree and draft PR per issue, and its skills";
+    const spec = flowSpec(root);
+    if (spec !== null && !isRelease(spec))
+        return { name: NAME, summary, installed: true, state: `package.json has ${spec}, not an exact release; agent-kitchen leaves it`, steps: [] };
+    const installed = flowVersion(root);
+    const latest = npmLatest(FLOW_PACKAGE);
+    const step = stepFor(installed, latest, root);
+    const known = latest === null ? " (npm cannot tell the latest)" : "";
+    const state = installed === null ? `not installed${known}` : latest !== null && compareVersions(latest, installed) > 0 ? `${installed}, ${latest} available` : `${installed}${known}`;
+    return { name: NAME, summary, installed: installed !== null, state, steps: step === null ? [] : [step] };
+}
+/**
+ * The flow's own doctor at the repo's version, and whether its skills are at that tag.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example issueFlowChecks(root)[0].name // "issue-flow: .agents/flow.json"
+ */
+export function issueFlowChecks(root) {
+    const spec = flowSpec(root);
+    if (spec === null)
+        return [{ name: NAME, status: "info", detail: "not installed" }];
+    const installed = flowVersion(root);
+    if (installed === null)
+        return [{ name: NAME, status: "info", detail: `package.json has ${spec}, not an exact release` }];
+    if (compareVersions(installed, JSON_DOCTOR) < 0)
+        return [{ name: NAME, status: "info", detail: `${installed} predates its doctor --json: run npx agent-kitchen to update it` }];
+    const result = captureNpx(root, [`${FLOW_PACKAGE}@${installed}`, "doctor", "--json"]);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        found = null;
+    }
+    const own = Array.isArray(found)
+        ? found.map((check) => ({ name: `${NAME}: ${String(check.name)}`, status: check.ok === true ? "ok" : "fail", detail: String(check.detail) }))
+        : [{ name: NAME, status: "fail", detail: `could not run its doctor; run 'npx ${FLOW_PACKAGE}@${installed} doctor'` }];
+    const off = skillsOff(root, installed);
+    const count = catalogSkills(root, FLOW_CATALOG).length;
+    const skills = count === 0 && off.length === 0
+        ? { name: `${NAME}: skills`, status: "info", detail: "none installed" }
+        : off.length === 0
+            ? { name: `${NAME}: skills`, status: "ok", detail: `${count} at v${installed}` }
+            : { name: `${NAME}: skills`, status: "fail", detail: `${off.join(", ")}, the CLI is ${installed}: run npx agent-kitchen` };
+    return [...own, skills];
+}

package/dist/pieces/skills.d.ts

@@ -0,0 +1,17 @@
+import { type Check, type PieceStatus } from "../piece.js";
+/** The piece's name, as `--skip` takes it. */
+export declare const NAME = "skills";
+/**
+ * What the repo has of the skills, and the steps it can take.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example skillsStatus(root).state // "6 installed"
+ */
+export declare function skillsStatus(root: string): PieceStatus;
+/**
+ * Whether `skills-manager check` passes: disk, lock and manifest agree.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example skillsChecks(root)[0].status // "ok"
+ */
+export declare function skillsChecks(root: string): Check[];

package/dist/pieces/skills.js

@@ -0,0 +1,155 @@
+/**
+ * @file The skills, through `skills-manager`: the flow's catalog (pinned to the flow's
+ * version, because its skills call the CLI) and the general catalogs (each skill at its
+ * own tag). The first time it opens the `skills-manager` menu with every catalog. Later it
+ * offers to move the general skills to their catalog's latest tag, and, unticked, to pick
+ * the skills a catalog has that the repo does not take yet. The flow's skills move with the
+ * flow (pieces/issue-flow.ts), never here.
+ */
+import { warn } from "../output.js";
+import { FLOW_CATALOG, GENERAL_CATALOGS, SKILLS_MANIFEST } from "../piece.js";
+import { readJson } from "../repo.js";
+import { catalogSkills, lockedSkills, manifestCatalogs, pinCatalog, skillsManagerSpec, updateSkills } from "../skills-files.js";
+import { captureNpx, compareVersions, latestTag, runNpx } from "../tools.js";
+import { flowVersion } from "./issue-flow.js";
+/** The piece's name, as `--skip` takes it. */
+export const NAME = "skills";
+/** The skills picked without a terminal: the flow's, and the audit `close-pr` uses. */
+const DEFAULT_SKILLS = [
+    ...["github-issues", "start-issue", "close-pr", "pr-review-comments", "pr-worktree"].map((name) => `catalog:${FLOW_CATALOG}/${name}`),
+    "catalog:ramon-sg/agent-skills/code-audit",
+];
+/** A release tag. */
+const RELEASE_TAG = /^v\d+\.\d+\.\d+$/;
+/**
+ * The `--catalog` flags: the flow's at the repo's flow version, if the repo has the flow,
+ * and the general ones.
+ * @param root - The repo.
+ * @returns The flags.
+ */
+function catalogArgs(root) {
+    const flow = flowVersion(root);
+    const catalogs = [...(flow === null ? [] : [`${FLOW_CATALOG}#v${flow}`]), ...GENERAL_CATALOGS];
+    return catalogs.flatMap((catalog) => ["--catalog", catalog]);
+}
+/**
+ * The default skills the manifest does not take yet, of the catalogs offered.
+ * @param root - The repo.
+ * @returns Their ids.
+ */
+function missingDefaults(root) {
+    const manifest = readJson(root, SKILLS_MANIFEST);
+    const sources = Array.isArray(manifest?.sources) ? manifest.sources : [];
+    const taken = new Set(sources.flatMap((source) => (typeof source.catalog === "string" && Array.isArray(source.skills) ? source.skills.map((name) => `catalog:${String(source.catalog)}/${String(name)}`) : [])));
+    const flow = flowVersion(root) !== null;
+    return DEFAULT_SKILLS.filter((id) => !taken.has(id) && (flow || !id.startsWith(`catalog:${FLOW_CATALOG}/`)));
+}
+/**
+ * Opens the `skills-manager` menu with the catalogs; without a terminal or with `--yes`,
+ * picks the default skills the repo does not have yet.
+ * @param context - Where it runs.
+ * @returns Whether `skills-manager` worked, or true if there was nothing to pick.
+ */
+function pick(context) {
+    const spec = skillsManagerSpec(context.root);
+    const args = [spec, readJson(context.root, SKILLS_MANIFEST) === null ? "init" : "add", ...catalogArgs(context.root)];
+    const choose = context.yes || !context.out.interactive;
+    const missing = choose ? missingDefaults(context.root) : [];
+    if (choose && missing.length === 0) {
+        context.out.stdout(`  the default skills are already in ${SKILLS_MANIFEST}\n`);
+        return true;
+    }
+    if (runNpx(context.root, choose ? [...args, "--select", missing.join(",")] : args))
+        return true;
+    warn(context.out, `skills-manager did not install the skills; run 'npx ${args.join(" ")}'.`);
+    return false;
+}
+/**
+ * The step that moves a general catalog's skills to its latest tag, if they are behind. A
+ * catalog that follows a branch has no tag to move to, so it gets no step.
+ * @param root - The repo.
+ * @param catalog - The catalog.
+ * @param ref - The ref the manifest pins it to, or null.
+ * @returns The step, or null.
+ */
+function updateStep(root, catalog, ref) {
+    if (ref !== null && !RELEASE_TAG.test(ref))
+        return null;
+    const latest = latestTag(catalog);
+    if (latest === null)
+        return null;
+    const behind = catalogSkills(root, catalog).filter((skill) => skill.tag !== null && RELEASE_TAG.test(skill.tag) && compareVersions(latest, skill.tag.replace(/^v/, "")) > 0);
+    if (behind.length === 0)
+        return null;
+    const from = [...new Set(behind.map((skill) => skill.tag ?? "?"))].join(", ");
+    return {
+        piece: NAME,
+        checked: true,
+        label: `${catalog}: ${behind.map((skill) => skill.name).join(", ")} ${from} → v${latest}`,
+        run: (context) => {
+            if (ref !== null)
+                pinCatalog(context.root, catalog, `v${latest}`);
+            const failed = updateSkills(context.root, behind.map((skill) => skill.name));
+            if (failed === null)
+                return true;
+            warn(context.out, `skills-manager did not update ${catalog}; run '${failed}' and then agent-kitchen again.`);
+            return false;
+        },
+    };
+}
+/**
+ * The skills the catalogs have and the repo does not take, as `skills-manager` lists them,
+ * without those already in the lock (it lists the ones that came through `requires`).
+ * @param root - The repo.
+ * @returns Their names, or null if `skills-manager` could not tell.
+ */
+function newSkills(root) {
+    const result = captureNpx(root, [skillsManagerSpec(root), "add", "--candidates", ...catalogArgs(root)]);
+    let found;
+    try {
+        found = JSON.parse(result?.out ?? "");
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(found))
+        return null;
+    const locked = lockedSkills(root);
+    return found.map((candidate) => String(candidate.name)).filter((name) => locked[name] === undefined);
+}
+/**
+ * What the repo has of the skills, and the steps it can take.
+ * @param root - The repo.
+ * @returns The piece's status.
+ * @example skillsStatus(root).state // "6 installed"
+ */
+export function skillsStatus(root) {
+    const summary = "skills: the flow's, planning, code and test audits";
+    if (readJson(root, SKILLS_MANIFEST) === null) {
+        const label = `skills: pick them from ${[FLOW_CATALOG, ...GENERAL_CATALOGS].join(" and ")} (without a terminal, the flow's and code-audit)`;
+        return { name: NAME, summary, installed: false, state: "not installed", steps: [{ piece: NAME, checked: true, label, run: pick }] };
+    }
+    const general = manifestCatalogs(root).filter((source) => source.catalog !== FLOW_CATALOG);
+    const steps = general.flatMap((source) => updateStep(root, source.catalog, source.ref) ?? []);
+    const fresh = newSkills(root);
+    if (fresh !== null && fresh.length > 0)
+        steps.push({ piece: NAME, checked: false, label: `skills: ${fresh.length} more to pick (${fresh.join(", ")})`, run: pick });
+    const count = manifestCatalogs(root).reduce((total, source) => total + catalogSkills(root, source.catalog).length, 0);
+    const behind = steps.filter((step) => step.checked).length;
+    return { name: NAME, summary, installed: true, state: `${count} installed${behind > 0 ? ", some behind" : ""}`, steps };
+}
+/**
+ * Whether `skills-manager check` passes: disk, lock and manifest agree.
+ * @param root - The repo.
+ * @returns The checks.
+ * @example skillsChecks(root)[0].status // "ok"
+ */
+export function skillsChecks(root) {
+    if (readJson(root, SKILLS_MANIFEST) === null)
+        return [{ name: NAME, status: "info", detail: "not installed" }];
+    const spec = skillsManagerSpec(root);
+    const result = captureNpx(root, [spec, "check"]);
+    if (result?.status === 0)
+        return [{ name: NAME, status: "ok", detail: "skills-manager check passes" }];
+    return [{ name: NAME, status: "fail", detail: `disk, lock and manifest disagree: run 'npx ${spec} check'` }];
+}