@jenga-ai/agent 1.2.0 → 1.2.1

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,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "JengaAgent — agentic project management CLI",
   "type": "module",
   "publishConfig": {

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/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 -->