@jenga-ai/agent 1.2.0 → 1.2.2

package/README.md

@@ -2,8 +2,34 @@
 
 **A structured multi-agent development workflow that works with any AI agent or AI-native IDE.** Three specialised AI agents — Scrum Master, Developer, and Tester — collaborate through a shared scrum board, an event-driven trigger queue, and 28 slash-command skills to take a project from idea to verified, committed code — across as many sessions as it takes.
 
+[![npm version](https://img.shields.io/npm/v/@jenga-ai/agent.svg)](https://www.npmjs.com/package/@jenga-ai/agent)
+[![license](https://img.shields.io/npm/l/@jenga-ai/agent.svg)](LICENSE)
+
+```sh
+npm install @jenga-ai/agent
+```
+
+## What You Get
+
+- **Three specialised agents** — Scrum Master, Developer, Tester — each with a distinct role and no self-graded work
+- **A persistent scrum board** — Epics, Stories, and Tasks tracked as Markdown files with structured frontmatter, surviving every session boundary
+- **28 slash-command skills** — from planning (`/pi-plan`, `/todo`) to execution (`/do`, `/dooo`) to review (`/status`, `/reconcile`)
+- **An event-driven trigger queue** — async handoffs between agents with a full audit trail in `project/logs/events.json`
+- **Isolated git worktrees per task** — the Developer never works directly on your main branch
+- **Works with any AI agent or IDE** — Claude Code, GitHub Copilot, Warp, and Codex CLI are all supported today
+
 > 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
 
+## Platform Support
+
+| Agent | Skills & Agents | Root Context File |
+|---|---|---|
+| **Claude Code** | `.claude/` — mirrored automatically on install | `CLAUDE.md` — generated by `/init` today |
+| **GitHub Copilot** | `.agents/` — mirrored automatically on install | `.github/copilot-instructions.md` — generated by `/init` today |
+| **Codex** | `.agents/` — mirrored automatically on install | `AGENTS.md` — generated by `/init` today |
+
+`CLAUDE.md` and `AGENTS.md` are generated unconditionally by `/init` — every agent gets a real, populated root-level context file out of the box, not just a pointer. If either file already exists as a genuine pre-existing user file, Jenga writes its own copy as `J-CLAUDE.md` / `J-AGENTS.md` instead and inserts a short reference into the existing file, leaving it otherwise untouched.
+
 ---
 
 ## The Problem It Solves

package/lib/commands/init.js

@@ -4,6 +4,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { validateConfig } from "../config-schema.js";
 import { injectSettings } from "../inject-settings.js";
+import { generateAgentContext } from "../generate-agent-context.js";
 
 const CONFIG_FILE = "jenga.cli.json";
 
@@ -198,6 +199,24 @@ export async function runInit(args, projectRoot = process.cwd()) {
       console.warn(`Warning: Could not write .github/copilot-instructions.md — ${e.message}`);
     }
 
+    // Generate CLAUDE.md / AGENTS.md from templates/agent-context.md.tpl.
+    // Unconditional — never gated on agentTarget (E41_S04): every agent
+    // benefits from these files being cheap to write, and users switch
+    // tools mid-project. Applies the J- collision rule and idempotent
+    // managed-block updates; see lib/generate-agent-context.js.
+    try {
+      const result = generateAgentContext(projectRoot, PACKAGE_ROOT);
+      if (result.skipped) {
+        console.warn("Warning: templates/agent-context.md.tpl not found — skipped CLAUDE.md/AGENTS.md generation.");
+      } else {
+        for (const { filename, mode } of result.written) {
+          console.log(`✓ ${filename} written (${mode})`);
+        }
+      }
+    } catch (e) {
+      console.warn(`Warning: Could not write CLAUDE.md/AGENTS.md — ${e.message}`);
+    }
+
     console.log('\nRun `jenga start` to start the router.');
 
     return config;

package/lib/config-schema.js

@@ -18,8 +18,8 @@ export const configSchema = {
     sessionTimeout: { type: "number", minimum: 0 },
     agentTarget: {
       oneOf: [
-        { type: "string", enum: ["claude", "copilot", "custom"] },
-        { type: "array", items: { type: "string", enum: ["claude", "copilot", "custom"] }, minItems: 1 }
+        { type: "string", enum: ["claude", "copilot", "custom", "codex"] },
+        { type: "array", items: { type: "string", enum: ["claude", "copilot", "custom", "codex"] }, minItems: 1 }
       ]
     }
   },
@@ -45,10 +45,10 @@ export function validateConfig(config) {
   if (typeof config.sessionTimeout !== "number" || config.sessionTimeout < 0) {
     return { valid: false, error: "sessionTimeout must be a non-negative number" };
   }
-  const validTargets = ["claude", "copilot", "custom"];
+  const validTargets = ["claude", "copilot", "custom", "codex"];
   const targets = Array.isArray(config.agentTarget) ? config.agentTarget : [config.agentTarget];
   if (targets.length === 0 || !targets.every(t => validTargets.includes(t))) {
-    return { valid: false, error: 'agentTarget must be one of: "claude", "copilot", "custom" (or an array of those values)' };
+    return { valid: false, error: 'agentTarget must be one of: "claude", "copilot", "custom", "codex" (or an array of those values)' };
   }
   return { valid: true };
 }

package/lib/generate-agent-context.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * lib/generate-agent-context.js — CLAUDE.md / AGENTS.md generation
+ *
+ * Single source of truth for scaffolding the two root-level agent-context
+ * files from templates/agent-context.md.tpl (E41_S04_T02). Used by:
+ *   - lib/commands/init.js         (published `jenga init` CLI)
+ *   - skills/init/scripts/init.sh  (this repo's own board-scaffolding flow,
+ *                                   invoked via `node` — see the CLI guard
+ *                                   at the bottom of this file)
+ *
+ * Design constraints (per E41_S04 story — do not re-litigate):
+ *   - CLAUDE.md and AGENTS.md are written unconditionally, never gated on
+ *     `agentTarget`.
+ *   - Both are written as real files — never a symlink.
+ *   - No AGENT.md (singular) is ever scaffolded.
+ *   - Collision rule: if the target file doesn't exist, write it directly.
+ *     If it already exists, Jenga's copy goes to `J-<NAME>.md` instead, and
+ *     a short, clearly-marked reference is inserted near the top of the
+ *     existing file. The J- prefix always belongs to the incoming Jenga
+ *     file; the user's file keeps its name and content.
+ *   - Idempotent across repeat runs: managed blocks update in place, the
+ *     reference line is never duplicated, and a J- file is updated in place
+ *     rather than re-triggering collision handling (no J-J-CLAUDE.md).
+ *
+ * ESM, Node built-ins only — mirrors lib/mirror.js and lib/inject-settings.js.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// This file lives at <package>/lib/generate-agent-context.js — one level up
+// is the installed jenga-agent package root, which holds templates/.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PACKAGE_ROOT = join(__dirname, "..");
+
+const CONTENT_START = "<!-- JENGA:START -->";
+const CONTENT_END = "<!-- JENGA:END -->";
+const REF_START = "<!-- JENGA:REF:START -->";
+const REF_END = "<!-- JENGA:REF:END -->";
+
+// One entry per generated file. skillDiscoveryPath reflects the reading
+// agent's own discovery convention: Claude Code reads .claude/skills/,
+// every other agent (Codex, generic AGENTS.md consumers, ...) reads
+// .agents/skills/.
+const TARGETS = [
+  { filename: "CLAUDE.md", skillDiscoveryPath: ".claude/skills/" },
+  { filename: "AGENTS.md", skillDiscoveryPath: ".agents/skills/" },
+];
+
+/**
+ * Build the rendered {{SKILL_LIST}} block by scanning the first existing
+ * skills directory among .claude/skills/ and .agents/skills/ — mirrored
+ * copies hold identical content, so either is representative. Mirrors the
+ * skill-list extraction already used for the Copilot template in
+ * lib/commands/init.js.
+ */
+function buildSkillList(projectRoot) {
+  const candidates = [".claude/skills", ".agents/skills"].map((p) => join(projectRoot, p));
+  const skillsDir = candidates.find(existsSync);
+  if (!skillsDir) return "_No skills found._";
+
+  const skillLines = [];
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillMdPath = join(skillsDir, entry.name, "SKILL.md");
+    let description = "";
+    if (existsSync(skillMdPath)) {
+      const content = readFileSync(skillMdPath, "utf8");
+      const match = content.match(/^description:\s*(.+)$/m);
+      if (match) description = match[1].trim();
+    }
+    skillLines.push(`- **${entry.name}**${description ? `: ${description}` : ""}`);
+  }
+  return skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
+}
+
+function resolveTemplatePath(projectRoot, packageRoot) {
+  const candidates = [
+    join(packageRoot, "templates", "agent-context.md.tpl"),
+    join(projectRoot, "templates", "agent-context.md.tpl"),
+  ];
+  return candidates.find(existsSync);
+}
+
+/**
+ * Replace only the JENGA:START..JENGA:END block in `existingContent` with
+ * `newBlock` (which itself includes the marker comments), preserving
+ * everything outside the markers. If no markers are present, append the
+ * block. Identical technique to the Copilot managed-block replace in
+ * lib/commands/init.js.
+ */
+function replaceManagedBlock(existingContent, newBlock) {
+  const startIdx = existingContent.indexOf(CONTENT_START);
+  const endIdx = existingContent.indexOf(CONTENT_END);
+  if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
+    return existingContent.slice(0, startIdx) + newBlock + existingContent.slice(endIdx + CONTENT_END.length);
+  }
+  return existingContent + (existingContent.endsWith("\n") ? "" : "\n") + newBlock + "\n";
+}
+
+/**
+ * Write `rendered` (full file content, including the JENGA:START/END block)
+ * to `path`. If the file doesn't exist, write it in full. If it does,
+ * replace only the managed block, preserving any content outside it (e.g.
+ * a user's own edits to the title line of a Jenga-owned file).
+ */
+function writeManagedFile(path, rendered) {
+  if (!existsSync(path)) {
+    writeFileSync(path, rendered, "utf8");
+    return;
+  }
+  const existing = readFileSync(path, "utf8");
+  const renderedStart = rendered.indexOf(CONTENT_START);
+  const renderedEnd = rendered.indexOf(CONTENT_END);
+  const newBlock = rendered.slice(renderedStart, renderedEnd + CONTENT_END.length);
+  const updated = replaceManagedBlock(existing, newBlock);
+  if (updated !== existing) writeFileSync(path, updated, "utf8");
+}
+
+/**
+ * Insert (or, on repeat runs, update in place) a short Jenga-marked
+ * reference block near the very top of a pre-existing user file, pointing
+ * at the J-<NAME>.md copy. Idempotent via its own REF marker pair, kept
+ * distinct from CONTENT_START/CONTENT_END so the two replace passes never
+ * interfere with each other in the same file.
+ */
+function insertOrUpdateReference(path, jFilename) {
+  const refBlock =
+    `${REF_START}\n` +
+    `> **Jenga framework note:** This project also uses [Jenga](https://github.com/samwelmunga/jenga-npm) — ` +
+    `see \`${jFilename}\` for Jenga's framework-specific agent context (skills, board, workflow). ` +
+    `This file is unrelated to Jenga and was left untouched.\n` +
+    `${REF_END}`;
+
+  const existing = readFileSync(path, "utf8");
+  const startIdx = existing.indexOf(REF_START);
+  const endIdx = existing.indexOf(REF_END);
+
+  let updated;
+  if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
+    updated = existing.slice(0, startIdx) + refBlock + existing.slice(endIdx + REF_END.length);
+  } else {
+    // No existing reference — insert at the very top, ahead of any content,
+    // satisfying "early / before the first major section" regardless of
+    // the existing file's structure.
+    updated = refBlock + "\n\n" + existing;
+  }
+  if (updated !== existing) writeFileSync(path, updated, "utf8");
+}
+
+/**
+ * Generate CLAUDE.md and AGENTS.md at projectRoot from the shared template,
+ * applying the J- collision rule and idempotent managed-block updates.
+ *
+ * @param {string} projectRoot - project root directory (default: cwd)
+ * @param {string} packageRoot - installed jenga-agent package root (default:
+ *   derived from this file's own location)
+ * @returns {{written: Array<{filename: string, mode: string}>, skipped?: boolean}}
+ */
+export function generateAgentContext(projectRoot = process.cwd(), packageRoot = DEFAULT_PACKAGE_ROOT) {
+  const tplPath = resolveTemplatePath(projectRoot, packageRoot);
+  if (!tplPath) {
+    return { written: [], skipped: true };
+  }
+
+  const tpl = readFileSync(tplPath, "utf8");
+  const skillList = buildSkillList(projectRoot);
+  const written = [];
+
+  for (const target of TARGETS) {
+    const rendered = tpl
+      .split("{{TARGET_FILENAME}}").join(target.filename)
+      .split("{{SKILL_DISCOVERY_PATH}}").join(target.skillDiscoveryPath)
+      .split("{{SKILL_LIST}}").join(skillList);
+
+    const targetPath = join(projectRoot, target.filename);
+    const jFilename = `J-${target.filename}`;
+    const jPath = join(projectRoot, jFilename);
+
+    if (existsSync(jPath)) {
+      // A J- file can only ever have been created by Jenga — this is a
+      // repeat run after a prior collision. Update it in place; never
+      // re-derive collision handling from it (no J-J-CLAUDE.md).
+      writeManagedFile(jPath, rendered);
+      if (existsSync(targetPath)) {
+        insertOrUpdateReference(targetPath, jFilename);
+      }
+      written.push({ filename: target.filename, mode: "updated-j-file" });
+      continue;
+    }
+
+    if (existsSync(targetPath)) {
+      const existingContent = readFileSync(targetPath, "utf8");
+      if (existingContent.includes(CONTENT_START)) {
+        // Jenga's own file from a prior *non-collision* run — update in
+        // place rather than treating it as a fresh collision.
+        writeManagedFile(targetPath, rendered);
+        written.push({ filename: target.filename, mode: "direct-update" });
+      } else {
+        // Genuine pre-existing user file — collision. Write Jenga's copy
+        // as J-<NAME>.md and insert a reference into the user's file.
+        writeFileSync(jPath, rendered, "utf8");
+        insertOrUpdateReference(targetPath, jFilename);
+        written.push({ filename: target.filename, mode: "collision-created-j-file" });
+      }
+      continue;
+    }
+
+    // Neither the target nor its J- copy exists — first-run, no collision.
+    writeManagedFile(targetPath, rendered);
+    written.push({ filename: target.filename, mode: "direct-write" });
+  }
+
+  return { written };
+}
+
+// CLI guard — allows `node lib/generate-agent-context.js [projectRoot]`,
+// used by skills/init/scripts/init.sh (this repo's own board-scaffolding
+// flow, where node is guaranteed available). The published npm CLI path
+// (lib/commands/init.js) imports generateAgentContext() directly instead.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const projectRoot = process.argv[2] || process.cwd();
+  const result = generateAgentContext(projectRoot);
+  if (result.skipped) {
+    console.warn("Warning: agent-context.md.tpl not found — skipped CLAUDE.md/AGENTS.md generation.");
+  } else {
+    for (const { filename, mode } of result.written) {
+      console.log(`✓ ${filename} (${mode})`);
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.2.0",
-  "description": "JengaAgent — agentic project management CLI",
+  "version": "1.2.2",
+  "description": "Structured multi-agent development workflow for AI coding agents — scrum board, role-bounded scrum master / developer / tester agents, and 30+ slash-command skills. Works with Claude Code, GitHub Copilot, and Codex.",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -9,8 +9,12 @@
   "bin": {
     "jenga": "./bin/jenga.js"
   },
+  "engines": {
+    "node": ">=14.13.1"
+  },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
+    "validate:npm-metadata": "bash scripts/validate_npm_metadata.sh",
     "ui:dev": "npm run ui:dev --prefix project/app",
     "ui:build": "npm run ui:build --prefix project/app",
     "api:start": "npm run api:start --prefix project/app",
@@ -32,10 +36,35 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/samwelmunga/jenga-npm"
+    "url": "git+https://github.com/samwelmunga/jenga-npm.git"
+  },
+  "homepage": "https://github.com/samwelmunga/jenga-npm#readme",
+  "bugs": {
+    "url": "https://github.com/samwelmunga/jenga-npm/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "agentic",
+    "agentic-workflow",
+    "multi-agent",
+    "agent-framework",
+    "ai-development",
+    "claude",
+    "claude-code",
+    "agents-md",
+    "copilot",
+    "github-copilot",
+    "codex",
+    "skills",
+    "project-management",
+    "developer-tools",
+    "cli"
+  ],
+  "author": {
+    "name": "Samwel Munga",
+    "email": "samwelmunga88@hotmail.se",
+    "url": "https://knappkod.se/jenga-ai"
   },
-  "keywords": [],
-  "author": "",
   "license": "MIT",
   "dependencies": {
     "@huggingface/transformers": "^4.2.0"

package/scripts/validate_npm_metadata.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+#
+# validate_npm_metadata.sh — deterministic check that package.json carries
+# the metadata npm/GitHub discovery depends on (E41_S01_T02).
+#
+# Rationale: per the repo's "Scripts Over Inline Logic" principle
+# (CLAUDE.md), this is a script rather than an agent instruction so that
+# future drift in package.json's publish-facing fields (e.g. keywords
+# accidentally cleared, or repository.url silently re-pointed at the
+# private samwelmunga/JengaAgent repo instead of the public jenga-npm
+# mirror) is caught deterministically instead of relying on an agent
+# noticing during review.
+#
+# IMPORTANT — no pinned version check:
+#   This script intentionally does NOT compare package.json's `version`
+#   field against any hardcoded literal. E41_S01_T01 established that the
+#   locally committed version and the version actually published to npm
+#   drift independently over time, so pinning a literal here would go
+#   stale on the very next release. If a version check is wanted at all,
+#   it is structural only (present + semver-shaped), never a pinned value.
+#
+# Usage:
+#   bash scripts/validate_npm_metadata.sh
+#   npm run validate:npm-metadata
+#
+# Exit codes:
+#   0  All checks passed.
+#   1  One or more checks failed (each failure is printed with a
+#      descriptive message; a summary count follows).
+#
+# Dependencies: node only (already a required runtime for this project —
+# see package.json's "engines" field). No new dependency is introduced.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PACKAGE_JSON="${1:-$REPO_ROOT/package.json}"
+
+if [[ ! -f "$PACKAGE_JSON" ]]; then
+  echo "FAIL: package.json not found at $PACKAGE_JSON" >&2
+  exit 1
+fi
+
+# All validation logic lives in one embedded Node script to avoid the
+# quoting/escaping pitfalls of parsing JSON arrays and nested objects from
+# bash. Node prints one "PASS: ..." or "FAIL: ..." line per check to
+# stdout, plus a final "SUMMARY: <n> failed" line. Bash only interprets
+# the final summary line to decide the exit code and print the banner.
+NODE_OUTPUT="$(node -e '
+const fs = require("fs");
+
+const pkgPath = process.argv[1];
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+
+const failures = [];
+const pass = (msg) => console.log("PASS: " + msg);
+const fail = (msg) => { failures.push(msg); console.log("FAIL: " + msg); };
+
+// keywords: must exist, be a non-empty array
+if (!Array.isArray(pkg.keywords) || pkg.keywords.length === 0) {
+  fail("keywords is empty or missing — package.json must declare a non-empty keywords array for npm/GitHub discoverability.");
+} else {
+  pass("keywords is present with " + pkg.keywords.length + " entries.");
+}
+
+// author: must exist and be non-empty (string or object form)
+const authorEmpty = (() => {
+  if (pkg.author == null) return true;
+  if (typeof pkg.author === "string") return pkg.author.trim().length === 0;
+  if (typeof pkg.author === "object") {
+    return !pkg.author.name || String(pkg.author.name).trim().length === 0;
+  }
+  return true;
+})();
+if (authorEmpty) {
+  fail("author is empty or missing — package.json must declare an author (string or {name, ...} object).");
+} else {
+  pass("author is present.");
+}
+
+// repository / homepage / bugs: must all be present
+if (pkg.repository == null || (typeof pkg.repository === "object" && Object.keys(pkg.repository).length === 0)) {
+  fail("repository is missing from package.json.");
+} else {
+  pass("repository is present.");
+}
+
+if (!pkg.homepage || String(pkg.homepage).trim().length === 0) {
+  fail("homepage is missing from package.json.");
+} else {
+  pass("homepage is present.");
+}
+
+if (pkg.bugs == null || (typeof pkg.bugs === "object" && Object.keys(pkg.bugs).length === 0)) {
+  fail("bugs is missing from package.json.");
+} else {
+  pass("bugs is present.");
+}
+
+// repository.url (object form) or repository (string form) must point at
+// the PUBLIC mirror (samwelmunga/jenga-npm), never the private repo.
+const PUBLIC_REPO_MARKER = "samwelmunga/jenga-npm";
+if (pkg.repository != null) {
+  const repoUrl = typeof pkg.repository === "string"
+    ? pkg.repository
+    : (pkg.repository.url || "");
+
+  if (!repoUrl || repoUrl.trim().length === 0) {
+    fail("repository is present but has no resolvable url.");
+  } else if (!repoUrl.includes(PUBLIC_REPO_MARKER)) {
+    fail("repository.url (\"" + repoUrl + "\") does not point at the public " + PUBLIC_REPO_MARKER + " repo — it must not reference a private repo (e.g. samwelmunga/JengaAgent) or any other location.");
+  } else {
+    pass("repository.url points at the public " + PUBLIC_REPO_MARKER + " repo.");
+  }
+}
+
+// version: structural semver check only — NEVER a pinned literal value.
+// See header comment for why a pinned check would go stale immediately.
+const SEMVER_RE = /^\d+\.\d+\.\d+/;
+if (!pkg.version || !SEMVER_RE.test(String(pkg.version))) {
+  fail("version (\"" + pkg.version + "\") is missing or not a valid semver-shaped string.");
+} else {
+  pass("version (\"" + pkg.version + "\") is a valid semver-shaped string (no pinned-value check performed, by design).");
+}
+
+console.log("SUMMARY: " + failures.length + " failed");
+process.exit(failures.length > 0 ? 1 : 0);
+' "$PACKAGE_JSON")" && NODE_EXIT=0 || NODE_EXIT=$?
+
+echo "$NODE_OUTPUT"
+echo
+
+FAILED_COUNT="$(echo "$NODE_OUTPUT" | grep -c '^FAIL:' || true)"
+
+if [[ "$NODE_EXIT" -ne 0 || "$FAILED_COUNT" -gt 0 ]]; then
+  echo "npm publish metadata validation FAILED ($FAILED_COUNT check(s) failed). See FAIL lines above." >&2
+  exit 1
+fi
+
+echo "All npm publish metadata checks passed."
+exit 0

package/skills/distribute/scripts/distribute-changes.sh

@@ -13,7 +13,7 @@
 #   2. Reads <project_path>/jenga.config.json for target_dir and project_name.
 #   3. Loads per-project exclusions from <project_path>/.jenga_ignore (warn, not error).
 #   4. Rsyncs each included item to both <target_dir>/ and .claude/ in the project.
-#   5. Copies AGENT.md, CLAUDE.md, WARP.md to the project root.
+#   5. Copies AGENTS.md, CLAUDE.md, WARP.md to the project root.
 #   6. Writes jenga.config.json atomically (temp + mv).
 #
 # Exit codes:
@@ -282,7 +282,7 @@ done
 # Step 6: Copy root-level docs to the consuming project root
 # ---------------------------------------------------------------------------
 
-ROOT_DOCS="AGENT.md CLAUDE.md WARP.md"
+ROOT_DOCS="AGENTS.md CLAUDE.md WARP.md"
 
 for doc in $ROOT_DOCS; do
   src="$REPO_ROOT/$doc"

package/skills/init/scripts/init.sh

@@ -73,7 +73,18 @@ cp "$SCRIPT_DIR/../../../templates/CHANGELOG_TEMPLATE.md" CHANGELOG.md
 echo "→ Applying project files visibility ($VISIBILITY)..."
 bash "$VISIBILITY_SCRIPT" "$VISIBILITY" "$PWD"
 
-# ─── 12. Initial commit ──────────────────────────────────────────────────────
+# ─── 12. Generate CLAUDE.md / AGENTS.md ──────────────────────────────────────
+# Unconditional — never gated on agentTarget (E41_S04). Applies the J-
+# collision rule and idempotent managed-block updates; see
+# lib/generate-agent-context.js (shared with the published `jenga init` CLI).
+echo "→ Generating CLAUDE.md / AGENTS.md..."
+if command -v node >/dev/null 2>&1; then
+  node "$SCRIPT_DIR/../../../lib/generate-agent-context.js" "$PWD"
+else
+  echo "  Warning: node not found — skipped CLAUDE.md/AGENTS.md generation." >&2
+fi
+
+# ─── 13. Initial commit ──────────────────────────────────────────────────────
 echo "→ Staging and committing scaffolded files..."
 git add -A
 git commit -m "init: scaffold project structure and workflow config"

package/skills/publish/adapters/npm-ci.md

@@ -190,7 +190,7 @@ A successful non-dry-run produces:
 - A history entry in `project/logs/publish-history.json` written by
   `publish_deploy.sh` with `platform_state: "triggered"`
 
-## Post-Deploy Manual Steps
+## Post-deploy manual steps
 
 After a successful deploy trigger, the adapter prints the workflow run URL.
 The operator should:

package/skills/publish/scripts/publish_deploy.sh

@@ -465,9 +465,18 @@ print_manual_steps() {
     droplet)
       adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/droplet.md"
       ;;
-    *)
+    npm)
+      adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/npm.md"
+      ;;
+    npm-ci)
+      adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/npm-ci.md"
+      ;;
+    mobile-ios)
       adapter_doc="$PUBLISH_REPO_ROOT/skills/publish/adapters/mobile-ios.md"
       ;;
