rhachet-roles-ehmpathy 1.13.2 → 1.13.3

package/dist/logic/roles/mechanic/.skills/git.worktree.set.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = findsert a git worktree for a branch
+#
+# .why  = enable parallel work on same repo without nested worktrees
+#         worktrees are placed outside repo so git diff stays clean
+#
+# .how  = creates worktree at @gitroot/../_worktrees/$reponame/$branch
+#
+# usage:
+#   git.worktree.set.sh <branch>            # findsert worktree
+#   git.worktree.set.sh <branch> --open     # findsert + open in codium
+#   git.worktree.set.sh <branch> --main     # create from origin/main
+#
+# guarantee:
+#   - idempotent: [KEEP] if exists, [CREATE] if not
+#   - works from root repo or from within a worktree
+#   - worktree placed outside repo (not nested)
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# parse arguments
+BRANCH=""
+FLAG_OPEN=false
+FLAG_MAIN=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --open)
+      FLAG_OPEN=true
+      shift
+      ;;
+    --main)
+      FLAG_MAIN=true
+      shift
+      ;;
+    -*)
+      echo "error: unknown flag '$1'"
+      echo "usage: git.worktree.set.sh <branch> [--open] [--main]"
+      exit 1
+      ;;
+    *)
+      if [[ -z "$BRANCH" ]]; then
+        BRANCH="$1"
+      else
+        echo "error: unexpected argument '$1'"
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+# validate branch argument
+if [[ -z "$BRANCH" ]]; then
+  echo "error: branch name required"
+  echo "usage: git.worktree.set.sh <branch> [--open] [--main]"
+  exit 1
+fi
+
+# resolve paths
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+WORKTREE_NAME="$(sanitize_branch_name "$BRANCH")"
+WORKTREE_PATH="$REPO_WORKTREES_DIR/$WORKTREE_NAME"
+
+# ensure parent directory exists
+mkdir -p "$REPO_WORKTREES_DIR"
+
+# findsert logic
+if [[ -d "$WORKTREE_PATH" ]]; then
+  echo "[KEEP] $WORKTREE_NAME => $WORKTREE_PATH"
+else
+  # create worktree
+  if [[ "$FLAG_MAIN" == true ]]; then
+    # fetch latest main first
+    git fetch origin main 2>/dev/null || git fetch origin master 2>/dev/null || true
+
+    # create new branch from origin/main
+    git worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/main 2>/dev/null || \
+      git worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/master
+  else
+    # check if branch exists
+    if git show-ref --verify --quiet "refs/heads/$BRANCH" 2>/dev/null; then
+      # branch exists locally, checkout existing
+      git worktree add "$WORKTREE_PATH" "$BRANCH"
+    elif git show-ref --verify --quiet "refs/remotes/origin/$BRANCH" 2>/dev/null; then
+      # branch exists on remote, track it
+      git worktree add --track -b "$BRANCH" "$WORKTREE_PATH" "origin/$BRANCH"
+    else
+      # create new branch from current HEAD
+      git worktree add -b "$BRANCH" "$WORKTREE_PATH"
+    fi
+  fi
+
+  echo "[CREATE] $WORKTREE_NAME => $WORKTREE_PATH"
+fi
+
+# open in codium if requested
+if [[ "$FLAG_OPEN" == true ]]; then
+  echo "opening in codium..."
+  codium "$WORKTREE_PATH"
+fi

package/dist/logic/roles/mechanic/.skills/git.worktree.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = dispatcher for git worktree management
+#
+# .why  = single entry point for get|set|del subcommands
+#         enables convenient `git.worktree.sh get|set|del` interface
+#
+# .how  = routes to git.worktree.{get,set,del}.sh based on subcommand
+#
+# usage:
+#   git.worktree.sh get                     # list worktrees
+#   git.worktree.sh set <branch>            # findsert worktree
+#   git.worktree.sh set <branch> --open     # findsert + open in codium
+#   git.worktree.sh set <branch> --main     # create from origin/main
+#   git.worktree.sh del <branch>            # remove worktree
+#
+# guarantee:
+#   - dispatches to correct subcommand script
+#   - shows usage on invalid/missing subcommand
+#   - fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUBCOMMAND="${1:-}"
+
+case "$SUBCOMMAND" in
+  get|set|del)
+    shift
+    exec "$SCRIPT_DIR/git.worktree.$SUBCOMMAND.sh" "$@"
+    ;;
+  *)
+    echo "usage: git.worktree.sh <command> [args]"
+    echo ""
+    echo "commands:"
+    echo "  get              list worktrees for this repo"
+    echo "  set <branch>     findsert worktree for branch"
+    echo "  del <branch>     remove worktree for branch"
+    echo ""
+    echo "options (for set):"
+    echo "  --open           open worktree in codium after creation"
+    echo "  --main           create branch from origin/main"
+    exit 1
+    ;;
+esac

