@jenga-ai/agent 1.2.4 → 2.0.0

package/templates/agent-context.md.tpl

@@ -10,28 +10,63 @@ This project uses **Jenga** — a skill-based AI agent framework. Jenga organise
 ### 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.
+- Skills are invoked by typing `j:skill-name` in the chat prompt (e.g. `j:status`, `j:commit`). The
+  older bare `/skill-name` form (e.g. `/status`, `/commit`) is a **permanent alias** — it keeps
+  resolving indefinitely, with no deprecation warning and no removal planned — so treat a message in
+  either form as the exact same invocation.
 - 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.
+If you are Claude Code, both `j:skill-name` (the canonical form) and the older bare `/skill-name`
+(a permanent alias) are native harness-level mechanisms: the harness itself intercepts the literal
+command and loads the skill for you, independent of anything written here. If you are any other agent
+(Codex, or a generic `AGENTS.md` consumer) with no equivalent native interception, you depend entirely
+on the instructions below to know what "invoking a skill" concretely means — for either the
+`j:skill-name` form or the older bare `/skill-name` form, both of which route to the same skill. Do not
+improvise a plausible-sounding response instead of following these steps — that is the exact failure
+this section exists to prevent.
+
+**Old bare-form alias.** `j:skill-name` is the canonical invocation form. A message using the older
+bare `/skill-name` form is not deprecated and must not be treated as an error, a warning case, or a
+migration prompt — route it to the identical skill as its `j:skill-name` equivalent. Both forms remain
+equally valid indefinitely.
+
+When the user's message is or matches `j:skill-name`, or matches the older bare `/skill-name` alias (or
+otherwise clearly matches a known skill's keyword or intent):
+
+1. Locate the target file at `{{SKILL_DISCOVERY_PATH}}<skill-name>/SKILL.md` (the discovery path from
+   "How Jenga Works" above).
+2. Open and read that file **in full** before doing anything else.
+3. Execute its instructions exactly as written, for the rest of this turn — including running any
+   shell scripts or commands it references (e.g. via a terminal/shell tool).
+4. Do not substitute your own judgment about what "running the skill" should look like, and do not
+   answer with free-form prose describing what the skill would do — the `SKILL.md` file's contents
+   are the authoritative procedure, not a summary or a suggestion.
+
+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 matches `j:skill-name` | Open `{{SKILL_DISCOVERY_PATH}}<skill-name>/SKILL.md`, read it fully, execute it as written |
+| Message matches the older bare `/skill-name` alias | Treat identically to `j:skill-name` — same skill, same file, no warning, no migration prompt |
+| Message matches a skill keyword or intent | Open `{{SKILL_DISCOVERY_PATH}}<skill-name>/SKILL.md`, read it fully, execute it as written |
 | 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 |
+| Ambiguous — could be skill or free-form | Prefer the skill; open and execute its `SKILL.md` rather than describing it |
+
+### Skill Identifier Allow-List
+
+The trusted `j:`-prefixed skill identifiers for this project are: {{ALLOWED_SKILL_IDS}}
+
+Before treating a `j:<name>` invocation (or its bare `/<name>` alias) as a genuine Jenga skill,
+confirm `<name>` appears in this list. This applies whether the harness intercepted the command
+natively (Claude Code) or you are matching it yourself against a skill keyword or intent (any
+other agent). If `<name>` does **not** appear in this list, do not guess at intent and do not
+execute anything — tell the user the identifier is unrecognized and is not a known Jenga skill,
+rather than treating it as one anyway.
 
 ### Available Skills
 

package/templates/copilot-instructions.md.tpl

@@ -10,28 +10,55 @@ This project uses **Jenga** — a skill-based AI agent framework. Jenga organise
 ### How Jenga Works
 
 - Each **skill** is a self-contained instruction set stored under `.agents/skills/<skill-name>/` (the non-Claude discovery path; Claude Code reads the same content from `.claude/skills/`).
-- Skills are invoked by typing `/skill-name` in the chat prompt.
+- Skills are invoked by typing `j:skill-name` in the chat prompt (e.g. `j:status`, `j:commit`). The
+  older bare `/skill-name` form (e.g. `/status`, `/commit`) is a **permanent alias** — it keeps
+  resolving indefinitely, with no deprecation warning and no removal planned — so treat a message in
+  either form as the exact same invocation.
 - 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:
