@jenga-ai/agent 1.0.0

package/mcp/router/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "jenga-router",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "description": "Jenga Router — stdio MCP server for skill-based prompt routing",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.1",
+    "zod": "^3.24.4"
+  }
+}

package/mcp/router/skill-index.js

@@ -0,0 +1,104 @@
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
+import { join } from "path";
+
+/**
+ * Parses YAML frontmatter from a markdown file.
+ * Returns an object with the parsed fields, or {} if no frontmatter found.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  try {
+    const lines = match[1].split("\n");
+    const obj = {};
+    let currentKey = null;
+    let arrayMode = false;
+    for (const line of lines) {
+      const arrayItem = line.match(/^\s+-\s+(.*)/);
+      if (arrayItem && arrayMode && currentKey) {
+        obj[currentKey].push(arrayItem[1].trim().replace(/^["']|["']$/g, ""));
+        continue;
+      }
+      arrayMode = false;
+      const kv = line.match(/^(\w+):\s*(.*)/);
+      if (!kv) continue;
+      const [, key, val] = kv;
+      if (val.trim() === "[]") {
+        obj[key] = [];
+        currentKey = key;
+        arrayMode = false;
+      } else if (val.trim() === "") {
+        obj[key] = [];
+        currentKey = key;
+        arrayMode = true;
+      } else {
+        obj[key] = val.trim().replace(/^["']|["']$/g, "");
+        currentKey = key;
+      }
+    }
+    return obj;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Recursively finds all SKILL.md files under a directory.
+ */
+function findSkillFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const results = [];
+  try {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      try {
+        if (statSync(full).isDirectory()) {
+          results.push(...findSkillFiles(full));
+        } else if (entry === "SKILL.md") {
+          results.push(full);
+        }
+      } catch {}
+    }
+  } catch {}
+  return results;
+}
+
+/**
+ * Builds the in-memory skill index from the skills directory.
+ * Optionally accepts an embedder ({ embed(text) }) to pre-compute skill embeddings.
+ * Returns an array of skill records.
+ */
+export async function buildSkillIndex(skillsPath, embedder = null) {
+  const start = Date.now();
+  const files = findSkillFiles(skillsPath);
+  const skills = [];
+
+  for (const filePath of files) {
+    try {
+      const content = readFileSync(filePath, "utf8");
+      const fm = parseFrontmatter(content);
+      if (!fm.name) {
+        process.stderr.write(`Warning: ${filePath} has no 'name' in frontmatter — skipped\n`);
+        continue;
+      }
+      const skill = {
+        name: fm.name,
+        description: fm.description || "",
+        keywords: Array.isArray(fm.keywords) ? fm.keywords : [],
+        examples: Array.isArray(fm.examples) ? fm.examples : [],
+        path: filePath,
+        embedding: null,
+      };
+      if (embedder) {
+        skill.embedding = await embedder.embed(skill.description);
+      }
+      skills.push(skill);
+    } catch (e) {
+      process.stderr.write(`Warning: failed to parse ${filePath}: ${e.message}\n`);
+    }
+  }
+
+  const elapsed = Date.now() - start;
+  process.stderr.write(`[jenga-router] Indexed ${skills.length} skills in ${elapsed}ms\n`);
+  return skills;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jenga-ai/agent",
+  "version": "1.0.0",
+  "description": "JengaAgent — agentic project management CLI",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "jenga": "./bin/jenga.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "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",
+    "api:dev": "npm run api:dev --prefix project/app",
+    "dashboard:start": "npm run dashboard:start --prefix project/app",
+    "dashboard:open": "npm run dashboard:open --prefix project/app"
+  },
+  "files": [
+    "skills/",
+    "agents/",
+    "hooks/",
+    "scripts/",
+    "templates/",
+    "bin/",
+    "lib/",
+    "mcp/execute-ticket/",
+    "mcp/help/",
+    "mcp/router/index.js",
+    "mcp/router/matcher.js",
+    "mcp/router/embedder.js",
+    "mcp/router/skill-index.js",
+    "mcp/router/package.json",
+    "mcp/router/package-lock.json",
+    "mcp/router/README.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@xenova/transformers": "^2.17.2"
+  }
+}

