@jenga-ai/agent 1.2.3 → 1.2.4

package/README.md

@@ -25,11 +25,13 @@ npm install @jenga-ai/agent
 | 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 |
+| **GitHub Copilot** | `.agents/` — mirrored automatically on install | `.github/copilot-instructions.md` — bootstrapped at `npm install` time, refined by `jenga init` |
 | **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.
 
+`.github/copilot-instructions.md` follows a different path: `scripts/postinstall.js` writes it unconditionally and non-interactively the moment `npm install` finishes, so Copilot has working `/skill-name` routing instructions even if a consumer's very first action is a Copilot slash command, before the separate `jenga init` CLI wizard has ever run. Running `jenga init` afterward refines the same file using the user's actual chosen skills path — it is never generated by the `/init` skill itself.
+
 ---
 
 ## The Problem It Solves

package/lib/commands/init.js

@@ -1,10 +1,11 @@
 import { createInterface } from "readline";
-import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync, readdirSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from "fs";
 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";
+import { generateCopilotInstructions } from "../generate-copilot-instructions.js";
 
 const CONFIG_FILE = "jenga.cli.json";
 
@@ -125,74 +126,28 @@ export async function runInit(args, projectRoot = process.cwd()) {
       console.warn("You can register it manually later by running jenga init again.");
     }
 
