@jenga-ai/agent 3.1.0 → 3.1.1

package/README.md

@@ -40,7 +40,7 @@ Jenga AI solves each of these with structure: persistent engineering context mai
 - **Isolated git worktrees per task** — the Developer never works directly on your main branch
 - **Works with any AI coding agent or AI-native IDE** — Claude Code, GitHub Copilot, and Codex CLI are all supported today
 
-> 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
+> 📖 **Full reference:** [Docs site](https://samwelmunga.github.io/jenga-npm/reference.html) · **Intro Guide:** [Docs site](https://samwelmunga.github.io/jenga-npm/getting-started.html) — mirrored at [project/.wiki/documentation.md](project/.wiki/documentation.md) / [intro-guide.md](project/.wiki/intro-guide.md)
 
 ### "Isn't this just an LLM grading another LLM?"
 
@@ -215,7 +215,7 @@ Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your
 | `j.do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
 | `j.status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
 
-> 📖 **Full skill list** (planning, review, committing & maintenance commands): [project/.wiki/documentation.md](project/.wiki/documentation.md#skills)
+> 📖 **Full skill list** (planning, review, committing & maintenance commands): [Docs site](https://samwelmunga.github.io/jenga-npm/skills.html) — mirrored at [project/.wiki/documentation.md#skills](project/.wiki/documentation.md#skills)
 
 ---
 
@@ -232,4 +232,4 @@ Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your
 - You're doing a quick one-off script or single-session experiment
 - Your project has no meaningful test surface
 
-📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md)
+📖 **Full reference:** [Docs site](https://samwelmunga.github.io/jenga-npm/reference.html) — mirrored at [project/.wiki/documentation.md](project/.wiki/documentation.md)

package/lib/skill-allow-list.json

@@ -1,5 +1,5 @@
 {
-  "generated_at": "2026-09-08T02:00:42.924Z",
+  "generated_at": "2026-09-08T21:53:54.204Z",
   "skill_count": 36,
   "skills": [
     "brainstorm",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "An agentic development workflow for Claude Code, Copilot, and Codex — with a persistent Epic/Story/Task board, an isolated git worktree per task, and a separate tester agent that runs your test suite before anything is marked done.",
   "type": "module",
   "publishConfig": {

package/scripts/build-pages-site.sh

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+# scripts/build-pages-site.sh
+#
+# Deterministically (re)generates the wiki-derived pages of the GitHub Pages
+# documentation site (docs/*.md) from the existing wiki mirror under
+# project/.wiki/. This is the sync mechanism behind E41_S13_T01's
+# source-of-truth decision ("restructure from the wiki, keep both in sync"):
+# project/.wiki/ stays the canonical, doc-sync-maintained content; this
+# script is the deterministic transform from that content into the
+# multi-page, navigable Pages site.
+#
+# WHEN TO RE-RUN: after `j.doc-sync` (or any manual edit) updates
+# project/.wiki/documentation.md, project/.wiki/intro-guide.md, or
+# project/.wiki/concepts/*.md, re-run this script to refresh the Pages site
+# so it doesn't silently drift from the wiki the way README.md and the wiki
+# itself have drifted from each other before (see skills/doc-sync/SKILL.md
+# for the doc-sync side of this convention).
+#
+# WHAT THIS SCRIPT DOES NOT TOUCH:
+#   - docs/_config.yml, docs/index.md — hand-authored site structure/config,
+#     not derived from wiki content. Edit these directly if the page set or
+#     nav changes.
+#   - docs/README.md — maintainer-facing decision record, not a rendered
+#     Jekyll page and not wiki-derived content.
+#
+# WHAT THIS SCRIPT REGENERATES (always overwritten, never hand-edit these):
+#   - docs/getting-started.md   <- project/.wiki/intro-guide.md
+#   - docs/concepts.md          <- project/.wiki/concepts/*.md (concatenated)
+#   - docs/skills.md            <- project/.wiki/documentation.md "## Skills"
+#   - docs/agents.md            <- project/.wiki/documentation.md "## Agents"
+#   - docs/hooks.md             <- project/.wiki/documentation.md "## Hooks"
+#   - docs/mcp-tools.md         <- project/.wiki/documentation.md "## MCP Tools"
+#   - docs/reference.md         <- project/.wiki/documentation.md
+#                                   "## Directory Structure" +
+#                                   "## Agent Communication Contract"
+#                                   (plus a short hand-authored index blurb
+#                                   linking to skills/agents/hooks/mcp-tools)
+#
+# KNOWN LIMITATION: this is a structural transform, not a fact-checker. It
+# ports project/.wiki/documentation.md's content as-is, including whatever
+# is currently stale in that file (e.g. it documents ~30 skills under the
+# old bare `/<name>` invocation form and does not yet list every skill in
+# skills/, including the `j-<name>` twins — a pre-existing wiki staleness
+# gap, not something introduced by this script). Fixing the wiki's own
+# staleness is doc-sync's job, not this script's — this script only keeps
+# the Pages site faithful to whatever the wiki currently says.
+#
+# HEADING-STABILITY ASSUMPTION: section extraction below is keyed to exact
+# top-level ("## ") heading text in documentation.md (Agents, Skills, MCP
+# Tools, Hooks, Directory Structure, Agent Communication Contract). If any
+# of those headings are renamed, update the `case` statement in
+# extract_sections() to match.
+#
+# Usage: scripts/build-pages-site.sh
+# Safe to re-run any number of times — every run fully overwrites its
+# output files from the current wiki content (no partial/incremental state).
+
+set -euo pipefail
+
+# shellcheck source=lib/resolve-project-dir.sh disable=SC1091
+source "$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh"
+
+REPO_ROOT="$JENGA_PROJECT_DIR"
+WIKI_DIR="$REPO_ROOT/project/.wiki"
+DOCS_DIR="$REPO_ROOT/docs"
+DOC_MD="$WIKI_DIR/documentation.md"
+INTRO_MD="$WIKI_DIR/intro-guide.md"
+CONCEPTS_DIR="$WIKI_DIR/concepts"
+
+for f in "$DOC_MD" "$INTRO_MD"; do
+  if [ ! -f "$f" ]; then
+    echo "build-pages-site.sh: required source file not found: $f" >&2
+    exit 1
+  fi
+done
+if [ ! -d "$CONCEPTS_DIR" ]; then
+  echo "build-pages-site.sh: required source directory not found: $CONCEPTS_DIR" >&2
+  exit 1
+fi
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# --- 1. Split documentation.md into per-section scratch files -------------
+# A line can only belong to one target section at a time; the generic
+# "any other ## heading" rule resets `section` to "" so unrelated top-level
+# sections (e.g. "## Table of Contents") are dropped rather than bleeding
+# into whichever named section preceded them.
+awk -v work="$WORK" '
+  /^## Agents$/                             { section = "agents"; next }
+  /^## Skills$/                             { section = "skills"; next }
+  /^## MCP Tools$/                          { section = "mcp-tools"; next }
+  /^## Hooks$/                              { section = "hooks"; next }
+  /^## Directory Structure$/                { section = "directory-structure"; next }
+  /^## Agent Communication Contract$/       { section = "contract"; next }
+  /^## /                                    { section = "" }
+  {
+    if (section != "") {
+      print >> (work "/section-" section ".md")
+    }
+  }
+' "$DOC_MD"
+
+for s in agents skills mcp-tools hooks directory-structure contract; do
+  [ -f "$WORK/section-$s.md" ] || touch "$WORK/section-$s.md"
+done
+
+write_page() {
+  # write_page <output-path> <title> <permalink> <body-file>
+  local out="$1" title="$2" permalink="$3" body="$4"
+  {
+    printf -- '---\n'
+    printf 'layout: page\n'
+    printf 'title: %s\n' "$title"
+    printf 'permalink: %s\n' "$permalink"
+    printf -- '---\n\n'
+    cat "$body"
+  } > "$out"
+}
+
+# --- 2. docs/agents.md, docs/hooks.md, docs/mcp-tools.md -------------------
+# Straight ports — no internal markdown links were found in these sections
+# of documentation.md, so no link rewriting is needed beyond the front
+# matter wrapper.
+write_page "$DOCS_DIR/agents.md" "Agents" "/agents.html" "$WORK/section-agents.md"
+write_page "$DOCS_DIR/hooks.md" "Hooks" "/hooks.html" "$WORK/section-hooks.md"
+write_page "$DOCS_DIR/mcp-tools.md" "MCP Tools" "/mcp-tools.html" "$WORK/section-mcp-tools.md"
+
+# --- 3. docs/skills.md ------------------------------------------------------
+# Single reference page (matches the story's own suggested top-level
+# category list: Getting Started / Concepts / Skills reference / Agents /
+# Hooks / MCP Tools — "Skills reference" is one page, not one page per
+# skill). Category (### ) and per-skill (#### ) structure is preserved
+# as-is from the source.
+write_page "$DOCS_DIR/skills.md" "Skills Reference" "/skills.html" "$WORK/section-skills.md"
+
+# --- 4. docs/reference.md ---------------------------------------------------
+# Combines the two remaining documentation.md sections (Directory Structure,
+# Agent Communication Contract) behind a short hand-authored index blurb
+# that links out to the pages built above — this replaces documentation.md's
+# original role as the single "full reference" entry point, now that its
+# content is split across multiple pages.
+{
+  cat <<'EOF'
+## Full Reference Index
+
+This page is the entry point into the full reference material, split across
+several pages so nothing requires scrolling through one giant file:
+
+- **[Skills Reference](./skills.md)** — every skill, grouped by Setup &
+  Planning, Execution, Status & Review, and Committing & Maintenance.
+- **[Agents](./agents.md)** — Scrum Master, Developer, Tester: roles,
+  ownership, and responsibilities.
+- **[Hooks](./hooks.md)** — session lifecycle hooks and what they run.
+- **[MCP Tools](./mcp-tools.md)** — Model Context Protocol tools available
+  in a Claude Code session.
+
+The rest of this page covers the repo's directory structure and the
+inter-agent communication contract (the typed "sender object" every agent
+call carries).
+
+---
+
+EOF
+  cat "$WORK/section-directory-structure.md"
+  printf '\n---\n\n'
+  cat "$WORK/section-contract.md"
+} > "$WORK/reference-body.md"
+write_page "$DOCS_DIR/reference.md" "Reference" "/reference.html" "$WORK/reference-body.md"
+
+# --- 5. docs/getting-started.md ---------------------------------------------
+# Port of intro-guide.md verbatim (drop the leading H1 — front matter
+# supplies the page title instead), with its two links into the
+# now-restructured reference/concepts pages rewritten.
+tail -n +2 "$INTRO_MD" > "$WORK/intro-body.md"
+# NOTE on delimiter choice: sed's `s<delim>pattern<delim>replacement<delim>`
+# breaks if the replacement text itself contains the delimiter character.
+# Several replacements below contain a literal "#" (anchor fragments), so
+# "#" cannot be used as the delimiter here — "|" is used instead, since
+# none of these paths/anchors contain a literal "|".
+sed -i.bak \
+  -e 's|\[documentation\.md\](\./documentation\.md)|[reference.md](./reference.md)|g' \
+  -e 's|(\./concepts/role-separation\.md)|(./concepts.md#role-separation)|g' \
+  -e 's|(\./concepts/board-hierarchy\.md)|(./concepts.md#board-hierarchy)|g' \
+  -e 's|(\./concepts/session-continuity\.md)|(./concepts.md#session-continuity)|g' \
+  -e 's|(\./concepts/first-feature\.md)|(./concepts.md#your-first-feature)|g' \
+  -e 's|(\./concepts/multi-session-work\.md)|(./concepts.md#working-across-sessions)|g' \
+  -e 's|(\./concepts/mid-flow-capture\.md)|(./concepts.md#capturing-mid-flow-ideas)|g' \
+  -e 's|(\./concepts/parallel-tasks\.md)|(./concepts.md#parallel-tasks)|g' \
+  "$WORK/intro-body.md"
+rm -f "$WORK/intro-body.md.bak"
+write_page "$DOCS_DIR/getting-started.md" "Getting Started" "/getting-started.html" "$WORK/intro-body.md"
+
+# --- 6. docs/concepts.md -----------------------------------------------------
+# Concatenates all 7 project/.wiki/concepts/*.md files into one page:
+#   - each file's H1 becomes an H2 section heading (slug listed below must
+#     stay in sync with each file's actual title text — GitHub Pages/kramdown
+#     slugifies headings to lowercase-hyphenated automatically)
+#   - all other headings are demoted one level (## -> ###, ### -> ####)
+#   - sibling/parent links are rewritten to point within the merged page
+#     and at the sibling getting-started.md / reference.md pages
+#
+{
+  cat <<'EOF'
+## Concepts
+
+The ideas behind Jenga AI's structure, and the how-tos for using it day to
+day. Jump to any section:
+
+- [Role Separation](#role-separation)
+- [Board Hierarchy](#board-hierarchy)
+- [Session Continuity](#session-continuity)
+- [Your First Feature](#your-first-feature)
+- [Working Across Sessions](#working-across-sessions)
+- [Capturing Mid-Flow Ideas](#capturing-mid-flow-ideas)
+- [Parallel Tasks](#parallel-tasks)
+
+---
+
+EOF
+} > "$WORK/concepts-body.md"
+
+append_concept() {
+  # append_concept <filename-stem> <section-title>
+  local stem="$1"
+  local title="$2"
+  local src="$CONCEPTS_DIR/$stem.md"
+  {
+    printf '## %s\n\n' "$title"
+    # NOTE on delimiter choice: same reasoning as the getting-started block
+    # above — replacements here contain a literal "#" anchor character, so
+    # "|" is used as the sed delimiter instead of "#".
+    #
+    # NOTE on heading demotion: a naive two-pass "## -> ###" then
+    # "### -> ####" sed would double-demote lines that were originally
+    # "## " (they'd match the first rule, becoming "### ", and then ALSO
+    # match the second rule on the same pass, becoming "#### " — wrong).
+    # The single extended-regex rule below captures the existing run of
+    # 2-3 "#" characters and prepends exactly one more, so each line is
+    # demoted exactly once regardless of its original level.
+    tail -n +2 "$src" \
+      | sed \
+        -e 's|\[documentation\.md\](\.\./documentation\.md)|[reference.md](./reference.md)|g' \
+        -e 's|(\.\./intro-guide\.md)|(./getting-started.md)|g' \
+        -e 's|(\.\./documentation\.md)|(./reference.md)|g' \
+        -e 's|(\./role-separation\.md)|(#role-separation)|g' \
+        -e 's|(\./board-hierarchy\.md)|(#board-hierarchy)|g' \
+        -e 's|(\./session-continuity\.md)|(#session-continuity)|g' \
+        -e 's|(\./first-feature\.md)|(#your-first-feature)|g' \
+        -e 's|(\./multi-session-work\.md)|(#working-across-sessions)|g' \
+        -e 's|(\./mid-flow-capture\.md)|(#capturing-mid-flow-ideas)|g' \
+        -e 's|(\./parallel-tasks\.md)|(#parallel-tasks)|g' \
+      | sed -E 's/^(#{2,3}) /#\1 /'
+    printf '\n---\n\n'
+  } >> "$WORK/concepts-body.md"
+}
+
+append_concept "role-separation" "Role Separation"
+append_concept "board-hierarchy" "Board Hierarchy"
+append_concept "session-continuity" "Session Continuity"
+append_concept "first-feature" "Your First Feature"
+append_concept "multi-session-work" "Working Across Sessions"
+append_concept "mid-flow-capture" "Capturing Mid-Flow Ideas"
+append_concept "parallel-tasks" "Parallel Tasks"
+
+write_page "$DOCS_DIR/concepts.md" "Concepts" "/concepts.html" "$WORK/concepts-body.md"
+
+echo "build-pages-site.sh: regenerated docs/{getting-started,concepts,skills,agents,hooks,mcp-tools,reference}.md from project/.wiki/*"

package/skills/j-uncharted/scripts/elicitation-state.sh

@@ -151,7 +151,21 @@ if [ -z "$REPO_ROOT" ]; then
   exit 2
 fi
 
-WITH_LOCK="$REPO_ROOT/scripts/with-lock.sh"
+# ─── Resolve with-lock.sh's package root ──────────────────────────────────
+# postinstall.js mirrors only skills/ and agents/ into a consumer's .claude/
+# and .agents/ — scripts/ (which owns with-lock.sh) is never copied there, so
+# this script — itself shipped under skills/j-uncharted/scripts/ and mirrored
+# alongside it — cannot assume "$REPO_ROOT/scripts/with-lock.sh" exists.
+# Mirrors skills/init/scripts/init.sh's PKG_ROOT fallback: prefer a monorepo
+# checkout's sibling scripts/ dir, else fall back to the installed npm
+# package under node_modules/@jenga-ai/agent.
+if [ -f "$SCRIPT_DIR/../../../scripts/with-lock.sh" ]; then
+  WITH_LOCK="$SCRIPT_DIR/../../../scripts/with-lock.sh"
+elif [ -f "$REPO_ROOT/node_modules/@jenga-ai/agent/scripts/with-lock.sh" ]; then
+  WITH_LOCK="$REPO_ROOT/node_modules/@jenga-ai/agent/scripts/with-lock.sh"
+else
+  WITH_LOCK="$REPO_ROOT/scripts/with-lock.sh"
+fi
 STATE_DIR="$REPO_ROOT/project/queue/elicitation-state"
 DEFAULT_CAP=5
 

package/skills/jenga/SKILL.md

@@ -132,13 +132,15 @@ If all applicable rules pass (or the task is a legacy task), proceed to the next
 
 ### Phase 0.75 — Entry Mode Resolution
 
-This phase determines **how `/jenga` was invoked** and, for two of the three entry modes, produces a **scoped set** — a confirmed list of board IDs (epics/stories/tasks) that Phases 1-4 must restrict themselves to. All board scanning, ID parsing, cascade expansion, and rendering used by this phase already live in `skills/jenga/scripts/` per this repo's "Scripts Over Inline Logic" principle — this phase never re-implements any of that logic inline. The executing agent's job here is limited to: invoking the right script with the right arguments, relaying its STDOUT verbatim to the user when the contract calls for that, capturing the `STATE_FILE:` line from STDERR for the next turn, and forwarding the user's raw reply back into the next invocation unmodified.
+This phase determines **how `/jenga` was invoked** and, for two of the four entry modes, produces a **scoped set** — a confirmed list of board IDs (epics/stories/tasks) that Phases 1-4 must restrict themselves to. All board scanning, ID parsing, cascade expansion, and rendering used by this phase already live in `skills/jenga/scripts/` per this repo's "Scripts Over Inline Logic" principle — this phase never re-implements any of that logic inline. The executing agent's job here is limited to: invoking the right script with the right arguments, relaying its STDOUT verbatim to the user when the contract calls for that, capturing the `STATE_FILE:` line from STDERR for the next turn, and forwarding the user's raw reply back into the next invocation unmodified.
 
 **Determine the invocation form** from the raw argument (if any) passed to `/jenga`:
 
 - No argument at all → **bare branch**.
 - The argument is the literal string `*` → **wildcard branch**.
-- Any other non-empty argument → **scoped branch** (treat the whole argument as the comma-separated raw ID list).
+- Any other non-empty argument → invoke `skills/jenga/scripts/detect-nl-intent.sh "<raw argument>"` (E53_S01_T01) and branch on its `classification` field:
+  - `all_resolved` or `mixed` → **scoped branch** (below) — this is the same branch as before; only its internal mechanics changed (see below).
+  - `nl_intent` → **natural-language branch** (below) — new for E53_S01, no new sigil or entry point, purely a new outcome of this same argument-shape detection.
 
 #### Wildcard branch (`/jenga *`)
 
@@ -154,10 +156,35 @@ Skip both the picker and the confirmation step entirely. There is no scoped set
 
 #### Scoped branch (`/jenga <ids>`)
 
-1. Invoke `skills/jenga/scripts/resolve-id.sh "<raw argument>"` directly — the picker is skipped entirely in this branch.
-2. Parse the JSON array response, one object per comma-delimited input segment.
-   - If **every** segment has `status: "resolved"`, collect their `resolved_id` values into a comma-separated list and continue to the shared confirmation step below.
-   - If **any** segment has `status: "rejected"`, halt this phase (do not proceed to confirmation or Phase 1) and report each rejected segment's `input` and `reason` to the user verbatim, per `resolve-id.sh`'s own contract — a partial or ambiguous ID is never guessed. The user must re-invoke `/jenga <ids>` with corrected input.
+This branch is entered when `detect-nl-intent.sh` (invoked above) classifies the argument as `all_resolved` or `mixed` — the picker is skipped entirely in this branch. `detect-nl-intent.sh` has already invoked `resolve-id.sh` internally and reduced its per-segment output to one of these two shapes; `skills/jenga/SKILL.md` never parses `resolve-id.sh`'s raw array itself (see `detect-nl-intent.sh`'s own header comment for the full classification contract, E53_S01_T01).
+
+1. On `all_resolved`, take the `resolved_ids` (or `resolved_ids_csv`) field directly from `detect-nl-intent.sh`'s output and continue to the shared confirmation step below.
+2. On `mixed`, halt this phase (do not proceed to confirmation or Phase 1) and report each entry in `detect-nl-intent.sh`'s `rejected` array — its `input` and `reason` — to the user verbatim; a partial or ambiguous ID is never guessed. The user must re-invoke `/jenga <ids>` with corrected input.
+
+#### Natural-language branch (`/jenga <free-form text>`)
+
+This branch is entered when `detect-nl-intent.sh` classifies the argument as `nl_intent` — every comma-delimited segment failed the ID grammar, so the raw argument is treated as natural-language intent rather than a malformed ID list. This is purely a new *outcome* of the same argument-shape detection above — no new sigil, trigger prefix, or separate entry point is introduced.
+
+1. **Load the catalog** — invoke `skills/jenga/scripts/load-nl-catalog.sh` with no arguments (E53_S01_T02). Its stdout is the full skill catalog (`name`/`description`/`keywords`/`examples`/`prefered_agent` per skill), sourced exclusively from `lib/generate-skill-allow-list.js`'s generated inventory — see the script's own header for the full contract. Never re-derive this catalog by re-scanning `skills/` inline.
+2. **Match** — run `skills/route/SKILL.md`'s **Step 2 — Match the Prompt to a Skill** (the three-pass keyword → example-similarity → description match, including its tie-break and no-match handling) against this catalog, treating `detect-nl-intent.sh`'s `raw_argument` field as the prompt. Reuse that section's matching logic by reference — do not re-author its prose here.
+3. **Confident single match** — report the routing decision using `skills/route/SKILL.md`'s **Step 7 — Report Routing Decision** format (substitute `/jenga` for `/route` as the invoking command named in the report), then invoke the matched skill exactly as `skills/route/SKILL.md`'s **Step 6 — Invoke the Matched Skill** already does: load `agents/<prefered_agent>.md` when the matched skill specifies `metadata.prefered_agent`, otherwise execute the skill instructions directly. The matched skill's own execution takes over from here — do not continue into this `/jenga` invocation's Phase 1.
+4. **No match, or an ambiguous multi-way tie (single-skill match)** — before surfacing `/route`'s generic disambiguation options, attempt a **playbook fallback** (E53_S02): invoke `skills/jenga/scripts/match-playbook.sh "<raw_argument>"`. This step only ever runs when step 3 above did NOT already commit to a confident single-skill match — a confident single-skill match always wins outright and this playbook fallback is never even invoked in that case. Branch on `match-playbook.sh`'s `classification` field:
+   - `playbook_match` → continue to **step 5 (Playbook proposal and execution)** below.
+   - `ambiguous` or `no_match` → continue to **step 6 (Fall through to `/route`'s disambiguation)** below — the exact behavior this branch already had before E53_S02, unchanged.
+5. **Playbook proposal and execution** — entered only on a `playbook_match` result from step 4. A proposed playbook is an ordered chain of skills (e.g. the canonical `brainstorm -> j.todo -> j.do -> j.dev-done -> j.mirror-public` chain defined in `skills/jenga/playbooks/brainstorm-to-mirror.json`) that must be confirmed, editable, and confirmable per `CLAUDE.md`'s Interaction Pattern before any step executes — the same confirm-before-execute posture `/jenga` already applies to the bare/scoped branches via `render-confirmation.sh`.
+   a. **Render and confirm the chain** — invoke `skills/jenga/scripts/render-playbook-confirmation.sh "<playbook_id>" "<name>" "<comma-separated steps>"` (start mode, using `match-playbook.sh`'s `playbook_id`/`name`/`steps` fields verbatim). Relay STDOUT (the numbered chain + instructions) to the user verbatim. Capture the `STATE_FILE:` path from STDERR.
+   b. Wait for the user's chat reply, then invoke `skills/jenga/scripts/render-playbook-confirmation.sh <state_file> "<raw_reply>"` (continue mode).
+      - **Toggle or error turn** (plain text on STDOUT, state file retained) — relay verbatim and return to step 5b for another reply. This loops exactly as the existing bare/scoped confirmation flow's own toggle/error turns already do.
+      - **Cancellation** — relay the cancellation acknowledgement and halt the entire `/jenga` invocation immediately, with no step executed — identical posture to the existing picker/confirmation cancellation edge cases already documented for the bare/scoped branches (see "## Edge Cases" below).
+      - **Confirmed** (JSON object on STDOUT, state file removed) — take the confirmed `steps` array (checked-only, in original playbook order) and continue to step 5c.
+   c. **Initialize the sequential runner** — invoke `skills/jenga/scripts/run-playbook-step.sh init "<playbook_id>" "<name>" "<comma-separated confirmed steps>"`. Its `step_ready` result names the first step to invoke.
+   d. **Execute steps in a loop** — for the step named by the runner's most recent `step_ready` result:
+      i. Invoke that step exactly as `skills/route/SKILL.md`'s **Step 6 — Invoke the Matched Skill** already does for a single matched skill: load `agents/<prefered_agent>.md` when that step's own `SKILL.md` specifies `metadata.prefered_agent`, otherwise execute its instructions directly.
+      ii. After that step's execution concludes, call `skills/jenga/scripts/run-playbook-step.sh advance <state_file> passed` (the step completed successfully) or `... advance <state_file> failed "<short failure note>"` (the step failed).
+      iii. On a `step_ready` result, repeat step 5d for the newly-named step.
+      iv. On a `complete` result, report the full list of completed steps to the user and stop — the playbook run is finished; do not continue into this `/jenga` invocation's Phase 1.
+      v. On a `halted` result, **immediately stop executing any further steps** — no silent skip-ahead. Report `failed_step`, `failed_note`, `completed` (steps that already finished), and `never_run` (steps that never got a chance to run) to the user verbatim from the halt report. Do not continue into this `/jenga` invocation's Phase 1.
+6. **Fall through to `/route`'s disambiguation** — entered when step 4 found no playbook match (`ambiguous` or `no_match`). Surface the same disambiguation options `skills/route/SKILL.md`'s **Step 2** already defines for these cases (browse `/help`, create a new skill via `/btw`, or proceed with the raw prompt) by reference to that section — do not re-copy its prose. Halt this `/jenga` invocation once the user picks an option; none of Phase 0.75's remaining steps or Phases 1-4 run for this branch.
 
 #### Shared confirmation step (bare and scoped branches only)
 
@@ -255,6 +282,11 @@ When no eligible candidates remain in Phase 4, exit and output:
 - **Bundle `/do` call failure** — treated as a skip for the entire bundle; mark all bundled tasks' status back to `Pending` and continue Phase 4 with remaining non-bundled candidates.
 - **Picker cancelled (bare branch)** — the entire `/jenga` run halts immediately after relaying the cancellation acknowledgement; no phase past 0.75 runs, and nothing on the board is modified.
 - **Confirmation cancelled (bare or scoped branch)** — same as picker cancellation: the entire `/jenga` run halts immediately; no scoped set is produced and no later phase runs.
-- **`resolve-id.sh` rejects one or more segments (scoped branch)** — the whole invocation halts at Phase 0.75 with the rejected segments' reasons reported verbatim; no partial scope is assembled from the segments that did resolve, and no fallback guess is made for the rejected ones. The user must re-invoke `/jenga <ids>` with corrected input.
+- **`detect-nl-intent.sh` classifies the argument as `mixed` (scoped branch)** — the whole invocation halts at Phase 0.75 with each rejected segment's `input`/`reason` reported verbatim, per `detect-nl-intent.sh`'s own classification contract (E53_S01_T01); no partial scope is assembled from the segments that did resolve, and no fallback guess is made for the rejected ones. The user must re-invoke `/jenga <ids>` with corrected input.
+- **`detect-nl-intent.sh` classifies the argument as `nl_intent`, no confident single-skill match, and `match-playbook.sh` (E53_S02) also finds no playbook match** — the natural-language branch's step 4 attempts the playbook fallback first (see the Natural-language branch's step 4/6), and only THEN surfaces `skills/route/SKILL.md`'s Step 2 no-match disambiguation options (browse `/help`, create a new skill via `/btw`, proceed with the raw prompt) instead of guessing; no phase past 0.75 runs until the user picks one.
+- **`detect-nl-intent.sh` classifies the argument as `nl_intent`, no confident single-skill match, and `match-playbook.sh` returns an ambiguous multi-way tie between playbooks** — treated the same as the no-playbook-match case above: falls through to `skills/route/SKILL.md`'s Step 2 tie-break prompt (top candidates + a "neither, describe what you need" option) instead of guessing; no phase past 0.75 runs until the user picks one. (`match-playbook.sh`'s own `ambiguous` result — a tie between playbooks — is intentionally not given its own separate disambiguation UI; it is treated identically to `no_match` and routed to the same `/route` Step 2 fallback prose, which already has its own tie-break handling.)
+- **`match-playbook.sh` returns `playbook_match` and the user confirms the full chain, and every step succeeds** — the Natural-language branch's step 5d reports the full `completed` steps list to the user and stops; `/jenga`'s own Phase 1 never runs for this invocation (execution was already fully handled by the playbook's own steps, e.g. `j.do`/`j.dev-done`).
+- **`match-playbook.sh` returns `playbook_match` but the user cancels at the chain confirmation step (step 5b)** — identical posture to the existing picker/confirmation cancellation cases above: the entire `/jenga` run halts immediately after relaying the cancellation acknowledgement, with NO step of the chain executed; nothing on the board is modified by this invocation.
+- **`match-playbook.sh` returns `playbook_match`, the user confirms, and a step mid-chain fails** — the Natural-language branch's step 5d(v) halts immediately on `run-playbook-step.sh`'s `halted` result: no step after the failed one runs (no silent skip-ahead), and the user is shown exactly which steps already completed, which step failed (with its note), and which steps never ran.
 - **`/jenga *` (wildcard branch)** — never produces a scoped set; Phases 1-4 run fully unrestricted over the entire board, identical to `/jenga`'s behavior before Phase 0.75 existed.
 - **Stale out-of-scope story queued in `todo.md` from an earlier run (scoped run only)** — Phase 3.5's scoped-set guard skips it entirely (not considered for bundling), so it cannot be dispatched via a bundle `/do <E##_S##>` call that would otherwise bypass Phase 4's own scoped-set exclusion; it remains untouched in `todo.md` until a future run's scope includes it.

package/skills/jenga/playbooks/brainstorm-to-mirror.json

@@ -0,0 +1,22 @@
+{
+  "id": "brainstorm-to-mirror",
+  "name": "Idea to Public Release",
+  "description": "Takes a rough idea all the way from planning through implementation, committing, and a public mirror release -- the canonical end-to-end Jenga workflow chain.",
+  "keywords": [
+    "idea to release",
+    "plan and ship",
+    "idea to done",
+    "full workflow",
+    "end to end",
+    "plan build ship",
+    "idea to production"
+  ],
+  "examples": [
+    "I have an idea, help me plan it, build it, and ship it",
+    "take this feature from idea to committed and published",
+    "let's go from a rough idea all the way to a public release",
+    "plan this out, implement it, commit it, and push it to the public mirror",
+    "walk this through the whole pipeline from brainstorm to release"
+  ],
+  "steps": ["brainstorm", "todo", "do", "dev-done", "mirror-public"]
+}

package/skills/jenga/playbooks/schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jenga.local/schemas/jenga-playbook.schema.json",
+  "title": "Jenga Multi-Skill Playbook",
+  "description": "Schema for a single multi-skill playbook definition consumed by skills/jenga/scripts/load-playbooks.sh (E53_S02_T01). A playbook is a dedicated, versionable data file describing an ORDERED chain of skills that /jenga's natural-language branch may propose (as an editable, confirmable numbered list -- see skills/jenga/scripts/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 via skills/route/SKILL.md's Step 2 matching. This file itself (schema.json) is never treated as a playbook -- load-playbooks.sh explicitly excludes it by filename when scanning skills/jenga/playbooks/*.json.",
+  "type": "object",
+  "required": ["id", "name", "description", "keywords", "examples", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable, unique, kebab-case identifier for this playbook (e.g. \"brainstorm-to-mirror\"). Must equal the filename's basename without the .json extension -- load-playbooks.sh validates this so a playbook's id can never silently drift from its file location.",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "name": {
+      "type": "string",
+      "description": "Short human-readable display name shown to the user in the confirmation prompt and in routing/report output, e.g. \"Idea to Public Release\"."
+    },
+    "description": {
+      "type": "string",
+      "description": "One-sentence explanation of what this playbook accomplishes end-to-end, used as the lowest-priority match signal (description match, same as skills/route/SKILL.md's Step 2 Pass 3) when keywords/examples don't produce a confident match."
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Short phrases (1-3 words) for verbatim, case-insensitive keyword matching against the raw natural-language prompt -- the highest-priority match signal (Pass 1), mirroring skills/route/SKILL.md's Step 2 Pass 1 semantics exactly, but scoped to this playbook's catalog rather than the single-skill catalog.",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "examples": {
+      "type": "array",
+      "description": "Natural-language example prompts a user might type that should resolve to this playbook. Used for the semantic similarity match (Pass 2), mirroring skills/route/SKILL.md's Step 2 Pass 2 semantics. At least one example must plausibly span the full breadth of this playbook's steps (not just its first step) so it is distinguishable from a plain single-skill match.",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "steps": {
+      "type": "array",
+      "description": "Ordered list of bare skill names (the directory name under skills/<name>/SKILL.md, e.g. \"brainstorm\", not \"j.brainstorm\" or \"/brainstorm\") that make up this playbook's chain, in the exact execution order. Each entry MUST resolve to an existing skills/<name>/SKILL.md at load time -- load-playbooks.sh skips (with a stderr warning) any playbook referencing a nonexistent skill rather than silently including a broken chain in the catalog.",
+      "items": { "type": "string" },
+      "minItems": 2
+    }
+  }
+}