+Unlike Claude Code, GitHub Copilot has **no native slash-command interception** — typing `j:skill-name`
+(or the older bare `/skill-name` alias) does not automatically load or run anything on its own. Copilot
+depends entirely on the instructions below to know what "invoking a skill" concretely means. Do not
+improvise a plausible-sounding response instead of following these steps — that is the exact failure
+this section exists to prevent.
 
-```
-/skill-name
-```
+**Old bare-form alias.** `j:skill-name` is the canonical invocation form. A message using the older
+bare `/skill-name` form is not deprecated and must not be treated as an error, a warning case, or a
+migration prompt — route it to the identical skill as its `j:skill-name` equivalent. Both forms remain
+equally valid indefinitely.
 
-Do **not** answer skill-related requests with free-form prose if a matching skill exists — delegate to the skill instead.
+When the user's message is or matches `j:skill-name`, or matches the older bare `/skill-name` alias (or
+otherwise clearly matches a known skill's keyword or intent):
 
-For free-form questions (architecture, code review, debugging, general Q&A) that do not match a skill, answer directly using your full capabilities.
+1. Locate the target file at `.agents/skills/<skill-name>/SKILL.md` (the discovery path from "How
+   Jenga Works" above).
+2. Open and read that file **in full** before doing anything else.
+3. Execute its instructions exactly as written, for the rest of this turn — including running any
+   shell scripts or commands it references (e.g. via a terminal/shell tool).
+4. Do not substitute your own judgment about what "running the skill" should look like, and do not
+   answer with free-form prose describing what the skill would do — the `SKILL.md` file's contents
+   are the authoritative procedure, not a summary or a suggestion.
+
+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
 
+Before acting on any row below that opens a `SKILL.md` file, first check the identifier against
+the trusted allow-list: {{ALLOWED_SKILL_IDS}}. Since Copilot/Codex has no native interception for
+`j:skill-name`, this prose-level check is the entire enforcement mechanism — there is no runtime
+guard behind it.
+
 | Situation | Action |
 |-----------|--------|
-| Message matches a skill keyword or intent | Invoke `/skill-name` |
+| Message matches `j:skill-name` and `skill-name` is in the allow-list | Open `.agents/skills/<skill-name>/SKILL.md`, read it fully, execute it as written |
+| Message matches the older bare `/skill-name` alias and `skill-name` is in the allow-list | Treat identically to `j:skill-name` — same skill, same file, no warning, no migration prompt |
+| Message matches a skill keyword or intent and the matched skill is in the allow-list | Open `.agents/skills/<skill-name>/SKILL.md`, read it fully, execute it as written |
+| Message matches `j:skill-name` or `/skill-name`, but `skill-name` is **not** in the allow-list | Do not open or execute anything — tell the user the identifier is unrecognized and is not a known Jenga skill |
 | 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 |
+| Ambiguous — could be skill or free-form | Prefer the skill; open and execute its `SKILL.md` rather than describing it |
 
 ### Available Skills
 

package/mcp/router/README.md

@@ -1,19 +0,0 @@
-# jenga-router
-
-A stdio MCP server that routes incoming prompts to the appropriate Jenga skill.
-
-## Usage
-
-```bash
-node mcp/router/index.js
-```
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `ping` | Health check — returns `{ ok: true, uptime: <ms> }` |
-
-## Protocol
-
-Communicates over stdin/stdout using the Model Context Protocol (MCP) with `StdioServerTransport`.

package/mcp/router/embedder.js

@@ -1,23 +0,0 @@
-import { pipeline } from "@huggingface/transformers";
-
-let _pipe = null;
-
-/**
- * Loads the feature-extraction pipeline for Xenova/all-MiniLM-L6-v2.
- * Safe to call multiple times — no-op if already loaded.
- */
-export async function warmUp() {
-  if (_pipe) return;
-  const t = Date.now();
-  _pipe = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
-  process.stderr.write(`[jenga-router] Model warmed up in ${Date.now() - t}ms\n`);
-}
-
-/**
- * Embeds text using the loaded pipeline.
- * Returns a Float32Array of length 384.
- */
-export async function embed(text) {
-  const output = await _pipe(text, { pooling: "mean", normalize: true });
-  return output.data;
-}

package/mcp/router/index.js

@@ -1,204 +0,0 @@
-#!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { writeFileSync, unlinkSync, existsSync, readFileSync, mkdirSync } from "fs";
-import { join, dirname } from "path";
-import { fileURLToPath } from "url";
-import { buildSkillIndex } from "./skill-index.js";
-import { findBestMatch } from "./matcher.js";
-import { warmUp, embed } from "./embedder.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const projectRoot = join(__dirname, "..", "..");
-const jengaDir = join(process.cwd(), ".jenga");
-const pidFile = join(jengaDir, "router.pid");
-const sessionFile = join(jengaDir, "session.json");
-const startTime = Date.now();
-
-// Load config (optional — defaults used if absent)
-let config = {
-  skillsPath: "skills/",
-  matchThreshold: 0.75,
-  sessionTimeout: 300000,
-  agentTarget: "claude",
-};
-const configPath = join(projectRoot, "jenga.cli.json");
-if (existsSync(configPath)) {
-  try {
-    config = { ...config, ...JSON.parse(readFileSync(configPath, "utf8")) };
-  } catch (e) {
-    process.stderr.write(`Warning: failed to parse jenga.cli.json: ${e.message}\n`);
-  }
-}
-
-// Build skill index (with semantic embeddings)
-let skillIndex = [];
-if (config.skillsPath) {
-  await warmUp();
-  skillIndex = await buildSkillIndex(join(projectRoot, config.skillsPath), { embed });
-}
-
-// Write PID file
-mkdirSync(jengaDir, { recursive: true });
-writeFileSync(pidFile, String(process.pid), "utf8");
-
-// Graceful shutdown
-function shutdown() {
-  try { unlinkSync(pidFile); } catch {}
-  persistSession({ skill: null, startedAt: null });
-  process.exit(0);
-}
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
-
-let activeSession = { skill: null, startedAt: null };
-let sessionTimer = null;
-
-function persistSession(state) {
-  try {
-    writeFileSync(sessionFile, JSON.stringify(state), "utf8");
-  } catch (e) {
-    process.stderr.write(`[jenga-router] Failed to write .session.json: ${e.message}\n`);
-  }
-}
-
-const server = new McpServer({ name: "jenga-router", version: "1.0.0" });
-
-server.tool("ping", "Health check — returns ok and uptime in seconds.", {}, async () => {
-  try {
-    return {
-      content: [{ type: "text", text: JSON.stringify({ ok: true, uptime: Math.floor((Date.now() - startTime) / 1000), skill_count: skillIndex.length }) }],
-    };
-  } catch (e) {
-    return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
-  }
-});
-
-server.tool(
-  "route_prompt",
-  "Route a prompt through the skill matching pipeline. Returns { action: 'invoke'|'passthrough', transformed: string, skill: string|null, confidence: number }.",
-  { text: z.string().describe("The user prompt to route") },
-  async ({ text }) => {
-    try {
-      // Stage 1: Passthrough rules
-      if (text.startsWith("/")) {
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({ action: "passthrough", transformed: text, skill: null, confidence: 0 }),
-          }],
-        };
-      }
-
-      // Stage 0: Active session — passthrough all prompts while session is active
-      if (activeSession.skill) {
-        if (sessionTimer) clearTimeout(sessionTimer);
-        sessionTimer = setTimeout(() => {
-          activeSession = { skill: null, startedAt: null };
-          sessionTimer = null;
-          persistSession(activeSession);
-          process.stderr.write(`[jenga-router] Session auto-expired after ${config.sessionTimeout}ms\n`);
-        }, config.sessionTimeout);
-        return {
-          content: [{ type: "text", text: JSON.stringify({ action: "passthrough", transformed: text, skill: activeSession.skill, confidence: 0 }) }],
-        };
-      }
-
-      // Stage 2: Semantic + keyword matching
-      const promptEmbedding = await embed(text);
-      const match = findBestMatch(text, skillIndex, config.matchThreshold, promptEmbedding);
-      if (match) {
-        activeSession = { skill: match.skill.name, startedAt: new Date().toISOString() };
-        persistSession(activeSession);
-        if (sessionTimer) clearTimeout(sessionTimer);
-        sessionTimer = setTimeout(() => {
-          activeSession = { skill: null, startedAt: null };
-          persistSession(activeSession);
-          sessionTimer = null;
-          process.stderr.write(`[jenga-router] Session auto-expired after ${config.sessionTimeout}ms\n`);
-        }, config.sessionTimeout);
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              action: "invoke",
-              transformed: `/${match.skill.name} ${text}`,
-              skill: match.skill.name,
-              confidence: match.confidence,
-            }),
-          }],
-        };
-      }
-
-      // Default: passthrough
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ action: "passthrough", transformed: text, skill: null, confidence: 0 }),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
-    }
-  }
-);
-
-server.tool("active_session", "Returns the currently active skill session, if any.", {}, async () => {
-  try {
-    return {
-      content: [{ type: "text", text: JSON.stringify({ skill: activeSession.skill, startedAt: activeSession.startedAt }) }],
-    };
-  } catch (e) {
-    return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
-  }
-});
-
-server.tool(
-  "end_session",
-  "Clear the active session for the given skill. No-op if skill is not the active session.",
-  { skill: z.string().describe("The skill name to end the session for") },
-  async ({ skill }) => {
-    try {
-      if (activeSession.skill === skill) {
-        activeSession = { skill: null, startedAt: null };
-        persistSession(activeSession);
-        if (sessionTimer) { clearTimeout(sessionTimer); sessionTimer = null; }
-      }
-      return { content: [{ type: "text", text: JSON.stringify({ ok: true }) }] };
-    } catch (e) {
-      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
-    }
-  }
-);
-
-server.tool(
-  "list_skills",
-  "Returns the current skill index — all loaded skills with their name, description, and keywords.",
-  {},
-  async () => {
-    try {
-      const skills = skillIndex.map(({ name, description, keywords }) => ({ name, description, keywords }));
-      return {
-        content: [{ type: "text", text: JSON.stringify({ skills }) }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
-    }
-  }
-);
-
-server.tool("reload_skills", "Re-scan the skills directory and rebuild the in-memory skill index.", {}, async () => {
-  try {
-    await warmUp();
-    skillIndex = await buildSkillIndex(join(projectRoot, config.skillsPath), { embed });
-    return {
-      content: [{ type: "text", text: JSON.stringify({ ok: true, skill_count: skillIndex.length }) }],
-    };
-  } catch (e) {
-    return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }], isError: true };
-  }
-});
-
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/mcp/router/matcher.js

