@jenga-ai/agent 1.0.0

package/bin/jenga.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * jenga — Jenga Agent CLI
+ * Usage: jenga <command> [options]
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"));
+
+const [,, cmd, ...args] = process.argv;
+
+const USAGE = `
+jenga — Jenga Agent CLI v${pkg.version}
+
+Usage:
+  jenga init      Run the setup wizard (creates jenga.cli.json, registers hook)
+  jenga attach    Write MCP config for this project so new sessions route through Jenga
+  jenga status    Show router status and active session
+
+Options:
+  --version, -v   Print version
+  --help, -h      Print this help message
+`.trim();
+
+async function main() {
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  if (cmd === "--version" || cmd === "-v") {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  switch (cmd) {
+    case "init": {
+      const { runInit } = await import("../lib/commands/init.js");
+      await runInit(args);
+      break;
+    }
+    case "start": {
+      const { runStart } = await import("../lib/commands/start.js");
+      await runStart(args);
+      break;
+    }
+    case "attach": {
+      const { runAttach } = await import("../lib/commands/attach.js");
+      await runAttach(args);
+      break;
+    }
+    case "status": {
+      const { runStatus } = await import("../lib/commands/status.js");
+      await runStatus(args);
+      break;
+    }
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.log(USAGE);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/hooks/copilot_session_end.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# hooks/copilot_session_end.sh
+#
+# Copilot CLI session-end entry point.
+#
+# GitHub Copilot CLI does not fire a native SessionEnd hook. Call this script
+# manually at the end of a Copilot session or as a post-step in any skill
+# that completes a significant pipeline stage (e.g. commit, lgtm).
+#
+# This wrapper:
+#   1. Sources lib/resolve-project-dir.sh to export JENGA_PROJECT_DIR,
+#      JENGA_AGENT_TYPE, and JENGA_SESSION_ID (idempotent — safe to call
+#      even if a parent script already sourced the resolver).
+#   2. Delegates to hooks/on_session_end.sh for all shared cleanup logic:
+#      queue routing, rapport detection, handoff file processing, and
+#      todo cleanup.
+#
+# Usage:
+#   bash hooks/copilot_session_end.sh
+#
+# Environment (optional — resolver provides defaults):
+#   JENGA_PROJECT_DIR   — override project root (default: git root or pwd)
+#   JENGA_AGENT_TYPE    — override agent type (default: "generic")
+#   JENGA_SESSION_ID    — override session ID (default: uuidgen / timestamp)
+
+# shellcheck source=lib/resolve-project-dir.sh
+source "$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh"
+
+exec bash "$JENGA_PROJECT_DIR/hooks/on_session_end.sh" "$@"

package/hooks/on_session_end.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# .claude/hooks/on_session_end.sh
+# Triggered on SessionEnd by all agents (scrum-master, developer, tester).
+#
+# Responsibilities:
+#   1. Log a sender event to events.json
+#   2. Detect new problem rapports using a manifest (not a timestamp)
+#      and write trigger payloads to the scrum master queue
+#   3. Write a status-review trigger to the scrum master queue
+#   4. Read .session_handoff.json (if present) and route the assignment
+#      to the correct next agent queue, then delete the handoff file
+#
+# Pipeline routing (section 4):
+#   scrum-master  planning_complete       → developer_triggers.jsonl
+#   developer     implementation_complete → tester_triggers.jsonl
+#   tester        passed / passed_with_remarks → scrum_triggers.jsonl (story_rollup)
+#   tester        failed / error          → developer_triggers.jsonl (rework) +
+#                                           scrum_triggers.jsonl (status_review)
+#
+# NOTE: Claude Code hooks cannot spawn a named agent session directly.
+# Instead, we write structured trigger payloads to the appropriate queue
+# files. Each agent reads its own queue at the start of its next session.
+
+# shellcheck source=lib/resolve-project-dir.sh
+source "$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh"
+
+PROJECT_DIR="$JENGA_PROJECT_DIR"
+RAPPORT_DIR="$PROJECT_DIR/project/rapports/problems"
+MANIFEST="$PROJECT_DIR/.claude/hooks/.rapport_manifest.json"
+QUEUE_DIR="$PROJECT_DIR/project/queue"
+QUEUE_FILE="$QUEUE_DIR/scrum_triggers.jsonl"
+DEV_QUEUE="$QUEUE_DIR/developer_triggers.jsonl"
+TESTER_QUEUE="$QUEUE_DIR/tester_triggers.jsonl"
+HANDOFF_FILE="$QUEUE_DIR/.session_handoff.json"
+EVENTS_LOG="$PROJECT_DIR/project/logs/events.json"
+AGENT="${JENGA_AGENT_TYPE:-unknown}"
+SESSION_ID="${JENGA_SESSION_ID:-}"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$PROJECT_DIR/project/logs" "$QUEUE_DIR"
+
+# --- 1. Log sender object ---
+
+SENDER=$(jq -n \
+  --arg agent "$AGENT" \
+  --arg session_id "$SESSION_ID" \
+  --arg date "$TIMESTAMP" \
+  '{
+    sender: {
+      agent: $agent,
+      session_id: $session_id,
+      task_id: "",
+      story_id: "",
+      epic_id: "",
+      date: $date,
+      paths: [],
+      worktree: ""
+    }
+  }')
+
+if [ -f "$EVENTS_LOG" ]; then
+  jq --argjson entry "$SENDER" '. += [$entry]' "$EVENTS_LOG" > /tmp/events_tmp.json \
+    && mv /tmp/events_tmp.json "$EVENTS_LOG"
+else
+  echo "[$SENDER]" > "$EVENTS_LOG"
+fi
+
+# --- 2. Manifest-based rapport detection ---
+# Use a JSON array of known filenames instead of a mtime sentinel file.
+# This prevents silently missing rapports written before the session ends
+# but after the sentinel was last touched.
+
+if [ ! -f "$MANIFEST" ]; then
+  echo "[]" > "$MANIFEST"
+fi
+
+if [ -d "$RAPPORT_DIR" ]; then
+  # Collect current rapport files (exclude .IGNORE.md files — already resolved)
+  # Results are stored in a bash array to avoid word-splitting on paths.
+  mapfile -t CURRENT_FILES < <(find "$RAPPORT_DIR" -name "*.md" ! -name "*.IGNORE.md" 2>/dev/null | sort)
+
+  # Identify new files not present in the manifest
+  NEW_FILES=()
+  for file in "${CURRENT_FILES[@]}"; do
+    known=$(jq --arg f "$file" 'index($f) != null' "$MANIFEST" 2>/dev/null)
+    if [ "$known" != "true" ]; then
+      NEW_FILES+=("$file")
+    fi
+  done
+
+  if [ "${#NEW_FILES[@]}" -gt 0 ]; then
+    echo "New rapport(s) detected: ${#NEW_FILES[@]} file(s). Writing trigger to queue."
+
+    # Build a safe JSON array of file paths — never interpolate paths into strings
+    FILES_JSON=$(printf '%s\n' "${NEW_FILES[@]}" | jq -R . | jq -s .)
+
+    TRIGGER=$(jq -n \
+      --arg type "rapport_review" \
+      --arg agent "$AGENT" \
+      --arg session_id "$SESSION_ID" \
+      --arg date "$TIMESTAMP" \
+      --argjson files "$FILES_JSON" \
+      '{
+        type: $type,
+        sender: { agent: $agent, session_id: $session_id, date: $date },
+        rapport_files: $files,
+        message: "New problem rapport(s) detected. Review each file and either create a backlog item or set the affected task/story/epic status to Failed with a rapport reference. Report back to the user with a summary."
+      }')
+
+    echo "$TRIGGER" >> "$QUEUE_FILE"
+
+    # Update the manifest to include all current files
+    printf '%s\n' "${CURRENT_FILES[@]}" | jq -R . | jq -s . > "$MANIFEST"
+  fi
+fi
+
+# --- 3. Status-review trigger ---
+
+TRIGGER=$(jq -n \
+  --arg type "status_review" \
+  --arg agent "$AGENT" \
+  --arg session_id "$SESSION_ID" \
+  --arg date "$TIMESTAMP" \
+  '{
+    type: $type,
+    sender: { agent: $agent, session_id: $session_id, date: $date },
+    message: "A session has just ended. Review the scrum board and update the status of any tasks, stories, or epics where status may have changed based on recent activity. Check story and epic rollup. Report back to the user with a summary of what changed."
+  }')
+
+echo "$TRIGGER" >> "$QUEUE_FILE"
+
+# --- 4. Session handoff routing ---
+# Each agent writes .session_handoff.json before its session ends.
+# This section reads that file and routes the work to the correct next
+# agent queue so the pipeline continues automatically.
+
+if [ -f "$HANDOFF_FILE" ]; then
+  HANDOFF_AGENT=$(jq -r '.agent // empty' "$HANDOFF_FILE" 2>/dev/null)
+  HANDOFF_STATUS=$(jq -r '.status // empty' "$HANDOFF_FILE" 2>/dev/null)
+
+  case "$HANDOFF_AGENT" in
+
+    scrum-master)
+      # Planning phase complete — forward tasks to developer queue
+      if [ "$HANDOFF_STATUS" = "planning_complete" ]; then
+        TRIGGER=$(jq -n \
+          --slurpfile h "$HANDOFF_FILE" \
+          --arg type "implementation_assignment" \
+          --arg date "$TIMESTAMP" \
+          '{
+            type: $type,
+            date: $date,
+            sender: { agent: "scrum-master", session_id: $h[0].session_id, date: $date },
+            task_ids: ($h[0].task_ids // []),
+            story_id: ($h[0].story_id // ""),
+            epic_id:  ($h[0].epic_id  // ""),
+            message:  "Scrum master planning complete. Implement the assigned tasks."
+          }')
+        echo "$TRIGGER" >> "$DEV_QUEUE"
+        echo "[on_session_end] scrum-master → developer queue: implementation_assignment"
+      fi
+      ;;
+
+    developer)
+      # Implementation complete — forward to tester queue
+      if [ "$HANDOFF_STATUS" = "implementation_complete" ]; then
+        TRIGGER=$(jq -n \
+          --slurpfile h "$HANDOFF_FILE" \
+          --arg type "test_assignment" \
+          --arg date "$TIMESTAMP" \
+          '{
+            type: $type,
+            date: $date,
+            sender: { agent: "developer", session_id: $h[0].session_id, date: $date },
+            task_id:  ($h[0].task_id  // ""),
+            story_id: ($h[0].story_id // ""),
+            epic_id:  ($h[0].epic_id  // ""),
+            worktree: ($h[0].worktree // ""),
+            paths:    ($h[0].paths    // []),
+            message:  "Developer session complete. Test the implementation in the assigned worktree."
+          }')
+        echo "$TRIGGER" >> "$TESTER_QUEUE"
+        echo "[on_session_end] developer → tester queue: test_assignment"
+      fi
+      ;;
+
+    tester)
+      # Tester session complete — always write story_rollup to scrum-master
+      ROLLUP=$(jq -n \
+        --slurpfile h "$HANDOFF_FILE" \
+        --arg type "story_rollup" \
+        --arg date "$TIMESTAMP" \
+        '{
+          type: $type,
+          date: $date,
+          sender: { agent: "tester", session_id: $h[0].session_id, date: $date },
+          task_id:     ($h[0].task_id     // ""),
+          story_id:    ($h[0].story_id    // ""),
+          epic_id:     ($h[0].epic_id     // ""),
+          test_status: ($h[0].status      // "unknown"),
+          rapport_file: ($h[0].rapport_file // ""),
+          message: ("Tester session complete with status: " + ($h[0].status // "unknown") + ". Check rollup and update board accordingly.")
+        }')
+      echo "$ROLLUP" >> "$QUEUE_FILE"
+      echo "[on_session_end] tester → scrum-master queue: story_rollup (status=$HANDOFF_STATUS)"
+
+      # Tests failed — also route back to developer for rework
+      if [ "$HANDOFF_STATUS" = "failed" ] || [ "$HANDOFF_STATUS" = "error" ]; then
+        REWORK=$(jq -n \
+          --slurpfile h "$HANDOFF_FILE" \
+          --arg type "rework_assignment" \
+          --arg date "$TIMESTAMP" \
+          '{
+            type: $type,
+            date: $date,
+            sender: { agent: "tester", session_id: $h[0].session_id, date: $date },
+            task_id:      ($h[0].task_id      // ""),
+            story_id:     ($h[0].story_id     // ""),
+            epic_id:      ($h[0].epic_id      // ""),
+            worktree:     ($h[0].worktree     // ""),
+            rapport_file: ($h[0].rapport_file // ""),
+            message: "Tests failed. Address the findings in the rapport and re-implement before calling the tester again."
+          }')
+        echo "$REWORK" >> "$DEV_QUEUE"
+        echo "[on_session_end] tester (failed) → developer queue: rework_assignment"
+      fi
+      ;;
+
+  esac
+
+  # Consume the handoff file — it is single-use
+  rm -f "$HANDOFF_FILE"
+fi
+
+# --- 5. Todo cleanup ---
+# Remove project/todo.md if it is effectively empty (only blanks, # Todo, and HTML comments).
+# Runs unconditionally on every session end regardless of agent type.
+bash "$PROJECT_DIR/scripts/todo_cleanup.sh"

package/hooks/prompt_router.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# hooks/prompt_router.sh
+# Claude Code UserPromptSubmit hook — routes prompts through the Jenga Router.
+# Reads JSON from stdin, routes through Jenga Router, outputs JSON to stdout.
+# Falls back to passthrough if the router is unreachable.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HELPER="$SCRIPT_DIR/prompt_router_helper.js"
+
+# Pass stdin through the Node.js helper
+exec node "$HELPER"

package/hooks/prompt_router_helper.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// hooks/prompt_router_helper.js
+// Companion helper for prompt_router.sh — implements Claude Code UserPromptSubmit logic.
+// Reads JSON payload from stdin, checks if the Jenga Router is running,
+// and either routes the prompt or passes it through unchanged.
+
+"use strict";
+const { readFileSync, existsSync } = require("fs");
+const { join } = require("path");
+
+const projectRoot = join(__dirname, "..");
+
+// Read stdin (JSON payload from Claude Code: {"prompt": "..."})
+let input;
+try {
+  const raw = readFileSync("/dev/stdin", "utf8").trim();
+  input = JSON.parse(raw);
+} catch {
+  process.stdout.write("{}");
+  process.exit(0);
+}
+
+const prompt = input.prompt || "";
+
+if (!prompt) {
+  process.stdout.write(JSON.stringify(input));
+  process.exit(0);
+}
+
+// Check if the Jenga Router is running via its PID file
+const pidFile = join(projectRoot, "mcp", "router", ".pid");
+if (!existsSync(pidFile)) {
+  // Router not running — passthrough
+  process.stdout.write(JSON.stringify(input));
+  process.exit(0);
+}
+
+let pid;
+try {
+  pid = parseInt(readFileSync(pidFile, "utf8").trim(), 10);
+  process.kill(pid, 0); // Signal 0 just checks if the process is alive
+} catch {
+  // Router not responsive — passthrough
+  process.stdout.write(JSON.stringify(input));
+  process.exit(0);
+}
+
+// Router is alive — call it with a ≤ 500ms timeout.
+// timeout enforced by calling code (e.g. AbortController / Promise.race in future router client)
+// Router client integration TBD; passthrough until wired up.
+process.stdout.write(JSON.stringify(input));
+process.exit(0);

package/hooks/session_end_helper.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// hooks/session_end_helper.js
+// Detects and strips [JENGA:SESSION_END:<skill>] from Claude output.
+
+import { readFileSync } from "fs";
+
+const SIGNAL_RE = /\[JENGA:SESSION_END:([a-zA-Z0-9_-]+)\]/;
+
+const input = readFileSync("/dev/stdin", "utf8");
+const lines = input.split("\n");
+const filteredLines = [];
+let detectedSkill = null;
+
+for (const line of lines) {
+  const match = line.match(SIGNAL_RE);
+  if (match) {
+    detectedSkill = match[1];
+    // Skip this line (strip it from output)
+  } else {
+    filteredLines.push(line);
+  }
+}
+
+if (detectedSkill) {
+  process.stderr.write(`[jenga-router] Session ended: ${detectedSkill}\n`);
+  // TODO: Call router end_session MCP tool (E11_S04)
+}
+
+process.stdout.write(filteredLines.join("\n"));

package/hooks/session_end_watcher.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# hooks/session_end_watcher.sh
+# Detects [JENGA:SESSION_END:<skill>] in output, signals router, strips marker.
+
+SIGNAL_PATTERN='\[JENGA:SESSION_END:[a-zA-Z0-9_-]+\]'
+
+# Read all input
+INPUT=$(cat)
+
+# Check for signal
+SIGNAL_LINE=$(echo "$INPUT" | grep -oE "$SIGNAL_PATTERN" | head -1)
+
+if [ -n "$SIGNAL_LINE" ]; then
+  # Extract skill name
+  SKILL=$(echo "$SIGNAL_LINE" | sed 's/\[JENGA:SESSION_END:\(.*\)\]/\1/')
+
+  # TODO: Call end_session on router via MCP (wired in E11_S04)
+  echo "[jenga-router] Session ended: $SKILL" >&2
+
+  # Strip the signal line from output
+  echo "$INPUT" | grep -vE "$SIGNAL_PATTERN"
+else
+  echo "$INPUT"
+fi

package/lib/commands/attach.js

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "..", "..");
+
+export async function runAttach(args) {
+  const cwd = process.cwd();
+  const configPath = join(cwd, "jenga.cli.json");
+
+  if (!existsSync(configPath)) {
+    console.error("No jenga.cli.json found. Run `jenga init` first.");
+    process.exit(1);
+  }
+
+  // Resolve absolute path to the jenga router script
+  const routerPath = resolve(packageRoot, "mcp", "router", "index.js");
+
+  // Read or initialise .claude/settings.json
+  const settingsDir = join(cwd, ".claude");
+  const settingsPath = join(settingsDir, "settings.json");
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch (e) {
+      console.error(`Failed to parse .claude/settings.json: ${e.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Merge jenga mcpServers entry (overwrite if already present)
+  if (!settings.mcpServers) settings.mcpServers = {};
+  settings.mcpServers["jenga"] = {
+    type: "stdio",
+    command: "node",
+    args: [routerPath],
+  };
+
+  mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+
+  console.log("Attached. Open a new session in this project to start routing through Jenga.");
+  console.log("  ✓ .claude/settings.json updated");
+}