@catladder/cli 0.0.0-next-80fd0ab4 → 0.0.0-next-ebc933f2

package/dist/pipeline/src/agentSkills/generateAgentSkills.js

@@ -0,0 +1,82 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.generateAgentSkills = exports.injectGeneratedMarker = exports.AGENT_SKILL_GENERATED_MARKER = void 0;
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const shippedSkills_1 = require("./shippedSkills");
+const types_1 = require("./types");
+/**
+ * marks a materialized skill file as generated. Cleanup only ever
+ * removes skill directories whose SKILL.md carries this marker, so a
+ * user's own skills are never touched — even if they picked a
+ * `catladder-*` name.
+ */
+exports.AGENT_SKILL_GENERATED_MARKER = "<!-- 🐱 🔨 generated by catladder — do not edit manually, this file is overwritten on every catenv run -->";
+/**
+ * inserts the generated-marker into a markdown file: after the YAML
+ * frontmatter when there is one (a leading comment would break
+ * frontmatter parsing), at the top otherwise
+ */
+const injectGeneratedMarker = content => {
+  if (content.startsWith("---\n")) {
+    const frontmatterEnd = content.indexOf("\n---\n", 3);
+    if (frontmatterEnd !== -1) {
+      const bodyStart = frontmatterEnd + "\n---\n".length;
+      return content.slice(0, bodyStart) + "\n" + exports.AGENT_SKILL_GENERATED_MARKER + "\n" + content.slice(bodyStart);
+    }
+  }
+  return exports.AGENT_SKILL_GENERATED_MARKER + "\n\n" + content;
+};
+exports.injectGeneratedMarker = injectGeneratedMarker;
+/**
+ * removes previously materialized catladder skills from ALL known
+ * target directories (not just the enabled ones), so that opting out
+ * or narrowing the targets doesn't leave stale copies behind
+ */
+const cleanupGeneratedAgentSkills = async rootDir => {
+  for (const targetDir of Object.values(types_1.AGENT_SKILL_TARGET_DIRS)) {
+    const skillsRoot = (0, path_1.join)(rootDir, targetDir);
+    if (!(0, fs_1.existsSync)(skillsRoot)) continue;
+    for (const entry of await (0, promises_1.readdir)(skillsRoot)) {
+      if (!entry.startsWith(shippedSkills_1.AGENT_SKILL_PREFIX)) continue;
+      const skillMd = (0, path_1.join)(skillsRoot, entry, "SKILL.md");
+      if (!(0, fs_1.existsSync)(skillMd)) continue;
+      const content = await (0, promises_1.readFile)(skillMd, "utf-8");
+      if (!content.includes(exports.AGENT_SKILL_GENERATED_MARKER)) continue;
+      await (0, promises_1.rm)((0, path_1.join)(skillsRoot, entry), {
+        recursive: true,
+        force: true
+      });
+    }
+  }
+};
+/**
+ * materializes the agent skills shipped with catladder (usage guides
+ * for AI coding agents) into the repository's agent skill directories,
+ * so agents working in the project use knowledge matching the installed
+ * catladder version. Opt out or narrow the targets via
+ * `agentSkills` in the config.
+ */
+const generateAgentSkills = async (context, rootDir = ".") => {
+  await cleanupGeneratedAgentSkills(rootDir);
+  const targets = (0, types_1.getAgentSkillTargets)(context.config.agentSkills);
+  if (targets.length === 0) return;
+  const skills = (0, shippedSkills_1.getShippedSkills)();
+  for (const target of targets) {
+    for (const skill of skills) {
+      for (const file of skill.files) {
+        const path = (0, path_1.join)(rootDir, types_1.AGENT_SKILL_TARGET_DIRS[target], skill.name, file.relativePath);
+        await (0, promises_1.mkdir)((0, path_1.dirname)(path), {
+          recursive: true
+        });
+        const content = file.relativePath.endsWith(".md") ? (0, exports.injectGeneratedMarker)(file.content) : file.content;
+        await context.fileWriter.writeGeneratedFileRaw(path, content);
+      }
+    }
+  }
+};
+exports.generateAgentSkills = generateAgentSkills;

package/dist/pipeline/src/agentSkills/generateAgentSkills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateAgentSkills.js","sourceRoot":"","sources":["../../../../../pipeline/src/agentSkills/generateAgentSkills.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/src/agentSkills/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./shippedSkills";
+export * from "./generateAgentSkills";

