@slamb2k/mad-skills 2.0.56 → 2.0.57

package/.claude-plugin/plugin.json

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

package/hooks/hooks.json

@@ -2,7 +2,10 @@
   "hooks": {
     "SessionStart": [{
       "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 }]
+      "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 }
+      ]
     }],
     "UserPromptSubmit": [{
       "hooks": [{ "type": "command", "command": "_R=\"${CLAUDE_PLUGIN_ROOT}\"; [ -z \"$_R\" ] && _R=\"$HOME/.claude/plugins/marketplaces/slamb2k\"; node \"$_R/hooks/session-guard.cjs\" remind", "timeout": 10 }]

package/package.json

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

package/skills/build/SKILL.md

@@ -76,6 +76,8 @@ Parse optional flags from the request:
 - `--no-ship`: Stop after Stage 8 docs update
 - `--parallel-impl`: Split implementation into parallel agents when independent
 - `--no-superpowers`: Force the standalone pipeline even when Superpowers is installed
+- `--handoff`: Skip the execution-mode question and hand off to a clean session
+- `--no-handoff`: Skip the execution-mode question and run here now
 
 ---
 
@@ -91,6 +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 |
 
 For each row, in order:
 1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
@@ -193,6 +196,67 @@ Before starting Stage 1, verify the working tree is suitable for building:
 
 ---
 
+## Execution Mode
+
+`/build` runs every heavy stage in subagents, so the primary conversation stays
+compact *during* the build. The one thing subagents can't fix is a context
+window that's **already** large when you invoke `/build` — the orchestrator
+(this thread) still reads reports and runs the review/ship loop on top of
+whatever came before. For that, a clean start beats a clean middle.
+
+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.
+
+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*
+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
+   unavailable and run here now).
+3. If the handover 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:
+   - **Context already large** — this session has had substantial prior work
+     before `/build` (long conversation, many file reads, a prior task), so the
+     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.
+
+   If **both** hold, ask via `AskUserQuestion`:
+   ```
+   "This session already carries significant context. Hand this build off to a
+   clean session, or run it here now?"
+   ```
+   Options:
+   - **"Run here now (Recommended)"** — orchestrate in this session (subagents underneath).
+   - **"Hand off to a clean session"** — reset context, resume the build fresh.
+
+   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
+"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
+signal and tells the user to `/clear`. **Stop here** — do not run Stage 1; the
+fresh session does.
+
+**If running here now:** continue to Stage 1 unchanged.
+
+---
+
 ## Stage 1: Explore
 
 Launch **feature-dev:code-explorer** (fallback: general-purpose):

package/skills/handover/SKILL.md

@@ -0,0 +1,164 @@
+---
+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.
+argument-hint: repo, tmp, commit (optional target; default repo)
+allowed-tools: Bash, Read, Write
+---
+
+# Handover - 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.
+CRITICAL: Reproduce the banner EXACTLY character-for-character, preserving all leading spaces.
+
+```
+{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!
+
+---
+
+## 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.
+
+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
+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
+```
+
+Read the argument from what the user typed. If none given, use `repo`.
+
+## Pre-flight
+
+Before starting, check dependencies:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| git | cli | `git rev-parse --show-toplevel` | no | fallback | Not in a git repo → use cwd for `repo` mode; skip `.git/info/exclude` step |
+| jq | cli | `command -v jq` | no | fallback | Signal loader falls back to sed + raw-stdout injection; no behavior change |
+
+Resolve the plugin root once for the signal command:
+
+```bash
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/slamb2k}"
+```
+
+## What to do
+
+Work through these steps in order. Don't skip the verification at the end.
+
+### 1. Resolve the target path
+
+First get the repo root and a timestamp:
+
+```bash
+git rev-parse --show-toplevel 2>/dev/null   # repo root, or empty if not a git repo
+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
+  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
+  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
+  `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
+  the user that they'll want to commit it.
+
+### 2. Write the handover 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.
+
+Fill it from the **actual conversation and repo state**, not generic boilerplate.
+Be concrete: real file paths, real function names, real commands, real decisions.
+Write for a competent engineer who has *zero* memory of this session — every
+assumption in your head right now is invisible to them unless you write it down.
+
+Gather git state to embed in the document:
+
+```bash
+git -C <repo_root> branch --show-current
+git -C <repo_root> status --short
+git -C <repo_root> log --oneline -8
+```
+
+Optimise for *their* context budget: include what unblocks action, link to files
+rather than pasting large code, and cut the narrative of how you got here unless a
+dead end is a genuine landmine worth a warning.
+
+### 3. Arm the one-shot signal
+
+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>"
+```
+
+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.
+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
+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
+> pick up where we left off. Nothing else gets auto-loaded; the signal is consumed
+> on first read.
+
+Keep this final message short. The work is done; don't bury the one action they
+need to take.
+
+## Important constraints
+
+- **`/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.
+- **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
+  re-arm the signal — the latest state wins.

package/skills/handover/references/handover-template.md

@@ -0,0 +1,89 @@
+# Handover 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
+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.
+
+---
+
+```markdown
+# Handover — <short task title>
+
+**Date:** <YYYY-MM-DD HH:MM>  ·  **Branch:** <git branch>  ·  **Repo:** <path>
+
+## TL;DR
+One or two sentences: what we're doing and what the very next action is.
+
+## Goal / definition of done
+The north star. What does "finished" look like? Include acceptance criteria or
+the user's original ask in their words if it matters.
+
+## Current status
+What's done and working (verified vs assumed — say which). What's the state of the
+tree right now. If something is half-built, say exactly how far it got.
+
+## Next steps
+Ordered, concrete, actionable. The first item should be immediately doable.
+1. ...
+2. ...
+
+## Key files & entry points
+The map. Where the relevant code lives and what each piece does.
+- `path/to/file.ext:line` — what it is / why it matters
+- ...
+
+## Key decisions & rationale
+Choices already made that the next session must respect, and *why* — so it doesn't
+unknowingly relitigate or contradict them.
+- Decided X because Y. Alternative Z was rejected because ...
+
+## Gotchas, dead ends & landmines
+Things that wasted time or will bite again. Approaches already tried that DON'T
+work (so the next session doesn't repeat them). Environment quirks, flaky steps,
+ordering constraints.
+- Tried A → failed because B. Don't retry without addressing B.
+- Watch out for ...
+
+## How to build / test / run
+Exact commands. The next session shouldn't have to rediscover these.
+- Build: `...`
+- Test: `...`
+- Run / verify: `...`
+
+## Open questions & assumptions
+Unresolved decisions awaiting the user, and assumptions made that might be wrong.
+Flag anything the user still needs to answer.
+- [ ] Question: ... (suggested default: ...)
+- Assumption: ... (if wrong, then ...)
+
+## Git state
+- Branch: <branch>  (tracking <remote/branch> or "local-only")
+- Uncommitted changes: <summary of `git status --short`, or "clean">
+- Recent commits:
+  ```
+  <git log --oneline -8>
+  ```
+
+## Context the next session can't infer
+Anything important that isn't in the code, git history, or CLAUDE.md — the stuff
+living only in this conversation. External constraints, user preferences expressed
+mid-session, credentials/access notes (reference, don't paste secrets), URLs,
+ticket numbers, people involved.
+```
+
+---
+
+## Filling guidance
+
+- **Verified vs assumed:** if you ran the test and it passed, say "verified". If you
+  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
+  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

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# handover.sh — companion to the `handover` skill.
+#
+#   handover.sh signal <abs_handover_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.
+#
+#   handover.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).
+#
+# 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"
+
+_key() {
+  # Stable, dependency-free hash of a directory path. cksum is POSIX.
+  printf '%s' "$1" | cksum | cut -d' ' -f1
+}
+
+cmd="${1:-load}"
+
+case "$cmd" in
+  signal)
+    handover_path="${2:?usage: handover.sh signal <abs_handover_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"
+    ;;
+
+  load)
+    input="$(cat)"
+
+    if command -v jq >/dev/null 2>&1; then
+      cwd="$(printf '%s' "$input" | jq -r '.cwd // empty')"
+    else
+      cwd="$(printf '%s' "$input" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)"
+    fi
+    [ -n "$cwd" ] || cwd="$(pwd)"
+
+    key="$(_key "$cwd")"
+    signal="$SIGNAL_DIR/$key.signal"
+    [ -f "$signal" ] || exit 0          # no handover pending — silent no-op
+
+    handover_path="$(head -n1 "$signal")"
+    rm -f "$signal"                      # one-shot: consume the signal
+    [ -f "$handover_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."
+
+    if command -v jq >/dev/null 2>&1; then
+      jq -n --arg pre "$preamble" --arg body "$content" \
+        '{hookSpecificOutput:{hookEventName:"SessionStart", additionalContext:($pre + "\n\n---\n\n" + $body)}}'
+    else
+      # Fallback: SessionStart adds raw stdout to context too.
+      printf '%s\n\n---\n\n%s\n' "$preamble" "$content"
+    fi
+    ;;
+
+  *)
+    printf 'handover.sh: unknown command "%s" (expected: signal | load)\n' "$cmd" >&2
+    exit 1
+    ;;
+esac