package/dist/logic/roles/mechanic/.skills/init.bhuild.sh

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = initialize a .behavior directory for bhuild thoughtroute
+#
+# .why  = standardize the behavior-driven development thoughtroute
+#         by scaffolding a structured directory with:
+#           - wish definition
+#           - vision statement
+#           - acceptance criteria
+#           - research prompts
+#           - distillation prompts
+#           - blueprint prompts
+#           - roadmap prompts
+#           - execution prompts
+#           - feedback template
+#
+# .how  = creates .behavior/v${isodate}.${behaviorname}/ with
+#         all necessary scaffold files for the bhuild thoughtroute
+#
+# usage:
+#   init.bhuild.sh --name <behaviorname> [--dir <directory>]
+#
+# guarantee:
+#   - creates .behavior/ if missing
+#   - creates versioned behavior directory
+#   - findserts all thoughtroute files (creates if missing, skips if exists)
+#   - idempotent: safe to rerun
+#   - fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+# parse arguments
+BEHAVIOR_NAME=""
+TARGET_DIR="$PWD"
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --name)
+      BEHAVIOR_NAME="$2"
+      shift 2
+      ;;
+    --dir)
+      TARGET_DIR="$2"
+      shift 2
+      ;;
+    *)
+      echo "error: unknown argument '$1'"
+      echo "usage: init.bhuild.sh --name <behaviorname> [--dir <directory>]"
+      exit 1
+      ;;
+  esac
+done
+
+# validate required arguments
+if [[ -z "$BEHAVIOR_NAME" ]]; then
+  echo "error: --name is required"
+  echo "usage: init.bhuild.sh --name <behaviorname> [--dir <directory>]"
+  exit 1
+fi
+
+# generate isodate in format YYYY_MM_DD
+ISO_DATE=$(date +%Y_%m_%d)
+
+# trim trailing .behavior from TARGET_DIR if present
+TARGET_DIR="${TARGET_DIR%/.behavior}"
+TARGET_DIR="${TARGET_DIR%.behavior}"
+
+# construct behavior directory path (absolute)
+BEHAVIOR_DIR="$TARGET_DIR/.behavior/v${ISO_DATE}.${BEHAVIOR_NAME}"
+
+# compute relative path from caller's $PWD for file contents
+BEHAVIOR_DIR_REL="$(realpath --relative-to="$PWD" "$TARGET_DIR")/.behavior/v${ISO_DATE}.${BEHAVIOR_NAME}"
+# normalize: remove leading ./ if present
+BEHAVIOR_DIR_REL="${BEHAVIOR_DIR_REL#./}"
+
+# create behavior directory (idempotent)
+mkdir -p "$BEHAVIOR_DIR"
+
+# helper: findsert file (create if missing, skip if exists)
+findsert() {
+  local filepath="$1"
+  if [[ -f "$filepath" ]]; then
+    echo "   [KEEP] $(basename "$filepath")"
+    return 0
+  fi
+  cat > "$filepath"
+  echo "   [CREATE] $(basename "$filepath")"
+}
+
+# findsert 0.wish.md
+findsert "$BEHAVIOR_DIR/0.wish.md" << 'EOF'
+wish =
+
+EOF
+
+# findsert 1.vision.md
+findsert "$BEHAVIOR_DIR/1.vision.md" << 'EOF'
+
+EOF
+
+# findsert 2.criteria.md
+findsert "$BEHAVIOR_DIR/2.criteria.md" << 'EOF'
+# usecase.1 = ...
+given()
+  when()
+    then()
+      sothat()
+    then()
+    then()
+      sothat()
+  when()
+    then()
+
+given()
+  ...
+
+# usecase.2 = ...
+...
+EOF
+
+# findsert 3.1.research.domain._.v1.src
+findsert "$BEHAVIOR_DIR/3.1.research.domain._.v1.src" << EOF
+research the domain available in order to fulfill the wish declared
+in $BEHAVIOR_DIR_REL/0.wish.md
+
+specifically
+- what are the domain objects that are involved with this wish
+  - entities
+  - events
+  - literals
+- what are the domain operations
+  - getOne
+  - getAll
+  - setCreate
+  - setUpdate
+  - setDelete
+  - ...
+
+---
+
+use web search to discover and research
+- cite every claim
+- number each citation
+- clone exact quotes from each citation
+
+focus on these sdk's for reference, if provided
+-
+
+---
+
+emit into $BEHAVIOR_DIR_REL/3.1.research.domain._.v1.i1.md
+EOF
+
+# findsert 3.2.distill.domain._.v1.src
+findsert "$BEHAVIOR_DIR/3.2.distill.domain._.v1.src" << EOF
+distill the declastruct domain.objects and domain.operations that would
+- enable fulfillment of this wish $BEHAVIOR_DIR_REL/0.wish.md
+- given the research declared here $BEHAVIOR_DIR_REL/3.1.research.domain._.v1.i1.md
+
+procedure
+1. declare the usecases and envision the contract that would be used to fulfill the usecases
+2. declare the domain.objects, domain.operations, and access.daos that would fulfill this, via the declastruct pattern in this repo
+
+emit into
+- $BEHAVIOR_DIR_REL/3.2.distill.domain._.v1.i1.md
+EOF
+
+# findsert 3.3.blueprint.v1.src
+findsert "$BEHAVIOR_DIR/3.3.blueprint.v1.src" << EOF
+propose a blueprint for how we can implement the wish described
+- in $BEHAVIOR_DIR_REL/0.wish.md
+
+with the domain distillation declared
+- in $BEHAVIOR_DIR_REL/3.2.distill.domain._.v1.i1.md
+
+follow the patterns already present in this repo
+
+---
+
+reference the below for full context
+- $BEHAVIOR_DIR_REL/0.wish.md
+- $BEHAVIOR_DIR_REL/3.1.research.domain._.v1.i1.md
+- $BEHAVIOR_DIR_REL/3.2.distill.domain._.v1.i1.md
+
+
+---
+
+emit to $BEHAVIOR_DIR_REL/3.3.blueprint.v1.i1.md
+EOF
+
+# findsert 4.1.roadmap.v1.src
+findsert "$BEHAVIOR_DIR/4.1.roadmap.v1.src" << EOF
+declare a roadmap,
+
+- checklist style
+- with ordered dependencies
+- with behavioral acceptance criteria
+- with behavioral acceptance verification at each step
+
+for how to execute the blueprint specified in $BEHAVIOR_DIR_REL/3.3.blueprint.v1.i1.md
+
+---
+
+emit into $BEHAVIOR_DIR_REL/4.1.roadmap.v1.i1.md
+EOF
+
+# findsert 5.1.execution.phase0_to_phaseN.v1.src
+findsert "$BEHAVIOR_DIR/5.1.execution.phase0_to_phaseN.v1.src" << EOF
+bootup your mechanic's role via \`npx rhachet roles boot --repo ehmpathy --role mechanic\`
+
+then, execute
+- phase0 to phaseN
+of roadmap
+- $BEHAVIOR_DIR_REL/4.1.roadmap.v1.i1.md
+
+ref:
+- $BEHAVIOR_DIR_REL/3.3.blueprint.v1.i1.md
+
+---
+
+track your progress
+
+emit todos and check them off into
+- $BEHAVIOR_DIR_REL/5.1.execution.phase0_to_phaseN.v1.i1.md
+EOF
+
+# findsert .ref.[feedback].v1.[given].by_human.md
+findsert "$BEHAVIOR_DIR/.ref.[feedback].v1.[given].by_human.md" << EOF
+emit your response to the feedback into
+- $BEHAVIOR_DIR_REL/.ref.[feedback].v1.[taken].by_robot.md
+
+1. emit your response checklist
+2. exec your response plan
+3. emit your response checkoffs into the checklist
+
+---
+
+first, bootup your mechanics briefs again
+
+npx rhachet roles boot --repo ehmpathy --role mechanic
+
+---
+---
+---
+
+
+# blocker.1
+
+---
+
+# nitpick.2
+
+---
+
+# blocker.3
+EOF
+
+echo ""
+echo "behavior thoughtroute initialized!"
+echo "   $BEHAVIOR_DIR"

