@jenga-ai/agent 3.2.0 → 3.4.0

package/skills/j-dashboard-share/scripts/upload-snapshot.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-dashboard-share/scripts/upload-snapshot.sh
+#
+# Uploads a local dashboard snapshot HTML file (as produced by j-dashboard's
+# `scripts/snapshot.sh`) to a configured rclone remote via `rclone copyto`, at
+# a templated, Drive-side (remote-side) destination path:
+#
+#   JengaAI/<repo-directory-name>/<datetime>-board-snapshot.html
+#
+#   - <repo-directory-name> is the basename of the repository root, derived
+#     via `basename "$(git rev-parse --show-toplevel)"` — never hardcoded to
+#     any specific project.
+#   - <datetime> is the actual UTC run time, formatted `%Y%m%dT%H%M%SZ`
+#     (compact ISO 8601-ish, sortable, filesystem/URL-safe).
+#
+# This destination path is entirely independent of the LOCAL snapshot
+# filename (whatever `snapshot.sh --out` wrote it as) — this script only
+# reads the local file's bytes and uploads them under its own remote-side
+# name.
+#
+# Before attempting any upload, this script verifies the target rclone
+# remote is actually configured (present in `rclone listremotes`). If it is
+# not, this script does NOT attempt the upload and does NOT let rclone
+# surface its own raw error — it dies with an actionable message pointing
+# the user at `j.cloud-connect` (E60_S01) to configure a remote first.
+#
+# HARD SCOPE BOUNDARY: this script uploads ONLY. It never invokes
+# `rclone link` or any other link-creating/sharing subcommand, anywhere in
+# its logic — that is a deliberate, separate, manual action reserved for the
+# user (see E47_S05's story decision). Do not add one.
+#
+# This script does not create or wire up the `j-dashboard-share` skill
+# itself (SKILL.md) — that is a separate task (E47_S05_T02). It assumes a
+# remote has already been configured via `j.cloud-connect`
+# (skills/j-cloud-connect/scripts/{install-rclone.sh,configure-backend.sh},
+# E60_S01) and that `rclone` is already on PATH.
+#
+# Invoked via `bash`, not executed directly: this script intentionally ships
+# without the executable bit, matching the convention already documented in
+# skills/j-cloud-connect/scripts/install-rclone.sh and
+# skills/j-dashboard/scripts/resolve-app-dir.sh. Whatever wires this into the
+# j-dashboard-share skill (E47_S05_T02) should invoke it as
+# `bash skills/j-dashboard-share/scripts/upload-snapshot.sh`.
+#
+# Usage:
+#   upload-snapshot.sh --file <local-snapshot-path> --remote <remote-name>
+#
+#   --file <path>     Path to the local snapshot HTML file to upload (e.g.
+#                      the output of `j.dashboard --snapshot`). Must exist
+#                      and be non-empty.
+#   --remote <name>   Name of an already-configured rclone remote (without a
+#                      trailing colon), e.g. `gdrive`. Checked against
+#                      `rclone listremotes` before any upload is attempted.
+#
+# Exit codes:
+#   0  Upload succeeded. The full remote destination path is printed on
+#      stdout as the last line.
+#   1  Any failure: bad arguments, missing/empty local file, `rclone` not on
+#      PATH, not inside a git repository, the target remote is not
+#      configured (points the user at `j.cloud-connect`), or `rclone copyto`
+#      itself failed. A human-readable reason is always printed to stderr.
+# -----------------------------------------------------------------------------
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: upload-snapshot.sh --file <local-snapshot-path> --remote <remote-name>
+
+Uploads a local dashboard snapshot HTML file to a configured rclone remote
+via `rclone copyto`, at the templated destination path:
+
+  JengaAI/<repo-directory-name>/<datetime>-board-snapshot.html
+
+  --file <path>     Path to the local snapshot HTML file to upload. Must
+                     exist and be non-empty.
+  --remote <name>   Name of an already-configured rclone remote (no
+                     trailing colon). If not configured, this script tells
+                     you to run j.cloud-connect instead of attempting the
+                     upload.
+
+Upload only — never runs `rclone link` or any other sharing/link-creating
+command.
+EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+# -----------------------------------------------------------------------------
+# Argument parsing.
+# -----------------------------------------------------------------------------
+
+LOCAL_FILE=""
+REMOTE_NAME=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --file)
+      [ "$#" -ge 2 ] || die "--file requires a value"
+      LOCAL_FILE="$2"
+      shift 2
+      ;;
+    --remote)
+      [ "$#" -ge 2 ] || die "--remote requires a value"
+      REMOTE_NAME="$2"
+      shift 2
+      ;;
+    *)
+      usage >&2
+      die "unknown argument: $1"
+      ;;
+  esac
+done
+
+[ -n "$LOCAL_FILE" ] || { usage >&2; die "--file is required"; }
+[ -n "$REMOTE_NAME" ] || { usage >&2; die "--remote is required"; }
+
+# -----------------------------------------------------------------------------
+# Preflight — local file, rclone availability, git repository.
+# -----------------------------------------------------------------------------
+
+[ -f "$LOCAL_FILE" ] || die "local snapshot file not found: $LOCAL_FILE"
+[ -s "$LOCAL_FILE" ] || die "local snapshot file is empty: $LOCAL_FILE"
+
+command -v rclone >/dev/null 2>&1 || die "rclone is not on PATH. Install it first (see skills/j-cloud-connect/scripts/install-rclone.sh) and re-run."
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || die "not inside a git repository — cannot derive <repo-directory-name> for the destination path. Run this script from within the project's repository."
+REPO_DIR_NAME="$(basename "$REPO_ROOT")"
+
+# -----------------------------------------------------------------------------
+# Step 1 — Verify the target remote is actually configured BEFORE attempting
+# any upload. Never let a raw rclone error surface for "remote not
+# configured" — point the user at j.cloud-connect instead.
+# -----------------------------------------------------------------------------
+
+REMOTES_OUTPUT="$(rclone listremotes 2>&1)" || die "'rclone listremotes' failed: $REMOTES_OUTPUT"
+
+if ! printf '%s\n' "$REMOTES_OUTPUT" | grep -Fxq "${REMOTE_NAME}:"; then
+  die "remote '$REMOTE_NAME' is not configured in rclone. Run j.cloud-connect first to set it up, then re-run this upload."
+fi
+
+# -----------------------------------------------------------------------------
+# Step 2 — Build the templated destination path.
+# -----------------------------------------------------------------------------
+
+DATETIME="$(date -u +%Y%m%dT%H%M%SZ)"
+DEST_RELATIVE_PATH="JengaAI/${REPO_DIR_NAME}/${DATETIME}-board-snapshot.html"
+DEST="${REMOTE_NAME}:${DEST_RELATIVE_PATH}"
+
+# -----------------------------------------------------------------------------
+# Step 3 — Upload. stdio inherited (no capture/reformatting), matching this
+# repo's j-cloud-connect script conventions. Upload only: this script never
+# calls `rclone link` or any other sharing/link-creating command.
+# -----------------------------------------------------------------------------
+
+echo "Uploading '$LOCAL_FILE' to '$DEST'..."
+
+COPY_EXIT=0
+rclone copyto "$LOCAL_FILE" "$DEST" || COPY_EXIT=$?
+if [ "$COPY_EXIT" -ne 0 ]; then
+  die "'rclone copyto $LOCAL_FILE $DEST' exited with status $COPY_EXIT. Upload did not succeed — see rclone's output above for the reason."
+fi
+
+echo "Upload succeeded."
+echo "$DEST"

