fellow-agents 0.0.16 → 0.0.18

package/dist/commands/start.js

@@ -100,10 +100,13 @@ export async function start(opts) {
     if (skillResult.written.length > 0) {
         console.log(`  Installed ${skillResult.written.length} skill file(s)`);
     }
+    if (skillResult.refreshed.length > 0) {
+        console.log(`  Refreshed ${skillResult.refreshed.length} skill file(s) to latest`);
+    }
     if (skillResult.skipped.length > 0) {
-        console.log(`  Preserved ${skillResult.skipped.length} existing skill file(s) — delete to refresh`);
+        console.log(`  Preserved ${skillResult.skipped.length} existing skill file(s) — customized or unowned`);
     }
-    if (skillResult.written.length === 0 && skillResult.skipped.length === 0) {
+    if (skillResult.written.length === 0 && skillResult.refreshed.length === 0 && skillResult.skipped.length === 0) {
         console.log("  No skills bundled");
     }
     // PATH trick: prepend bin dir so agents find emcom/tracker

package/dist/lib/skills.js

@@ -1,6 +1,7 @@
-import { existsSync, readdirSync, mkdirSync, copyFileSync, readFileSync, statSync, rmSync, rmdirSync } from "fs";
+import { existsSync, readdirSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, statSync, rmSync, rmdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { createHash } from "crypto";
 import { skillsDir } from "./paths.js";
 // Three target paths per agentskills.io convention — installed CLIs vary; we write to all three
 // so the skill works regardless of which AI CLI the user is using.
@@ -9,15 +10,24 @@ const targetRoots = [
     join(homedir(), ".copilot", "skills"), // GitHub Copilot CLI
     join(homedir(), ".agents", "skills"), // pi + cross-tool universal location
 ];
+// Sidecar suffix — written next to each shipped file, contains the SHA-256 of
+// the content we shipped. Used to detect "we wrote this, user hasn't touched"
+// vs "user customized" on later installs and uninstall.
+const SIDECAR_SUFFIX = ".fellow-agents-shipped";
 /**
  * Copy bundled skills to all known target paths.
  *
- * Strategy: write if absent. Never overwrite existing files (treated as
- * user-customized). To force a refresh, the user can delete the target file
- * and re-run fellow-agents.
+ * Update semantics (v0.0.18+):
+ * - Target absent: write file + sidecar.
+ * - Target has sidecar AND target SHA matches sidecar: we own it, user hasn't
+ *   modified — safe to refresh with new content. Write file + update sidecar.
+ * - Target has sidecar AND target SHA differs from sidecar: user edited our
+ *   shipped file. Preserve, don't touch sidecar.
+ * - Target exists with NO sidecar: pre-existing file (pre-v0.0.18 install, or
+ *   user-placed). Preserve — we can't prove we own it.
  */
 export function installSkills() {
-    const result = { written: [], skipped: [] };
+    const result = { written: [], refreshed: [], skipped: [] };
     if (!existsSync(skillsDir))
         return result;
     const skillNames = readdirSync(skillsDir).filter((name) => {
@@ -33,16 +43,42 @@ export function installSkills() {
         const skillFiles = walkSkillFiles(sourceSkillDir);
         for (const relPath of skillFiles) {
             const sourceFile = join(sourceSkillDir, relPath);
+            const sourceSha = sha256File(sourceFile);
             for (const root of targetRoots) {
                 const targetFile = join(root, skillName, relPath);
-                if (existsSync(targetFile)) {
-                    // User-customized or already-installed — never overwrite
+                const sidecarFile = targetFile + SIDECAR_SUFFIX;
+                if (!existsSync(targetFile)) {
+                    // First-time install
+                    mkdirSync(join(root, skillName, ...relPath.split(/[\\/]/).slice(0, -1)), { recursive: true });
+                    copyFileSync(sourceFile, targetFile);
+                    writeFileSync(sidecarFile, sourceSha, "utf-8");
+                    result.written.push(targetFile);
+                    continue;
+                }
+                // Target exists — decide based on sidecar
+                if (!existsSync(sidecarFile)) {
+                    // No sidecar → we can't prove we own this file, preserve
                     result.skipped.push(targetFile);
                     continue;
                 }
-                mkdirSync(join(root, skillName, ...relPath.split(/[\\/]/).slice(0, -1)), { recursive: true });
-                copyFileSync(sourceFile, targetFile);
-                result.written.push(targetFile);
+                const recordedSha = readFileSync(sidecarFile, "utf-8").trim();
+                const currentSha = sha256File(targetFile);
+                if (currentSha === recordedSha) {
+                    // Target matches what we previously shipped → user hasn't touched → safe refresh
+                    if (currentSha === sourceSha) {
+                        // Same shipped version, nothing to do
+                        result.skipped.push(targetFile);
+                    }
+                    else {
+                        copyFileSync(sourceFile, targetFile);
+                        writeFileSync(sidecarFile, sourceSha, "utf-8");
+                        result.refreshed.push(targetFile);
+                    }
+                }
+                else {
+                    // User edited the file after we shipped it — preserve
+                    result.skipped.push(targetFile);
+                }
             }
         }
     }
@@ -51,13 +87,15 @@ export function installSkills() {
 /**
  * Remove skill files we installed, if the user hasn't modified them.
  *
- * Compares each target file byte-for-byte against the bundled version.
- * Matching → safe to delete (we wrote it, nothing changed). Differing →
- * preserve (user customized or it was already there before we showed up).
+ * Sidecar-based ownership detection (v0.0.18+):
+ * - Target has sidecar AND target SHA matches sidecar → we own it, user
+ *   hasn't touched → delete file + sidecar.
+ * - Target has sidecar AND target SHA differs → user customized → preserve
+ *   (file and sidecar).
+ * - Target has no sidecar → we can't prove we own it → preserve.
  *
  * After file removal, attempts to clean up empty skill directories and
- * empty target root directories (e.g., ~/.copilot/skills/ if user doesn't
- * have Copilot installed).
+ * empty target root directories.
  */
 export function uninstallSkills() {
     const result = { removed: [], preserved: [] };
@@ -79,15 +117,21 @@ export function uninstallSkills() {
             if (!existsSync(targetSkillDir))
                 continue;
             for (const relPath of skillFiles) {
-                const sourceFile = join(sourceSkillDir, relPath);
                 const targetFile = join(targetSkillDir, relPath);
+                const sidecarFile = targetFile + SIDECAR_SUFFIX;
                 if (!existsSync(targetFile))
                     continue;
+                if (!existsSync(sidecarFile)) {
+                    // No sidecar — can't prove ownership, preserve
+                    result.preserved.push(targetFile);
+                    continue;
+                }
                 try {
-                    const sourceBytes = readFileSync(sourceFile);
-                    const targetBytes = readFileSync(targetFile);
-                    if (Buffer.compare(sourceBytes, targetBytes) === 0) {
+                    const recordedSha = readFileSync(sidecarFile, "utf-8").trim();
+                    const currentSha = sha256File(targetFile);
+                    if (currentSha === recordedSha) {
                         rmSync(targetFile);
+                        rmSync(sidecarFile);
                         result.removed.push(targetFile);
                     }
                     else {
@@ -95,18 +139,18 @@ export function uninstallSkills() {
                     }
                 }
                 catch {
-                    // Can't read either file — skip, don't risk data loss
                     result.preserved.push(targetFile);
                 }
             }
-            // Try to remove empty skill dir (best effort — won't remove if user has
-            // their own files in there or any preserved files remain)
             tryRemoveIfEmpty(targetSkillDir);
             tryRemoveIfEmpty(root);
         }
     }
     return result;
 }
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
 function tryRemoveIfEmpty(dir) {
     try {
         if (existsSync(dir) && readdirSync(dir).length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fellow-agents",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Multi-agent system — multiple Claude Code instances collaborating via messaging",
   "type": "module",
   "bin": {

package/skills/emcom/SKILL.md

@@ -111,11 +111,9 @@ Don't reply blind to in-flight work. A short delay to read the thread first prev
 emcom <subcommand> [args]
 ```
 
-If `emcom` is not in PATH, the binary lives at one of:
-- `~/.claude/skills/emcom/bin/emcom` (Claude Code skill install)
-- `~/.copilot/skills/emcom/bin/emcom` (GitHub Copilot skill install)
-- `~/.agents/skills/emcom/bin/emcom` (pi / universal skill install)
-- Or whatever PATH was set up by `npm install -g fellow-agents`
+`emcom` is on PATH when fellow-agents has been installed (`npm install -g fellow-agents`) — the npm-created shim wraps `~/.fellow-agents/bin/<platform>/emcom`. **Use the bare command. Do not prepend any skills-directory path.**
+
+If a CLI environment can't find `emcom` on PATH, that means fellow-agents isn't installed (or its bin shim hasn't been picked up by the shell). Tell the user to run `npm install -g fellow-agents` rather than guessing at a skill-bundled path — fellow-agents does not ship binaries inside `~/.claude/skills/`, `~/.copilot/skills/`, or `~/.agents/skills/`.
 
 **Permission-friendly invocation** (matters in some CLIs that gate command execution):