package/dist/logic/roles/mechanic/.skills/init.claude.hooks.forbid.stderr.redirect.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind forbid.stderr.redirect hook to Claude settings
+#
+# .why  = when Claude uses 2>&1, error messages are hidden and
+#         debugging becomes harder. this hook blocks such commands.
+#
+# .how  = uses jq to findsert the PreToolUse hook configuration
+#         into .claude/settings.local.json
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (permissions, other hooks)
+#   ✔ idempotent: no-op if hook already present
+#   ✔ prepends to hooks array (runs before other Bash hooks)
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+SKILLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_SCRIPT="$SKILLS_DIR/claude.hooks/forbid.stderr.redirect.sh"
+
+# Verify hook script exists
+if [[ ! -f "$HOOK_SCRIPT" ]]; then
+  echo "❌ hook script not found: $HOOK_SCRIPT" >&2
+  exit 1
+fi
+
+# Define the hook configuration to findsert
+HOOK_CONFIG=$(cat <<EOF
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOOK_SCRIPT",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+)
+
+# Ensure .claude directory exists
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+# Initialize settings file if it doesn't exist
+if [[ ! -f "$SETTINGS_FILE" ]]; then
+  echo "{}" > "$SETTINGS_FILE"
+fi
+
+# Findsert: ensure hook is at the front of the hooks array
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: $hook.hooks.PreToolUse[0].hooks[0].command;
+
+  # Check if hook is already first in the Bash matcher
+  def hookIsFirst:
+    (.hooks.PreToolUse // [])
+    | map(select(.matcher == "Bash") | .hooks // [])
+    | flatten
+    | first
+    | .command == targetCmd;
+
+  # If hook is already first, return unchanged
+  if hookIsFirst then
+    .
+  else
+    # Ensure .hooks exists
+    .hooks //= {} |
+
+    # Ensure .hooks.PreToolUse exists
+    .hooks.PreToolUse //= [] |
+
+    # Check if our matcher already exists
+    if (.hooks.PreToolUse | map(.matcher) | index("Bash")) then
+      # Matcher exists - remove our hook if present, then prepend it
+      .hooks.PreToolUse |= map(
+        if .matcher == "Bash" then
+          # Remove existing instance of our hook, then prepend
+          .hooks = $hook.hooks.PreToolUse[0].hooks + (.hooks | map(select(.command != targetCmd)))
+        else
+          .
+        end
+      )
+    else
+      # Matcher does not exist, add the entire entry
+      .hooks.PreToolUse += $hook.hooks.PreToolUse
+    end
+  end
+' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp"
+
+# Check if any changes were made
+if diff -q "$SETTINGS_FILE" "$SETTINGS_FILE.tmp" >/dev/null 2>&1; then
+  rm "$SETTINGS_FILE.tmp"
+  echo "👌 forbid.stderr.redirect hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 forbid.stderr.redirect hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ Claude will now be blocked from using 2>&1 in commands"

package/dist/logic/roles/mechanic/.skills/init.claude.hooks.pretooluse.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic PreToolUse hook to Claude settings
+#
+# .why  = when Claude attempts a Bash command not covered by existing
+#         permissions, this hook provides feedback asking it to
+#         reconsider whether a pre-approved command could work instead.
+#
+#         this reduces unnecessary permission prompts and encourages
+#         consistent command patterns across the project.
+#
+# .how  = uses jq to findsert the PreToolUse hook configuration
+#         into .claude/settings.local.json
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (permissions, other hooks)
+#   ✔ idempotent: no-op if hook already present
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+SKILLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_SCRIPT="$SKILLS_DIR/claude.hooks/check.pretooluse.permissions.sh"
+
+# Verify hook script exists
+if [[ ! -f "$HOOK_SCRIPT" ]]; then
+  echo "❌ hook script not found: $HOOK_SCRIPT" >&2
+  exit 1
+fi
+
+# Define the hook configuration to findsert
+HOOK_CONFIG=$(cat <<EOF
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOOK_SCRIPT",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+)
+
+# Ensure .claude directory exists
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+# Initialize settings file if it doesn't exist
+if [[ ! -f "$SETTINGS_FILE" ]]; then
+  echo "{}" > "$SETTINGS_FILE"
+fi
+
+# Findsert: merge the hook configuration if not already present
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: $hook.hooks.PreToolUse[0].hooks[0].command;
+
+  # Check if hook already exists
+  def hookExists:
+    (.hooks.PreToolUse // [])
+    | map(select(.matcher == "Bash") | .hooks // [])
+    | flatten
+    | map(.command)
+    | any(. == targetCmd);
+
+  # If hook already exists, return unchanged
+  if hookExists then
+    .
+  else
+    # Ensure .hooks exists
+    .hooks //= {} |
+
+    # Ensure .hooks.PreToolUse exists
+    .hooks.PreToolUse //= [] |
+
+    # Check if our matcher already exists
+    if (.hooks.PreToolUse | map(.matcher) | index("Bash")) then
+      # Matcher exists, add our hook to its hooks array
+      .hooks.PreToolUse |= map(
+        if .matcher == "Bash" then
+          .hooks += $hook.hooks.PreToolUse[0].hooks
+        else
+          .
+        end
+      )
+    else
+      # Matcher does not exist, add the entire entry
+      .hooks.PreToolUse += $hook.hooks.PreToolUse
+    end
+  end
+' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp"
+
+# Check if any changes were made
+if diff -q "$SETTINGS_FILE" "$SETTINGS_FILE.tmp" >/dev/null 2>&1; then
+  rm "$SETTINGS_FILE.tmp"
+  echo "👌 mechanic PreToolUse hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 mechanic PreToolUse hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ Claude will now be reminded to check existing permissions before requesting new ones"