@jenga-ai/agent 2.0.0 → 3.0.0

package/agents/tester.md

@@ -167,7 +167,7 @@ Always include the sender object in the response.
 
 **Trigger.** During steps 4-6 of "Invoked for test implementation and/or execution" above, you find a defect. Before defaulting to step 9's rapport path, classify it: is this **mechanical** (safe to fix in place) or does it **need a rapport** (a design decision or real risk is involved)? This classification is what determines which of the two remediation paths below you take — it is not optional bookkeeping, and it happens at the moment the defect is found, not retroactively.
 
-**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j:self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
+**Motivating case.** `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md` Finding 3: the tester found `skills/dev-done/scripts/classify-commit-outcome.sh` committed without its executable bit (`chmod +x`) plus a dead, unreachable error branch. Both were one-line-class fixes, but the only path available at the time was the full formal one — a `test_failure` rapport, a separate developer fix commit, a re-verification pass, and a second complete `j.self-sync` mirror run. That produced 3 of the task's 6 total commits for defects that needed no design judgment at all. This subsection exists so that pattern doesn't repeat.
 
 **Qualifying examples (mechanical — fix in place).**
 - A missing executable bit or other permission-bit error (e.g. a script committed without `chmod +x`) — the exact E42_S04 Finding 3 case.
@@ -258,11 +258,11 @@ Append this as a new array entry — never overwrite existing log content. This
 
 **Trigger.** The task being verified — or its parent story — carries `crucial_level: locked` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
 
-**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j:jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
+**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j.jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03). As tester, verify this field is actually `inline` on any `locked` item you're validating — a value that slipped through would itself be a defect worth flagging.
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j:jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of its `execution_scope` value. This is enforced at two points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)** and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**. This matters directly to you as tester: you must never yourself dispatch, recommend, or improvise a background subagent, a separate worktree-isolated session, or a bundled batch run in order to verify a `locked` item faster or in parallel with other work — verification of a `locked` item happens in the same foreground session the guards already pinned it to, same as implementation.
 
-**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j:do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
+**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j.do` guards above) before the developer ever begins work — none of this depends on you noticing or remembering anything mid-verification. Your only obligation is to recognize that a `locked` task always runs (and was always verified) in the current foreground session, and to never suggest or perform a workaround that would route around that guarantee. If you find evidence during verification that a `locked` item was actually run in a backgrounded or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to silently pass.
 
 ### Invoked for analysis or comparison testing
 When invoked to run an analysis or comparison:
@@ -455,7 +455,7 @@ There is no default analytics run. Analytics only happen when explicitly scoped
 
 ## Investigative Mode
 
-**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `j:uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
+**Trigger.** You are sometimes dispatched not to validate a task's implementation, but purely to build understanding of what the existing test suite actually covers for a named flow or target — e.g. by the scrum-master during `j.uncharted`'s conversational architecture elicitation, alongside the developer's Investigative Mode pass over the same flow. This is a distinct dispatch mode from the standard Sender Object / Task Intake / Status Management flow above, recognized by the request itself (you are asked to *trace coverage*, not to *validate a task*), not by any board field.
 
 **Hard constraints.** Investigative Mode is strictly read-only:
 - No worktree is created for write purposes, no test files are written or modified, no test runs that mutate state, no dependency installs.

package/lib/generate-skill-allow-list.js