package/scripts/board_resolver.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Resolves the board path from project/configs/workflow.json.
+# Outputs a normalised path (always ends with exactly one '/') to stdout.
+# Falls back to "project/board/" when the config file is missing or the key is absent.
+# Exits non-zero and prints to stderr when the config file exists but is malformed JSON.
+
+CONFIG="project/configs/workflow.json"
+DEFAULT="project/board/"
+
+if [ ! -f "$CONFIG" ]; then
+  printf '%s\n' "$DEFAULT"
+  exit 0
+fi
+
+if command -v jq >/dev/null 2>&1; then
+  # Validate JSON first
+  if ! jq empty "$CONFIG" 2>/dev/null; then
+    echo "Error: $CONFIG contains malformed JSON" >&2
+    exit 1
+  fi
+
+  board_path=$(jq -r '.paths.board // empty' "$CONFIG" 2>/dev/null)
+else
+  # Validate JSON portably: check that the file starts with '{' or '[' after whitespace
+  first_char=$(sed 's/^[[:space:]]*//' "$CONFIG" | head -c1)
+  if [ "$first_char" != "{" ] && [ "$first_char" != "[" ]; then
+    echo "Error: $CONFIG contains malformed JSON" >&2
+    exit 1
+  fi
+
+  # Portable grep+sed fallback: extract "board": "value"
+  board_path=$(grep -o '"board"[[:space:]]*:[[:space:]]*"[^"]*"' "$CONFIG" \
+    | sed 's/.*"board"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' \
+    | head -1)
+fi
+
+if [ -z "$board_path" ]; then
+  printf '%s\n' "$DEFAULT"
+  exit 0
+fi
+
+# Normalise: ensure exactly one trailing slash
+board_path="${board_path%/}/"
+
+printf '%s\n' "$board_path"
+exit 0