package/skills/handover/tests/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "handover",
+  "cases": [
+    {
+      "name": "explicit slash invocation",
+      "prompt": "/handover",
+      "expect_skill": "handover",
+      "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",
+        "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",
+      "assertions": [
+        "Recognizes the intent to reset context while preserving state",
+        "Captures task, status, next steps, key files, decisions, and git state",
+        "Does not attempt to run /clear itself — leaves that to the user"
+      ]
+    },
+    {
+      "name": "committed checkpoint variant",
+      "prompt": "/handover commit",
+      "expect_skill": "handover",
+      "assertions": [
+        "Writes to docs/handovers/HANDOVER-<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/hoist/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: hoist
+description: >-
+  Generate secure, low-infrastructure release pipelines that publish artifacts
+  directly — language packages (npm, PyPI, crates, RubyGems, NuGet, Go), GitHub
+  Releases with binaries, static sites/Pages, or serverless functions — without
+  building a container image. OIDC/trusted publishing, provenance, idempotent
+  publish guards, and three trigger models (auto-bump with optional approval,
+  tag, manual). The non-container sibling of /dock. Use when releasing a package
+  or app that doesn't ship as a container.
+argument-hint: "--skip-interview, --dry-run, --registry <name>"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, Agent
+---
+
+# Hoist - Non-Container Release Pipelines
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading characters (one invisible braille-blank + 3 spaces) — you MUST preserve them.
+
+```
+{tagline}
+
+⠀   ██╗██╗  ██╗ ██████╗ ██╗███████╗████████╗
+   ██╔╝██║  ██║██╔═══██╗██║██╔════╝╚══██╔══╝
+  ██╔╝ ███████║██║   ██║██║███████╗   ██║
+ ██╔╝  ██╔══██║██║   ██║██║╚════██║   ██║
+██╔╝   ██║  ██║╚██████╔╝██║███████║   ██║
+╚═╝    ╚═╝  ╚═╝ ╚═════╝ ╚═╝╚══════╝   ╚═╝
+```
+
+Taglines:
+- 📦 Up and away — published!
+- 🏗️ Hoisting your release skyward!
+- 🚀 From main to registry in one pull!
+- 🪝 Latched on, lifting off!
+- ⬆️ Straight to the top shelf!
+- 🎁 Wrapped, signed, and shipped!
+- 🛎️ Release, served fresh!
+- 🔖 Tag it and bag it!
+
+## Flags
+- `--skip-interview`: detected + platform-aware defaults
+- `--dry-run`: show generated files without writing
+- `--registry <name>`: force the target registry
+
+## Output Formatting
+(Input box, Pre-flight table, stage headers, status icons — copy the conventions
+from skills/dock/SKILL.md.)
+
+## Pre-flight
+6-column dependency table: git (required, stop), gh (optional for GitHub release
+ops), sync (optional skill, fallback git pull), node/language toolchain (optional,
+detected). Follow the resolution-strategy list format used by other skills.
+
+## Platform Detection
+Detect github vs azdo from the remote URL (same block as skills/dock/SKILL.md).
+
+## Phase 0: Sync
+Invoke /sync (fallback git pull).
+
+## Phase 1: Detection
+Explore subagent using references/interview-guide.md#detection-prompt → DETECTION_REPORT.
+
+## Phase 2: Interview
+Follow references/interview-guide.md#interview-questions. Compile HOIST_CONFIG
+(target, registry/host, trigger model, approval gate, signing).
+
+## Phase 3: Generate
+Read references/release-templates.md and references/hardening.md. Emit the CI
+workflow for the detected target + chosen trigger (secure by default: id-token,
+provenance, idempotent publish guard, concurrency; token exceptions per
+hardening.md). For binaries, add SHA256SUMS + optional signing. Generate
+deploy/SETUP.md from references/setup-guides.md.
+
+## Phase 4: Verify
+Validate workflow YAML. Confirm the generated workflow carries the required
+hardening for its target (OIDC/`id-token: write` or a flagged token secret;
+provenance where supported; the version-exists guard; publish-before-tag).
+--dry-run previews without writing.
+
+## Final Report
+Box report with target, trigger model, generated files, and a 🔐 Required setup
+section pointing at deploy/SETUP.md.
+
+## Integration
+Complements /dock (containers) — pick whichever fits. Runs after /rig; /ship's
+merge can trigger the generated auto-bump release. Only the serverless target may
+reference /keel for cloud identity.

package/skills/hoist/references/hardening.md

@@ -0,0 +1,62 @@
+# Release Hardening Reference
+
+How `/hoist` hardens the release pipelines it generates. Same ethos as `/dock`,
+translated from container promotion to artifact publishing. Secure by default.
+
+## Trusted Publishing (OIDC)
+
+Publish with the CI provider's OIDC identity instead of a stored token, wherever
+the registry supports it:
+
+- **npm** — `permissions: id-token: write` + `npm publish --provenance`. Configure
+  the package's trusted publisher on npmjs.com (repo + workflow). No `NODE_AUTH_TOKEN`.
+- **PyPI** — `pypa/gh-action-pypi-publish` with `id-token: write`; configure a
+  PyPI trusted publisher. No API token.
+- **RubyGems** — trusted publishing via OIDC; configure on rubygems.org.
+- **GitHub Pages** — `id-token: write` + `actions/deploy-pages`.
+- **AWS Lambda** — `aws-actions/configure-aws-credentials` with `role-to-assume`
+  (GitHub OIDC → IAM role). No access keys.
+
+Azure Pipelines uses a **Workload Identity Federation service connection**
+(`azureSubscription`) where cloud auth is needed.
+
+## Provenance & Attestation
+
+- npm: `--provenance` (SLSA provenance attestation).
+- PyPI: `gh-action-pypi-publish` emits attestations by default.
+- Binaries: generate SLSA build provenance and attach it to the release.
+
+## Idempotent Publish Guard
+
+Publish is **check-then-act** and runs **before** any git tag/commit, so a failed
+publish leaves git clean and a re-run is safe (recovery mode):
+
+- npm: `npm view <pkg>@<version> version` — skip publish if it returns.
+- PyPI: query the simple index / `pip index versions`.
+- crates.io: query the index; RubyGems: `gem list -r -e`.
+- GitHub Release: `gh release view vX.Y.Z` — skip if it exists.
+
+Only after a successful (or already-present) publish does the workflow tag +
+create the release. A `concurrency:` group keyed on workflow + ref with
+`cancel-in-progress` prevents overlapping release runs.
+
+## Approval Gate
+
+For the auto-bump-on-merge trigger, optionally run the publish job in a protected
+**environment** so it pauses for human approval before publishing:
+
+- GitHub: `environment: release` on the publish job + required reviewers configured
+  on the `release` environment.
+- Azure: an environment with a manual-approval check.
+
+## Token Exceptions
+
+Registries/platforms without OIDC trusted publishing at authoring time use a
+**scoped token stored as a CI secret** — the documented exception to the
+no-token rule. Flag these in `deploy/SETUP.md`:
+
+- crates.io (`CARGO_REGISTRY_TOKEN`), NuGet (`NUGET_API_KEY`),
+  Cloudflare (`CLOUDFLARE_API_TOKEN`), Vercel (`VERCEL_TOKEN`),
+  Deno Deploy (`DENO_DEPLOY_TOKEN`).
+
+Use the narrowest scope the platform allows (publish-only, single package/project).

package/skills/hoist/references/interview-guide.md

@@ -0,0 +1,28 @@
+# Interview Guide
+
+## Detection Prompt
+
+Scan the repo and return a DETECTION_REPORT (max 20 lines):
+- language/framework
+- manifest(s): package.json / pyproject.toml / Cargo.toml / *.gemspec / *.csproj / go.mod
+- target family: `package` (library) | `binaries` (app shipping executables) |
+  `static` (static-site framework) | `serverless` (function handler)
+- detected registry from manifest metadata (npm/PyPI/crates/RubyGems/NuGet/Go)
+- existing CI: .github/workflows/ , azure-pipelines.yml
+- existing release config
+
+## Interview Questions
+
+Ask only where detection is ambiguous; confirm otherwise.
+
+1. **Target family** — confirm `package` / `binaries` / `static` / `serverless`.
+2. **Registry / host** — the specific index (npm/PyPI/…), GitHub Releases vs
+   Azure artifacts, GitHub Pages vs Azure Static Web Apps, or the serverless
+   provider (Lambda/Cloudflare/Vercel/Deno).
+3. **Trigger model** — auto-bump-on-merge / tag-triggered / manual-dispatch.
+4. **Approval gate** — (auto-bump only) run publish in a protected `release`
+   environment with required reviewers? Default: no.
+5. **Signing** — (binaries) cosign keyless / minisign / none.
+
+`--skip-interview`: use detected defaults + GitHub Releases/Pages, OIDC where
+supported, auto-bump, no approval gate.

package/skills/hoist/references/release-templates.md

@@ -0,0 +1,136 @@
+# Release Pipeline Templates
+
+Canonical, composable hardened release workflows. The generator picks ONE
+trigger block and ONE publish snippet for the detected target, and drops
+unused jobs. Placeholders: `{DEFAULT_BRANCH}`, `{PKG_NAME}`, `{ARTIFACT}`.
+
+## GitHub Actions
+
+### Canonical release workflow
+
+```yaml
+name: Release
+
+on: {} # replaced by ONE trigger block from "### Trigger blocks" below
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write     # tag + create release
+  id-token: write     # OIDC trusted publishing / keyless signing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # environment: release   # uncomment for the optional approval gate (auto-bump)
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      # Resolve VERSION per trigger — see "### Trigger blocks".
+      - name: Resolve version
+        id: version
+        run: echo "value=<resolved>" >> "$GITHUB_OUTPUT"
+
+      # Idempotency guard (publish-before-git-write). Example: npm.
+      - name: Skip if already published
+        id: guard
+        run: |
+          if npm view "{PKG_NAME}@${{ steps.version.outputs.value }}" version >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build
+        if: steps.guard.outputs.exists == 'false'
+        run: echo "build {ARTIFACT}"    # replaced by detected build step
+
+      # Publish — ONE snippet from "### Publish snippets by target".
+      - name: Publish
+        if: steps.guard.outputs.exists == 'false'
+        run: npm publish --provenance --access public
+
+      # Tag + release only after successful publish (auto-bump trigger).
+      - name: Tag and release
+        if: steps.guard.outputs.exists == 'false'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.value }}
+          generate_release_notes: true
+```
+
+### Trigger blocks
+
+Pick ONE and substitute into `on:` (and adjust the version-resolve step):
+
+```yaml
+# auto-bump on merge to main
+on:
+  push: { branches: [{DEFAULT_BRANCH}] }
+# version-resolve: compute next semver patch (or conventional-commits) in-CI
+
+# tag-triggered
+on:
+  push: { tags: ["v*"] }
+# version-resolve: VERSION = ${GITHUB_REF_NAME#v}
+
+# manual dispatch
+on:
+  workflow_dispatch:
+    inputs: { version: { description: "x.y.z", required: true } }
+# version-resolve: VERSION = ${{ inputs.version }}
+```
+
+### Publish snippets by target
+
+Replace the "Publish" step body:
+
+- **npm:** `npm publish --provenance --access public`
+- **PyPI:** `- uses: pypa/gh-action-pypi-publish@release/v1` (with `id-token: write`; attestations on by default)
+- **RubyGems:** `gem push {ARTIFACT}.gem` (OIDC trusted publishing)
+- **crates.io (token):** `cargo publish` with `CARGO_REGISTRY_TOKEN` secret
+- **NuGet (token):** `dotnet nuget push {ARTIFACT}.nupkg -k $NUGET_API_KEY -s https://api.nuget.org/v3/index.json`
+- **Go:** no publish step — the tag is the release; the module proxy fetches it
+- **Binaries → GitHub Release:** cross-compile matrix → `sha256sum * > SHA256SUMS` → optional `cosign sign-blob`/`minisign` → `softprops/action-gh-release@v2` with `files: dist/*`
+- **Static site → Pages:** `- uses: actions/upload-pages-artifact@v3` then `- uses: actions/deploy-pages@v4` (`id-token: write`)
+- **Serverless (Lambda):** `- uses: aws-actions/configure-aws-credentials@v4` (`role-to-assume`) then `aws lambda update-function-code ...`
+
+## Azure Pipelines
+
+Canonical release pipeline. Cloud auth (Lambda/SWA) uses a Workload Identity
+Federation service connection (`azureSubscription`); package registries use OIDC
+or a scoped token secret per target.
+
+```yaml
+trigger:                      # pick ONE, mirroring the GitHub trigger blocks
+  branches: { include: [{DEFAULT_BRANCH}] }   # auto-bump
+  # tags: { include: ["v*"] }                 # tag-triggered
+# (manual: use the Pipelines UI "Run pipeline" with a version variable)
+
+pool: { vmImage: ubuntu-latest }
+
+stages:
+  - stage: Release
+    jobs:
+      - deployment: Publish
+        environment: release   # optional approval gate (add a manual-approval check)
+        strategy:
+          runOnce:
+            deploy:
+              steps:
+                - script: |
+                    VERSION="<resolved per trigger>"
+                    if npm view "{PKG_NAME}@$VERSION" version >/dev/null 2>&1; then
+                      echo "##vso[task.setvariable variable=exists]true"
+                    else
+                      echo "##vso[task.setvariable variable=exists]false"
+                    fi
+                  displayName: Idempotency guard
+                - script: npm publish --provenance --access public
+                  condition: ne(variables.exists, 'true')
+                  displayName: Publish (npm shown; swap per target)
+                # Cloud targets: wrap deploy in AzureCLI@2 with azureSubscription (WIF).
+```

package/skills/hoist/references/setup-guides.md

@@ -0,0 +1,30 @@
+# Setup Guides
+
+`/hoist` writes `deploy/SETUP.md` into the target repo, tailored to the chosen
+target. Bodies below (substitute `OWNER/REPO`, package name, workflow filename).
+
+## Generated deploy/SETUP.md
+
+### npm / PyPI / RubyGems (trusted publisher — no token)
+- Configure the **trusted publisher** on the registry: reference repo `OWNER/REPO`
+  and the workflow filename (e.g. `.github/workflows/release.yml`).
+- No token to create. The workflow's `id-token: write` does the rest.
+
+### crates.io / NuGet / Cloudflare / Vercel / Deno (Token exception)
+- Create a scoped, publish-only token on the platform.
+- Store it as the named CI secret (`CARGO_REGISTRY_TOKEN` / `NUGET_API_KEY` /
+  `CLOUDFLARE_API_TOKEN` / `VERCEL_TOKEN` / `DENO_DEPLOY_TOKEN`).
+- This is the documented exception to the no-token rule.
+
+### GitHub Pages
+- Repo Settings → Pages → Source: **GitHub Actions**. No token.
+
+### Serverless (AWS Lambda)
+- Create an IAM role trusting the GitHub OIDC provider, condition
+  `sub = repo:OWNER/REPO:ref:refs/heads/main`; grant the lambda update
+  permissions; put the role ARN in `role-to-assume`. Or run `/keel` to
+  provision this.
+
+### Approval gate (optional, auto-bump)
+- Create a `release` environment and add required reviewers so publishing pauses
+  for approval.

package/skills/hoist/tests/evals.json

@@ -0,0 +1,36 @@
+[
+  {
+    "name": "banner-display",
+    "prompt": "/hoist",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "semantic", "value": "Displays an ASCII art banner for the hoist skill before doing anything else" }
+    ]
+  },
+  {
+    "name": "npm-trusted-publishing",
+    "prompt": "/hoist --skip-interview for an npm library",
+    "assertions": [
+      { "type": "semantic", "value": "Uses npm OIDC trusted publishing with no stored NODE_AUTH_TOKEN" },
+      { "type": "semantic", "value": "Publishes with provenance (npm publish --provenance)" },
+      { "type": "semantic", "value": "Guards publish with a version-already-exists check so re-runs are idempotent" }
+    ]
+  },
+  {
+    "name": "binaries-release",
+    "prompt": "/hoist for a Go CLI that ships cross-platform binaries",
+    "assertions": [
+      { "type": "semantic", "value": "Builds cross-platform binaries in a matrix and produces SHA256SUMS checksums" },
+      { "type": "semantic", "value": "Attaches the artifacts to a GitHub Release" }
+    ]
+  },
+  {
+    "name": "auto-bump-approval",
+    "prompt": "/hoist an npm package, auto-bump on merge to main with an approval gate before publishing",
+    "assertions": [
+      { "type": "semantic", "value": "Auto-computes the next version and publishes on merge to the default branch" },
+      { "type": "semantic", "value": "Runs the publish step behind an environment approval gate requiring a human reviewer" },
+      { "type": "semantic", "value": "Generates a deploy/SETUP.md describing the required one-time setup" }
+    ]
+  }
+]

package/skills/manifest.json

@@ -1,6 +1,6 @@
 {
-  "generated": "2026-07-06T03:27:34.322Z",
-  "count": 11,
+  "generated": "2026-07-07T07:32:19.484Z",
+  "count": 13,
   "skills": [
     {
       "name": "brace",
@@ -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": 468,
+      "lines": 532,
       "hasScripts": false,
       "hasReferences": true,
       "hasAssets": false,
@@ -42,6 +42,26 @@
       "hasAssets": false,
       "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,
+      "hasScripts": true,
+      "hasReferences": true,
+      "hasAssets": false,
+      "hasTests": true
+    },
+    {
+      "name": "hoist",
+      "directory": "hoist",
+      "description": ">- Generate secure, low-infrastructure release pipelines that publish artifacts directly — language packages (npm, PyPI, crates, RubyGems, NuGet, Go), GitHub Releases with binaries, static sites/Pages, or serverless functions — without building a container image. OIDC/trusted publishing, provenance, idempotent publish guards, and three trigger models (auto-bump with optional approval, tag, manual). The non-container sibling of /dock. Use when releasing a package or app that doesn't ship as a container.",
+      "lines": 90,
+      "hasScripts": false,
+      "hasReferences": true,
+      "hasAssets": false,
+      "hasTests": true
+    },
     {
       "name": "keel",
       "directory": "keel",