package/skills/j-playbook/SKILL.md

@@ -32,6 +32,18 @@ this skill is id resolution (step 1 below).
 
 ## Instructions
 
+0. **Bare invocation — no id given.** If this skill was invoked with no argument at all, do not
+   proceed to step 1. Instead:
+   a. Invoke `skills/jenga/scripts/load-playbooks.sh` with no arguments (its existing full-catalog
+      mode — the same call step 1's `"not_found"` branch already uses for its "did you mean"
+      nudge; no new script is introduced for this).
+   b. Render the returned JSON array as a Markdown table with columns `Id`, `Name`, `Source`, and
+      `Steps`. For the `Source` column, render `Built-in` for a `source` field of `"builtin"` and
+      `Project` for `"project"`. For the `Steps` column, render each entry in that playbook's
+      `steps` array joined by `->`: a bare string step renders as itself; a StepObject step
+      renders its `skill` or `playbook` field value (whichever is present).
+   c. Halt this invocation after rendering the table — do not proceed to step 1.
+
 1. **Resolve the id** — invoke `skills/jenga/scripts/load-playbooks.sh lookup "<id>"`
    (`E53_S06_T02`), where `<id>` is this skill's argument. Branch on the returned `status` field:
 

package/skills/j-playbook-new/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: j.playbook-new
+description: Guided wizard that walks you through authoring a new project-local playbook — id, name, description, keywords, examples, and an ordered list of skills — validates every input against the real catalogs, and self-validates the written file before reporting success.
+keywords:
+  - new playbook
+  - create playbook
+  - author playbook
+  - project playbook
+  - custom playbook
+examples:
+  - "I want to create my own playbook"
+  - "help me author a new project-local playbook"
+  - "set up a custom workflow chain for my project"
+  - "j.playbook-new"
+---
+
+# Playbook New — Guided Playbook-Authoring Wizard
+
+## Purpose
+
+`skills/jenga/scripts/load-playbooks.sh` merges two playbook sources into one catalog: the
+framework-owned `skills/jenga/playbooks/` tree, and a project-owned `project/.playbooks/`
+directory (`E53_S09_T01`). This skill is the guided authoring path for the second source — it
+walks the user step by step through the required fields, validates each one against the real,
+live catalogs (never a hand-maintained list of skill names or existing playbook ids), writes
+`project/.playbooks/<id>.json`, and re-validates the just-written file via
+`skills/jenga/scripts/load-playbooks.sh lookup` before ever declaring success. Hand-editing the
+written JSON file remains the escape hatch for anything this wizard doesn't author (see the "v1
+scope cut" note below).
+
+**All deterministic work — slug/uniqueness validation, catalog lookups, and the JSON write
+itself — lives in `skills/j-playbook-new/scripts/playbook-new.sh`** (per `CLAUDE.md`'s "Scripts
+Over Inline Logic" principle). This skill's own job is only to run the conversational loop around
+that script and interpret its JSON results — it never re-implements any validation or catalog
+logic inline.
+
+**v1 scope cut (deliberate, matches `E53_S09`'s story-level scope cut):** this wizard authors
+plain, ordered, bare-string skill-name chains only — no `forward_from`, `resolve`, `conditional`,
+or `playbook`-type (composition) `StepObject` fields. Hand-edit the written file directly if you
+need any of those.
+
+**Scope note — keywords and examples.** The playbook schema
+(`skills/jenga/playbooks/schema.json`) requires every playbook to carry non-empty `keywords` and
+`examples` arrays, exactly like every existing built-in playbook file already does — these are
+what let `/jenga`'s own natural-language matching (`match-playbook.sh`) ever propose this playbook
+from a free-text request. This wizard therefore asks for both, in addition to id/name/description/
+skill-list, so the result is a genuinely useful, matchable playbook rather than one that merely
+parses.
+
+## Instructions
+
+1. **Ask for an id** — a short, stable, kebab-case identifier (e.g. `my-release-flow`). Validate
+   it by running:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh validate-id "<id>"
+   ```
+   Parse the single JSON object printed to stdout:
+   - `{"valid": true}` — continue to step 2.
+   - `{"valid": false, "reason": "..."}` — show the `reason` to the user verbatim and re-prompt
+     for a different id. Do not proceed until a validation call returns `valid: true`.
+
+2. **Ask for a `name`** — a short, human-readable display name (e.g. "My Release Flow"), shown to
+   users in confirmation prompts and routing output, mirroring every existing playbook's `name`
+   field. No script validation needed beyond "non-empty" — re-prompt if the user gives an empty
+   answer.
+
+3. **Ask for a `description`** — one sentence explaining what this playbook accomplishes
+   end-to-end. Re-prompt if empty.
+
+4. **Ask for `keywords`** — one or more short phrases (1-3 words each) a user might type that
+   should match this playbook, mirroring every existing playbook's `keywords` field (see
+   `skills/jenga/playbooks/brainstorm-to-mirror.json` for a concrete example of the expected
+   shape and specificity). Accept them one at a time or as a single comma-separated batch —
+   your judgment, whichever the user's response shape suggests. Require at least one.
+
+5. **Ask for `examples`** — one or more natural-language example prompts a user might type that
+   should resolve to this playbook (again, mirror the existing built-in playbooks' style and
+   level of specificity). Require at least one; at least one example should plausibly span the
+   full breadth of the playbook's steps, not just its first one, so it's distinguishable from a
+   single-skill match — use your judgment coaching the user toward this if their first example is
+   too narrow.
+
+6. **Ask for an ordered list of skill names** — one at a time, or as a single ordered batch —
+   your judgment based on how the user responds. For **each** name entered, validate it by
+   running:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh validate-skill "<name>"
+   ```
+   Parse the JSON result:
+   - `{"valid": true}` — accept it into the ordered list and continue.
+   - `{"valid": false, "reason": "..."}` — show the `reason` verbatim and re-prompt for that
+     position in the list (do not silently drop it or guess a correction).
+
+   Once the user signals they're done adding skills, require **at least 2** total (a playbook is a
+   chain — a single-skill "playbook" isn't a meaningful use of this mechanism). If fewer than 2
+   were entered, tell the user this and continue prompting for more.
+
+7. **Write the playbook.** Assemble the JSON payload from steps 1-6:
+   ```json
+   {
+     "id": "<id>",
+     "name": "<name>",
+     "description": "<description>",
+     "keywords": ["<keyword 1>", "..."],
+     "examples": ["<example 1>", "..."],
+     "steps": ["<skill 1>", "<skill 2>", "..."]
+   }
+   ```
+   Pipe it to stdin of:
+   ```
+   skills/j-playbook-new/scripts/playbook-new.sh write
+   ```
+   Parse the JSON result:
+   - `{"written": true, "path": "..."}` — continue to step 8.
+   - `{"written": false, "reason": "..."}` — show the `reason` to the user verbatim. This should
+     only happen if something changed between validation and write (e.g. a race, or a shape
+     issue this wizard's own prompts didn't already catch) — do not silently retry; tell the user
+     what failed and, if it's fixable (e.g. the id collided after all), loop back to the relevant
+     earlier step.
+
+8. **Self-validate before declaring success — never skip this step.** Run:
+   ```
+   skills/jenga/scripts/load-playbooks.sh lookup "<id>"
+   ```
+   Branch on the returned `status`:
+   - **`"valid"`** — report success to the user: the playbook was written to
+     `project/.playbooks/<id>.json` and is confirmed loadable. Mention it can now be invoked via
+     `j.playbook <id>` or matched naturally through `j.jenga`.
+   - **`"invalid"`** — report the `reason` field to the user **verbatim** — never a generic
+     failure message. This is a real defect (the write succeeded but load-time validation still
+     rejects it) — do not claim success.
+   - **`"not_found"`** — report to the user that the write appears to have silently failed (the
+     file the wizard just wrote could not be found by the loader) — this would indicate an
+     environment problem (e.g. a different project root being resolved by the two scripts), not a
+     normal outcome. Never claim success.
+
+   Under no circumstances report success to the user without having seen `"status": "valid"` from
+   this exact call.
+
+## Edge Cases
+
+- **The user wants to add `forward_from`/`resolve`/`conditional`/composition to a step.** Tell
+  them this wizard doesn't author those fields (v1 scope cut) and that they can hand-edit
+  `project/.playbooks/<id>.json` afterward — the schema supports these fields identically
+  regardless of which directory a playbook file lives in.
+- **The id collides with a project playbook that already exists on disk but is currently
+  invalid** (e.g. a hand-edited file with a JSON syntax error) — `validate-id` still rejects it (it
+  checks raw file existence, not just catalog membership) rather than silently overwriting a file
+  the user may not realize is broken.
+- **A skill name the user enters exists under multiple forms in the catalog** (e.g. both a bare
+  and a `j-`-prefixed directory, during this repo's ongoing `E50` naming-contract transition) —
+  accept whichever exact form the user typed if `validate-skill` reports it valid; this wizard
+  does not impose a preference between forms the catalog itself doesn't distinguish.
+- **The user cancels mid-wizard** — do not write anything; only step 7 ever touches disk, and only
+  once a complete, locally-validated payload exists.

package/skills/j-playbook-new/scripts/playbook-new.sh

@@ -0,0 +1,332 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/j-playbook-new/scripts/playbook-new.sh
+#
+# Deterministic helper behind the `j.playbook-new` guided wizard (E53_S09_T02). Per CLAUDE.md's
+# "Scripts Over Inline Logic" principle, every mechanical step of the wizard -- id slug/uniqueness
+# validation, skill-name validation against the real catalog, and the JSON write itself -- lives
+# here rather than as inline agent prose in skills/j-playbook-new/SKILL.md. The agent driving the
+# wizard calls this script once per step and interprets its JSON result; it never re-implements
+# any of this logic itself.
+#
+# Reuses, never re-implements, the two existing single-source-of-truth catalogs:
+#   - skills/jenga/scripts/load-playbooks.sh   (merged builtin+project playbook catalog, E53_S09_T01)
+#   - skills/jenga/scripts/load-nl-catalog.sh  (the real, generated skill catalog /jenga's own
+#                                                natural-language matching already uses)
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   playbook-new.sh validate-id <id>
+#
+# Checks <id> is slug-safe (the same pattern skills/jenga/playbooks/schema.json requires:
+# ^[a-z0-9]+(-[a-z0-9]+)*$) and does not collide with any id already present in the merged catalog
+# (skills/jenga/scripts/load-playbooks.sh, no arguments -- built-in and project sources both) OR an
+# existing (possibly currently invalid, and therefore catalog-invisible) file at
+# project/.playbooks/<id>.json. Prints exactly one JSON object to stdout:
+#   {"valid": true}
+#   {"valid": false, "reason": "<human-readable reason>"}
+# Exit 0 for BOTH outcomes -- mirrors load-playbooks.sh's own `lookup` mode convention of
+# reserving a non-zero exit for usage/setup errors only, never for a normal negative validation
+# result the caller is expected to branch on.
+#
+#   playbook-new.sh validate-skill <name>
+#
+# Checks <name> is a real, currently-loadable skill per skills/jenga/scripts/load-nl-catalog.sh's
+# generated catalog -- the exact source /jenga's own natural-language matching already uses, never
+# a hand-maintained list. Prints:
+#   {"valid": true}
+#   {"valid": false, "reason": "..."}
+# Exit 0 for both outcomes, same convention as validate-id.
+#
+#   playbook-new.sh write
+#
+# Reads a single JSON object from stdin:
+#   {"id": "...", "name": "...", "description": "...", "keywords": ["..."],
+#    "examples": ["..."], "steps": ["...", "..."]}
+# Pre-validates it against the same required-field / non-empty-list / steps-shape rules
+# skills/jenga/playbooks/schema.json declares (id slug pattern, all six required fields present,
+# keywords/examples non-empty lists of non-empty strings, steps a list of >= 2 non-empty strings --
+# this wizard authors bare-string steps only, per this task's v1 scope cut) BEFORE writing anything
+# to disk. This is a defensive, redundant pre-check only -- the actual source of truth for validity
+# remains load-playbooks.sh's own load-time validation, which the wizard's own self-validation step
+# (SKILL.md step 8) always runs afterward regardless of this result. Creates project/.playbooks/ if
+# it does not yet exist, and refuses to overwrite an already-existing file for the same id. On
+# success, writes project/.playbooks/<id>.json (pretty-printed) and prints
+# {"written": true, "path": "<absolute path>"}. On any shape/overwrite failure, prints
+# {"written": false, "reason": "..."} and writes nothing. Exit 0 for both outcomes.
+#
+# ---------------------------------------------------------------------------
+# PROJECT ROOT RESOLUTION
+# ---------------------------------------------------------------------------
+# Honors JENGA_PLAYBOOKS_TEST_ROOT -- the SAME override variable load-playbooks.sh itself defines
+# (see that script's header "TESTING OVERRIDE"), not a second, script-specific one -- so a fixture
+# pointing this script at a throwaway project root also makes load-playbooks.sh (invoked internally
+# by validate-id, and by the wizard's own later self-validation step) resolve project/.playbooks/
+# under that same root. Never set this variable in a real invocation.
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   a result JSON object was printed to stdout (whether valid:true/false or written:true/false)
+#   2   usage error, or a real setup failure (missing python3, the sibling load-playbooks.sh /
+#       load-nl-catalog.sh scripts could not be located, one of them exited non-zero, or the
+#       project/.playbooks/ directory could not be created)
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOAD_PLAYBOOKS="$SCRIPT_DIR/../../jenga/scripts/load-playbooks.sh"
+LOAD_NL_CATALOG="$SCRIPT_DIR/../../jenga/scripts/load-nl-catalog.sh"
+
+if [ ! -f "$LOAD_PLAYBOOKS" ]; then
+  echo "Error: could not locate load-playbooks.sh at $LOAD_PLAYBOOKS" >&2
+  exit 2
+fi
+if [ ! -f "$LOAD_NL_CATALOG" ]; then
+  echo "Error: could not locate load-nl-catalog.sh at $LOAD_NL_CATALOG" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by playbook-new.sh" >&2
+  exit 2
+fi
+
+if [ -n "${JENGA_PLAYBOOKS_TEST_ROOT:-}" ]; then
+  # Test-only override -- see header "PROJECT ROOT RESOLUTION" above. Never set in a real
+  # invocation.
+  PROJECT_DIR="$JENGA_PLAYBOOKS_TEST_ROOT"
+else
+  PROJECT_DIR="${JENGA_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)}}"
+fi
+PLAYBOOKS_TARGET_DIR="$PROJECT_DIR/project/.playbooks"
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $(basename "$0") <validate-id|validate-skill|write> [args...]" >&2
+  exit 2
+fi
+MODE="$1"
+shift
+
+PY_SCRIPT="$(mktemp -t playbook-new-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import os
+import re
+import sys
+
+mode = sys.argv[1]
+SLUG_RE = re.compile(r'^[a-z0-9]+(-[a-z0-9]+)*$')
+
+
+def emit(obj):
+    print(json.dumps(obj))
+
+
+if mode == "validate-id":
+    target_id = sys.argv[2]
+    playbooks_target_dir = sys.argv[3]
+
+    if not SLUG_RE.match(target_id):
+        emit({
+            "valid": False,
+            "reason": (
+                f"'{target_id}' is not slug-safe -- must match ^[a-z0-9]+(-[a-z0-9]+)*$ "
+                f"(lowercase letters, digits, single hyphens between segments)"
+            ),
+        })
+        sys.exit(0)
+
+    existing_file = os.path.join(playbooks_target_dir, f"{target_id}.json")
+    if os.path.isfile(existing_file):
+        emit({
+            "valid": False,
+            "reason": (
+                f"a file already exists at {existing_file} -- choose a different id or edit "
+                f"that file directly"
+            ),
+        })
+        sys.exit(0)
+
+    try:
+        catalog = json.load(sys.stdin)
+    except Exception as e:
+        emit({
+            "valid": False,
+            "reason": f"could not read the playbook catalog to check for collisions ({e})",
+        })
+        sys.exit(0)
+
+    for entry in catalog:
+        if entry.get("id") == target_id:
+            src = entry.get("source", "unknown")
+            emit({
+                "valid": False,
+                "reason": (
+                    f"id '{target_id}' collides with an already-loaded {src} playbook (see "
+                    f"skills/jenga/scripts/load-playbooks.sh's merged catalog) -- choose a "
+                    f"different id"
+                ),
+            })
+            sys.exit(0)
+
+    emit({"valid": True})
+    sys.exit(0)
+
+elif mode == "validate-skill":
+    target_name = sys.argv[2]
+
+    try:
+        nl_catalog = json.load(sys.stdin)
+    except Exception as e:
+        emit({"valid": False, "reason": f"could not read the generated skill catalog ({e})"})
+        sys.exit(0)
+
+    for entry in nl_catalog:
+        if entry.get("name") == target_name:
+            emit({"valid": True})
+            sys.exit(0)
+
+    emit({
+        "valid": False,
+        "reason": (
+            f"'{target_name}' is not a recognized skill directory name in the generated skill "
+            f"catalog (skills/jenga/scripts/load-nl-catalog.sh) -- check spelling and the exact "
+            f"directory-name form the catalog currently lists"
+        ),
+    })
+    sys.exit(0)
+
+elif mode == "write":
+    playbooks_target_dir = sys.argv[2]
+
+    try:
+        payload = json.load(sys.stdin)
+    except Exception as e:
+        emit({"written": False, "reason": f"stdin was not valid JSON ({e})"})
+        sys.exit(0)
+
+    if not isinstance(payload, dict):
+        emit({"written": False, "reason": "stdin JSON must be an object"})
+        sys.exit(0)
+
+    required_fields = ["id", "name", "description", "keywords", "examples", "steps"]
+    missing = [f for f in required_fields if f not in payload]
+    if missing:
+        emit({"written": False, "reason": f"missing required field(s) {missing}"})
+        sys.exit(0)
+
+    target_id = payload["id"]
+    if not isinstance(target_id, str) or not SLUG_RE.match(target_id):
+        emit({
+            "written": False,
+            "reason": f"id '{target_id}' is not slug-safe -- must match ^[a-z0-9]+(-[a-z0-9]+)*$",
+        })
+        sys.exit(0)
+
+    for field in ("name", "description"):
+        if not isinstance(payload[field], str) or not payload[field]:
+            emit({"written": False, "reason": f"'{field}' must be a non-empty string"})
+            sys.exit(0)
+
+    for field in ("keywords", "examples"):
+        value = payload[field]
+        if (
+            not isinstance(value, list)
+            or len(value) == 0
+            or not all(isinstance(v, str) and v for v in value)
+        ):
+            emit({
+                "written": False,
+                "reason": f"'{field}' must be a non-empty list of non-empty strings",
+            })
+            sys.exit(0)
+
+    steps = payload["steps"]
+    if not isinstance(steps, list) or len(steps) < 2 or not all(isinstance(s, str) and s for s in steps):
+        emit({
+            "written": False,
+            "reason": (
+                "'steps' must be a list of at least 2 non-empty strings (bare skill-name steps "
+                "only -- this wizard authors no StepObject fields, per this task's v1 scope cut)"
+            ),
+        })
+        sys.exit(0)
+
+    target_file = os.path.join(playbooks_target_dir, f"{target_id}.json")
+    if os.path.isfile(target_file):
+        emit({
+            "written": False,
+            "reason": f"a file already exists at {target_file} -- refusing to overwrite",
+        })
+        sys.exit(0)
+
+    try:
+        os.makedirs(playbooks_target_dir, exist_ok=True)
+    except OSError as e:
+        print(f"Error: could not create {playbooks_target_dir}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    ordered = {
+        "id": target_id,
+        "name": payload["name"],
+        "description": payload["description"],
+        "keywords": payload["keywords"],
+        "examples": payload["examples"],
+        "steps": steps,
+    }
+
+    try:
+        with open(target_file, "w", encoding="utf-8") as fh:
+            json.dump(ordered, fh, indent=2)
+            fh.write("\n")
+    except OSError as e:
+        print(f"Error: could not write {target_file}: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    emit({"written": True, "path": os.path.abspath(target_file)})
+    sys.exit(0)
+
+else:
+    print(f"Error: unrecognized mode '{mode}' (usage: validate-id|validate-skill|write)", file=sys.stderr)
+    sys.exit(2)
+PY
+
+case "$MODE" in
+  validate-id)
+    if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+      echo "Usage: $(basename "$0") validate-id <id>" >&2
+      exit 2
+    fi
+    TARGET_ID="$1"
+    if ! CATALOG_JSON="$("$LOAD_PLAYBOOKS")"; then
+      echo "Error: load-playbooks.sh failed while checking id '$TARGET_ID' for collisions" >&2
+      exit 2
+    fi
+    printf '%s' "$CATALOG_JSON" | python3 "$PY_SCRIPT" validate-id "$TARGET_ID" "$PLAYBOOKS_TARGET_DIR"
+    ;;
+  validate-skill)
+    if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+      echo "Usage: $(basename "$0") validate-skill <name>" >&2
+      exit 2
+    fi
+    TARGET_NAME="$1"
+    if ! NL_CATALOG_JSON="$("$LOAD_NL_CATALOG")"; then
+      echo "Error: load-nl-catalog.sh failed while validating skill name '$TARGET_NAME'" >&2
+      exit 2
+    fi
+    printf '%s' "$NL_CATALOG_JSON" | python3 "$PY_SCRIPT" validate-skill "$TARGET_NAME"
+    ;;
+  write)
+    python3 "$PY_SCRIPT" write "$PLAYBOOKS_TARGET_DIR"
+    ;;
+  *)
+    echo "Error: unrecognized mode '$MODE' (usage: $(basename "$0") <validate-id|validate-skill|write> [args...])" >&2
+    exit 2
+    ;;
+esac