@jenga-ai/agent 3.0.0 → 3.1.1

package/skills/jenga/scripts/detect-nl-intent.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/detect-nl-intent.sh
+#
+# Deterministic classification wrapper around `resolve-id.sh` for `/jenga`'s
+# Phase 0.75 entry-mode resolution (E53_S01). Phase 0.75's scoped branch used
+# to call `resolve-id.sh` directly and halt the whole invocation the moment
+# ANY comma-delimited segment was rejected by the ID grammar. E53_S01 adds a
+# new outcome: when EVERY segment is rejected, the raw argument is not a
+# malformed ID list at all — it's natural-language intent, which should be
+# routed to /jenga's new NL branch (wired up in E53_S01_T03) instead of
+# halting.
+#
+# This script performs exactly that classification and nothing else. Per
+# CLAUDE.md's "Skill Implementation Principle — Scripts Over Inline Logic",
+# `skills/jenga/SKILL.md` never parses `resolve-id.sh`'s raw JSON array
+# itself for this decision — it only ever reads this script's three output
+# shapes below.
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/detect-nl-intent.sh "<raw Phase 0.75 argument>"
+#
+# The argument is passed through verbatim to `resolve-id.sh` — this script
+# does not itself split, clean, or reinterpret it. See `resolve-id.sh`'s own
+# header for the exact ID grammar and its per-segment output schema.
+#
+# ---------------------------------------------------------------------------
+# CLASSIFICATION CONTRACT (stable — E53_S01_T03 wires against this exactly)
+# ---------------------------------------------------------------------------
+# `resolve-id.sh`'s JSON array (one object per comma-delimited segment) is
+# reduced to exactly ONE of three classifications, based on the distinct set
+# of `status` values across all segments:
+#
+#   1. every segment "resolved"  -> "all_resolved"
+#   2. every segment "rejected"  -> "nl_intent"
+#   3. a mix of both             -> "mixed"
+#
+# stdout is always a single JSON object. Nothing else is ever written to
+# stdout — errors and warnings go to stderr only.
+#
+#   "all_resolved":
+#     {
+#       "classification":   "all_resolved",
+#       "resolved_ids":     ["E01_S02", ...],
+#       "resolved_ids_csv": "E01_S02,..."
+#     }
+#     exit 0 — the existing scoped-branch confirmation flow in
+#     `skills/jenga/SKILL.md` is unaffected by this script's introduction.
+#
+#   "nl_intent":
+#     {
+#       "classification": "nl_intent",
+#       "raw_argument":   "<the original $1, verbatim>"
+#     }
+#     exit 0 — this is the signal E53_S01_T03's new branch uses to enter
+#     natural-language matching instead of halting.
+#
+#   "mixed":
+#     {
+#       "classification": "mixed",
+#       "rejected": [
+#         {"input": "<raw segment>", "reason": "<human-readable reason>"},
+#         ...
+#       ]
+#     }
+#     exit 1 — preserves the exact current halt-and-report behavior already
+#     documented in `skills/jenga/SKILL.md`'s "`resolve-id.sh` rejects one or
+#     more segments" edge case. No partial scope is ever assembled from the
+#     segments that did resolve.
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   "all_resolved" or "nl_intent" classification (see above)
+#   1   "mixed" classification (see above)
+#   2   usage error (no argument given) or a `resolve-id.sh` / `board-scan.sh`
+#       setup failure — a real setup problem, not a classification outcome.
+#       `resolve-id.sh`'s own stderr message (already emitted by it) is what
+#       explains the failure; this script does not re-emit a second message
+#       on top of it.
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RESOLVE_ID="$SCRIPT_DIR/resolve-id.sh"
+
+if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+  echo 'Usage: detect-nl-intent.sh "<raw Phase 0.75 argument>"' >&2
+  exit 2
+fi
+
+RAW_INPUT="$1"
+
+if [ ! -x "$RESOLVE_ID" ]; then
+  echo "Error: resolve-id.sh not found or not executable at $RESOLVE_ID" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by detect-nl-intent.sh" >&2
+  exit 2
+fi
+
+# resolve-id.sh exits 0 (all resolved) or 1 (at least one rejected) as
+# legitimate per-segment outcomes — only exit 2 (usage/setup failure) is a
+# real problem here. Guard the capture explicitly so `set -e` doesn't abort
+# this script on resolve-id.sh's own exit 1.
+set +e
+RESOLVE_JSON="$("$RESOLVE_ID" "$RAW_INPUT")"
+RESOLVE_EXIT=$?
+set -e
+
+if [ "$RESOLVE_EXIT" -eq 2 ]; then
+  # resolve-id.sh already wrote a plain-text error to stderr — just
+  # propagate its exit code rather than re-deriving a second message.
+  exit 2
+fi
+
+PY_SCRIPT="$(mktemp -t detect-nl-intent-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import sys
+
+raw_argument = sys.argv[1]
+resolve_json = sys.stdin.read()
+
+try:
+    segments = json.loads(resolve_json)
+except Exception as e:
+    print(f"Error: could not parse resolve-id.sh output as JSON: {e}", file=sys.stderr)
+    sys.exit(2)
+
+if not isinstance(segments, list) or len(segments) == 0:
+    # resolve-id.sh only emits [] for an empty/whitespace-only argument,
+    # which should never reach this script — Phase 0.75 routes an empty
+    # argument to the bare branch before detect-nl-intent.sh is ever
+    # invoked. Treat this as a setup problem rather than silently guessing
+    # a classification for input this script was never meant to see.
+    print("Error: resolve-id.sh produced an empty or non-array result", file=sys.stderr)
+    sys.exit(2)
+
+statuses = {seg.get("status") for seg in segments}
+
+if statuses == {"resolved"}:
+    resolved_ids = [seg["resolved_id"] for seg in segments]
+    print(json.dumps({
+        "classification": "all_resolved",
+        "resolved_ids": resolved_ids,
+        "resolved_ids_csv": ",".join(resolved_ids),
+    }))
+    sys.exit(0)
+
+if statuses == {"rejected"}:
+    print(json.dumps({
+        "classification": "nl_intent",
+        "raw_argument": raw_argument,
+    }))
+    sys.exit(0)
+
+rejected = [
+    {"input": seg.get("input"), "reason": seg.get("reason")}
+    for seg in segments
+    if seg.get("status") == "rejected"
+]
+print(json.dumps({
+    "classification": "mixed",
+    "rejected": rejected,
+}))
+sys.exit(1)
+PY
+
+python3 "$PY_SCRIPT" "$RAW_INPUT" <<< "$RESOLVE_JSON"
+exit $?

