@jenga-ai/agent 1.0.0

package/skills/reconcile-origin/scripts/reconcile-origin.sh

@@ -0,0 +1,372 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+emit_error() {
+  local branch="${1:-}"
+  local code="$2"
+  local message="$3"
+  python3 - "$branch" "$code" "$message" <<'PY'
+import json
+import sys
+
+branch, code, message = sys.argv[1:4]
+payload = {
+    "status": "error",
+    "code": code,
+    "message": message,
+}
+if branch:
+    payload["branch"] = branch
+print(json.dumps(payload, ensure_ascii=False))
+PY
+}
+
+emit_local_branch_missing() {
+  local branch="$1"
+  local remote_exists="$2"
+  python3 - "$branch" "$remote_exists" <<'PY'
+import json
+import sys
+
+branch = sys.argv[1]
+remote_exists = sys.argv[2].lower() == "true"
+print(json.dumps({
+    "status": "local_branch_missing",
+    "branch": branch,
+    "remote_exists": remote_exists,
+    "message": "The requested branch does not exist locally."
+}, ensure_ascii=False))
+PY
+}
+
+emit_ok() {
+  local branch="$1"
+  local rebased_commits="$2"
+  python3 - "$branch" "$rebased_commits" <<'PY'
+import json
+import sys
+
+branch, rebased_commits = sys.argv[1], int(sys.argv[2])
+print(json.dumps({
+    "status": "ok",
+    "branch": branch,
+    "rebased_commits": rebased_commits,
+}, ensure_ascii=False))
+PY
+}
+
+emit_handled_later() {
+  local file="$1"
+  python3 - "$file" <<'PY'
+import json
+import sys
+
+print(json.dumps({
+    "status": "handled_later",
+    "file": sys.argv[1],
+}, ensure_ascii=False))
+PY
+}
+
+rebase_in_progress() {
+  local git_dir
+  git_dir="$(git rev-parse --git-dir)"
+  [[ -d "$git_dir/rebase-merge" || -d "$git_dir/rebase-apply" ]]
+}
+
+annotate_conflicts() {
+  local file="$1"
+  local branch="$2"
+  python3 - "$file" "$branch" <<'PY'
+from pathlib import Path
+import sys
+
+path = Path(sys.argv[1])
+branch = sys.argv[2]
+lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+comment_block = [
+    "# RECONCILE-ORIGIN CONFLICT:\n",
+    f"# Local commits and origin/{branch} both changed the lines below in {path}.\n",
+    "# Resolve the conflict when you are ready, then remove this note if it is no longer needed.\n",
+]
+
+result = []
+i = 0
+while i < len(lines):
+    line = lines[i]
+    if line.startswith("<<<<<<< "):
+        if len(result) >= len(comment_block) and result[-len(comment_block):] == comment_block:
+            pass
+        else:
+            result.extend(comment_block)
+    result.append(line)
+    i += 1
+
+path.write_text("".join(result), encoding="utf-8")
+PY
+}
+
+build_conflict_report() {
+  local branch="$1"
+  shift
+  python3 - "$branch" "$@" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+branch = sys.argv[1]
+files = sys.argv[2:]
+conflicts = []
+
+for file_path in files:
+    path = Path(file_path)
+    if not path.exists():
+        continue
+
+    lines = path.read_text(encoding="utf-8").splitlines()
+    blocks = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if line.startswith("<<<<<<< "):
+            i += 1
+            origin_lines = []
+            while i < len(lines) and lines[i] != "=======":
+                origin_lines.append(lines[i])
+                i += 1
+            if i < len(lines) and lines[i] == "=======":
+                i += 1
+            local_lines = []
+            while i < len(lines) and not lines[i].startswith(">>>>>>>"):
+                local_lines.append(lines[i])
+                i += 1
+            while i < len(lines) and not lines[i].startswith(">>>>>>>"):
+                i += 1
+            if i < len(lines) and lines[i].startswith(">>>>>>>"):
+                i += 1
+            blocks.append(("\n".join(local_lines).strip(), "\n".join(origin_lines).strip()))
+        else:
+            i += 1
+
+    if not blocks:
+        continue
+
+    local_text = "\n\n---\n\n".join(block[0] for block in blocks)
+    origin_text = "\n\n---\n\n".join(block[1] for block in blocks)
+    conflicts.append({
+        "file": file_path,
+        "local_section": local_text,
+        "origin_section": origin_text,
+        "description": f"Overlapping edits between local commits and origin/{branch} across {len(blocks)} conflict block(s).",
+    })
+
+print(json.dumps({
+    "status": "conflict",
+    "branch": branch,
+    "conflicts": conflicts,
+}, ensure_ascii=False))
+PY
+}
+
+fetch_origin_branch() {
+  local branch="$1"
+  git fetch origin "refs/heads/$branch:refs/remotes/origin/$branch" >/dev/null 2>&1
+}
+
+ensure_clean_worktree() {
+  if [[ -n "$(git status --porcelain)" ]]; then
+    emit_error "$1" "uncommitted_changes" "Uncommitted changes detected. Stash or commit them before reconciling with origin."
+    exit 1
+  fi
+}
+
+ensure_branch_context() {
+  local branch="$1"
+  local create_tracking="$2"
+  local current_branch
+  current_branch="$(git branch --show-current)"
+
+  if ! git show-ref --verify --quiet "refs/heads/$branch"; then
+    if git ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
+      if [[ "$create_tracking" == "true" ]]; then
+        fetch_origin_branch "$branch" || {
+          emit_error "$branch" "branch_not_found_on_origin" "Unable to fetch origin/$branch."
+          exit 1
+        }
+        git checkout -b "$branch" --track "origin/$branch" >/dev/null 2>&1 || {
+          emit_error "$branch" "checkout_failed" "Unable to create and check out local tracking branch $branch."
+          exit 1
+        }
+      else
+        emit_local_branch_missing "$branch" "true"
+        exit 0
+      fi
+    else
+      emit_local_branch_missing "$branch" "false"
+      exit 0
+    fi
+  elif [[ "$current_branch" != "$branch" ]]; then
+    git checkout "$branch" >/dev/null 2>&1 || {
+      emit_error "$branch" "checkout_failed" "Unable to check out local branch $branch."
+      exit 1
+    }
+  fi
+}
+
+run_standard_reconcile() {
+  local branch="$1"
+  fetch_origin_branch "$branch" || {
+    emit_error "$branch" "branch_not_found_on_origin" "Branch origin/$branch was not found or could not be fetched."
+    exit 1
+  }
+
+  local rebased_commits
+  rebased_commits="$(git rev-list --count "origin/$branch..HEAD" 2>/dev/null || echo 0)"
+
+  if git rebase "origin/$branch" >/dev/null 2>&1; then
+    emit_ok "$branch" "$rebased_commits"
+    return 0
+  fi
+
+  local conflict_files
+  conflict_files="$(git diff --name-only --diff-filter=U || true)"
+  if [[ -n "$conflict_files" ]]; then
+    local -a conflict_array=()
+    while IFS= read -r line; do
+      [[ -n "$line" ]] && conflict_array+=("$line")
+    done <<<"$conflict_files"
+    local report
+    report="$(build_conflict_report "$branch" "${conflict_array[@]}")"
+    git rebase --abort >/dev/null 2>&1 || true
+    printf '%s\n' "$report"
+    return 0
+  fi
+
+  if rebase_in_progress; then
+    git rebase --abort >/dev/null 2>&1 || true
+  fi
+  emit_error "$branch" "rebase_failed" "The rebase failed before conflict details could be collected."
+  exit 1
+}
+
+run_handle_later() {
+  local branch="$1"
+  local target_file="$2"
+
+  fetch_origin_branch "$branch" || {
+    emit_error "$branch" "branch_not_found_on_origin" "Branch origin/$branch was not found or could not be fetched."
+    exit 1
+  }
+
+  local rebased_commits
+  rebased_commits="$(git rev-list --count "origin/$branch..HEAD" 2>/dev/null || echo 0)"
+
+  if git rebase "origin/$branch" >/dev/null 2>&1; then
+    emit_ok "$branch" "$rebased_commits"
+    return 0
+  fi
+
+  local conflict_files
+  conflict_files="$(git diff --name-only --diff-filter=U || true)"
+  if [[ -z "$conflict_files" ]]; then
+    if rebase_in_progress; then
+      git rebase --abort >/dev/null 2>&1 || true
+    fi
+    emit_error "$branch" "rebase_failed" "The rebase failed before the requested conflict could be handled."
+    exit 1
+  fi
+
+  if ! printf '%s\n' "$conflict_files" | grep -Fxq "$target_file"; then
+    local -a conflict_array=()
+    while IFS= read -r line; do
+      [[ -n "$line" ]] && conflict_array+=("$line")
+    done <<<"$conflict_files"
+    local report
+    report="$(build_conflict_report "$branch" "${conflict_array[@]}")"
+    git rebase --abort >/dev/null 2>&1 || true
+    printf '%s\n' "$report"
+    exit 1
+  fi
+
+  while true; do
+    annotate_conflicts "$target_file" "$branch"
+    git add "$target_file"
+
+    if GIT_EDITOR=true git rebase --continue >/dev/null 2>&1; then
+      emit_handled_later "$target_file"
+      return 0
+    fi
+
+    conflict_files="$(git diff --name-only --diff-filter=U || true)"
+    if [[ -z "$conflict_files" ]]; then
+      emit_error "$branch" "rebase_continue_failed" "Rebase continuation failed after annotating $target_file."
+      exit 1
+    fi
+
+    if printf '%s\n' "$conflict_files" | grep -Fxq "$target_file"; then
+      continue
+    fi
+
+    emit_handled_later "$target_file"
+    return 0
+  done
+}
+
+branch_arg=""
+handle_later_file=""
+create_tracking="false"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --handle-later)
+      shift
+      if [[ $# -eq 0 ]]; then
+        emit_error "$branch_arg" "missing_handle_later_file" "The --handle-later flag requires a file path."
+        exit 1
+      fi
+      handle_later_file="$1"
+      ;;
+    --create-tracking)
+      create_tracking="true"
+      ;;
+    -h|--help)
+      cat <<'USAGE'
+Usage: reconcile-origin.sh [<branch>] [--handle-later <file>] [--create-tracking]
+USAGE
+      exit 0
+      ;;
+    *)
+      if [[ -n "$branch_arg" ]]; then
+        emit_error "$branch_arg" "unexpected_argument" "Unexpected argument: $1"
+        exit 1
+      fi
+      branch_arg="$1"
+      ;;
+  esac
+  shift
+done
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  emit_error "$branch_arg" "not_a_git_repository" "This command must be run inside a git work tree."
+  exit 1
+fi
+
+if rebase_in_progress; then
+  emit_error "$branch_arg" "rebase_in_progress" "A rebase is already in progress. Resolve or abort it before running reconcile-origin."
+  exit 1
+fi
+
+branch="${branch_arg:-$(git branch --show-current)}"
+if [[ -z "$branch" ]]; then
+  emit_error "$branch" "detached_head" "Unable to determine the current branch from a detached HEAD state."
+  exit 1
+fi
+
+ensure_clean_worktree "$branch"
+ensure_branch_context "$branch" "$create_tracking"
+
+if [[ -n "$handle_later_file" ]]; then
+  run_handle_later "$branch" "$handle_later_file"
+else
+  run_standard_reconcile "$branch"
+fi