package/dist/pipeline/src/agentSkills/index.js

@@ -0,0 +1,27 @@
+"use strict";
+
+var __createBinding = this && this.__createBinding || (Object.create ? function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  var desc = Object.getOwnPropertyDescriptor(m, k);
+  if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+    desc = {
+      enumerable: true,
+      get: function () {
+        return m[k];
+      }
+    };
+  }
+  Object.defineProperty(o, k2, desc);
+} : function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  o[k2] = m[k];
+});
+var __exportStar = this && this.__exportStar || function (m, exports) {
+  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+__exportStar(require("./types"), exports);
+__exportStar(require("./shippedSkills"), exports);
+__exportStar(require("./generateAgentSkills"), exports);

package/dist/pipeline/src/agentSkills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../pipeline/src/agentSkills/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,kDAAgC;AAChC,wDAAsC"}

package/dist/pipeline/src/agentSkills/shippedSkills.d.ts

@@ -0,0 +1,22 @@
+/**
+ * all catladder skills use this prefix; it marks the namespace
+ * catladder owns inside the agent skill directories (regeneration may
+ * remove stale `catladder-*` skills it generated earlier)
+ */
+export declare const AGENT_SKILL_PREFIX = "catladder-";
+export type ShippedSkill = {
+  /** the skill directory name, e.g. "catladder-config" */
+  name: string;
+  /** all files of the skill, relative to the skill directory */
+  files: Array<{
+    relativePath: string;
+    content: string;
+  }>;
+};
+/**
+ * the directory containing the agent skill definitions shipped with
+ * the package (copied into dist at build time; the repository layout
+ * is the fallback for development and tests)
+ */
+export declare const getShippedSkillsDir: () => string;
+export declare const getShippedSkills: () => ShippedSkill[];

package/dist/pipeline/src/agentSkills/shippedSkills.js

@@ -0,0 +1,56 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getShippedSkills = exports.getShippedSkillsDir = exports.AGENT_SKILL_PREFIX = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * all catladder skills use this prefix; it marks the namespace
+ * catladder owns inside the agent skill directories (regeneration may
+ * remove stale `catladder-*` skills it generated earlier)
+ */
+exports.AGENT_SKILL_PREFIX = "catladder-";
+/**
+ * the directory containing the agent skill definitions shipped with
+ * the package (copied into dist at build time; the repository layout
+ * is the fallback for development and tests)
+ */
+const getShippedSkillsDir = () => {
+  const candidates = [
+  // built pipeline package: dist/agentSkills -> dist/skills
+  // bundled cli package (what consumers install): the ncc bundles live
+  // in dist/bundles/<name>, so both resolve to dist/bundles/skills
+  (0, path_1.join)(__dirname, "..", "skills"),
+  // cli tsc dist (catenv-dev): dist/pipeline/src/agentSkills -> dist/skills
+  // repository: pipeline/src/agentSkills -> <root>/skills
+  (0, path_1.join)(__dirname, "..", "..", "..", "skills")];
+  const found = candidates.find(candidate => (0, fs_1.existsSync)(candidate));
+  if (!found) {
+    throw new Error("shipped agent skill definitions not found");
+  }
+  return found;
+};
+exports.getShippedSkillsDir = getShippedSkillsDir;
+const readFilesRecursively = (dir, relativeTo) => (0, fs_1.readdirSync)(dir).sort().flatMap(entry => {
+  const fullPath = (0, path_1.join)(dir, entry);
+  if ((0, fs_1.statSync)(fullPath).isDirectory()) {
+    return readFilesRecursively(fullPath, relativeTo);
+  }
+  return [{
+    relativePath: fullPath.slice(relativeTo.length + 1),
+    content: (0, fs_1.readFileSync)(fullPath, "utf-8")
+  }];
+});
+const getShippedSkills = () => {
+  const skillsDir = (0, exports.getShippedSkillsDir)();
+  return (0, fs_1.readdirSync)(skillsDir).sort().filter(entry => (0, fs_1.statSync)((0, path_1.join)(skillsDir, entry)).isDirectory()).map(name => {
+    const skillDir = (0, path_1.join)(skillsDir, name);
+    return {
+      name,
+      files: readFilesRecursively(skillDir, skillDir)
+    };
+  });
+};
+exports.getShippedSkills = getShippedSkills;

package/dist/pipeline/src/agentSkills/shippedSkills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shippedSkills.js","sourceRoot":"","sources":["../../../../../pipeline/src/agentSkills/shippedSkills.ts"],"names":[],"mappings":";;;AAAA,2BAAqE;AACrE,+BAA4B;AAE5B;;;;GAIG;AACU,QAAA,kBAAkB,GAAG,YAAY,CAAC;AAS/C;;;;GAIG;AACI,MAAM,mBAAmB,GAAG,GAAW,EAAE;IAC9C,MAAM,UAAU,GAAG;QACjB,0DAA0D;QAC1D,qEAAqE;QACrE,iEAAiE;QACjE,IAAA,WAAI,EAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC;QAC/B,0EAA0E;QAC1E,wDAAwD;QACxD,IAAA,WAAI,EAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC;KAC5C,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAA,eAAU,EAAC,SAAS,CAAC,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAfW,QAAA,mBAAmB,uBAe9B;AAEF,MAAM,oBAAoB,GAAG,CAC3B,GAAW,EACX,UAAkB,EACgC,EAAE,CACpD,IAAA,gBAAW,EAAC,GAAG,CAAC;KACb,IAAI,EAAE;KACN,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;IACjB,MAAM,QAAQ,GAAG,IAAA,WAAI,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClC,IAAI,IAAA,aAAQ,EAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACrC,OAAO,oBAAoB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACpD,CAAC;IACD,OAAO;QACL;YACE,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;YACnD,OAAO,EAAE,IAAA,iBAAY,EAAC,QAAQ,EAAE,OAAO,CAAC;SACzC;KACF,CAAC;AACJ,CAAC,CAAC,CAAC;AAEA,MAAM,gBAAgB,GAAG,GAAmB,EAAE;IACnD,MAAM,SAAS,GAAG,IAAA,2BAAmB,GAAE,CAAC;IACxC,OAAO,IAAA,gBAAW,EAAC,SAAS,CAAC;SAC1B,IAAI,EAAE;SACN,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAA,aAAQ,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SACjE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,QAAQ,GAAG,IAAA,WAAI,EAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;IACnE,CAAC,CAAC,CAAC;AACP,CAAC,CAAC;AATW,QAAA,gBAAgB,oBAS3B"}

package/dist/pipeline/src/agentSkills/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * where agent skills get materialized, per agent ecosystem:
+ * - claude-code: the Claude Code project skills directory
+ * - agents: the cross-agent universal skills directory
+ *   (https://agents.md convention, picked up by Cursor, Codex, ...)
+ */
+export declare const AGENT_SKILL_TARGET_DIRS: {
+  readonly "claude-code": ".claude/skills";
+  readonly agents: ".agents/skills";
+};
+export type AgentSkillTargetName = keyof typeof AGENT_SKILL_TARGET_DIRS;
+/**
+ * agent skills materialization, see {@link Config.agentSkills}
+ */
+export type AgentSkillsConfig = boolean | {
+  /**
+   * which agent skill directories to write to.
+   * Defaults to all known targets.
+   */
+  targets?: AgentSkillTargetName[];
+};
+export declare const getAgentSkillTargets: (agentSkills: AgentSkillsConfig | undefined) => AgentSkillTargetName[];

package/dist/pipeline/src/agentSkills/types.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getAgentSkillTargets = exports.AGENT_SKILL_TARGET_DIRS = void 0;
+/**
+ * where agent skills get materialized, per agent ecosystem:
+ * - claude-code: the Claude Code project skills directory
+ * - agents: the cross-agent universal skills directory
+ *   (https://agents.md convention, picked up by Cursor, Codex, ...)
+ */
+exports.AGENT_SKILL_TARGET_DIRS = {
+  "claude-code": ".claude/skills",
+  agents: ".agents/skills"
+};
+const getAgentSkillTargets = agentSkills => {
+  var _a;
+  if (agentSkills === false) return [];
+  if (agentSkills === true || agentSkills === undefined) {
+    return Object.keys(exports.AGENT_SKILL_TARGET_DIRS);
+  }
+  return (_a = agentSkills.targets) !== null && _a !== void 0 ? _a : Object.keys(exports.AGENT_SKILL_TARGET_DIRS);
+};
+exports.getAgentSkillTargets = getAgentSkillTargets;

package/dist/pipeline/src/agentSkills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../pipeline/src/agentSkills/types.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,uBAAuB,GAAG;IACrC,aAAa,EAAE,gBAAgB;IAC/B,MAAM,EAAE,gBAAgB;CAChB,CAAC;AAiBJ,MAAM,oBAAoB,GAAG,CAClC,WAA0C,EAClB,EAAE;;IAC1B,IAAI,WAAW,KAAK,KAAK;QAAE,OAAO,EAAE,CAAC;IACrC,IAAI,WAAW,KAAK,IAAI,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,MAAM,CAAC,IAAI,CAAC,+BAAuB,CAA2B,CAAC;IACxE,CAAC;IACD,OAAO,CACL,MAAA,WAAW,CAAC,OAAO,mCAClB,MAAM,CAAC,IAAI,CAAC,+BAAuB,CAA4B,CACjE,CAAC;AACJ,CAAC,CAAC;AAXW,QAAA,oBAAoB,wBAW/B"}

package/dist/pipeline/src/constants.js

@@ -4,5 +4,5 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.DOCKER_REGISTRY = exports.PIPELINE_IMAGE_TAG = void 0;
-exports.PIPELINE_IMAGE_TAG = "next-80fd0ab4" || "latest";
+exports.PIPELINE_IMAGE_TAG = "next-ebc933f2" || "latest";
 exports.DOCKER_REGISTRY = "git.panter.ch:5001/catladder/catladder" || "git.panter.ch:5001/catladder/catladder";

package/dist/pipeline/src/pipeline/generatePipelineFiles.js

@@ -10,6 +10,7 @@ const backends_1 = require("../backends");
 const gitlab_1 = require("../backends/gitlab");
 const jobImagesPlan_1 = require("../customImages/jobImagesPlan");
 const shippedCatci_1 = require("../catci/shippedCatci");
+const agentSkills_1 = require("../agentSkills");
 /**
  * generates the pipeline files of all pipeline types enabled in the
  * config (see `pipelines`). Pass an explicit `pipelineType` to generate
@@ -31,6 +32,9 @@ async function generatePipelineFiles(context, pipelineType) {
       recursive: true,
       force: true
     });
+    // agent skills are backend-independent, materialized once per full
+    // generation
+    await (0, agentSkills_1.generateAgentSkills)(context);
   }
   for (const type of pipelineTypes) {
     await generatePipelineFilesForBackend(context, (0, backends_1.getPipelineBackend)(type));

package/dist/pipeline/src/pipeline/generatePipelineFiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"generatePipelineFiles.js","sourceRoot":"","sources":["../../../../../pipeline/src/pipeline/generatePipelineFiles.ts"],"names":[],"mappings":";;;AAAA,0CAAwC;AACxC,+BAA+B;AAI/B,0CAA0E;AAC1E,+CAAmD;AAEnD,iEAAwE;AACxE,wDAA+D;AAE/D;;;;GAIG;AACI,KAAK,UAAU,qBAAqB,CACzC,OAAsB,EACtB,YAA2B;IAE3B,MAAM,aAAa,GAAG,YAAY;QAChC,CAAC,CAAC,CAAC,YAAY,CAAC;QAChB,CAAC,CAAC,IAAA,kCAAuB,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,oEAAoE;QACpE,kEAAkE;QAClE,oEAAoE;QACpE,0CAA0C;QAC1C,MAAM,IAAA,aAAE,EAAC,uCAAuB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,iEAAiE;QACjE,MAAM,IAAA,aAAE,EAAC,qCAAsB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,+BAA+B,CAAC,OAAO,EAAE,IAAA,6BAAkB,EAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AArBD,sDAqBC;AAED,KAAK,UAAU,+BAA+B,CAC5C,OAAsB,EACtB,OAAwB;IAExB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExD,4CAA4C;IAC5C,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACxB,cAAc;IACd,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QACpC,MAAM,IAAA,gBAAK,EAAC,IAAA,cAAO,EAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChE,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,yBAAyB,CAAC,MAAc;IAC5D,OAAO,IAAI,sBAAa,EAAE,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC5D,CAAC;AAFD,8DAEC"}
+{"version":3,"file":"generatePipelineFiles.js","sourceRoot":"","sources":["../../../../../pipeline/src/pipeline/generatePipelineFiles.ts"],"names":[],"mappings":";;;AAAA,0CAAwC;AACxC,+BAA+B;AAI/B,0CAA0E;AAC1E,+CAAmD;AAEnD,iEAAwE;AACxE,wDAA+D;AAC/D,gDAAqD;AAErD;;;;GAIG;AACI,KAAK,UAAU,qBAAqB,CACzC,OAAsB,EACtB,YAA2B;IAE3B,MAAM,aAAa,GAAG,YAAY;QAChC,CAAC,CAAC,CAAC,YAAY,CAAC;QAChB,CAAC,CAAC,IAAA,kCAAuB,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,oEAAoE;QACpE,kEAAkE;QAClE,oEAAoE;QACpE,0CAA0C;QAC1C,MAAM,IAAA,aAAE,EAAC,uCAAuB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,iEAAiE;QACjE,MAAM,IAAA,aAAE,EAAC,qCAAsB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,mEAAmE;QACnE,aAAa;QACb,MAAM,IAAA,iCAAmB,EAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,+BAA+B,CAAC,OAAO,EAAE,IAAA,6BAAkB,EAAC,IAAI,CAAC,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAxBD,sDAwBC;AAED,KAAK,UAAU,+BAA+B,CAC5C,OAAsB,EACtB,OAAwB;IAExB,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAExD,4CAA4C;IAC5C,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IACxB,cAAc;IACd,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QACpC,MAAM,IAAA,gBAAK,EAAC,IAAA,cAAO,EAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChE,CAAC;aAAM,CAAC;YACN,MAAM,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,yBAAyB,CAAC,MAAc;IAC5D,OAAO,IAAI,sBAAa,EAAE,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC5D,CAAC;AAFD,8DAEC"}

package/dist/pipeline/src/types/config.d.ts

@@ -8,6 +8,7 @@ import type { AgentConfig } from "./agent";
 import type { Hooks } from "./hooks";
 import type { ReleaseConfig } from "./release";
 import type { CatladderStore } from "../store";
+import type { AgentSkillsConfig } from "../agentSkills/types";
 import type { VerifyConfig } from "../verify/types";
 export declare const ALL_PIPELINE_TRIGGERS: readonly ["mainBranch", "mr", "taggedRelease"];
 export type PipelineTrigger = (typeof ALL_PIPELINE_TRIGGERS)[number];
@@ -254,6 +255,20 @@ export type Config<C extends ConfigProps = never> = {
    *   github, where the central registry is not reachable)
    */
   jobImages?: "central" | "repo";
+  /**
+   * materialize the agent skills shipped with catladder (usage guides
+   * for AI coding agents like Claude Code) into the repository, so
+   * agents working in the project use knowledge matching the installed
+   * catladder version. The skills are written on every generation into
+   * `catladder-*` directories under the agent skill folders (e.g.
+   * `.claude/skills/`) — that namespace is owned by catladder and must
+   * not be edited manually.
+   *
+   * - `true` (default): write to all known agent skill directories
+   * - `false`: opt out (previously generated skills are removed)
+   * - `{ targets: [...] }`: only write to the given targets
+   */
+  agentSkills?: AgentSkillsConfig;
   /**
    * name of the customer or group
    */

package/dist/pipeline/src/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAaa,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAGX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEX;;;;GAIG;AACI,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAE,EAAE,CAC/D,MAAM,CAAC,OAAO,CAAC,iBAAS,CAAC;KACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,CAAC,CAAC,QAAuC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC7D;KACA,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAY,CAAC,CAAC;AALnB,QAAA,oBAAoB,wBAKD;AAEnB,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAca,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAGX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEX;;;;GAIG;AACI,MAAM,oBAAoB,GAAG,CAAC,OAAwB,EAAE,EAAE,CAC/D,MAAM,CAAC,OAAO,CAAC,iBAAS,CAAC;KACtB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CACf,CAAC,CAAC,QAAuC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC7D;KACA,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAY,CAAC,CAAC;AALnB,QAAA,oBAAoB,wBAKD;AAEnB,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB"}

package/dist/skills/catladder-cli/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: catladder-cli
+description: How to invoke the catladder CLI non-interactively — command structure, passing inputs via flags or --inputs JSON, skipping prompts, and the full generated command reference. Use when running any `catladder` command (project setup, doctor, secrets, k8s, ci, cloudsql, mongo) or when unsure which catladder command exists for a task. Triggers on "catladder command", "yarn catladder", "project doctor", "project setup", "run catladder".
+---
+
+# Using the catladder CLI
+
+catladder is installed per project — invoke it as `yarn catladder`
+(never a globally installed copy). Every command can run
+non-interactively, which is the mode agents should use.
+
+## Invocation
+
+```sh
+yarn catladder <command...> [args] [flags]
+
+# examples
+yarn catladder project doctor
+yarn catladder project ci job-log
+yarn catladder --help                 # command tree
+yarn catladder project --help         # subcommands of a group
+```
+
+## Passing inputs
+
+Commands declare typed inputs. Any input not provided on the command
+line is prompted for interactively — in a non-interactive context
+(agents!) provide them up front:
+
+- positional inputs: `yarn catladder project k8s list-pods dev:api`
+- flag per input: `--some-input value` (kebab-case of the input name),
+  booleans as `--flag` / `--no-flag`
+- all at once as JSON: `--inputs '{"envComponent": "dev:api"}'`
+- `-y` / `--yes` skips confirmation prompts
+
+A missing required input fails with a message naming the exact flag to
+pass. Environment/component selectors use the `env:component` form
+(e.g. `dev:api`, `review-123:www`).
+
+Some commands are inherently interactive (e.g.
+`project config-secrets` opens `$EDITOR`) — ask the user to run those.
+
+## Command reference
+
+See [references/commands.md](references/commands.md) for all commands
+with their descriptions and inputs (generated from the CLI itself, so
+it matches the installed version).
+
+## Related skills
+
+- `catladder-config` — catladder.ts structure and regeneration
+- `catladder-secrets` — env vars and secret management
+- `catladder-pipelines` — pipeline behavior and CI debugging

package/dist/skills/catladder-cli/references/commands.md

@@ -0,0 +1,273 @@
+# catladder CLI command reference
+
+<!-- rendered from the command definitions by
+     cli/src/scripts/generateCliSkillReference.ts — do not edit -->
+
+All commands run non-interactively as `yarn catladder <command> ...`;
+see SKILL.md for how to pass inputs.
+
+## `catladder cloudsql restore-db`
+
+restore a db from one source to another target
+
+- `--source <value>`: Source instance (connection string or 'local')?
+- `--source-local-port <value>`: Local Port for source? (default: 5432)
+- `--source-username <value>`: Source Username? (default: "postgres")
+- `--source-password <value>`: Source Password?
+- `--source-db-name <value>`: Source DB name?
+- `--target <value>`: Target INSTANCE (connection string or 'local')?
+- `--target-local-port <value>`: Local Port for target? (default: 5432)
+- `--target-username <value>`: Target Username? (default: "postgres")
+- `--target-password <value>`: Target Password?
+- `--target-db-name <value>`: Target DB name?
+
+## `catladder fun dadjoke`
+
+something for jonas.
+
+## `catladder fun starwars`
+
+Long time ago... in a galaxy far far away...
+
+## `catladder k8s current-context`
+
+show current kubernetes context
+
+## `catladder k8s get-shell [namespace]`
+
+get a shell to a pod in the environment
+
+- `namespace` (positional): kubernetes namespace
+- `--pod-name <value>`: Which pod?
+
+## `catladder k8s list-namespaces`
+
+list all namespaces
+
+## `catladder k8s list-pods [namespace]`
+
+list all pods of namespace
+
+- `namespace` (positional): kubernetes namespace
+
+## `catladder k8s list-secrets [namespace]`
+
+show secrets
+
+- `namespace` (positional): kubernetes namespace
+
+## `catladder k8s port-forward [namespace]`
+
+start port-forwarding
+
+- `namespace` (positional): kubernetes namespace
+- `--pod-name <value>`: Which pod?
+- `--local-port <value>`: Local port:
+- `--remote-port <value>`: Remote port:
+
+## `catladder k8s stop-portforward [name]`
+
+stop a running port forward
+
+- `name` (positional): port forward name
+
+## `catladder k8s trigger-cronjob [namespace]`
+
+trigger cronjob
+
+- `namespace` (positional): kubernetes namespace
+- `--job-name <value>`: Which cronjob?
+
+## `catladder project ci job-log`
+
+Show a job's log
+
+- `--job-name <value>`: Which job?
+
+## `catladder project ci job-open`
+
+Open a Job
+
+- `--job-name <value>`: Which job?
+
+## `catladder project cloudsql proxy [envComponent]`
+
+proxy to cloud sql db
+
+- `envComponent` (positional): environment:component
+- `--local-port <value>`: Local port: (default: 54320)
+
+## `catladder project cloudsql restore-db`
+
+restores a project db from one source to another target
+
+- `--source <value>`: Source instance?
+- `--target <value>`: target env?
+- `--confirm-instance <value>`: confirm:
+
+## `catladder project config-secrets [envComponent]`
+
+setup/update secrets stored in pass
+
+- `envComponent` (positional): environment:component
+
+## `catladder project doctor [component]`
+
+Checks for drift between the config and the provisioned infrastructure (read-only): service accounts, IAM roles, gitlab tokens, github secrets, store entries.
+
+- `component` (positional): component name
+
+## `catladder project env-vars [envComponent]`
+
+list env vars
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s delete [envComponent]`
+
+deletes a environment of a project (it deletes the namespace)
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s delete-pods [envComponent]`
+
+delete / restart pods
+
+- `envComponent` (positional): environment:component
+- `--selected-pod-names <value>`: Which pods to delete / restart ?
+
+## `catladder project k8s get-shell [envComponent]`
+
+get a shell to a pod in the environment
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+
+## `catladder project k8s list-pods [envComponent]`
+
+list pods of local project
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s namespace [envComponent]`
+
+show namespace of local project
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s pause [envComponent]`
+
+halts all running pods (scales to 0)
+
+- `envComponent` (positional): environment:component
+
+## `catladder project k8s trigger-cronjob [envComponent]`
+
+trigger cronjob
+
+- `envComponent` (positional): environment:component
+- `--job-name <value>`: Which cronjob?
+
+## `catladder project logs open [envComponent]`
+
+open logs for a component (Google Cloud Logging)
+
+- `envComponent` (positional): environment:component
+
+## `catladder project mongo destroy-member [envComponent]`
+
+DESTROY a member of a replicaset in order to reinitialize it
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+
+## `catladder project mongo get-shell [envComponent]`
+
+get a shell to a mongodb in the environment
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+
+## `catladder project mongo port-forward [envComponent]`
+
+port forward to a mongodb
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+- `--local-port <value>`: Local port: (default: 30000)
+
+## `catladder project open env [envComponent]`
+
+open the live environment
+
+- `envComponent` (positional): environment:component
+
+## `catladder project open git`
+
+open the repo on gitlab / github in your browser
+
+## `catladder project port-forward [envComponent]`
+
+start port-forwarding
+
+- `envComponent` (positional): environment:component
+- `--pod-name <value>`: Which pod?
+- `--local-port <value>`: Local port:
+- `--remote-port <value>`: Remote port:
+- `--mr <value>`: Which mr
+
+## `catladder project renew-token`
+
+Configures the project access token for semantic release.
+
+## `catladder project secrets-clear-backups`
+
+clears all backups
+
+- `--keep <value>`: How many backups should we keep? (default: 1)
+
+## `catladder project secrets-sync-github [repo] [env]`
+
+copies all secrets from the vault to github repo secrets (same names), for the github pipeline
+
+- `repo` (positional): github repository (owner/name)
+- `env` (positional): only sync these environments (comma-separated, e.g. review,dev) — github allows at most 100 repo secrets
+
+## `catladder project security-evaluate`
+
+evaluate project's security audit document
+
+## `catladder project setup [component]`
+
+Initializes all environments and creates required resources, service accounts, etc.
+
+- `component` (positional): component name
+
+## `catladder project worktime`
+
+show the total worktime that you spent on a project
+
+## `catladder security audit ci-job [path] [token] [mainBranch] [projectId] [userId]`
+
+Evaluates security audit document. Creates MR with template if missing.
+
+- `path` (positional): path to project root
+- `token` (positional): GitLab token (api scope)
+- `mainBranch` (positional): main branch name
+- `projectId` (positional): GitLab project ID
+- `userId` (positional): GitLab user ID (assignee)
+
+## `catladder security audit create [token] [mainBranch] [projectId] [userId]`
+
+Creates a MR with the latest security audit template document
+
+- `token` (positional): GitLab token (api scope)
+- `mainBranch` (positional): main branch name
+- `projectId` (positional): GitLab project ID
+- `userId` (positional): GitLab user ID (assignee)
+
+## `catladder security audit evaluate [path]`
+
+Evaluates security audit document in given path
+
+- `path` (positional): path to project root