@daldindev/agentic-skills 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-05
+
+### Added
+
+- `agentic-skills sync`: installs when the target is missing and updates when it is already there, so one command covers both states. It is the command for a `postinstall` hook, a CI step, or a container build, where the run cannot stop to ask which state it is in. Local edits are preserved as with `update`; `--force` overwrites them, so exit code 2 cannot happen.
+
+### Changed
+
+- The note about a missing manifest is printed only when files were actually skipped, and now appears for every command rather than only `update`.
+- The error `init` raises on a non-empty target points at `sync` for unattended runs.
+
 ## [0.1.0] - 2026-09-03
 
 ### Added

package/README.md

@@ -31,7 +31,7 @@ npx agentic-skills init
 Requirements:
 
 - Node.js `>=20.11`
-- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init` or `update`
+- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init`, `update`, or `sync`
 
 ## Quick Start
 
@@ -55,6 +55,7 @@ Point your assistant at `.agents/ARCHITECTURE.md`. It lists every component with
 | --- | --- |
 | `agentic-skills init` | Download ag-kit and install the content. Refuses a non-empty target unless `--force` |
 | `agentic-skills update` | Download ag-kit again and update installed files, keeping the ones you edited |
+| `agentic-skills sync` | Install if missing, update if present. One command that works in both states, for unattended runs |
 | `agentic-skills status` | Show what is installed, from which upstream commit, and which files were changed locally |
 
 | Option | Purpose |
@@ -92,6 +93,28 @@ To stay on a known upstream state instead of `main`, pass a tag or commit. The s
 npx @daldindev/agentic-skills update --ref v2026.8.31
 ```
 
+### Unattended runs
+
+`sync` reconciles the install against upstream whatever state it is in: it creates the directory when it is missing and updates it when it is already there. Nothing has to be known about the target beforehand, which is what makes it the command to put where no one is watching — a `postinstall` hook, a CI step, a container build:
+
+```json
+{
+  "scripts": {
+    "postinstall": "agentic-skills sync"
+  }
+}
+```
+
+Every `npm i` then brings the install to the current upstream, on a fresh clone and on a checkout that already has the content alike.
+
+Your edits survive it: a file you changed is kept, listed, and the command exits `2`. Reach for `--force` only when the install is a derived tree your project regenerates and never edits by hand, `.agents/` in `.gitignore` for instance:
+
+```bash
+agentic-skills sync --force
+```
+
+Copying that second line into a project where `.agents/` is committed means losing an edited skill on every `npm i`, silently. And `--force` only removes exit `2`: a download that cannot reach GitHub still exits `1`.
+
 ## What gets installed
 
 | Upstream path | Installed as |
@@ -127,6 +150,7 @@ In scope:
 - Downloading the upstream roles, skills, and workflows and installing them anywhere
 - Updating an install while preserving local edits
 - Recording upstream provenance with every install
+- Running unattended, from a postinstall hook or a CI step, with one command that works in either state
 
 Out of scope:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daldindev/agentic-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install the ag-kit agent roles, skills, and workflows into any project, for any model and any agent harness.",
   "author": "daldindev",
   "license": "MIT",

package/src/cli.mjs

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { PACKAGE_ROOT, readJson } from "./fs-utils.mjs";
-import { DEFAULT_INSTALL_DIR, init, status, update } from "./install.mjs";
+import { DEFAULT_INSTALL_DIR, init, status, sync, update } from "./install.mjs";
 import { UPSTREAM, extractPort, loadArchive, materialize } from "./upstream.mjs";
 
 const HELP = `agentic-skills - install the ag-kit agent roles, skills, and workflows into any project