package/skills/redo/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: redo
+description: Redo parts or entire previous implementations identified by a commit SHA or an Epic/Story number (e.g. E01, E02_S03). Expects an identifier and a description of what to redo and why. Use when the user wants to revisit, rework, or rewrite previously completed work, including updating all affected documentation.
+keywords:
+  - redo
+  - rework
+  - rewrite
+  - revisit
+  - redo task
+examples:
+  - "redo the login implementation"
+  - "rewrite story E02_S01"
+metadata: 
+  prefered_agent: scrum-master
+---
+
+# Redo — Rework a Previous Implementation
+
+## Input Format
+
+```
+/redo <identifier> <description>
+```
+
+- **identifier** — One of:
+  - A git commit SHA (full or short, e.g. `a1b2c3f`)
+  - An Epic number (e.g. `E01`)
+  - A Story number (e.g. `E02_S03`)
+- **description** — What should be redone and, if relevant, why, how, or to what end.
+
+If either part is missing, ask the user to provide it before proceeding.
+
+## Instructions
+
+### 1. Resolve the identifier
+**Commit SHA:**
+- Run `git --no-pager log --stat -1 <SHA>` to retrieve the commit message and changed files.
+- Run `git --no-pager show <SHA>` to inspect the full diff.
+
+**Epic / Story number:**
+- Read the matching file under `$(bash scripts/board_resolver.sh)epics/` or `$(bash scripts/board_resolver.sh)stories/` to understand the scope.
+- Use `git --no-pager log --all --oneline --grep="<epic or story title>"` to locate related commits and their diffs.
+
+Collect the list of **files originally changed** and the **original intent** of the implementation.
+
+### 2. Assess scope
+Compare the user's redo description against the original implementation to determine:
+- Which files need to change.
+- Whether the redo is a partial revision (some files/logic) or a full rewrite.
+- Which tests cover the affected code.
+- Which documentation files reference the affected code or feature (check `project/`, `documentation/`, `project/documentation/`, `README.md`, `WARP.md`).
+
+Summarise scope findings to the user in a brief list before continuing.
+
+### 3. Plan the redo
+Populate `skills/todo/assets/todo_handoff_template.md` with the following pre-collected context:
+- **Mission title**: a short name for the redo work
+- **Goal / objective**: the redo objective — what is changing and the desired outcome
+- **Affected files or scope**: code, tests, and documentation files identified in step 2
+- **Intended approach**: step-by-step changes
+- **Epic/Story linkage**: the identifier resolved in step 1 (e.g. `E02_S03`), or `None` if a commit SHA
+
+Then invoke the `/todo` skill with the populated template. Since the template fields are pre-filled, `/todo` should skip any questions already answered.
+
+Wait for user approval before executing unless the user explicitly told you to go ahead.
+
+## Examples
+- `/redo a1b2c3f Rewrite the auth middleware to use JWT instead of session tokens`
+- `/redo E02_S03 Replace the REST endpoints with GraphQL — the client team needs a flexible query interface`
+- `/redo E01 Redo the entire onboarding epic using the new design-system components`