@@ -55,10 +55,16 @@ function extractName(content) {
   const nameMatch = fmMatch[1].match(/^name:\s*(.+)$/m);
   if (!nameMatch) return null;
   const rawName = nameMatch[1].trim().replace(/^["']|["']$/g, "");
-  // Frontmatter may carry either the pre-E50_S01 bare form or the post-rename "j:<name>" form
-  // (skills/*/SKILL.md was migrated in E50_S01_T02) — strip the prefix so the allow-list always
+  // Frontmatter may carry the pre-E50_S01 bare form, the E50_S01 "j:<name>" form, or the
+  // current "j.<name>" form (E50_S07_T01 swapped the separator because GitHub Copilot CLI
+  // rejects ":" in a skill name) — strip whichever prefix is present so the allow-list always
   // holds bare identifiers, matching mcp/router/skill-index.js's `bareName` handling.
-  return rawName.replace(/^j:/i, "");
+  //
+  // Both separators must stay accepted: this guard is the E50_S02 anti-masquerading check, and
+  // a normalizer that fails to strip silently populates the allow-list with prefixed entries
+  // ("j.brainstorm" instead of "brainstorm"), which no longer match what the guard compares
+  // against. That is a security-guard failure, not a cosmetic one.
+  return rawName.replace(/^j[.:]/i, "");
 }
 
 /**

package/lib/skill-allow-list.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-09-04T00:52:12.012Z",
-  "skill_count": 37,
+  "generated_at": "2026-09-06T15:53:37.575Z",
+  "skill_count": 36,
   "skills": [
     "brainstorm",
     "btw",
@@ -22,7 +22,6 @@
     "idea",
     "improve",
     "init",
-    "j-init",
     "jbp",
     "jenga",
     "jenga-permission-level",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "2.0.0",
-  "description": "Structured multi-agent development workflow for AI coding agents \u2014 scrum board, role-bounded scrum master / developer / tester agents, and 30+ slash-command skills. Works with Claude Code, GitHub Copilot, and Codex.",
+  "version": "3.0.0",
+  "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": {
     "access": "public"
@@ -54,36 +54,26 @@
     "url": "https://github.com/samwelmunga/jenga-npm/issues"
   },
   "keywords": [
-    "ai-agents",
+    "ai",
+    "agent",
     "agentic",
-    "agentic-workflow",
-    "multi-agent",
-    "agent-framework",
-    "ai-development",
+    "workflow",
+    "framework",
+    "engineering",
+    "development",
+    "coding",
+    "context",
+    "software",
+    "kanban",
+    "board",
+    "management",
     "claude",
     "claude-code",
     "agents-md",
     "copilot",
-    "github-copilot",
     "codex",
-    "skills",
-    "project-management",
-    "developer-tools",
-    "cli",
     "jenga",
-    "jenga-ai",
-    "ai-coding",
-    "ai-coding-agent",
-    "coding-agent",
-    "coding-agents",
-    "ai-workflow",
-    "coding-workflow",
-    "development-workflow",
-    "software-development",
-    "developer-workflow",
-    "ai-framework",
-    "agentic-engineering",
-    "ai-engineering"
+    "jenga-ai"
   ],
   "author": {
     "name": "Samwel Munga",

package/scripts/apply-j-prefix.sh

@@ -1,23 +1,29 @@
 #!/usr/bin/env bash
-# scripts/apply-j-prefix.sh — mechanical j: prefix rename for skill invocation
+# scripts/apply-j-prefix.sh — mechanical j. prefix rename for skill invocation
 #
 # Implements the mechanism decided in docs/skill-authoring.md's "Invocation Convention"
-# section (E50_S01_T01):
+# section (E50_S01_T01), with the separator corrected from ":" to "." in E50_S07_T01:
 #
 #   1. Frontmatter-only rename. For every skills/<name>/SKILL.md, rewrites the
-#      frontmatter `name:` field from `<name>` to `j:<name>`. Directory names are
-#      left untouched — ":" is not a Windows-safe filename character, and Claude
-#      Code's native skill resolution is a literal-string match against the
+#      frontmatter `name:` field from `<name>` to `j.<name>`. Directory names are
+#      left untouched — neither ":" nor "." is worth putting in a path here, and
+#      Claude Code's native skill resolution is a literal-string match against the
 #      discovery-path directory name, independent of frontmatter content (see the
 #      docs section for the full investigation and citation).
 #   2. Bare-form prose rewrite. For every agents/*.md file, rewrites bare
-#      "/<name>" invocation mentions in prose to "j:<name>", for every skill name
+#      "/<name>" invocation mentions in prose to "j.<name>", for every skill name
 #      discovered in step 1 — longest-name-first, boundary-safe (skill names
 #      contain hyphens, so a naive `\b` regex would misfire — e.g. it would
 #      falsely match "/doc" inside "/doc-sync"; this only rewrites a match when
 #      the character immediately before/after it is not itself an identifier
 #      character: letter, digit, "-", or ":").
 #
+# Separator history (E50_S07): this script originally emitted "j:<name>". GitHub
+# Copilot CLI validates the frontmatter `name:` VALUE and rejects anything outside
+# [A-Za-z0-9], hyphen, underscore, dot, and space — so the colon made every skill
+# fail to load there. The separator is now "." which is on that allow-list. The
+# namespace intent of E50 is unchanged; only the separator character moved.
+#
 # This script does NOT remove or disable the old bare "/<name>" form. The
 # migration decision recorded alongside the mechanism above is "alias" — both
 # forms keep resolving. This script only ever writes inside skills/ and
@@ -34,8 +40,10 @@
 #   --skills-only   Only process skills/*/SKILL.md frontmatter (step 1).
 #   --agents-only   Only process agents/*.md prose (step 2).
 #
-# Idempotent: already-migrated skills (name already starts with "j:") are
-# silently skipped, not re-applied or reported as an error.
+# Idempotent: already-migrated skills (name already starts with "j.") are
+# silently skipped, not re-applied or reported as an error. Skills still carrying
+# the legacy "j:<name>" form are REPAIRED to "j.<name>" rather than skipped —
+# skipping them would silently leave a Copilot-breaking name in place.
 
 set -euo pipefail
 
@@ -125,10 +133,15 @@ if os.path.isdir(skills_dir):
 
         skill_names.append(entry)
 
-        if current_name.startswith("j:"):
+        if current_name.startswith("j."):
             continue  # already migrated — not an error, nothing to do
 
-        if current_name != entry:
+        # Legacy "j:<name>" form (emitted by this script before E50_S07_T01).
+        # The colon is rejected by GitHub Copilot CLI's skill-name validator, so
+        # this is repaired to "j.<name>" rather than skipped as "already migrated".
+        base_name = current_name[2:] if current_name.startswith("j:") else current_name
+
+        if base_name != entry:
             errors.append(
                 f"{skill_path}: frontmatter name '{current_name}' does not match "
                 f"directory name '{entry}' — skipped for safety"
@@ -138,7 +151,7 @@ if os.path.isdir(skills_dir):
         if not do_skills:
             continue
 
-        new_line = f"name: j:{entry}\n"
+        new_line = f"name: j.{entry}\n"
         changes.append({
             "type": "frontmatter",
             "file": skill_path,
@@ -185,7 +198,7 @@ if do_agents and os.path.isdir(agents_dir):
                     continue  # e.g. "/doc" inside "/doc-sync"
                 matches.append((start, end))
             for start, end in reversed(matches):
-                text = text[:start] + f"j:{name}" + text[end:]
+                text = text[:start] + f"j.{name}" + text[end:]
                 file_changes += 1
 
         if file_changes:

package/scripts/generate-j-alias.sh

@@ -0,0 +1,333 @@
+#!/usr/bin/env bash
+# scripts/generate-j-alias.sh — generate/sync a j-<name> polyfill alias skill directory
+#
+# Mechanizes the hand-maintained pattern that produced skills/j-init/ (E50_S04): a
+# literal-directory-name duplicate of skills/<name>/ that gives a guaranteed-unshadowed
+# way to reach a skill even when a host tool's own built-in command of the same name
+# would otherwise shadow the bare /<name> form. Per CLAUDE.md's Skill Implementation
+# Principle, this must not be repeated by hand across every skill — this script performs
+# both the initial generation and any later resync-after-source-change as a single
+# deterministic command (E50_S05_T01).
+#
+# For the given <skill-name>, this script:
+#   1. Copies the full skills/<skill-name>/ tree into skills/j-<skill-name>/, overwriting
+#      the destination on re-run (the sync case).
+#   2. Rewrites every self-referential "skills/<skill-name>/" path reference inside the
+#      copied SKILL.md and any copied scripts to "skills/j-<skill-name>/" — including the
+#      .claude/skills/<skill-name>/ and .agents/skills/<skill-name>/ mirrored-install
+#      fallback paths, which fall out of the same literal substring replace.
+#   3. Rewrites the copied SKILL.md's frontmatter: name: j.<skill-name> -> name:
+#      j.j-<skill-name>; description: reframed as a polyfill alias; keywords: gets
+#      j-<skill-name> and polyfill appended (existing keywords preserved, list created
+#      if absent); examples: gets a "j-<skill-name>" example appended if the list exists.
+#   4. Inserts a short, programmatically generated lockstep/duplicate-alias note near the
+#      top of the body.
+#
+# Idempotent: the target directory is always fully rebuilt from the source on every run
+# (never incrementally patched), so two runs against an unchanged source produce a
+# byte-identical result, and a source change is picked up in full on the next run.
+#
+# Exclusions:
+#   - Only operates on directories containing a SKILL.md (skips e.g. skills/index/,
+#     which has no SKILL.md and is not part of skill routing) — enforced as a hard error,
+#     not a silent no-op, so a typo'd or non-skill argument fails clearly.
+#   - Refuses to touch the skills/init/ <-> skills/j-init/ pair — that pair already
+#     exists, is hand-maintained, and is explicitly out of scope for this story.
+#   - Refuses to touch skills/jenga/ or skills/jenga-permission-level/ (and their would-be
+#     j-jenga/j-jenga-permission-level twins) — hard error, non-zero exit (E50_S06_T01).
+#     These are root orchestrator commands; their invocation surface must stay exactly
+#     /jenga (j.jenga) and /jenga-permission-level (j.jenga-permission-level), never a
+#     doubled j-jenga alias. A prior generic run of this generator produced exactly that
+#     unreachable doubled twin by mistake — see docs/skill-authoring.md's "j-<name>
+#     directory twins" Exclusions paragraph.
+#
+# This is a single-skill generator only. Running it across every skill in the repo is a
+# separate task (E50_S05_T02) — deliberately not built here.
+#
+# Usage:
+#   scripts/generate-j-alias.sh <skill-name>
+#
+# Examples:
+#   scripts/generate-j-alias.sh status      # generates/syncs skills/j-status/
+#   scripts/generate-j-alias.sh close-story # generates/syncs skills/j-close-story/
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/resolve-project-dir.sh
+source "$SCRIPT_DIR/../lib/resolve-project-dir.sh"
+
+PROJECT_DIR="$JENGA_PROJECT_DIR"
+SKILLS_DIR="$PROJECT_DIR/skills"
+
+usage() {
+  echo "Usage: $(basename "$0") <skill-name>" >&2
+  echo "  Generates/syncs skills/j-<skill-name>/ as a polyfill alias of skills/<skill-name>/." >&2
+}
+
+if [ "$#" -ne 1 ]; then
+  usage
+  exit 1
+fi
+
+case "$1" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+esac
+
+SKILL_NAME="$1"
+
+# Security guard (E50_S05_T01 rework — see
+# project/rapports/problems/E50_S05_T01-generator-path-traversal.md): validate
+# the skill-name argument BEFORE any path is constructed from it, let alone
+# before anything destructive runs. An unsanitized argument containing '/' or
+# '..' segments previously let SRC_DIR/TARGET_DIR (built by plain string
+# concatenation below) resolve outside $SKILLS_DIR, and the destructive
+# rmtree-then-copytree step ran before the one existing safety check
+# (frontmatter name match) ever fired. This allowlist alone closes that vector
+# — it forbids '/' and '.' entirely — and runs first, ahead of every other
+# check including the init/j-init special-case below.
+if [[ ! "$SKILL_NAME" =~ ^[a-z0-9][a-z0-9_-]*$ ]]; then
+  echo "generate-j-alias.sh: error: '$SKILL_NAME' is not a valid skill name — must match ^[a-z0-9][a-z0-9_-]*\$ (lowercase letters, digits, '-', '_' only, starting with a letter or digit). Refusing to construct a path from it." >&2
+  exit 1
+fi
+
+if [[ "$SKILL_NAME" == "init" || "$SKILL_NAME" == "j-init" ]]; then
+  echo "generate-j-alias.sh: refusing to touch '$SKILL_NAME' — the skills/init/ <-> skills/j-init/ pair already exists and is hand-maintained (out of scope for this generator, E50_S05). No-op." >&2
+  exit 0
+fi
+
+# Hard exclusion (E50_S06_T01): jenga and jenga-permission-level are root orchestrator
+# commands whose invocation surface must stay exactly /jenga (j.jenga) and
+# /jenga-permission-level (j.jenga-permission-level) — never a doubled j-jenga alias.
+# Unlike the init/j-init case above (a silent no-op, exit 0, because that pair is
+# legitimately hand-maintained and pre-dates this generator), this is a hard error with a
+# non-zero exit: a j-jenga/j-jenga-permission-level twin should never be generated at all,
+# so a future accidental invocation must fail loudly rather than silently succeed as a
+# no-op. See docs/skill-authoring.md's "j-<name> directory twins" Exclusions paragraph.
+if [[ "$SKILL_NAME" == "jenga" || "$SKILL_NAME" == "j-jenga" || "$SKILL_NAME" == "jenga-permission-level" || "$SKILL_NAME" == "j-jenga-permission-level" ]]; then
+  echo "generate-j-alias.sh: error: refusing to generate a j-<name> twin for '$SKILL_NAME' — jenga and jenga-permission-level are root orchestrator commands and are hard-excluded from this generator (E50_S06_T01). Their invocation surface must stay exactly /jenga (j.jenga) and /jenga-permission-level (j.jenga-permission-level), never a doubled j-jenga alias. This is not a no-op — it is an intentional hard failure." >&2
+  exit 1
+fi
+
+SRC_DIR="$SKILLS_DIR/$SKILL_NAME"
+SRC_SKILL_MD="$SRC_DIR/SKILL.md"
+
+if [ ! -f "$SRC_SKILL_MD" ]; then
+  echo "generate-j-alias.sh: error: '$SRC_DIR' does not contain a SKILL.md — not a skill directory, refusing to generate skills/j-$SKILL_NAME/." >&2
+  exit 1
+fi
+
+TARGET_DIR="$SKILLS_DIR/j-$SKILL_NAME"
+
+# Defense in depth (belt and suspenders on top of the allowlist above):
+# resolve SRC_DIR/TARGET_DIR to absolute canonical paths and hard-fail unless
+# each is confined to a direct child of $SKILLS_DIR. This protects against the
+# allowlist regex being weakened in a future edit, or $SKILLS_DIR itself
+# containing a symlink that could redirect an otherwise-validated path outside
+# skills/. Both checks below run before the python heredoc, i.e. strictly
+# before any rmtree/copytree call.
+REAL_SKILLS_DIR="$(realpath "$SKILLS_DIR")"
+REAL_SRC_DIR="$(realpath "$SRC_DIR")"
+if [ "$(dirname "$REAL_SRC_DIR")" != "$REAL_SKILLS_DIR" ]; then
+  echo "generate-j-alias.sh: error: resolved source path '$REAL_SRC_DIR' escapes '$REAL_SKILLS_DIR' — refusing to proceed." >&2
+  exit 1
+fi
+
+# TARGET_DIR may not exist yet (first-run generation case), and this
+# platform's realpath has no -m/--canonicalize-missing option, so it can't be
+# realpath'd directly when absent. Its parent is always $SKILLS_DIR by
+# construction (SKILL_NAME is a single path component, and the allowlist above
+# already forbids '/' and '..' in it), so check the literal parent/basename
+# shape here, and additionally realpath the target itself when it already
+# exists (the resync case) to catch a symlink planted at the target that
+# points outside skills/.
+TARGET_BASENAME="$(basename "$TARGET_DIR")"
+if [[ "$TARGET_BASENAME" == "." || "$TARGET_BASENAME" == ".." || "$TARGET_BASENAME" == */* ]]; then
+  echo "generate-j-alias.sh: error: computed target basename '$TARGET_BASENAME' is unsafe — refusing to proceed." >&2
+  exit 1
+fi
+if [ "$(dirname "$TARGET_DIR")" != "$SKILLS_DIR" ]; then
+  echo "generate-j-alias.sh: error: computed target path '$TARGET_DIR' does not resolve directly under '$SKILLS_DIR' — refusing to proceed." >&2
+  exit 1
+fi
+if [ -e "$TARGET_DIR" ] || [ -L "$TARGET_DIR" ]; then
+  REAL_TARGET_DIR="$(realpath "$TARGET_DIR")"
+  if [ "$(dirname "$REAL_TARGET_DIR")" != "$REAL_SKILLS_DIR" ]; then
+    echo "generate-j-alias.sh: error: resolved target path '$REAL_TARGET_DIR' escapes '$REAL_SKILLS_DIR' — refusing to proceed." >&2
+    exit 1
+  fi
+fi
+
+export SKILL_NAME SRC_DIR TARGET_DIR
+
+python3 - <<'PY'
+import os
+import re
+import shutil
+import sys
+
+skill_name = os.environ["SKILL_NAME"]
+src_dir = os.environ["SRC_DIR"]
+target_dir = os.environ["TARGET_DIR"]
+
+old_ref = f"skills/{skill_name}/"
+new_ref = f"skills/j-{skill_name}/"
+
+# ---- 1. Copy the full tree, overwriting the destination (the sync case) ----
+if os.path.lexists(target_dir):
+    shutil.rmtree(target_dir)
+shutil.copytree(src_dir, target_dir, symlinks=True)
+
+# ---- 2. Rewrite self-referential paths in every copied file ----
+for dirpath, _dirnames, filenames in os.walk(target_dir):
+    for fn in filenames:
+        fpath = os.path.join(dirpath, fn)
+        try:
+            with open(fpath, "r", encoding="utf-8") as fh:
+                content = fh.read()
+        except (UnicodeDecodeError, OSError):
+            continue  # binary or unreadable — leave untouched
+        if old_ref in content:
+            with open(fpath, "w", encoding="utf-8") as fh:
+                fh.write(content.replace(old_ref, new_ref))
+
+# ---- 3. Rewrite SKILL.md frontmatter + insert the lockstep note ----
+target_skill_md = os.path.join(target_dir, "SKILL.md")
+with open(target_skill_md, "r", encoding="utf-8") as fh:
+    lines = fh.readlines()
+
+if not lines or lines[0].strip() != "---":
+    sys.exit(f"generate-j-alias.sh: error: {target_skill_md} has no opening '---' frontmatter marker")
+
+close_idx = None
+for idx in range(1, len(lines)):
+    if lines[idx].strip() == "---":
+        close_idx = idx
+        break
+if close_idx is None:
+    sys.exit(f"generate-j-alias.sh: error: {target_skill_md} has no closing '---' frontmatter marker")
+
+# Parse the frontmatter into an ordered list of top-level fields. This is the same
+# informal line-oriented approach scripts/apply-j-prefix.sh already uses elsewhere in
+# this repo for SKILL.md frontmatter — not a full YAML parser, consistent with how
+# frontmatter is already handled here.
+key_re = re.compile(r'^([A-Za-z_][\w-]*):(.*)$')
+fields = []
+i = 1
+while i < close_idx:
+    line = lines[i]
+    m = key_re.match(line)
+    if not m:
+        i += 1
+        continue
+    block = [line]
+    j = i + 1
+    if m.group(2).strip() == "":
+        # possible nested block (list or mapping) — consume indented continuation lines
+        while j < close_idx and lines[j].startswith(" "):
+            block.append(lines[j])
+            j += 1
+    fields.append({"key": m.group(1), "lines": block})
+    i = j
+
+
+def find_field(key):
+    for f in fields:
+        if f["key"] == key:
+            return f
+    return None
+
+
+name_field = find_field("name")
+desc_field = find_field("description")
+
+if name_field is None or len(name_field["lines"]) != 1:
+    sys.exit(f"generate-j-alias.sh: error: {target_skill_md} has no single-line 'name:' field")
+if desc_field is None or len(desc_field["lines"]) != 1:
+    sys.exit(f"generate-j-alias.sh: error: {target_skill_md} has no single-line 'description:' field")
+
+current_name = key_re.match(name_field["lines"][0]).group(2).strip().strip('"\'')
+# Accepts the current "j.<name>" form, the bare "<name>" form, and the legacy
+# "j:<name>" form (pre-E50_S07_T01) so a twin can still be regenerated from a
+# not-yet-migrated source instead of hard-aborting. Whatever the source carries,
+# the twin is always emitted on the current "j." separator.
+if current_name not in (f"j.{skill_name}", f"j:{skill_name}", skill_name):
+    sys.exit(
+        f"generate-j-alias.sh: error: frontmatter name '{current_name}' in {target_skill_md} "
+        f"does not match expected 'j.{skill_name}' (or bare '{skill_name}') — refusing to guess, aborting."
+    )
+name_field["lines"][0] = f"name: j.j-{skill_name}\n"
+
+original_desc = key_re.match(desc_field["lines"][0]).group(2).strip().strip('"\'').rstrip(".")
+new_desc = (
+    f"Polyfill alias of the {skill_name} skill under a collision-safe directory name. "
+    f"Identical behavior to /{skill_name} — {original_desc}. "
+    f"Use when the bare /{skill_name} form is shadowed by another tool's own built-in "
+    f"command of the same name."
+)
+desc_field["lines"][0] = f"description: {new_desc}\n"
+
+keywords_field = find_field("keywords")
+if keywords_field is not None:
+    keywords_field["lines"].append(f"  - j-{skill_name}\n")
+    keywords_field["lines"].append("  - polyfill\n")
+else:
+    fields.append({
+        "key": "keywords",
+        "lines": ["keywords:\n", f"  - j-{skill_name}\n", "  - polyfill\n"],
+    })
+
+examples_field = find_field("examples")
+if examples_field is not None:
+    examples_field["lines"].append(f'  - "j-{skill_name}"\n')
+# if absent: per spec, do not fabricate an examples: list where none existed
+
+new_frontmatter_lines = []
+for f in fields:
+    new_frontmatter_lines.extend(f["lines"])
+
+body_lines = lines[close_idx + 1:]
+
+note_text = (
+    f"This skill is a literal-directory-name duplicate of `skills/{skill_name}/`. It exists so "
+    f"that `/j-{skill_name}` (and `j.j-{skill_name}`) give a guaranteed-unshadowed way to reach "
+    f"the same flow as `/{skill_name}`, even if a host tool's own built-in command of the same "
+    f"name would otherwise shadow or override the bare `/{skill_name}` alias (Claude Code's "
+    f"native skill resolution is a literal-string, directory-name-based match — see "
+    f"`docs/skill-authoring.md`'s \"Invocation Convention\").\n\n"
+    f"This file is generated/synced by `scripts/generate-j-alias.sh {skill_name}` from "
+    f"`skills/{skill_name}/SKILL.md` — do not hand-edit it; re-run the generator instead to "
+    f"pick up source changes."
+)
+note_block = []
+for para in note_text.split("\n\n"):
+    note_block.append(para + "\n")
+    note_block.append("\n")
+
+heading_idx = None
+for idx, bl in enumerate(body_lines):
+    if bl.startswith("# "):
+        heading_idx = idx
+        break
+
+if heading_idx is not None:
+    insert_at = heading_idx + 1
+    if insert_at < len(body_lines) and body_lines[insert_at].strip() == "":
+        insert_at += 1
+    prefix = body_lines[:insert_at]
+    if prefix and prefix[-1].strip() != "":
+        prefix = prefix + ["\n"]
+    new_body_lines = prefix + note_block + body_lines[insert_at:]
+else:
+    new_body_lines = note_block + body_lines
+
+new_lines = [lines[0]] + new_frontmatter_lines + [lines[close_idx]] + new_body_lines
+
+with open(target_skill_md, "w", encoding="utf-8") as fh:
+    fh.writelines(new_lines)
+
+print(f"generate-j-alias.sh: generated/synced skills/j-{skill_name}/ from skills/{skill_name}/")
+PY

package/skills/{brainstorm → j-brainstorm}/SKILL.md

@@ -1,21 +1,28 @@
 ---
-name: j:brainstorm
-description: Engage the scrum-master agent in a focused planning session to define, refine, or challenge features, improvements, tasks, stories, and epics. The agent asks probing questions, challenges assumptions, and helps shape ideas into actionable backlog items.
+name: j.brainstorm
+description: Polyfill alias of the brainstorm skill under a collision-safe directory name. Identical behavior to /brainstorm — Engage the scrum-master agent in a focused planning session to define, refine, or challenge features, improvements, tasks, stories, and epics. The agent asks probing questions, challenges assumptions, and helps shape ideas into actionable backlog items. Use when the bare /brainstorm form is shadowed by another tool's own built-in command of the same name.
 keywords:
   - brainstorm
   - plan
   - ideate
   - feature planning
   - requirements
+  - j-brainstorm
+  - polyfill
 examples:
   - "let's brainstorm ideas for X"
   - "I need to plan a new feature"
+  - "j-brainstorm"
 metadata: 
   prefered_agent: scrum-master
 ---
 
 # Brainstorm — Collaborative Planning with the Scrum Master
 
+This skill is a literal-directory-name duplicate of `skills/brainstorm/`. It exists so that `/j-brainstorm` (and `j.j-brainstorm`) give a guaranteed-unshadowed way to reach the same flow as `/brainstorm`, even if a host tool's own built-in command of the same name would otherwise shadow or override the bare `/brainstorm` alias (Claude Code's native skill resolution is a literal-string, directory-name-based match — see `docs/skill-authoring.md`'s "Invocation Convention").
+
+This file is generated/synced by `scripts/generate-j-alias.sh brainstorm` from `skills/brainstorm/SKILL.md` — do not hand-edit it; re-run the generator instead to pick up source changes.
+
 ## Instructions
 
 1. **Invoke the `scrum-master` agent** — Pass the user's input directly to it as the opening prompt for the brainstorm session.

package/skills/{btw → j-btw}/SKILL.md

@@ -1,21 +1,28 @@
 ---
-name: j:btw
-description: Capture a new mission (feature, change, or addition) and fit it into the project's Epic/Story structure, then choose to implement now or defer.
+name: j.btw
+description: Polyfill alias of the btw skill under a collision-safe directory name. Identical behavior to /btw — Capture a new mission (feature, change, or addition) and fit it into the project's Epic/Story structure, then choose to implement now or defer. Use when the bare /btw form is shadowed by another tool's own built-in command of the same name.
 keywords:
   - btw
   - capture
   - mission
   - new idea
   - side task
+  - j-btw
+  - polyfill
 examples:
   - "btw I also need to add X"
   - "capture this as a new task"
+  - "j-btw"
 metadata: 
   prefered_agent: scrum-master
 ---
 
 # BTW — Capture a Mission
 
+This skill is a literal-directory-name duplicate of `skills/btw/`. It exists so that `/j-btw` (and `j.j-btw`) give a guaranteed-unshadowed way to reach the same flow as `/btw`, even if a host tool's own built-in command of the same name would otherwise shadow or override the bare `/btw` alias (Claude Code's native skill resolution is a literal-string, directory-name-based match — see `docs/skill-authoring.md`'s "Invocation Convention").
+
+This file is generated/synced by `scripts/generate-j-alias.sh btw` from `skills/btw/SKILL.md` — do not hand-edit it; re-run the generator instead to pick up source changes.
+
 ## Instructions
 
 1. **Gather mission details** — Ask the user: