@slamb2k/mad-skills 2.0.57 → 2.0.59

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mad-skills",
   "description": "AI-assisted planning, development and governance tools",
-  "version": "2.0.57",
+  "version": "2.0.59",
   "author": {
     "name": "slamb2k",
     "url": "https://github.com/slamb2k"

package/hooks/hooks.json

@@ -4,7 +4,7 @@
       "matcher": "startup|clear|compact",
       "hooks": [
         { "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; node \"$_R/hooks/session-guard.cjs\" check", "timeout": 30 },
-        { "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; bash \"$_R/skills/handover/scripts/handover.sh\" load", "timeout": 10 }
+        { "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; bash \"$_R/skills/ferry/scripts/ferry.sh\" load", "timeout": 10 }
       ]
     }],
     "UserPromptSubmit": [{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slamb2k/mad-skills",
-  "version": "2.0.57",
+  "version": "2.0.59",
   "description": "Claude Code skills collection — full lifecycle development tools",
   "type": "module",
   "repository": {

package/skills/build/SKILL.md

@@ -93,7 +93,7 @@ Before starting, check all dependencies in this table:
 | feature-dev:code-architect | agent | — | no | fallback | Uses general-purpose agent |
 | feature-dev:code-reviewer | agent | — | no | fallback | Uses general-purpose agent |
 | superpowers | plugin | on-disk glob via scripts/lib/superpowers.js | no | fallback | Routes Stage 4 impl core to superpowers:executing-plans / subagent-driven-development when present; see references/superpowers-deferral.md |
-| handover | skill | `ls .claude/skills/handover/SKILL.md ~/.claude/skills/handover/SKILL.md ~/.claude/plugins/marketplaces/slamb2k/skills/handover/SKILL.md 2>/dev/null` | no | fallback | Powers the "hand off to a clean session" execution mode; ships with mad-skills, so normally present |
+| ferry | skill | `ls .claude/skills/ferry/SKILL.md ~/.claude/skills/ferry/SKILL.md ~/.claude/plugins/marketplaces/slamb2k/skills/ferry/SKILL.md 2>/dev/null` | no | fallback | Powers the "hand off to a clean session" execution mode; ships with mad-skills, so normally present |
 
 For each row, in order:
 1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
@@ -208,19 +208,20 @@ So there is exactly one execution-mode decision, and subagents are always on
 underneath either choice:
 
 - **Run here now** — orchestrate the build in this session, stages in subagents.
-- **Hand off to a clean session** — write a handover, arm the resume signal, and
-  let a fresh session run the *same* `/build` with its own subagents.
+- **Hand off to a clean session** — ferry the state across (write a waybill),
+  arm the resume signal, and let a fresh session run the *same* `/build` with its
+  own subagents.
 
 These are mutually exclusive — one stops here, one continues here. Do **not**
-offer a "clear? yes/no" toggle on top of run-now; the handover mode *replaces*
+offer a "clear? yes/no" toggle on top of run-now; the hand-off mode *replaces*
 the run-now decision.
 
 **Resolve the mode:**
 
 1. If `--no-handoff` → run here now. Skip to Stage 1.
-2. If `--handoff` → hand off (only if the handover skill exists; else warn it's
+2. If `--handoff` → hand off (only if the `ferry` skill exists; else warn it's
    unavailable and run here now).
-3. If the handover skill is **not** installed (pre-flight) → run here now
+3. If the `ferry` skill is **not** installed (pre-flight) → run here now
    silently. No question.
 4. Otherwise, decide whether to *offer* the hand-off at all. Only offer it when a
    clean start would actually help **and** the plan can survive the reset:
@@ -229,9 +230,9 @@ the run-now decision.
      orchestrator would start bloated. A fresh `/build` invocation in an empty
      session does not need this — just run here now.
    - **Plan is self-contained** — PLAN is a spec file or a complete written plan
-     that a handover doc can capture losslessly. If the plan leans on nuance from
-     *this* conversation (decisions made live, things looked at together), a
-     handover is lossy — prefer run-here-now so that context isn't thrown away.
+     that a waybill can capture losslessly. If the plan leans on nuance from
+     *this* conversation (decisions made live, things looked at together), the
+     waybill is lossy — prefer run-here-now so that context isn't thrown away.
 
    If **both** hold, ask via `AskUserQuestion`:
    ```
@@ -245,11 +246,11 @@ the run-now decision.
    If either condition fails, don't ask — run here now.
 
 **If handing off:** capture the resolved PLAN and any Stage-2 clarifications
-gathered so far, then invoke the `handover` skill. The handover document's
+gathered so far, then invoke the `ferry` skill. The waybill's
 "next steps" MUST be a single resume action: re-run this exact build in the
 fresh session, e.g. `/build {original PLAN argument}` (plus any active flags,
 minus `--handoff`). Include the resolved plan content and PROJECT_CONFIG so the
-fresh session doesn't re-derive them. The handover skill arms the one-shot
+fresh session doesn't re-derive them. The `ferry` skill arms the one-shot
 signal and tells the user to `/clear`. **Stop here** — do not run Stage 1; the
 fresh session does.
 

package/skills/{handover → ferry}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: handover
-description: Persist a session handover document and signal the next fresh session to resume from it. Use when the user types /handover, says they want to hand off, checkpoint, wrap up, clear context, or start fresh while preserving state, or asks to carry work into a new session with clean optimised context. Captures everything a brand-new session needs — task, status, next steps, key files, decisions, gotchas, git state — writes it to disk, arms a one-shot signal, and tells the user to /clear so the next session auto-loads it.
+name: ferry
+description: Ferry a session's live state across a context reset — persist a waybill document and signal the next fresh session to resume from it. Use when the user types /ferry, says they want to hand off, checkpoint, wrap up, clear context, or start fresh while preserving state, or asks to carry work into a new session with clean optimised context. Captures everything a brand-new session needs — task, status, next steps, key files, decisions, gotchas, git state — writes it to disk as waybill.md, arms a one-shot signal, and tells the user to /clear so the next session auto-loads it.
 argument-hint: repo, tmp, commit (optional target; default repo)
 allowed-tools: Bash, Read, Write
 ---
 
-# Handover - Clean-Context Session Handoff
+# Ferry - Clean-Context Session Handoff
 
 When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
 Pick ONE tagline at random — vary your choice each time.
@@ -14,45 +14,46 @@ CRITICAL: Reproduce the banner EXACTLY character-for-character, preserving all l
 ```
 {tagline}
 
-██╗  ██╗ █████╗ ███╗   ██╗██████╗  ██████╗ ██╗   ██╗███████╗██████╗
-██║  ██║██╔══██╗████╗  ██║██╔══██╗██╔═══██╗██║   ██║██╔════╝██╔══██╗
-███████║███████║██╔██╗ ██║██║  ██║██║   ██║██║   ██║█████╗  ██████╔╝
-██╔══██║██╔══██║██║╚██╗██║██║  ██║██║   ██║╚██╗ ██╔╝██╔══╝  ██╔══██╗
-██║  ██║██║  ██║██║ ╚████║██████╔╝╚██████╔╝ ╚████╔╝ ███████╗██║  ██║
-╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝  ╚═════╝   ╚═══╝  ╚══════╝╚═╝  ╚═╝
+███████╗███████╗██████╗ ██████╗ ██╗   ██╗
+██╔════╝██╔════╝██╔══██╗██╔══██╗╚██╗ ██╔╝
+█████╗  █████╗  ██████╔╝██████╔╝ ╚████╔╝
+██╔══╝  ██╔══╝  ██╔══██╗██╔══██╗  ╚██╔╝
+██║     ███████╗██║  ██║██║  ██║   ██║
+╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝
 ```
 
 Taglines:
-- 🪂 Packing the parachute for a clean landing...
-- 🧳 Bagging up the context, checking out...
-- 🤝 Passing the baton to a fresh runner!
-- 📦 Boxing up everything the next session needs!
-- 🧹 Clearing the desk, leaving a tidy note!
-- 🛟 Nobody loses the thread on my watch!
-- 🌅 Fresh session, same mission!
+- 📋 Filing the waybill for the crossing...
+- 🧳 All aboard — carrying the context across!
+- 🤝 Passing the waybill to a fresh crew!
+- 📋 Waybill stamped, casting off to a clean session!
+- 🌊 Ferrying the thread over calm water!
+- 🛟 Nobody's work goes overboard on my watch!
+- 🌅 New session on the far shore, same voyage!
 
 ---
 
 ## What this does
 
-Capture the live state of this session into a handover document, arm a one-shot
-signal, and hand the user off to a clean session that will automatically resume
-from the document. The point is to **reset the context window without losing the
-thread** — the next session starts lean but fully briefed.
+Ferry the live state of this session across a context reset: capture it into a
+**waybill document** (`waybill.md`), arm a one-shot signal, and hand the user off to
+a clean session that will automatically resume from the waybill. The point is to
+**reset the context window without losing the thread** — the next session starts
+lean but fully briefed.
 
 Long sessions accumulate noise: dead ends, superseded plans, stale file reads. A
 fresh session is faster and sharper, but naively starting over loses hard-won
-context. `/handover` distills only what the *next* session needs, persists it, and
-signals that session to pick it up — once. It will not re-read old handovers on
+context. `/ferry` distills only what the *next* session needs, persists it, and
+signals that session to pick it up — once. It will not re-read old waybill on
 unrelated future sessions, because the signal is consumed on first read.
 
 ## Usage
 
 ```
-/handover            # default: HANDOVER.md in repo root, kept OUT of git
-/handover repo       # same as default (explicit)
-/handover tmp        # write under /tmp — never touches the repo at all
-/handover commit     # write docs/handovers/HANDOVER-<timestamp>.md, meant to be committed
+/ferry            # default: waybill.md in repo root, kept OUT of git
+/ferry repo       # same as default (explicit)
+/ferry tmp        # write under /tmp — never touches the repo at all
+/ferry commit     # write docs/ferry/waybill-<timestamp>.md, meant to be committed
 ```
 
 Read the argument from what the user typed. If none given, use `repo`.
@@ -87,24 +88,24 @@ date +%Y-%m-%d-%H%M
 
 Then pick the path based on the argument:
 
-- **`repo`** (default): `<repo_root>/HANDOVER.md`. If not inside a git repo, use the
+- **`repo`** (default): `<repo_root>/waybill.md`. If not inside a git repo, use the
   current working directory instead. After writing, keep it out of version control
-  by appending `HANDOVER.md` to `<repo_root>/.git/info/exclude` if it's a git repo
+  by appending `waybill.md` to `<repo_root>/.git/info/exclude` if it's a git repo
   and not already listed there. This is a *local* ignore — it never modifies the
   tracked `.gitignore`, so it won't show up in anyone else's checkout or your diffs.
-- **`tmp`**: `/tmp/claude-handover/<key>/HANDOVER.md` where `<key>` is
+- **`tmp`**: `/tmp/claude-ferry/<key>/waybill.md` where `<key>` is
   `printf '%s' "$(pwd)" | cksum | cut -d' ' -f1`. Create the directory first.
   Nothing is written inside the repo.
-- **`commit`**: `<repo_root>/docs/handovers/HANDOVER-<timestamp>.md`. Create the
-  `docs/handovers/` directory if needed. Do **not** ignore it — this variant exists
-  precisely so the handover lands in git history as a durable checkpoint. Mention to
+- **`commit`**: `<repo_root>/docs/ferry/waybill-<timestamp>.md`. Create the
+  `docs/ferry/` directory if needed. Do **not** ignore it — this variant exists
+  precisely so the waybill lands in git history as a durable checkpoint. Mention to
   the user that they'll want to commit it.
 
-### 2. Write the handover document
+### 2. Write the waybill document
 
 This is the core of the skill — the document quality determines whether the next
 session is productive or lost. Follow the structure in
-`references/handover-template.md`. Read that file now if you haven't.
+`references/waybill-template.md`. Read that file now if you haven't.
 
 Fill it from the **actual conversation and repo state**, not generic boilerplate.
 Be concrete: real file paths, real function names, real commands, real decisions.
@@ -128,22 +129,22 @@ dead end is a genuine landmine worth a warning.
 After the document is written, run (using the `PLUGIN_ROOT` resolved in pre-flight):
 
 ```bash
-bash "$PLUGIN_ROOT/skills/handover/scripts/handover.sh" signal "<absolute_path_to_handover>"
+bash "$PLUGIN_ROOT/skills/ferry/scripts/ferry.sh" signal "<absolute_path_to_waybill>"
 ```
 
 This drops a signal keyed to the current project directory. The next session's
 `SessionStart` hook — shipped with this plugin in `hooks/hooks.json` — detects it,
-injects the handover as context, and deletes the signal so it fires exactly once.
+injects the waybill as context, and deletes the signal so it fires exactly once.
 Use the **absolute** path.
 
 ### 4. Hand off to a fresh session
 
-Tell the user plainly that the handover is ready and they should start the fresh
+Tell the user plainly that the waybill is ready and they should start the fresh
 session themselves. You **cannot** trigger `/clear` programmatically — it is a
 user-only command — so the final step is theirs. Say something like:
 
-> Handover written to `<path>` and the next session is armed. Type **`/clear`**
-> (or **`/new`**) now — the fresh session will automatically load this handover and
+> Waybill written to `<path>` and the next session is armed. Type **`/clear`**
+> (or **`/new`**) now — the fresh session will automatically load this waybill and
 > pick up where we left off. Nothing else gets auto-loaded; the signal is consumed
 > on first read.
 
@@ -155,10 +156,10 @@ need to take.
 - **`/clear` is the user's to type.** No skill, hook, or command can clear the
   context window automatically. Always end by asking them to do it.
 - **The signal is one-shot and project-scoped.** It's keyed to the working
-  directory and deleted on first read, so handovers never leak into unrelated
-  sessions. A `HANDOVER.md` left sitting in a repo is inert unless re-armed.
+  directory and deleted on first read, so waybill never leaks into unrelated
+  sessions. A `waybill.md` left sitting in a repo is inert unless re-armed.
 - **Don't pollute git by default.** Only the `commit` variant is meant to be
   tracked. `repo` mode relies on `.git/info/exclude`; `tmp` mode stays entirely
   outside the repo.
-- **If `/handover` is run again later**, overwrite the existing document and
+- **If `/ferry` is run again later**, overwrite the existing document and
   re-arm the signal — the latest state wins.

package/skills/{handover/references/handover-template.md → ferry/references/waybill-template.md}

@@ -1,4 +1,4 @@
-# Handover document template
+# Waybill document template
 
 Fill every section that applies. Drop sections that genuinely don't (e.g. no open
 questions). Lead with what unblocks action; a fresh session should be able to make
@@ -6,12 +6,12 @@ its **next move within the first minute** of reading this.
 
 Write concretely. "Fix the bug in the parser" is useless; "`parseImportFile()` in
 `src/import.js:42` throws on empty `days` — needs a guard before the `Object.entries`
-loop" is a handover. Prefer absolute or repo-relative file paths with line numbers.
+loop" is waybill worth carrying. Prefer absolute or repo-relative file paths with line numbers.
 
 ---
 
 ```markdown
-# Handover — <short task title>
+# Waybill — <short task title>
 
 **Date:** <YYYY-MM-DD HH:MM>  ·  **Branch:** <git branch>  ·  **Repo:** <path>
 
@@ -83,7 +83,7 @@ ticket numbers, people involved.
   think it works but didn't check, say "assumed — not yet run". A fresh session has
   no way to tell otherwise and false confidence is expensive.
 - **Link, don't paste:** point to files and line ranges rather than dumping large
-  code blocks. The next session can read them on demand; bloating the handover just
+  code blocks. The next session can read them on demand; bloating the waybill just
   refills the context window you're trying to clear.
 - **Keep it skimmable:** headers, short bullets, code spans for paths/commands. A
   wall of prose defeats the purpose.

package/skills/{handover/scripts/handover.sh → ferry/scripts/ferry.sh}

@@ -1,21 +1,21 @@
 #!/usr/bin/env bash
-# handover.sh — companion to the `handover` skill.
+# ferry.sh — companion to the `ferry` skill.
 #
-#   handover.sh signal <abs_handover_path> [cwd]
+#   ferry.sh signal <abs_waybill_path> [cwd]
 #       Drop a one-shot signal keyed to the current project (cwd) pointing at
-#       the handover document. The next session's SessionStart hook consumes it.
+#       the waybill document. The next session's SessionStart hook consumes it.
 #
-#   handover.sh load
+#   ferry.sh load
 #       SessionStart hook entrypoint. Reads the event JSON on stdin; if a signal
-#       exists for this cwd, emits the handover as additionalContext and deletes
-#       the signal (one-shot — a stale HANDOVER.md is never re-injected).
+#       exists for this cwd, emits the waybill as additionalContext and deletes
+#       the signal (one-shot — a stale waybill.md is never re-injected).
 #
 # The signal is keyed on the working directory, NOT the session id, because the
 # session id changes after /clear. cwd is stable across a clear, so the fresh
 # session finds the signal its predecessor left.
 set -euo pipefail
 
-SIGNAL_DIR="/tmp/claude-handover"
+SIGNAL_DIR="/tmp/claude-ferry"
 
 _key() {
   # Stable, dependency-free hash of a directory path. cksum is POSIX.
@@ -26,12 +26,12 @@ cmd="${1:-load}"
 
 case "$cmd" in
   signal)
-    handover_path="${2:?usage: handover.sh signal <abs_handover_path> [cwd]}"
+    waybill_path="${2:?usage: ferry.sh signal <abs_waybill_path> [cwd]}"
     cwd="${3:-$(pwd)}"
     mkdir -p "$SIGNAL_DIR"
     key="$(_key "$cwd")"
-    printf '%s\n' "$handover_path" > "$SIGNAL_DIR/$key.signal"
-    printf 'handover: signal armed for %s -> %s\n' "$cwd" "$handover_path"
+    printf '%s\n' "$waybill_path" > "$SIGNAL_DIR/$key.signal"
+    printf 'ferry: signal armed for %s -> %s\n' "$cwd" "$waybill_path"
     ;;
 
   load)
@@ -46,14 +46,14 @@ case "$cmd" in
 
     key="$(_key "$cwd")"
     signal="$SIGNAL_DIR/$key.signal"
-    [ -f "$signal" ] || exit 0          # no handover pending — silent no-op
+    [ -f "$signal" ] || exit 0          # no waybill pending — silent no-op
 
-    handover_path="$(head -n1 "$signal")"
+    waybill_path="$(head -n1 "$signal")"
     rm -f "$signal"                      # one-shot: consume the signal
-    [ -f "$handover_path" ] || exit 0    # document vanished — nothing to inject
+    [ -f "$waybill_path" ] || exit 0    # document vanished — nothing to inject
 
-    content="$(cat "$handover_path")"
-    preamble="The previous session left a handover document at ${handover_path} and signalled that this session should resume from it. Treat it as your primary context for continuing the work. Read any files it references before acting. This is one-shot: do not seek out or re-read handover documents in future sessions unless signalled again."
+    content="$(cat "$waybill_path")"
+    preamble="The previous session left a waybill document at ${waybill_path} and signalled that this session should resume from it. Treat it as your primary context for continuing the work. Read any files it references before acting. This is one-shot: do not seek out or re-read waybill documents in future sessions unless signalled again."
 
     if command -v jq >/dev/null 2>&1; then
       jq -n --arg pre "$preamble" --arg body "$content" \
@@ -65,7 +65,7 @@ case "$cmd" in
     ;;
 
   *)
-    printf 'handover.sh: unknown command "%s" (expected: signal | load)\n' "$cmd" >&2
+    printf 'ferry.sh: unknown command "%s" (expected: signal | load)\n' "$cmd" >&2
     exit 1
     ;;
 esac

package/skills/{handover → ferry}/tests/evals.json

@@ -1,20 +1,20 @@
 {
-  "skill": "handover",
+  "skill": "ferry",
   "cases": [
     {
       "name": "explicit slash invocation",
-      "prompt": "/handover",
-      "expect_skill": "handover",
+      "prompt": "/ferry",
+      "expect_skill": "ferry",
       "assertions": [
-        "Writes a handover document to HANDOVER.md in the repo root by default",
-        "Arms the one-shot signal via scripts/handover.sh signal with an absolute path",
+        "Writes a waybill document to waybill.md in the repo root by default",
+        "Arms the one-shot signal via scripts/ferry.sh signal with an absolute path",
         "Tells the user to type /clear to start the fresh session themselves"
       ]
     },
     {
       "name": "natural language wrap-up",
       "prompt": "Let's wrap up and start fresh with a clean context window without losing where we are.",
-      "expect_skill": "handover",
+      "expect_skill": "ferry",
       "assertions": [
         "Recognizes the intent to reset context while preserving state",
         "Captures task, status, next steps, key files, decisions, and git state",
@@ -23,10 +23,10 @@
     },
     {
       "name": "committed checkpoint variant",
-      "prompt": "/handover commit",
-      "expect_skill": "handover",
+      "prompt": "/ferry commit",
+      "expect_skill": "ferry",
       "assertions": [
-        "Writes to docs/handovers/HANDOVER-<timestamp>.md instead of the ignored repo-root file",
+        "Writes to docs/ferry/waybill-<timestamp>.md instead of the ignored repo-root file",
         "Does not add the file to .git/info/exclude",
         "Notes the user will want to commit the checkpoint"
       ]

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "generated": "2026-07-07T07:32:19.484Z",
+  "generated": "2026-07-07T11:12:00.649Z",
   "count": 13,
   "skills": [
     {
@@ -16,7 +16,7 @@
       "name": "build",
       "directory": "build",
       "description": "Context-isolated feature development pipeline. Takes a detailed design/plan as argument and executes the full feature-dev lifecycle (explore, question, architect, implement, review, ship) inside subagents so the primary conversation stays compact. Use when you have a well-defined plan and want autonomous execution with minimal context window consumption.",
-      "lines": 532,
+      "lines": 533,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -43,10 +43,10 @@
       "hasTests": true
     },
     {
-      "name": "handover",
-      "directory": "handover",
-      "description": "Persist a session handover document and signal the next fresh session to resume from it. Use when the user types /handover, says they want to hand off, checkpoint, wrap up, clear context, or start fresh while preserving state, or asks to carry work into a new session with clean optimised context. Captures everything a brand-new session needs — task, status, next steps, key files, decisions, gotchas, git state — writes it to disk, arms a one-shot signal, and tells the user to /clear so the next session auto-loads it.",
-      "lines": 165,
+      "name": "ferry",
+      "directory": "ferry",
+      "description": "Ferry a session's live state across a context reset — persist a waybill document and signal the next fresh session to resume from it. Use when the user types /ferry, says they want to hand off, checkpoint, wrap up, clear context, or start fresh while preserving state, or asks to carry work into a new session with clean optimised context. Captures everything a brand-new session needs — task, status, next steps, key files, decisions, gotchas, git state — writes it to disk as waybill.md, arms a one-shot signal, and tells the user to /clear so the next session auto-loads it.",
+      "lines": 166,
       "hasScripts": true,
       "hasReferences": true,
       "hasAssets": false,