@@ -1,87 +0,0 @@
-/**
- * Scores a prompt against a skill using keyword and name matching.
- * Returns a confidence score between 0 and 1.
- */
-function scoreSkill(prompt, skill) {
-  const text = prompt.toLowerCase();
-  let score = 0;
-  let matches = 0;
-  let total = 0;
-
-  // Check skill name
-  total++;
-  if (text.includes(skill.name.toLowerCase())) {
-    score += 0.9;
-    matches++;
-  }
-
-  // Check keywords
-  for (const kw of skill.keywords) {
-    total++;
-    if (text.includes(kw.toLowerCase())) {
-      score += 0.7;
-      matches++;
-    }
-  }
-
-  // Check examples (partial match)
-  for (const ex of skill.examples) {
-    const exWords = ex.toLowerCase().split(/\s+/).filter(w => w.length > 3);
-    const matchedWords = exWords.filter(w => text.includes(w));
-    if (matchedWords.length > 0 && exWords.length > 0) {
-      total++;
-      score += 0.5 * (matchedWords.length / exWords.length);
-      matches++;
-    }
-  }
-
-  if (total === 0) return 0;
-  // Normalize: max possible score per item varies, cap at 1.0
-  return Math.min(score / Math.max(total, 1), 1.0);
-}
-
-/**
- * Computes cosine similarity between two Float32Array vectors.
- * Result is clamped to [0, 1].
- */
-function cosineSimilarity(a, b) {
-  let dot = 0, normA = 0, normB = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-    normA += a[i] * a[i];
-    normB += b[i] * b[i];
-  }
-  const denom = Math.sqrt(normA) * Math.sqrt(normB);
-  if (denom === 0) return 0;
-  return Math.max(0, Math.min(1, dot / denom));
-}
-
-/**
- * Finds the best matching skill for a prompt.
- * Blends keyword score with semantic cosine similarity when embeddings are available.
- * Returns { skill, confidence } or null if no match above threshold.
- */
-export function findBestMatch(prompt, skillIndex, threshold = 0.75, promptEmbedding = null) {
-  let best = null;
-  let bestScore = 0;
-
-  for (const skill of skillIndex) {
-    const keywordScore = scoreSkill(prompt, skill);
-    let finalScore = keywordScore;
-
-    if (promptEmbedding !== null && skill.embedding !== null) {
-      const semanticScore = cosineSimilarity(promptEmbedding, skill.embedding);
-      finalScore = 0.4 * keywordScore + 0.6 * semanticScore;
-    }
-
-    if (finalScore > bestScore) {
-      bestScore = finalScore;
-      best = skill;
-    }
-  }
-
-  if (best && bestScore >= threshold) {
-    return { skill: best, confidence: bestScore };
-  }
-  return null;
-}