@@ -12,6 +12,7 @@ const HELP = `agentic-skills - install the ag-kit agent roles, skills, and workf
 Usage:
   agentic-skills init    [options]   Download ag-kit and install the content into <path>/<dir>
   agentic-skills update  [options]   Download ag-kit again and update installed files, preserving local edits
+  agentic-skills sync    [options]   Install if missing, update if present; safe to run unattended
   agentic-skills status  [options]   Show what is installed and which files were changed locally
 
 Options:
@@ -100,10 +101,10 @@ const printPlan = (result) => {
   );
   list("Skipped (modified locally; use --force to overwrite)", plan.skip, (item) => `${item.file}: ${item.reason}`);
   list("Kept (removed upstream but modified locally)", plan.keep, (item) => `${item.file}: ${item.reason}`);
-  if (result.mode === "update" && result.hadManifest === false) {
+  if (result.hadManifest === false && plan.skip.length) {
     console.log("\nNo manifest was found, so files that differ from upstream were skipped. Re-run with --force to overwrite them.");
   }
-  if (result.mode === "init" && !result.dryRun) {
+  if (result.created && !result.dryRun) {
     console.log(`\nPoint your assistant at ${path.join(result.installDir, "ARCHITECTURE.md")} to get the inventory.`);
   }
 };
@@ -133,7 +134,7 @@ try {
     console.log(pkg.version);
   } else if (values.help || !command || command === "help") {
     process.stdout.write(HELP);
-  } else if (command === "init" || command === "update") {
+  } else if (command === "init" || command === "update" || command === "sync") {
     const incoming = await fetchIncoming();
     try {
       const options = {
@@ -144,7 +145,8 @@ try {
         incomingDir: incoming.dir,
         upstream: incoming.upstream,
       };
-      const result = command === "init" ? await init(options) : await update(options);
+      const run = { init, update, sync }[command];
+      const result = await run(options);
       if (values.json) console.log(JSON.stringify(result, null, 2));
       else printPlan(result);
       if (result.plan.skip.length || result.plan.keep.length) process.exitCode = 2;

package/src/install.mjs

@@ -120,49 +120,64 @@ async function hasContent(dir) {
   return entries.length > 0;
 }
 
-export async function init(options = {}) {
+/**
+ * Plan against the incoming tree, apply it, and record the manifest.
+ * The three commands differ only in the preconditions they enforce first.
+ */
+async function reconcile(mode, options) {
   const { installDir } = resolveTarget(options);
   const { incomingDir, upstream = null } = options;
-  const force = Boolean(options.force);
-
-  if (!force && (await hasContent(installDir))) {
-    throw new Error(
-      `${installDir} already exists and is not empty. Run "agentic-skills update" to update it, ` +
-      "or pass --force to overwrite managed files in place.",
-    );
-  }
 
+  const created = !(await hasContent(installDir));
   const manifest = await loadManifest(installDir);
-  const plan = await planUpdate({ installDir, incomingDir, manifest, force });
+  const plan = await planUpdate({ installDir, incomingDir, manifest, force: Boolean(options.force) });
   if (!options.dryRun) {
     await applyPlan({ installDir, incomingDir, plan });
     await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
   }
-  return { mode: "init", installDir, plan, upstream, dryRun: Boolean(options.dryRun) };
+  return {
+    mode,
+    installDir,
+    plan,
+    upstream,
+    created,
+    hadManifest: Boolean(manifest),
+    dryRun: Boolean(options.dryRun),
+  };
+}
+
+export async function init(options = {}) {
+  const { installDir } = resolveTarget(options);
+
+  if (!options.force && (await hasContent(installDir))) {
+    throw new Error(
+      `${installDir} already exists and is not empty. Run "agentic-skills update" to update it, ` +
+      '"agentic-skills sync" if this runs unattended, or pass --force to overwrite managed files in place.',
+    );
+  }
+
+  return reconcile("init", options);
 }
 
 export async function update(options = {}) {
   const { installDir } = resolveTarget(options);
-  const { incomingDir, upstream = null } = options;
 
   if (!(await exists(installDir))) {
     throw new Error(`${installDir} does not exist. Run "agentic-skills init" first.`);
   }
 
-  const manifest = await loadManifest(installDir);
-  const plan = await planUpdate({ installDir, incomingDir, manifest, force: Boolean(options.force) });
-  if (!options.dryRun) {
-    await applyPlan({ installDir, incomingDir, plan });
-    await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
-  }
-  return {
-    mode: "update",
-    installDir,
-    plan,
-    upstream,
-    hadManifest: Boolean(manifest),
-    dryRun: Boolean(options.dryRun),
-  };
+  return reconcile("update", options);
+}
+
+/**
+ * Reconcile whatever state the target is in: install it when missing, update it
+ * when it is already there. Neither precondition applies, so this is the command
+ * to run unattended - a postinstall, a CI step, a container build - where one
+ * line has to work on a fresh clone and on an existing tree alike. Local edits
+ * are preserved exactly as with update, and --force overwrites them.
+ */
+export async function sync(options = {}) {
+  return reconcile("sync", options);
 }
 
 /** Local report only; nothing is fetched. */