package/scripts/e25_s01_extract_board_graph.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+# THROWAWAY — spike prototype for E25_S01 latency measurement. Do not import.
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+PREFIXED_REF = r"(?:[A-Z0-9]+_)?"
+EPIC_ID_RE = re.compile(rf"^{PREFIXED_REF}E\d{{2}}$")
+STORY_ID_RE = re.compile(rf"^{PREFIXED_REF}E\d{{2}}_S\d{{2}}$")
+TASK_ID_RE = re.compile(rf"^{PREFIXED_REF}E\d{{2}}_S\d{{2}}_T\d{{2}}$")
+TARGET_REF_RE = re.compile(rf"^({PREFIXED_REF}E\d{{2}}_S\d{{2}}(?:_T\d{{2}})?)-(plan|summary)\.md$")
+TODO_REF_RE = re.compile(rf"\b({PREFIXED_REF}E\d{{2}}_S\d{{2}}(?:_T\d{{2}})?)\b")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Throwaway board graph extractor for E25_S01.")
+    parser.add_argument("root", nargs="?", default="project", help="Project-like root containing board/, documentation/, and todo.md")
+    parser.add_argument("--profile", action="store_true", help="Include coarse timing breakdown in the output JSON")
+    return parser.parse_args()
+
+
+def parse_scalar(value: str):
+    text = value.strip()
+    if text in {"", "null", "~"}:
+        return ""
+    if text.startswith("[") and text.endswith("]"):
+        inner = text[1:-1].strip()
+        if not inner:
+            return []
+        return [item.strip().strip("'\"") for item in inner.split(",") if item.strip()]
+    return text.strip("'\"")
+
+
+def parse_frontmatter(path: Path) -> tuple[dict, str]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}, text
+    parts = text.split("\n---\n", 1)
+    if len(parts) != 2:
+        return {}, text
+    raw, body = parts
+    lines = raw.splitlines()[1:]
+    data: dict[str, object] = {}
+    current_key = None
+    for line in lines:
+        if not line.strip():
+            continue
+        if line.startswith("  - ") and current_key:
+            data.setdefault(current_key, [])
+            cast = data[current_key]
+            if isinstance(cast, list):
+                cast.append(line[4:].strip().strip("'\""))
+            continue
+        if ":" not in line:
+            current_key = None
+            continue
+        key, value = line.split(":", 1)
+        key = key.strip()
+        parsed = parse_scalar(value)
+        data[key] = parsed
+        current_key = key if parsed == "" else None
+    return data, body
+
+
+def relpath(path: Path, root: Path) -> str:
+    return path.relative_to(root).as_posix()
+
+
+def node_sort_key(node: dict) -> tuple:
+    return (node.get("type", ""), node.get("id", ""), node.get("path", ""), node.get("line_number", 0))
+
+
+def edge_sort_key(edge: dict) -> tuple:
+    return (edge.get("type", ""), edge.get("from", ""), edge.get("to", ""), edge.get("source", ""))
+
+
+def rounded_timings(timings: dict[str, float]) -> dict[str, float]:
+    return {key: round(value, 3) for key, value in timings.items()}
+
+
+def add_board_nodes(
+    root: Path,
+    collection: str,
+    node_type: str,
+    nodes: list[dict],
+    records: list[dict],
+    timings: dict[str, float],
+):
+    base = root / "board" / collection
+    walk_started = time.perf_counter()
+    paths = sorted(base.glob("*.md"))
+    timings["board_directory_walk_ms"] = timings.get("board_directory_walk_ms", 0.0) + ((time.perf_counter() - walk_started) * 1000)
+    for path in paths:
+        parse_started = time.perf_counter()
+        frontmatter, _ = parse_frontmatter(path)
+        timings["board_frontmatter_parse_ms"] = timings.get("board_frontmatter_parse_ms", 0.0) + ((time.perf_counter() - parse_started) * 1000)
+        node = {
+            "id": frontmatter.get("id") or path.stem.split("_", 1)[0],
+            "type": node_type,
+            "path": relpath(path, root),
+            "title": frontmatter.get("title", ""),
+            "status": frontmatter.get("status", ""),
+        }
+        if frontmatter.get("epic_id"):
+            node["epic_id"] = frontmatter["epic_id"]
+        if frontmatter.get("story_id"):
+            node["story_id"] = frontmatter["story_id"]
+        if isinstance(frontmatter.get("stories"), list):
+            node["stories"] = list(frontmatter["stories"])
+        if isinstance(frontmatter.get("tasks"), list):
+            node["tasks"] = list(frontmatter["tasks"])
+        nodes.append(node)
+        records.append({"node": node, "frontmatter": frontmatter})
+
+
+def add_doc_nodes(
+    root: Path,
+    folder: str,
+    node_type: str,
+    nodes: list[dict],
+    records: list[dict],
+    timings: dict[str, float],
+):
+    base = root / "documentation" / folder
+    walk_started = time.perf_counter()
+    paths = sorted(base.glob("*.md"))
+    timings["doc_directory_walk_ms"] = timings.get("doc_directory_walk_ms", 0.0) + ((time.perf_counter() - walk_started) * 1000)
+    for path in paths:
+        parse_started = time.perf_counter()
+        frontmatter, _ = parse_frontmatter(path)
+        timings["doc_frontmatter_parse_ms"] = timings.get("doc_frontmatter_parse_ms", 0.0) + ((time.perf_counter() - parse_started) * 1000)
+        stem = path.stem
+        node = {
+            "id": stem,
+            "type": node_type,
+            "path": relpath(path, root),
+            "title": frontmatter.get("title") or frontmatter.get("id") or stem,
+        }
+        match = TARGET_REF_RE.match(path.name)
+        if match:
+            node["target_ref"] = match.group(1)
+        nodes.append(node)
+        records.append({"node": node, "frontmatter": frontmatter})
+
+
+def add_todo_nodes(root: Path, nodes: list[dict], records: list[dict], timings: dict[str, float]):
+    todo_path = root / "todo.md"
+    started = time.perf_counter()
+    for line_number, raw_line in enumerate(todo_path.read_text(encoding="utf-8").splitlines(), start=1):
+        line = raw_line.strip()
+        if not line or line.startswith("<!--"):
+            continue
+        if line.startswith("#"):
+            continue
+        if set(line) <= {"-"}:
+            continue
+        refs = TODO_REF_RE.findall(line)
+        digest = hashlib.sha1(line.encode("utf-8")).hexdigest()[:12]
+        node = {
+            "id": f"todo:{line_number}:{digest}",
+            "type": "TodoEntry",
+            "path": relpath(todo_path, root),
+            "line_number": line_number,
+            "text": line,
+        }
+        if refs:
+            node["board_refs"] = refs
+        nodes.append(node)
+        records.append({"node": node, "refs": refs})
+    timings["todo_parse_ms"] = timings.get("todo_parse_ms", 0.0) + ((time.perf_counter() - started) * 1000)
+
+
+def target_type(target_id: str) -> str:
+    if TASK_ID_RE.match(target_id):
+        return "Task"
+    if STORY_ID_RE.match(target_id):
+        return "Story"
+    if EPIC_ID_RE.match(target_id):
+        return "Epic"
+    return "Unknown"
+
+
+def main() -> int:
+    args = parse_args()
+    root = Path(args.root).resolve()
+    nodes: list[dict] = []
+    edges: list[dict] = []
+
+    started = time.perf_counter()
+    timings: dict[str, float] = {}
+
+    t0 = time.perf_counter()
+    epic_records: list[dict] = []
+    story_records: list[dict] = []
+    task_records: list[dict] = []
+    add_board_nodes(root, "epics", "Epic", nodes, epic_records, timings)
+    add_board_nodes(root, "stories", "Story", nodes, story_records, timings)
+    add_board_nodes(root, "tasks", "Task", nodes, task_records, timings)
+    plan_records: list[dict] = []
+    summary_records: list[dict] = []
+    add_doc_nodes(root, "plans", "Plan", nodes, plan_records, timings)
+    add_doc_nodes(root, "summaries", "Summary", nodes, summary_records, timings)
+    todo_records: list[dict] = []
+    add_todo_nodes(root, nodes, todo_records, timings)
+    timings["node_extraction_ms"] = round((time.perf_counter() - t0) * 1000, 3)
+
+    t0 = time.perf_counter()
+    known_ids = {node["id"] for node in nodes}
+    for record in epic_records:
+        source = record["node"]
+        for story_id in source.get("stories", []):
+            edges.append({
+                "type": "contains",
+                "from": source["id"],
+                "to": story_id,
+                "from_type": "Epic",
+                "to_type": target_type(story_id),
+                "source": source["path"],
+            })
+    for record in story_records:
+        source = record["node"]
+        for task_id in source.get("tasks", []):
+            edges.append({
+                "type": "contains",
+                "from": source["id"],
+                "to": task_id,
+                "from_type": "Story",
+                "to_type": target_type(task_id),
+                "source": source["path"],
+            })
+    for record in plan_records:
+        source = record["node"]
+        target = source.get("target_ref")
+        if target:
+            edges.append({
+                "type": "plans",
+                "from": source["id"],
+                "to": target,
+                "from_type": "Plan",
+                "to_type": target_type(target),
+                "source": source["path"],
+            })
+    for record in summary_records:
+        source = record["node"]
+        target = source.get("target_ref")
+        if target:
+            edges.append({
+                "type": "summarizes",
+                "from": source["id"],
+                "to": target,
+                "from_type": "Summary",
+                "to_type": target_type(target),
+                "source": source["path"],
+            })
+    for record in todo_records:
+        source = record["node"]
+        for ref in record.get("refs", []):
+            if ref in known_ids:
+                edges.append({
+                    "type": "queued_as",
+                    "from": source["id"],
+                    "to": ref,
+                    "from_type": "TodoEntry",
+                    "to_type": target_type(ref),
+                    "source": source["path"],
+                })
+    timings["edge_derivation_ms"] = round((time.perf_counter() - t0) * 1000, 3)
+
+    t0 = time.perf_counter()
+    nodes.sort(key=node_sort_key)
+    edges.sort(key=edge_sort_key)
+    payload = {"nodes": nodes, "edges": edges}
+    if args.profile:
+        payload["profile"] = rounded_timings(timings)
+    rendered = json.dumps(payload, indent=2, sort_keys=True)
+    timings["json_serialization_ms"] = round((time.perf_counter() - t0) * 1000, 3)
+    if args.profile:
+        timings["total_ms"] = round((time.perf_counter() - started) * 1000, 3)
+        payload["profile"] = rounded_timings(timings)
+        rendered = json.dumps(payload, indent=2, sort_keys=True)
+    sys.stdout.write(rendered)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/e25_s01_generate_synthetic_board.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# THROWAWAY — spike prototype for E25_S01 latency measurement. Do not import.
+
+import argparse
+import re
+import shutil
+from pathlib import Path
+
+BOARD_REF_RE = re.compile(r"\b(E\d{2}(?:_S\d{2})?(?:_T\d{2})?)\b")
+FILE_GROUPS = [
+    ("board/epics", "*.md"),
+    ("board/stories", "*.md"),
+    ("board/tasks", "*.md"),
+    ("documentation/plans", "*.md"),
+    ("documentation/summaries", "*.md"),
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Generate a deterministic synthetic 10x board for E25_S01.")
+    parser.add_argument("source_root", nargs="?", default="project", help="Source project-like root")
+    parser.add_argument("output_root", nargs="?", default="project/.synthetic/E25_S01_board_10x", help="Synthetic output root")
+    parser.add_argument("--replicas", type=int, default=10, help="Number of synthetic replicas to generate")
+    return parser.parse_args()
+
+
+def prefix_for(index: int) -> str:
+    return f"SYNTH{index:02d}_"
+
+
+def rewrite_board_refs(text: str, prefix: str) -> str:
+    return BOARD_REF_RE.sub(lambda match: f"{prefix}{match.group(1)}", text)
+
+
+def rewrite_file(source_file: Path, destination_file: Path, prefix: str) -> None:
+    rewritten = rewrite_board_refs(source_file.read_text(encoding="utf-8"), prefix)
+    destination_file.write_text(rewritten, encoding="utf-8")
+
+
+def ensure_clean_dir(path: Path) -> None:
+    if path.exists():
+        shutil.rmtree(path)
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def generate_docs(source_root: Path, output_root: Path, replicas: int) -> None:
+    for relative_dir, pattern in FILE_GROUPS:
+        source_dir = source_root / relative_dir
+        destination_dir = output_root / relative_dir
+        destination_dir.mkdir(parents=True, exist_ok=True)
+        for index in range(1, replicas + 1):
+            prefix = prefix_for(index)
+            for source_file in sorted(source_dir.glob(pattern)):
+                destination_name = f"{prefix}{source_file.name}"
+                rewrite_file(source_file, destination_dir / destination_name, prefix)
+
+
+def generate_todo(source_root: Path, output_root: Path, replicas: int) -> None:
+    source_lines = (source_root / "todo.md").read_text(encoding="utf-8").splitlines()
+    preserved = []
+    entries = []
+    for line in source_lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or stripped.startswith("<!--") or set(stripped) <= {"-"}:
+            preserved.append(line)
+        else:
+            entries.append(line)
+    todo_lines = list(preserved)
+    if todo_lines and todo_lines[-1] != "":
+        todo_lines.append("")
+    for index in range(1, replicas + 1):
+        prefix = prefix_for(index)
+        todo_lines.append(f"<!-- {prefix[:-1]} -->")
+        todo_lines.extend(rewrite_board_refs(line, prefix) for line in entries)
+        todo_lines.append("")
+    (output_root / "todo.md").write_text("\n".join(todo_lines).rstrip() + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    args = parse_args()
+    source_root = Path(args.source_root).resolve()
+    output_root = Path(args.output_root).resolve()
+    ensure_clean_dir(output_root)
+    generate_docs(source_root, output_root, args.replicas)
+    generate_todo(source_root, output_root, args.replicas)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/measurement-10x.json

@@ -0,0 +1,50 @@
+{
+  "results": [
+    {
+      "command": "python3 scripts/e25_s01_extract_board_graph.py project/.synthetic/E25_S01_board_10x >/dev/null",
+      "mean": 0.9473466919,
+      "stddev": 0.04213956306422262,
+      "median": 0.9491800002000002,
+      "user": 0.27642483999999995,
+      "system": 0.17378274,
+      "min": 0.8851443542000001,
+      "max": 1.0109388122,
+      "times": [
+        0.9744102712000001,
+        0.8890629382000002,
+        0.9989147292,
+        0.8851443542000001,
+        0.9441933962000001,
+        0.9595782292000001,
+        1.0109388122,
+        0.9420493132000001,
+        0.9150082712000001,
+        0.9541666042000001
+      ],
+      "memory_usage_byte": [
+        39600128,
+        39600128,
+        39600128,
+        39600128,
+        39600128,
+        39600128,
+        40730624,
+        40730624,
+        40730624,
+        40730624
+      ],
+      "exit_codes": [
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0,
+        0
+      ]
+    }
+  ]
+}

package/scripts/measurement-10x.txt

@@ -0,0 +1,4 @@
+Benchmark 1: python3 scripts/e25_s01_extract_board_graph.py project/.synthetic/E25_S01_board_10x >/dev/null
+  Time (mean ± σ):     947.3 ms ±  42.1 ms    [User: 276.4 ms, System: 173.8 ms]
+  Range (min … max):   885.1 ms … 1010.9 ms    10 runs
+