-    // Generate .github/copilot-instructions.md from template.
-    // Templates ship inside the jenga-agent package (node_modules/jenga-agent/templates/).
-    // Fall back to a bare `templates/` at the project root only for the dev-repo case.
+    // Generate .github/copilot-instructions.md from template, via the shared generator
+    // (lib/generate-copilot-instructions.js) also used unconditionally by scripts/postinstall.js
+    // at install time (E46_S03_T01). Templates ship inside the jenga-agent package
+    // (node_modules/jenga-agent/templates/), with a bare `templates/` at the project root as a
+    // fallback for the dev-repo case — both handled inside the shared generator.
+    //
+    // skillsPath may be a string or an array (multi-target installs); pick the first existing
+    // directory — mirrored copies hold identical content. This pass uses the user's actual
+    // chosen skillsPath from the wizard, which may differ from postinstall's `.agents/skills`
+    // default and refines whatever postinstall already bootstrapped. The shared generator's
+    // idempotent marker-replace logic means running it again here never duplicates the JENGA
+    // block or corrupts content outside the markers.
     try {
-      const tplCandidates = [
-        join(PACKAGE_ROOT, "templates", "copilot-instructions.md.tpl"),
-        join(projectRoot, "templates", "copilot-instructions.md.tpl"),
-      ];
-      const tplPath = tplCandidates.find(existsSync);
-      if (tplPath) {
-        const tpl = readFileSync(tplPath, "utf8");
-
-        // Build skill list from skillsPath. skillsPath may be a string or an
-        // array (multi-target installs); pick the first existing directory —
-        // mirrored copies hold identical content.
-        const skillsPathList = Array.isArray(config.skillsPath) ? config.skillsPath : [config.skillsPath];
-        const skillsDir = skillsPathList
-          .map(p => join(projectRoot, p))
-          .find(existsSync);
-        let skillLines = [];
-        if (skillsDir) {
-          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}` : ""}`);
-          }
-        }
-        const skillList = skillLines.length > 0 ? skillLines.join("\n") : "_No skills found._";
-        const rendered = tpl.replace("{{SKILL_LIST}}", skillList);
-
-        const githubDir = join(projectRoot, ".github");
-        const copilotInstructionsPath = join(githubDir, "copilot-instructions.md");
-
-        if (!existsSync(githubDir)) mkdirSync(githubDir, { recursive: true });
-
-        if (!existsSync(copilotInstructionsPath)) {
-          writeFileSync(copilotInstructionsPath, rendered, "utf8");
-        } else {
-          // Replace only the JENGA block; preserve content outside the markers
-          const existing = readFileSync(copilotInstructionsPath, "utf8");
-          const startMarker = "<!-- JENGA:START -->";
-          const endMarker = "<!-- JENGA:END -->";
-          const startIdx = existing.indexOf(startMarker);
-          const endIdx = existing.indexOf(endMarker);
-
-          // Extract the new JENGA block from rendered template
-          const renderedStart = rendered.indexOf(startMarker);
-          const renderedEnd = rendered.indexOf(endMarker);
-          const newBlock = rendered.slice(renderedStart, renderedEnd + endMarker.length);
-
-          let updated;
-          if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
-            updated =
-              existing.slice(0, startIdx) +
-              newBlock +
-              existing.slice(endIdx + endMarker.length);
-          } else {
-            // No existing markers — append the block
-            updated = existing + (existing.endsWith("\n") ? "" : "\n") + newBlock + "\n";
-          }
-          writeFileSync(copilotInstructionsPath, updated, "utf8");
-        }
+      const skillsPathList = Array.isArray(config.skillsPath) ? config.skillsPath : [config.skillsPath];
+      const skillsDir = skillsPathList
+        .map(p => join(projectRoot, p))
+        .find(existsSync);
+
+      const result = generateCopilotInstructions(projectRoot, PACKAGE_ROOT, skillsDir);
+      if (result.skipped) {
+        console.warn("Warning: templates/copilot-instructions.md.tpl not found — skipped .github/copilot-instructions.md generation.");
+      } else {
         console.log("✓ .github/copilot-instructions.md written");
       }
     } catch (e) {

package/lib/generate-copilot-instructions.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * lib/generate-copilot-instructions.js — .github/copilot-instructions.md generation
+ *
+ * Single source of truth for scaffolding the Copilot routing-instructions file from
+ * templates/copilot-instructions.md.tpl (extracted from lib/commands/init.js per E46_S03_T01).
+ * Used by:
+ *   - scripts/postinstall.js  (runs unconditionally, non-interactively, on every `npm install`)
+ *   - lib/commands/init.js    (the interactive `jenga init` CLI wizard, using the user's chosen
+ *                              skillsPath — may differ from postinstall's default)
+ *
+ * Root-cause context: `.github/copilot-instructions.md` teaches Copilot the `/skill-name` →
+ * `.agents/skills/<name>/SKILL.md` routing convention. It was previously written only by the
+ * `jenga init` CLI wizard, never by postinstall.js — so a consumer whose very first action was
+ * typing `/init` inside Copilot (before ever running `jenga init`) got no routing at all.
+ * Extracting this into a shared, parameterized function lets postinstall.js bootstrap a working
+ * routing file immediately, with `jenga init` free to refine it later using the user's actual
+ * chosen skills path.
+ *
+ * Collision behaviour (preserved verbatim from the original inline implementation — do not
+ * rewrite this algorithm, only relocate it):
+ *   - If `.github/copilot-instructions.md` does not exist, write the rendered template in full.
+ *   - If it exists, replace only the content between `<!-- JENGA:START -->` and
+ *     `<!-- JENGA:END -->`, preserving everything outside the markers.
+ *   - If it exists but has no JENGA markers, append the block to the end of the file.
+ * This makes repeat runs (postinstall run twice, or postinstall followed by `jenga init`)
+ * idempotent: the JENGA block is never duplicated and content outside the markers is never
+ * touched.
+ *
+ * ESM, Node built-ins only — mirrors lib/generate-agent-context.js and lib/mirror.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-copilot-instructions.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 START_MARKER = "<!-- JENGA:START -->";
+const END_MARKER = "<!-- JENGA:END -->";
+
+function resolveTemplatePath(projectRoot, packageRoot) {
+  const candidates = [
+    join(packageRoot, "templates", "copilot-instructions.md.tpl"),
+    join(projectRoot, "templates", "copilot-instructions.md.tpl"),
+  ];
+  return candidates.find(existsSync);
+}
+
+/**
+ * Build the {{SKILL_LIST}} markdown block by scanning `skillsDir` for subdirectories
+ * containing a SKILL.md, extracting each one's `description:` frontmatter line.
+ */
+function buildSkillList(skillsDir) {
+  if (!skillsDir || !existsSync(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._";
+}
+
+/**
+ * Replace only the JENGA:START..JENGA:END block in an existing copilot-instructions.md with the
+ * freshly rendered one, preserving everything outside the markers. If no existing file, write
+ * the rendered template in full. If the existing file has no markers, append the block.
+ */
+function writeCopilotInstructions(path, rendered) {
+  if (!existsSync(path)) {
+    writeFileSync(path, rendered, "utf8");
+    return;
+  }
+
+  const existing = readFileSync(path, "utf8");
+  const startIdx = existing.indexOf(START_MARKER);
+  const endIdx = existing.indexOf(END_MARKER);
+
+  const renderedStart = rendered.indexOf(START_MARKER);
+  const renderedEnd = rendered.indexOf(END_MARKER);
+  const newBlock = rendered.slice(renderedStart, renderedEnd + END_MARKER.length);
+
+  let updated;
+  if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
+    updated = existing.slice(0, startIdx) + newBlock + existing.slice(endIdx + END_MARKER.length);
+  } else {
+    // No existing markers — append the block.
+    updated = existing + (existing.endsWith("\n") ? "" : "\n") + newBlock + "\n";
+  }
+  writeFileSync(path, updated, "utf8");
+}
+
+/**
+ * Generate (or idempotently refresh) `.github/copilot-instructions.md` at projectRoot from the
+ * shared template.
+ *
+ * @param {string} projectRoot - project root directory (default: cwd)
+ * @param {string} packageRoot - installed jenga-agent package root (default: derived from this
+ *   file's own location)
+ * @param {string} skillsDir - path to the skills directory, resolved relative to projectRoot if
+ *   not already absolute (e.g. ".agents/skills" from postinstall, or the user's chosen
+ *   skillsPath from the `jenga init` wizard)
+ * @returns {{written: boolean, path?: string, skipped?: boolean}}
+ */
+export function generateCopilotInstructions(
+  projectRoot = process.cwd(),
+  packageRoot = DEFAULT_PACKAGE_ROOT,
+  skillsDir
+) {
+  const tplPath = resolveTemplatePath(projectRoot, packageRoot);
+  if (!tplPath) {
+    return { written: false, skipped: true };
+  }
+
+  const tpl = readFileSync(tplPath, "utf8");
+
+  const resolvedSkillsDir = skillsDir
+    ? (skillsDir.startsWith("/") ? skillsDir : join(projectRoot, skillsDir))
+    : undefined;
+  const skillList = buildSkillList(resolvedSkillsDir);
+  const rendered = tpl.replace("{{SKILL_LIST}}", skillList);
+
+  const githubDir = join(projectRoot, ".github");
+  const copilotInstructionsPath = join(githubDir, "copilot-instructions.md");
+
+  if (!existsSync(githubDir)) mkdirSync(githubDir, { recursive: true });
+
+  writeCopilotInstructions(copilotInstructionsPath, rendered);
+
+  return { written: true, path: copilotInstructionsPath };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "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": {

package/scripts/postinstall.js

@@ -32,6 +32,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { mirror } from '../lib/mirror.js';
+import { generateCopilotInstructions } from '../lib/generate-copilot-instructions.js';
 
 // ESM equivalent of __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -153,6 +154,26 @@ function main() {
     totalSkipped += result.skipped.length;
   }
 
+  // Bootstrap .github/copilot-instructions.md unconditionally, right after the mirror step —
+  // no interactive prompts, since postinstall runs unattended during `npm install`. Without
+  // this, a consumer whose very first action is a Copilot slash command (before ever running
+  // the separate `jenga init` CLI wizard) gets no `/skill-name` routing instructions at all
+  // (E46_S03_T01). `.agents/skills` is passed as the skills directory because that's the
+  // directory the mirror step above just populated, regardless of which agentTarget the user
+  // eventually picks in `jenga init`. The shared generator's idempotent marker-replace logic
+  // (lib/generate-copilot-instructions.js) means a later `jenga init` run — using the user's
+  // actual chosen skillsPath — safely refines this file without duplicating the JENGA block.
+  try {
+    const result = generateCopilotInstructions(consumerRoot, packageRoot, '.agents/skills');
+    if (result.skipped) {
+      console.log('  ⚠  templates/copilot-instructions.md.tpl not found — skipped .github/copilot-instructions.md bootstrap');
+    } else {
+      console.log('  ✓ .github/copilot-instructions.md bootstrapped');
+    }
+  } catch (e) {
+    console.log(`  ⚠  Could not bootstrap .github/copilot-instructions.md — ${e.message}`);
+  }
+
   // Write .jenga-version to record the installed version at consumer root
   fs.writeFileSync(versionFile, packageVersion + '\n', 'utf8');