package/skills/route/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: route
+description: Intelligently routes a prompt to the best-matching skill in the project. Reads available skills, matches the input semantically and by keyword, enriches the prompt with board context and documentation references, then invokes the matched skill with the full context prepended.
+keywords:
+  - "route"
+  - "dispatch"
+  - "auto skill"
+  - "smart prompt"
+  - "find skill"
+examples:
+  - "route: I want to plan a new feature"
+  - "route: something is broken in the auth module"
+  - "route: let's review what's done so far"
+  - "route: analyze this approach in depth before we commit"
+  - "route: add a task to capture this idea"
+---
+
+# Route — Intelligent Skill Dispatcher
+
+## Purpose
+
+`/route <prompt>` takes any natural-language input, finds the best-matching skill in the project, enriches it with live board context and documentation references, and invokes the matched skill — all in a single, fully-loaded message.
+
+---
+
+## Instructions
+
+### Step 1 — Discover Available Skills
+
+Scan both skill registries (they may differ slightly — check both):
+
+```
+.agents/skills/<name>/SKILL.md
+.claude/skills/<name>/SKILL.md       (if the directory exists)
+skills/<name>/SKILL.md               (if the directory exists)
+```
+
+For each skill found, extract the following fields from its YAML front-matter:
+
+| Field | Purpose |
+|---|---|
+| `name` | Canonical identifier |
+| `description` | Primary match signal |
+| `keywords` | Exact/partial keyword match |
+| `examples` | Semantic match reference |
+| `metadata.prefered_agent` | Which agent to delegate to |
+
+Build an in-memory skill registry from this data before proceeding.
+
+---
+
+### Step 2 — Match the Prompt to a Skill
+
+Run matching in three passes (stop at first confident match):
+
+#### Pass 1 — Keyword Match
+Check whether any phrase from a skill's `keywords` list appears verbatim (case-insensitive) in the prompt.
+
+#### Pass 2 — Example Similarity
+Compare the prompt against each skill's `examples` list. Treat this as a semantic similarity check: pick the skill whose examples most closely reflect the intent of the prompt.
+
+#### Pass 3 — Description Match
+If no clear winner has emerged, compare the prompt against each skill's `description` field. Pick the skill whose description best captures what the user is trying to do.
+
+**If two or more skills score equally**, present the top candidates and ask the user to choose:
+
+```
+More than one skill matches your prompt. Which should I apply?
+1. /<skill-a> — <one-line description>
+2. /<skill-b> — <one-line description>
+3. Neither — describe what you need
+```
+
+**If no skill matches at all**, inform the user and offer:
+
+```
+No matching skill found for: "<prompt>"
+Would you like to:
+1. Browse all available skills (/help)
+2. Create a new skill for this use case (/btw)
+3. Proceed without a skill (raw prompt)
+```
+
+---
+
+### Step 3 — Check the Board for Related Context
+
+Read `project/configs/workflow.json` for board paths (default: `project/board/`).
+
+Scan the board for items that are topically related to the prompt:
+
+1. **Epics** — `project/board/epics/` — check `title` and `description` fields
+2. **Stories** — `project/board/stories/` — check `title` and `description` fields
+3. **Tasks** — `project/board/tasks/` — check `title` and `description` fields
+
+Extract any items whose title or description contains keywords from the prompt. Limit to the **top 5 most relevant** results. Do not include items whose status is `Archived` or `Cancelled`.
+
+---
+
+### Step 4 — Check Documentation
+
+Scan the following directories for relevant documentation files:
+
+```
+project/documentation/plans/
+project/documentation/summaries/
+project/documentation/examples/
+docs/
+```
+
+Match filenames and headings against the prompt keywords. Collect the **top 3 most relevant** file paths.
+
+---
+
+### Step 5 — Construct the Enriched Prompt
+
+Assemble the following composite message in **exactly this order**:
+
+#### Part A — Matched Skill (full content)
+Inline the **full body** of the matched skill's `SKILL.md` (everything after the YAML front-matter). This is placed first so the agent reads the skill instructions before anything else.
+
+```
+<!-- SKILL: /<matched-skill-name> -->
+<full skill instructions>
+<!-- END SKILL -->
+```
+
+#### Part B — Board & Documentation Context
+Immediately after the skill, append a context block:
+
+```markdown
+---
+## 📋 Relevant Board Context
+
+<list each matched board item as:>
+- [<status>] **<ID>** — <title> (`project/board/<type>/<filename>`)
+
+## 📄 Relevant Documentation
+
+<list each matched doc as:>
+- `<file-path>` — <one-line summary of the doc's purpose>
+---
+```
+
+If no board items or docs were found, omit the corresponding section rather than leaving it empty.
+
+#### Part C — Original Prompt
+Finally, append the user's original unmodified prompt:
+
+```
+## 🗣 Original Prompt
+
+> <original prompt verbatim>
+```
+
+---
+
+### Step 6 — Invoke the Matched Skill
+
+Deliver the enriched composite message to the appropriate agent:
+
+- If the matched skill specifies `metadata.prefered_agent`, load that agent's definition from `agents/<prefered_agent>.md` and pass the full composite message to it.
+- If no `prefered_agent` is specified, execute the skill instructions directly using the composite message as the working input.
+
+Do **not** summarise or restate the composite message — deliver it as-is.
+
+---
+
+### Step 7 — Report Routing Decision
+
+Before invoking the skill, briefly inform the user:
+
+```
+Routing to: /<matched-skill-name>
+Reason: <one sentence explaining why this skill was chosen>
+Board items found: <count>
+Docs found: <count>
+```
+
+Then proceed immediately — do not wait for user confirmation unless the match was ambiguous (Step 2 tie-break already handled that).

