@jenga-ai/agent 1.3.0 → 3.0.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.3.0",
-  "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.",
+  "version": "3.0.0",
+  "description": "An agentic development workflow for Claude Code, Copilot, and Codex — with a persistent Epic/Story/Task board, an isolated git worktree per task, and a separate tester agent that runs your test suite before anything is marked done.",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "jenga": "./bin/jenga.js"
+    "jenga": "bin/jenga.js"
   },
   "engines": {
     "node": ">=14.13.1"
@@ -54,22 +54,26 @@
     "url": "https://github.com/samwelmunga/jenga-npm/issues"
   },
   "keywords": [
-    "ai-agents",
+    "ai",
+    "agent",
     "agentic",
-    "agentic-workflow",
-    "multi-agent",
-    "agent-framework",
-    "ai-development",
+    "workflow",
+    "framework",
+    "engineering",
+    "development",
+    "coding",
+    "context",
+    "software",
+    "kanban",
+    "board",
+    "management",
     "claude",
     "claude-code",
     "agents-md",
     "copilot",
-    "github-copilot",
     "codex",
-    "skills",
-    "project-management",
-    "developer-tools",
-    "cli"
+    "jenga",
+    "jenga-ai"
   ],
   "author": {
     "name": "Samwel Munga",

package/scripts/apply-j-prefix.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# scripts/apply-j-prefix.sh — mechanical j. prefix rename for skill invocation
+#
+# Implements the mechanism decided in docs/skill-authoring.md's "Invocation Convention"
+# section (E50_S01_T01), with the separator corrected from ":" to "." in E50_S07_T01:
+#
+#   1. Frontmatter-only rename. For every skills/<name>/SKILL.md, rewrites the
+#      frontmatter `name:` field from `<name>` to `j.<name>`. Directory names are
+#      left untouched — neither ":" nor "." is worth putting in a path here, and
+#      Claude Code's native skill resolution is a literal-string match against the
+#      discovery-path directory name, independent of frontmatter content (see the
+#      docs section for the full investigation and citation).
+#   2. Bare-form prose rewrite. For every agents/*.md file, rewrites bare
+#      "/<name>" invocation mentions in prose to "j.<name>", for every skill name
+#      discovered in step 1 — longest-name-first, boundary-safe (skill names
+#      contain hyphens, so a naive `\b` regex would misfire — e.g. it would
+#      falsely match "/doc" inside "/doc-sync"; this only rewrites a match when
+#      the character immediately before/after it is not itself an identifier
+#      character: letter, digit, "-", or ":").
+#
+# Separator history (E50_S07): this script originally emitted "j:<name>". GitHub
+# Copilot CLI validates the frontmatter `name:` VALUE and rejects anything outside
+# [A-Za-z0-9], hyphen, underscore, dot, and space — so the colon made every skill
+# fail to load there. The separator is now "." which is on that allow-list. The
+# namespace intent of E50 is unchanged; only the separator character moved.
+#
+# This script does NOT remove or disable the old bare "/<name>" form. The
+# migration decision recorded alongside the mechanism above is "alias" — both
+# forms keep resolving. This script only ever writes inside skills/ and
+# agents/; it never touches .claude/ or .agents/ (generated mirrors — see
+# CLAUDE.md's Source of Truth rule) and makes no other filesystem change.
+#
+# Usage:
+#   scripts/apply-j-prefix.sh [--dry-run] [--skills-only | --agents-only]
+#
+#   --dry-run       Print the full change list without writing anything.
+#                    Exit code is 0 whether or not changes were found (unless
+#                    --skills-only/--agents-only surface a hard error, e.g. a
+#                    frontmatter `name:` that doesn't match its directory).
+#   --skills-only   Only process skills/*/SKILL.md frontmatter (step 1).
+#   --agents-only   Only process agents/*.md prose (step 2).
+#
+# Idempotent: already-migrated skills (name already starts with "j.") are
+# silently skipped, not re-applied or reported as an error. Skills still carrying
+# the legacy "j:<name>" form are REPAIRED to "j.<name>" rather than skipped —
+# skipping them would silently leave a Copilot-breaking name in place.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/resolve-project-dir.sh
+source "$SCRIPT_DIR/../lib/resolve-project-dir.sh"
+
+PROJECT_DIR="$JENGA_PROJECT_DIR"
+SKILLS_DIR="$PROJECT_DIR/skills"
+AGENTS_DIR="$PROJECT_DIR/agents"
+
+DRY_RUN=0
+DO_SKILLS=1
+DO_AGENTS=1
+
+for arg in "$@"; do
+  case "$arg" in
+    --dry-run) DRY_RUN=1 ;;
+    --skills-only) DO_AGENTS=0 ;;
+    --agents-only) DO_SKILLS=0 ;;
+    -h|--help)
+      echo "Usage: $(basename "$0") [--dry-run] [--skills-only | --agents-only]"
+      exit 0
+      ;;
+    *)
+      echo "❌ Unknown argument: $arg" >&2
+      echo "Usage: $(basename "$0") [--dry-run] [--skills-only | --agents-only]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+export DRY_RUN DO_SKILLS DO_AGENTS SKILLS_DIR AGENTS_DIR
+
+python3 - <<'PY'
+import os
+import re
+import sys
+
+skills_dir = os.environ["SKILLS_DIR"]
+agents_dir = os.environ["AGENTS_DIR"]
+dry_run = os.environ["DRY_RUN"] == "1"
+do_skills = os.environ["DO_SKILLS"] == "1"
+do_agents = os.environ["DO_AGENTS"] == "1"
+
+changes = []
+errors = []
+
+# ---- Step 1: discover skills + (optionally) rewrite frontmatter name: field ----
+skill_names = []  # bare directory names, in sorted order
+name_re = re.compile(r'^name:\s*(.+?)\s*$')
+
+if os.path.isdir(skills_dir):
+    for entry in sorted(os.listdir(skills_dir)):
+        skill_path = os.path.join(skills_dir, entry, "SKILL.md")
+        if not os.path.isfile(skill_path):
+            continue  # not a skill dir (e.g. skills/index/ has no SKILL.md)
+
+        with open(skill_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+
+        if not lines or lines[0].strip() != "---":
+            errors.append(f"{skill_path}: no frontmatter block found")
+            continue
+
+        close_idx = None
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                close_idx = i
+                break
+        if close_idx is None:
+            errors.append(f"{skill_path}: unterminated frontmatter block")
+            continue
+
+        name_idx = None
+        current_name = None
+        for i in range(1, close_idx):
+            m = name_re.match(lines[i])
+            if m:
+                name_idx = i
+                current_name = m.group(1).strip('"\'')
+                break
+
+        if name_idx is None:
+            errors.append(f"{skill_path}: no 'name:' field in frontmatter")
+            continue
+
+        skill_names.append(entry)
+
+        if current_name.startswith("j."):
+            continue  # already migrated — not an error, nothing to do
+
+        # Legacy "j:<name>" form (emitted by this script before E50_S07_T01).
+        # The colon is rejected by GitHub Copilot CLI's skill-name validator, so
+        # this is repaired to "j.<name>" rather than skipped as "already migrated".
+        base_name = current_name[2:] if current_name.startswith("j:") else current_name
+
+        if base_name != entry:
+            errors.append(
+                f"{skill_path}: frontmatter name '{current_name}' does not match "
+                f"directory name '{entry}' — skipped for safety"
+            )
+            continue
+
+        if not do_skills:
+            continue
+
+        new_line = f"name: j.{entry}\n"
+        changes.append({
+            "type": "frontmatter",
+            "file": skill_path,
+            "before": lines[name_idx].rstrip("\n"),
+            "after": new_line.rstrip("\n"),
+        })
+
+        if not dry_run:
+            lines[name_idx] = new_line
+            with open(skill_path, "w", encoding="utf-8") as f:
+                f.writelines(lines)
+elif do_skills:
+    errors.append(f"skills directory not found: {skills_dir}")
+
+# ---- Step 2: rewrite bare "/<name>" prose mentions in agents/*.md ----
+if do_agents and os.path.isdir(agents_dir):
+    # Longest name first so "/jenga-permission-level" is matched (and
+    # consumed) before the shorter "/jenga" gets a chance to.
+    ordered_names = sorted(skill_names, key=len, reverse=True)
+    boundary_chars = set(
+        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-:"
+    )
+
+    for entry in sorted(os.listdir(agents_dir)):
+        if not entry.endswith(".md"):
+            continue
+        agent_path = os.path.join(agents_dir, entry)
+        if not os.path.isfile(agent_path):
+            continue
+
+        with open(agent_path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        file_changes = 0
+
+        for name in ordered_names:
+            pattern = re.compile(r"/" + re.escape(name))
+            matches = []
+            for m in pattern.finditer(text):
+                start, end = m.start(), m.end()
+                if start > 0 and text[start - 1] in boundary_chars:
+                    continue  # part of a longer token, e.g. "x/status"
+                if end < len(text) and text[end] in boundary_chars:
+                    continue  # e.g. "/doc" inside "/doc-sync"
+                matches.append((start, end))
+            for start, end in reversed(matches):
+                text = text[:start] + f"j.{name}" + text[end:]
+                file_changes += 1
+
+        if file_changes:
+            changes.append({
+                "type": "agent-prose",
+                "file": agent_path,
+                "count": file_changes,
+            })
+            if not dry_run:
+                with open(agent_path, "w", encoding="utf-8") as f:
+                    f.write(text)
+elif do_agents and not os.path.isdir(agents_dir):
+    errors.append(f"agents directory not found: {agents_dir}")
+
+# ---- report ----
+mode = "DRY RUN — no files written" if dry_run else "APPLIED"
+print(f"apply-j-prefix.sh — {mode}")
+print(f"Skills discovered: {len(skill_names)}")
+print()
+
+if not changes:
+    print("No changes.")
+else:
+    for c in changes:
+        if c["type"] == "frontmatter":
+            print(f"[frontmatter] {c['file']}")
+            print(f"    - {c['before']}")
+            print(f"    + {c['after']}")
+        else:
+            print(f"[agent-prose] {c['file']} — {c['count']} occurrence(s) rewritten")
+    print()
+    print(f"Total: {len(changes)} change group(s)")
+
+if errors:
+    print()
+    print("Errors / skipped:")
+    for e in errors:
+        print(f"  ⚠ {e}")
+    sys.exit(1)
+
+sys.exit(0)
+PY

package/scripts/consume-context-digest.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# scripts/consume-context-digest.sh
+#
+# Read-and-delete helper for the resolved_context digest handoff convention
+# (E49_S01). The receiving subagent (the one whose sender object carries a
+# resolved_context / resolved_context_path pointing at a file under
+# project/queue/context/) calls this once, as part of reading its own sender
+# object, to fetch the digest content and immediately mark the file consumed
+# — mirroring project/queue/handoffs/'s single-use lifecycle rather than
+# leaving cleanup to a convention every receiver has to remember to follow.
+#
+# Atomic claim: before reading, the target file is renamed to a
+# `.claimed.$$` sibling in the same directory (same TOCTOU-safe pattern
+# hooks/on_session_end.sh section 4 already uses when routing
+# project/queue/handoffs/ files). `mv` between two paths on the same
+# filesystem is a rename(2) syscall — the kernel guarantees exactly one
+# concurrent claimer wins. If the rename fails, another process already
+# consumed (or is consuming) this file; this invocation exits 3 without
+# printing anything, rather than risking a double-read of a file that's
+# about to disappear out from under it.
+#
+# This script does NOT sweep for abandoned digests nobody ever consumes —
+# that backstop is scripts/sweep-stale-context-digests.sh, invoked from
+# hooks/on_session_end.sh.
+#
+# Usage:
+#   consume-context-digest.sh <path-to-digest-file>
+#   consume-context-digest.sh --raw <path-to-digest-file>
+#
+# Options:
+#   --raw    print only the digest field's text (not the full JSON envelope)
+#   -h, --help
+#
+# Output (stdout):
+#   the digest file's full JSON envelope (default), or just its `digest`
+#   field's text with --raw
+#
+# Exit codes:
+#   0  digest read and file deleted
+#   1  usage error
+#   2  target file does not exist (already consumed, or never written)
+#   3  target file was claimed by a concurrent consumer first
+#   4  target file is not valid JSON / missing expected fields
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SELF="$(basename "$0")"
+
+die() {
+  local code="$1"; shift
+  printf '%s: error: %s\n' "$SELF" "$*" >&2
+  exit "$code"
+}
+
+usage() {
+  sed -n '/^# Usage:/,/^# Exit codes:/p' "$0" | sed 's/^# \{0,1\}//' >&2
+  exit 1
+}
+
+command -v jq >/dev/null 2>&1 || die 1 "jq is required but not found on PATH"
+
+RAW=0
+TARGET=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --raw)
+      RAW=1; shift ;;
+    -h|--help)
+      usage ;;
+    -*)
+      die 1 "unknown option: $1" ;;
+    *)
+      [ -z "$TARGET" ] || die 1 "unexpected extra argument: $1"
+      TARGET="$1"; shift ;;
+  esac
+done
+
+[ -n "$TARGET" ] || usage
+[ -f "$TARGET" ] || die 2 "digest file not found: $TARGET (already consumed, or never written)"
+
+CLAIMED_FILE="${TARGET}.claimed.$$"
+if ! mv "$TARGET" "$CLAIMED_FILE" 2>/dev/null; then
+  die 3 "digest file '$TARGET' was claimed by a concurrent consumer — skipping"
+fi
+
+# Always attempt to remove the claimed temp file, whether jq succeeds or not,
+# so a malformed digest can't leave a permanent orphan behind.
+cleanup() {
+  rm -f "$CLAIMED_FILE" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+if [ "$RAW" -eq 1 ]; then
+  DIGEST_TEXT=$(jq -r '.digest // empty' "$CLAIMED_FILE" 2>/dev/null) || die 4 "'$TARGET' is not valid digest JSON"
+  [ -n "$DIGEST_TEXT" ] || die 4 "'$TARGET' has no 'digest' field"
+  printf '%s\n' "$DIGEST_TEXT"
+else
+  jq -e '.' "$CLAIMED_FILE" >/dev/null 2>&1 || die 4 "'$TARGET' is not valid JSON"
+  cat "$CLAIMED_FILE"
+fi