+    *)
+      return 0
+      ;;
   esac
   [[ -f "$adapter_doc" ]] || return 0
   local manual_steps

package/skills/reconcile/scripts/detect-unlinked-code.sh

@@ -509,8 +509,10 @@ linked_by_board = linked_by_commit = 0
 
 for rec in linkage.get("results", []):
     # Key on the path we ASKED about, not the resolver's `target_relative`. The resolver
-    # realpath()s its target, so a tracked symlink (`AGENTS.md -> AGENT.md`) reports its
-    # destination and would silently overwrite that destination's own record.
+    # realpath()s its target, so a tracked symlink (e.g. this repo's now-retired
+    # `AGENTS.md -> AGENT.md`, before E41_S04_T05 made AGENTS.md a real file) reports its
+    # destination and would silently overwrite that destination's own record. The general
+    # case (any tracked symlink) still applies even though that specific example is gone.
     path = rec.get("argument") or rec.get("target_relative")
     if not path:
         continue

package/templates/agent-context.md.tpl

@@ -0,0 +1,46 @@
+# {{TARGET_FILENAME}}
+
+This file gives AI coding agents context on this project. The block between the Jenga markers is managed automatically by `jenga init` — do not edit it manually.
+
+<!-- JENGA:START -->
+## Jenga Agent Framework
+
+This project uses **Jenga** — a skill-based AI agent framework. Jenga organises project work into Epics, Stories, and Tasks managed on a scrum board. It routes user messages to specialised **skills** that execute defined workflows.
+
+### How Jenga Works
+
+- Each **skill** is a self-contained instruction set stored under `{{SKILL_DISCOVERY_PATH}}<skill-name>/`.
+- Skills are invoked by typing `/skill-name` in the chat prompt.
+- The active project directory is available via the `JENGA_PROJECT_DIR` environment variable. **Use `JENGA_PROJECT_DIR` — not `CLAUDE_PROJECT_DIR` or any other agent-specific variable** — as the canonical path to the project folder.
+
+### Skill Routing
+
+When a user's message matches a known skill keyword or intent, invoke the skill immediately using the slash-command syntax:
+
+```
+/skill-name
+```
+
+Do **not** answer skill-related requests with free-form prose if a matching skill exists — delegate to the skill instead.
+
+For free-form questions (architecture, code review, debugging, general Q&A) that do not match a skill, answer directly using your full capabilities.
+
+#### Routing decision table
+
+| Situation | Action |
+|-----------|--------|
+| Message matches a skill keyword or intent | Invoke `/skill-name` |
+| Message is a general coding or project question | Answer directly |
+| Ambiguous — could be skill or free-form | Prefer the skill; mention it is being invoked |
+
+### Available Skills
+
+{{SKILL_LIST}}
+
+### Notes
+
+- Always resolve file paths relative to `JENGA_PROJECT_DIR`.
+- When a skill asks you to read a file such as `SKILL.md` or a task file, look for it inside `JENGA_PROJECT_DIR/{{SKILL_DISCOVERY_PATH}}` or `JENGA_PROJECT_DIR/project/board/` respectively.
+- Commit messages and branch names follow the EST naming convention (`E<n>_S<n>_T<n>`).
+- Agent definitions (scrum-master, developer, tester, and any others) live in the `agents/` directory that sits alongside the skills directory shown above, at the same discovery root.
+<!-- JENGA:END -->