package/skills/self-sync/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: self-sync
+description: Mirror this repo's root-level framework directories into its own `.claude/` and `.agents/` sub-trees so edits to `/skills/*`, `/agents/*`, `/hooks/*`, `/scripts/*`, `/templates/*`, and `settings.json` take effect in the current Claude Code (and non-Claude) agent session — the in-repo replacement for the retired `/distribute` self-sync loop.
+keywords:
+  - "self sync"
+  - "mirror skills"
+  - "sync .claude"
+  - "sync .agents"
+  - "in-repo distribute"
+examples:
+  - "self-sync the mirrors"
+  - "/self-sync --dry-run"
+  - "refresh .claude/skills from root"
+---
+
+# Self-Sync
+
+Copies the framework's root-level entries into this repo's own `.claude/` and `.agents/` mirrors so agent tooling (Claude Code, Copilot, custom) picks up local edits without reinstalling or running `/distribute`.
+
+Delegates the actual filesystem work to `lib/mirror.js`, the same helper used by `scripts/postinstall.js` on consumer installs. Two-directory mirror + delete reconciliation are the only differences from that consumer path.
+
+## Instructions
+
+1. If the user passed `--dry-run` (or asked for a preview), invoke:
+   ```
+   node skills/self-sync/scripts/run.js --dry-run
+   ```
+   Report the printed plan (added / overwritten / deleted) verbatim.
+
+2. Otherwise, invoke:
+   ```
+   node skills/self-sync/scripts/run.js
+   ```
+   Report the printed summary. Do not run any inline `cp`, `rsync`, or `fs` commands — all mirroring goes through the script.
+
+3. If the summary shows `+0 ~0 -0` on a second consecutive real run, the mirrors are already in sync — surface that as confirmation of idempotency.
+
+## Copy Set
+
+The script mirrors exactly these root-level entries:
+
+```
+bin/  lib/  scripts/  agents/  hooks/  mcp/  skills/  templates/  settings.json
+```
+
+This is an **explicit constant** in `scripts/run.js`, deliberately not derived at runtime from `package.json` `files`. Two reasons:
+
+- `package.json` `files` includes `README.md` and `LICENSE`, which should not appear in the agent mirrors.
+- `settings.json` is required in the mirrors but is intentionally not shipped in the npm tarball, so it does not appear in `files`.
+
+The list is kept aligned with `package.json` `files` by convention. If a new top-level framework directory is added, update both.
+
+## Invocation Model
+
+**Manual invocation only.** The user runs `/self-sync` (or `node skills/self-sync/scripts/run.js`) after making framework edits and before expecting them to be visible to the current agent session.
+
+Rationale: an on-`/commit` or file-watch trigger would fire on every edit — including drafts that shouldn't leak into the mirrors — and would obscure the write footprint (delete reconciliation prunes orphans, so accidental deletes on the source side propagate). Making the sync explicit keeps the human in the loop for a destructive-by-default operation, which matches the framework's boundary-checked, dry-runnable posture.
+
+## Dry-Run Behavior
+
+`--dry-run` computes the full plan (added / overwritten / deleted / unchanged) via `lib/mirror.js` without touching the filesystem. Use it before every real run when the mirror state is uncertain, or when running in a repo where uncommitted mirror edits might exist.
+
+## Safety Guarantees
+
+- **Never writes outside the repo root.** `lib/mirror.js` boundary-checks every destination path with `assertInside(destRoot, target)`; the helper throws if a resolved child escapes its destination root.
+- **Additive helper + explicit reconciliation.** The mirror helper is additive by default; delete reconciliation is enabled only because this skill passes `reconcileDeletes: true`.
+- **No shell out.** Pure Node built-ins (`node:fs`, `node:path`) — no `cp`, `rsync`, or subprocess calls.
+- **Idempotent.** A second consecutive run reports `+0 ~0 -0` because the byte-comparison in `filesEqual` classifies unchanged files as `skipped`.
+
+## Guard Rails
+
+- Do not inline mirroring logic in this skill body — all filesystem work goes through `scripts/run.js` → `lib/mirror.js`.
+- Do not run this skill from a directory other than a checkout of the framework repo itself. `scripts/postinstall.js` handles consumer installs; this skill handles the framework's own repo.