package/skills/jenga/scripts/load-nl-catalog.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * skills/jenga/scripts/load-nl-catalog.js
+ *
+ * Node (ESM) helper behind `load-nl-catalog.sh` — the SINGLE REQUIRED SOURCE of skill-catalog
+ * data for `/jenga`'s natural-language branch (E53_S01_T03). `skills/jenga/SKILL.md` must never
+ * re-implement its own skill directory scan or hand-maintain a skill list; it only ever reads
+ * this script's stdout.
+ *
+ * The catalog's NAME LIST comes exclusively from `lib/generate-skill-allow-list.js`'s generated
+ * inventory (`readSkillAllowList()`, which reads the committed `lib/skill-allow-list.json`
+ * artifact) — this script does not independently re-scan `skills/` for a name list of its own,
+ * per E53_S01_T02's acceptance criteria and the drift lesson E41_S04 already documented for that
+ * generator. For each name in that inventory, this script reads exactly one file —
+ * `skills/<name>/SKILL.md` — to populate the remaining catalog fields: `description`, `keywords`,
+ * `examples`, and `metadata.prefered_agent`. These are the same fields `/route`'s Step 1
+ * ("Discover Available Skills") collects.
+ *
+ * ---------------------------------------------------------------------------
+ * USAGE
+ * ---------------------------------------------------------------------------
+ *   node load-nl-catalog.js <projectRoot> <pkgRoot>
+ *
+ *   <projectRoot>  the consuming project's root (passed through to
+ *                  readSkillAllowList's projectRoot fallback candidate)
+ *   <pkgRoot>      the jenga-agent PACKAGE root — where lib/generate-skill-allow-list.js and the
+ *                  canonical skills/ tree actually live (monorepo checkout root, or
+ *                  node_modules/@jenga-ai/agent for an installed consumer)
+ *
+ * ---------------------------------------------------------------------------
+ * OUTPUT SCHEMA
+ * ---------------------------------------------------------------------------
+ * stdout is a single JSON array, one object per catalog entry, e.g.:
+ *
+ *   [
+ *     {
+ *       "name":           "btw",
+ *       "description":    "...",
+ *       "keywords":       ["..."],
+ *       "examples":       ["..."],
+ *       "prefered_agent": "scrum-master"   // or null when absent
+ *     },
+ *     ...
+ *   ]
+ *
+ * Nothing but this JSON array is ever written to stdout. Warnings (a skill skipped because its
+ * SKILL.md is missing/unreadable, or its frontmatter lacks `description`) go to stderr only, and
+ * are non-fatal.
+ *
+ * ---------------------------------------------------------------------------
+ * EXIT CODES
+ * ---------------------------------------------------------------------------
+ *   0   catalog written to stdout (possibly with skip warnings already emitted to stderr)
+ *   2   usage error, or a real setup failure (allow-list inventory unreadable/empty, or
+ *       lib/generate-skill-allow-list.js failed to load)
+ *
+ * ---------------------------------------------------------------------------
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+/**
+ * Parses YAML frontmatter from a SKILL.md's content into a plain object. This is a hand-rolled,
+ * intentionally minimal parser scoped to the small set of shapes SKILL.md frontmatter actually
+ * uses — it follows the same overall approach as mcp/router/skill-index.js's `parseFrontmatter`
+ * (scalar keys, and array keys introduced by an empty `key:` line followed by `  - item` lines),
+ * extended here to also recognize ONE level of nested mapping (the `metadata:` block, e.g.
+ * `metadata:\n  prefered_agent: developer`) — a shape skill-index.js's parser doesn't need to
+ * handle, since it never reads `metadata`.
+ *
+ * Returns {} if no frontmatter block is found.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+
+  const lines = match[1].split("\n");
+  const obj = {};
+  let i = 0;
+
+  const stripQuotes = (s) => s.trim().replace(/^["']|["']$/g, "");
+
+  while (i < lines.length) {
+    const topMatch = lines[i].match(/^(\w+):\s*(.*)$/);
+    if (!topMatch) {
+      i++;
+      continue;
+    }
+    const [, key, valRaw] = topMatch;
+    const val = valRaw.trim();
+
+    if (val === "[]") {
+      obj[key] = [];
+      i++;
+      continue;
+    }
+
+    if (val !== "") {
+      obj[key] = stripQuotes(val);
+      i++;
+      continue;
+    }
+
+    // Empty value — look ahead at indented child lines to decide whether this key is an array
+    // (child lines shaped `  - item`) or a nested map (child lines shaped `  childKey: value`).
+    // A block is only ever consistently one or the other in this repo's frontmatter, so the
+    // first child line's shape decides it.
+    let j = i + 1;
+    const arrayItems = [];
+    const mapObj = {};
+    let sawArray = false;
+    let sawMap = false;
+
+    while (j < lines.length && /^\s+\S/.test(lines[j])) {
+      const arrItem = lines[j].match(/^\s+-\s+(.*)$/);
+      const mapItem = lines[j].match(/^\s+(\w+):\s*(.*)$/);
+      if (arrItem && !sawMap) {
+        sawArray = true;
+        arrayItems.push(stripQuotes(arrItem[1]));
+      } else if (mapItem && !sawArray) {
+        sawMap = true;
+        mapObj[mapItem[1]] = stripQuotes(mapItem[2]);
+      }
+      j++;
+    }
+
+    obj[key] = sawArray ? arrayItems : sawMap ? mapObj : [];
+    i = j;
+  }
+
+  return obj;
+}
+
+async function main() {
+  const [projectRoot, pkgRoot] = process.argv.slice(2);
+  if (!projectRoot || !pkgRoot) {
+    process.stderr.write("Usage: load-nl-catalog.js <projectRoot> <pkgRoot>\n");
+    process.exit(2);
+  }
+
+  const generatorPath = join(pkgRoot, "lib", "generate-skill-allow-list.js");
+  let readSkillAllowList;
+  try {
+    ({ readSkillAllowList } = await import(pathToFileURL(generatorPath).href));
+  } catch (e) {
+    process.stderr.write(`Error: failed to load ${generatorPath}: ${e.message}\n`);
+    process.exit(2);
+    return;
+  }
+
+  const names = readSkillAllowList(projectRoot, pkgRoot);
+  if (!Array.isArray(names) || names.length === 0) {
+    process.stderr.write(
+      "Error: skill allow-list inventory is empty or unreadable (lib/skill-allow-list.json) — cannot build NL catalog\n"
+    );
+    process.exit(2);
+    return;
+  }
+
+  const catalog = [];
+  for (const name of names) {
+    const skillMdPath = join(pkgRoot, "skills", name, "SKILL.md");
+    if (!existsSync(skillMdPath)) {
+      process.stderr.write(
+        `Warning: ${skillMdPath} not found for allow-listed skill '${name}' — skipped\n`
+      );
+      continue;
+    }
+
+    let content;
+    try {
+      content = readFileSync(skillMdPath, "utf8");
+    } catch (e) {
+      process.stderr.write(`Warning: failed to read ${skillMdPath}: ${e.message} — skipped\n`);
+      continue;
+    }
+
+    const fm = parseFrontmatter(content);
+    if (!fm.description) {
+      process.stderr.write(
+        `Warning: ${skillMdPath} missing 'description' in frontmatter — skipped\n`
+      );
+      continue;
+    }
+
+    catalog.push({
+      name,
+      description: fm.description,
+      keywords: Array.isArray(fm.keywords) ? fm.keywords : [],
+      examples: Array.isArray(fm.examples) ? fm.examples : [],
+      prefered_agent:
+        fm.metadata && typeof fm.metadata === "object" && fm.metadata.prefered_agent
+          ? fm.metadata.prefered_agent
+          : null,
+    });
+  }
+
+  process.stdout.write(JSON.stringify(catalog, null, 2) + "\n");
+}
+
+main().catch((e) => {
+  process.stderr.write(`Error: ${e.message}\n`);
+  process.exit(2);
+});

package/skills/jenga/scripts/load-nl-catalog.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/load-nl-catalog.sh
+#
+# Thin bash entry point for `load-nl-catalog.js` — the SINGLE REQUIRED SOURCE of skill-catalog
+# data for `/jenga`'s natural-language branch (E53_S01_T03). `skills/jenga/SKILL.md` must never
+# re-implement its own skill directory scan or hand-maintain a skill list; it only ever invokes
+# this script and reads its stdout.
+#
+# This script's only job is root resolution: it locates JENGA_PROJECT_DIR (the consuming
+# project's root) and PKG_ROOT (the jenga-agent PACKAGE root — where the canonical skills/ tree
+# and lib/generate-skill-allow-list.js actually live, which may differ from the project root for
+# an npm-installed consumer) and hands both to the Node helper, which does the actual reading and
+# JSON assembly (see load-nl-catalog.js's own header for the full contract).
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/load-nl-catalog.sh
+#
+# No arguments. Emits the full JSON catalog array to stdout — see load-nl-catalog.js's header for
+# the exact per-entry shape (name/description/keywords/examples/prefered_agent).
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   catalog written to stdout
+#   2   setup failure: package root could not be located, node is missing, or the Node helper
+#       itself failed (see its own stderr message for the reason)
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolve JENGA_PROJECT_DIR the same way every other script in skills/jenga/scripts/ does.
+if [ -f "$SCRIPT_DIR/../../../lib/resolve-project-dir.sh" ]; then
+  # shellcheck source=/dev/null
+  source "$SCRIPT_DIR/../../../lib/resolve-project-dir.sh"
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  JENGA_PROJECT_DIR="$CLAUDE_PROJECT_DIR"
+else
+  JENGA_PROJECT_DIR="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)"
+fi
+
+# Resolve the jenga-agent PACKAGE root (where lib/generate-skill-allow-list.js and the canonical
+# skills/ tree actually live) — same monorepo-checkout vs. installed-npm-package detection used
+# by skills/init/scripts/init.sh's PKG_ROOT resolution.
+if [ -d "$SCRIPT_DIR/../../../templates" ]; then
+  PKG_ROOT="$SCRIPT_DIR/../../.."
+elif [ -d "$JENGA_PROJECT_DIR/node_modules/@jenga-ai/agent/templates" ]; then
+  PKG_ROOT="$JENGA_PROJECT_DIR/node_modules/@jenga-ai/agent"
+else
+  echo "Error: could not locate the jenga-agent package root (templates/ not found via monorepo checkout or node_modules/@jenga-ai/agent)." >&2
+  exit 2
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Error: node is required by load-nl-catalog.sh" >&2
+  exit 2
+fi
+
+node "$SCRIPT_DIR/load-nl-catalog.js" "$JENGA_PROJECT_DIR" "$PKG_ROOT"
+exit $?

package/skills/jenga/scripts/load-playbooks.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/load-playbooks.sh
+#
+# Deterministic loader for `/jenga`'s multi-skill PLAYBOOK catalog (E53_S02_T01) — the SINGLE
+# REQUIRED SOURCE of playbook data for E53_S02_T02's `match-playbook.sh` and E53_S02_T04's wiring
+# into `skills/jenga/SKILL.md`. Neither of those may re-scan `skills/jenga/playbooks/` or
+# hand-maintain a playbook list of their own; they only ever invoke this script and read its
+# stdout, mirroring the single-source contract `load-nl-catalog.sh` already established for the
+# single-skill catalog (E53_S01_T02).
+#
+# A "playbook" is an ORDERED chain of skills (e.g. brainstorm -> todo -> do -> dev-done ->
+# mirror-public) that `/jenga`'s natural-language branch may propose, as an editable, confirmable
+# numbered list (see `render-playbook-confirmation.sh`, E53_S02_T03), when free-text intent spans
+# more than one skill and does not cleanly resolve to a single one.
+#
+# ---------------------------------------------------------------------------
+# DATA SOURCE
+# ---------------------------------------------------------------------------
+# Every `*.json` file directly under `skills/jenga/playbooks/`, EXCLUDING `schema.json` (which
+# documents the required shape — see that file's own header — but is never itself a playbook
+# entry). See `schema.json` for the authoritative field list; this script's validation below is
+# a runtime mirror of that schema, not a substitute for it.
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/load-playbooks.sh
+#
+# No arguments. Emits the full JSON playbook catalog array to stdout.
+#
+# ---------------------------------------------------------------------------
+# OUTPUT SCHEMA
+# ---------------------------------------------------------------------------
+# stdout is a single JSON array, one object per valid playbook:
+#
+#   [
+#     {
+#       "id":          "brainstorm-to-mirror",
+#       "name":        "Idea to Public Release",
+#       "description": "...",
+#       "keywords":    ["..."],
+#       "examples":    ["..."],
+#       "steps":       ["brainstorm", "todo", "do", "dev-done", "mirror-public"]
+#     },
+#     ...
+#   ]
+#
+# Nothing but this JSON array is ever written to stdout. Skip warnings go to stderr only and are
+# non-fatal — a single malformed playbook file never aborts the whole catalog load.
+#
+# ---------------------------------------------------------------------------
+# VALIDATION / SKIP CONDITIONS (each skip is a stderr warning, never fatal)
+# ---------------------------------------------------------------------------
+#   - File is not valid JSON, or is not a JSON object                      -> skipped
+#   - Missing any required field: id, name, description, keywords,
+#     examples, steps                                                     -> skipped
+#   - `keywords`, `examples`, or `steps` present but empty (or not a
+#     list)                                                                -> skipped
+#   - `id` does not equal the filename's basename without `.json`          -> skipped
+#     (prevents a playbook's identity from silently drifting from its
+#     file location)
+#   - Any entry in `steps` has no corresponding `skills/<name>/SKILL.md`
+#     on disk                                                              -> skipped (the whole
+#     playbook is skipped, not just the bad step — a chain with a broken
+#     link is not a usable chain)
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   catalog written to stdout (possibly with skip warnings already emitted to stderr;
+#       an empty catalog `[]` is a valid, non-error outcome — e.g. every playbook file was
+#       malformed, or no playbook files exist yet beyond schema.json)
+#   2   usage error, or a real setup failure (playbooks directory missing entirely, or
+#       python3 unavailable)
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Resolve the jenga-agent PACKAGE root (where the canonical skills/ tree actually lives) — same
+# monorepo-checkout vs. installed-npm-package detection used by
+# skills/jenga/scripts/load-nl-catalog.sh's PKG_ROOT resolution and skills/init/scripts/init.sh.
+if [ -d "$SCRIPT_DIR/../../../templates" ]; then
+  PKG_ROOT="$SCRIPT_DIR/../../.."
+elif [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -d "${CLAUDE_PROJECT_DIR}/node_modules/@jenga-ai/agent/templates" ]; then
+  PKG_ROOT="${CLAUDE_PROJECT_DIR}/node_modules/@jenga-ai/agent"
+else
+  echo "Error: could not locate the jenga-agent package root (templates/ not found via monorepo checkout or node_modules/@jenga-ai/agent)." >&2
+  exit 2
+fi
+
+PLAYBOOKS_DIR="$PKG_ROOT/skills/jenga/playbooks"
+SKILLS_DIR="$PKG_ROOT/skills"
+
+if [ ! -d "$PLAYBOOKS_DIR" ]; then
+  echo "Error: playbooks directory not found at $PLAYBOOKS_DIR" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by load-playbooks.sh" >&2
+  exit 2
+fi
+
+PY_SCRIPT="$(mktemp -t load-playbooks-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import os
+import sys
+
+playbooks_dir = sys.argv[1]
+skills_dir = sys.argv[2]
+
+REQUIRED_FIELDS = ["id", "name", "description", "keywords", "examples", "steps"]
+LIST_FIELDS = ["keywords", "examples", "steps"]
+
+catalog = []
+
+try:
+    filenames = sorted(
+        f for f in os.listdir(playbooks_dir)
+        if f.endswith(".json") and f != "schema.json"
+    )
+except OSError as e:
+    print(f"Error: could not list {playbooks_dir}: {e}", file=sys.stderr)
+    sys.exit(2)
+
+for filename in filenames:
+    path = os.path.join(playbooks_dir, filename)
+    basename = filename[: -len(".json")]
+
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except Exception as e:
+        print(f"Warning: {path} is not valid JSON ({e}) — skipped", file=sys.stderr)
+        continue
+
+    if not isinstance(data, dict):
+        print(f"Warning: {path} is not a JSON object — skipped", file=sys.stderr)
+        continue
+
+    missing = [f for f in REQUIRED_FIELDS if f not in data]
+    if missing:
+        print(f"Warning: {path} missing required field(s) {missing} — skipped", file=sys.stderr)
+        continue
+
+    bad_list = [
+        f for f in LIST_FIELDS
+        if not isinstance(data.get(f), list) or len(data.get(f)) == 0
+    ]
+    if bad_list:
+        print(f"Warning: {path} field(s) {bad_list} must be non-empty lists — skipped", file=sys.stderr)
+        continue
+
+    if data["id"] != basename:
+        print(
+            f"Warning: {path} has id '{data['id']}' which does not match its filename "
+            f"'{basename}.json' — skipped",
+            file=sys.stderr,
+        )
+        continue
+
+    missing_skills = [
+        step for step in data["steps"]
+        if not os.path.isfile(os.path.join(skills_dir, step, "SKILL.md"))
+    ]
+    if missing_skills:
+        print(
+            f"Warning: {path} references nonexistent skill(s) {missing_skills} "
+            f"(no skills/<name>/SKILL.md found) — playbook skipped",
+            file=sys.stderr,
+        )
+        continue
+
+    catalog.append({
+        "id": data["id"],
+        "name": data["name"],
+        "description": data["description"],
+        "keywords": data["keywords"],
+        "examples": data["examples"],
+        "steps": data["steps"],
+    })
+
+print(json.dumps(catalog, indent=2))
+PY
+
+python3 "$PY_SCRIPT" "$PLAYBOOKS_DIR" "$SKILLS_DIR"
+exit $?