passalong 0.3.1 → 0.3.2

package/README.md

@@ -48,6 +48,7 @@ passalong team join <link>    accept an invite
 passalong team use <slug>     switch the current team
 passalong setup               install the Claude Code capture skill + register the MCP server
 passalong mcp                 run the MCP server over stdio
+passalong version             print the installed version (also -v, --version)
 ```
 
 ## Teams

package/bin/passalong

@@ -30,6 +30,7 @@
 //   passalong team use <slug>     switch the current team
 //   passalong setup               install the Claude Code capture skill + register the MCP server
 //   passalong mcp                 run the MCP server over stdio
+//   passalong version             print the installed version (also -v, --version)
 import { execFileSync, spawnSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -490,5 +491,11 @@ const commands = {
 
 const argv = flags(process.argv.slice(2));
 const cmd = argv._.shift() || "help";
-if (cmd === "--help" || cmd === "-h" || !commands[cmd]) commands.help();
+// The first thing anyone runs when something is off, and until now it printed the help page. The
+// parser only knows `--x`, so `--version` arrives as a flag on an empty command and `-v` as a word;
+// both are caught here, with `version`, before dispatch. Only the number goes to stdout, so
+// `passalong -v` can be read by a script comparing it against the registry.
+if (cmd === "-v" || cmd === "version" || (cmd === "help" && argv.version === true)) {
+  console.log(JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version);
+} else if (cmd === "--help" || cmd === "-h" || !commands[cmd]) commands.help();
 else await commands[cmd](argv).catch((e) => die(e.message));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",

package/skill/SKILL.md

@@ -33,6 +33,13 @@ session's history. Write for execution, not for permanence.
    team"), add `--to <team>` or `--to <team>/<handle>`; `passalong team` lists the current
    team's members and their handles. It prints the guide id on stdout and the share link (and
    who it was handed to) on stderr.
+
+   **If this session started from a passalong guide** — you ran `passalong start` or `pull` on an
+   id, or an agent opened one — and what you are capturing is what doing it taught you, add
+   `--follows <that id>`. The original then lists this one as a follow-up. That is the case when
+   you departed from it: changed or skipped a Step, adapted an `ASSUMES` for this stack, found the
+   fix a failing guide did not have, or hit a Gotcha it does not list. If it worked exactly as
+   written there is nothing to capture — say so with `passalong works <id>` instead.
 6. **Report** the id (and link if synced) and one line on how to use it on the other side:
    `passalong start <id>` in the target repo, or "start passalong <id>" to an agent with the
    Passalong MCP server. `start` rather than `pull` on purpose: it takes the handoff as well as

package/src/mcp.js

@@ -95,7 +95,13 @@ export async function serve() {
         "shows whether the guides they handed off have landed. When the user asks what they have " +
         "been working on, or wants a standup or a summary of a period, call log — but say that it " +
         "holds what they passed along and not everything they did. Gotchas are " +
-        "the highest-value section: record what failed and why.",
+        "the highest-value section: record what failed and why.\n" +
+        "A FOLLOW-UP IS A GUIDE, NOT A NOTE. When you worked from a guide and departed from it — " +
+        "changed or skipped a Step, adapted an ASSUMES for this stack, found the fix a failing " +
+        "guide did not have, or hit a Gotcha it does not list — publish what you learned as its " +
+        "own guide with publish_guide `parent` set to that guide's id; the original then lists it " +
+        "as a follow-up. If it worked exactly as written, do not: answer with verify_guide, or " +
+        "every guide collects copies that say nothing new.",
     },
   );
 
@@ -223,7 +229,10 @@ export async function serve() {
       description:
         "After following a guide's Verification section, report the result. This is the only way " +
         "the author learns their handoff did not land — `set_guide_status consumed` says it was " +
-        "implemented, this says it actually works. A failing verdict must say what went wrong.",
+        "implemented, this says it actually works. A failing verdict must say what went wrong. " +
+        "If doing it taught you something the guide did not say — a flag it needed, a step that " +
+        "was wrong for this stack — publish that as its own guide with publish_guide `parent` set " +
+        "to this id. The author sees it as a follow-up; a verdict note is one line and gets lost.",
       inputSchema: {
         id: z.string().describe("passalong id"),
         ok: z.boolean().describe("true if the Verification steps passed"),
@@ -307,7 +316,8 @@ export async function serve() {
         const siblings = await related(meta);
         return text(
           `${lead}${r.markdown}${siblings}` +
-            `\n\n<!-- passalong: ${r.from}; written to ${r.path}; ${took} -->`,
+            `\n\n<!-- passalong: ${r.from}; written to ${r.path}; ${took} -->` +
+            `\n${passalong.followUpNote(meta)}`,
         );
       } catch (err) {
         return fail(err);
@@ -356,7 +366,8 @@ export async function serve() {
         return text(
           `${lead}${markdown}${siblings}` +
             `\n\n<!-- passalong: ${from}; written to ${path} -->` +
-            `\n${passalong.handoffNudge(meta)}`,
+            `\n${passalong.handoffNudge(meta)}` +
+            `\n${passalong.followUpNote(meta)}`,
         );
       } catch (err) {
         return fail(err);

package/src/passalong.js

@@ -296,6 +296,33 @@ export async function attach(file, { name = "" } = {}) {
   return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
 }
 
+/**
+ * The line a guide arrives with, saying when what you do next deserves to be a guide of its own.
+ *
+ * Trailing, like the handoff nudge, so it never sits in front of the frontmatter. It is here and
+ * not only in the server's instructions because an agent reads the payload it is working from and
+ * skims everything else — the same reason the bug lead is inside the document.
+ *
+ * It says when *not* to as well. A follow-up for a guide that worked exactly as written is a copy
+ * that says nothing new, and a guide collecting those is worse than one with none; that answer is a
+ * verdict. For a bug the question is different — nothing to depart from, but a fix worth repeating
+ * elsewhere is a transfer guide, and the bug is where it came from.
+ */
+export function followUpNote(meta = {}) {
+  if (!meta.id) return "";
+  if (meta.kind === "bug")
+    return (
+      "<!-- passalong: once this is fixed, if the fix is worth repeating somewhere else, publish " +
+      `it as a transfer guide with publish_guide parent=${meta.id} so this bug lists it. -->`
+    );
+  return (
+    "<!-- passalong: if you depart from this guide — change or skip a Step, adapt an ASSUMES for " +
+    "this stack, find a fix it did not have, hit a Gotcha it does not list — publish what you " +
+    `learned as its own guide with publish_guide parent=${meta.id}. If it worked exactly as ` +
+    "written, answer with verify_guide instead. -->"
+  );
+}
+
 /** Local guides merged with synced ones (by id), newest first, optionally filtered. */
 export async function list(query = "", { remote = true, scope = "" } = {}) {
   const local = scope && scope !== "all" && scope !== "mine" ? [] : store.search(query);