rhachet-roles-ehmpathy 1.9.0 → 1.10.0

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.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic SessionStart hook to Claude settings
+#
+# .why  = the mechanic role needs to boot on every Claude session
+#         to ensure project context and briefs are loaded.
+#
+#         this script "findserts" (find-or-insert) the SessionStart
+#         hook into .claude/settings.local.json, ensuring:
+#           • the hook is present after running this skill
+#           • no duplication if already present
+#           • idempotent: safe to rerun
+#
+# .how  = uses jq to merge the SessionStart hook configuration
+#         into the existing hooks structure, creating it if absent.
+#
+# 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"
+
+# Define the hook configuration to findsert
+HOOK_CONFIG=$(cat <<'EOF'
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx rhachet roles boot --repo ehmpathy --role mechanic",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+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
+# Strategy: deep merge with existing hooks, creating structure if needed
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: "npx rhachet roles boot --repo ehmpathy --role mechanic";
+
+  # Check if hook already exists
+  def hookExists:
+    (.hooks.SessionStart // [])
+    | map(select(.matcher == "*") | .hooks // [])
+    | flatten
+    | map(.command)
+    | index(targetCmd) != null;
+
+  # If hook already exists, return unchanged
+  if hookExists then
+    .
+  else
+    # Ensure .hooks exists
+    .hooks //= {} |
+
+    # Ensure .hooks.SessionStart exists
+    .hooks.SessionStart //= [] |
+
+    # Check if our matcher already exists
+    if (.hooks.SessionStart | map(.matcher) | index("*")) then
+      # Matcher exists, add our hook to its hooks array
+      .hooks.SessionStart |= map(
+        if .matcher == "*" then
+          .hooks += $hook.hooks.SessionStart[0].hooks
+        else
+          .
+        end
+      )
+    else
+      # Matcher does not exist, add the entire entry
+      .hooks.SessionStart += $hook.hooks.SessionStart
+    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 SessionStart hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 mechanic SessionStart hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ next time you start a Claude session, the mechanic will boot automatically"

package/dist/logic/roles/mechanic/.skills/init.claude.permissions.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic permissions to Claude settings
+#
+# .why  = the mechanic role needs conservative permissions to operate
+#         safely while still being productive.
+#
+#         this script manages permissions in .claude/settings.local.json:
+#           • replaces existing allows entirely (conservative)
+#           • extends denies by appending new entries (conservative)
+#           • extends asks by appending new entries (conservative)
+#           • idempotent: safe to rerun
+#
+# .how  = uses jq to merge the permissions configuration
+#         into the existing settings structure, creating it if absent.
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (hooks, other configs)
+#   ✔ replaces allow list entirely
+#   ✔ appends to deny list (no duplicates)
+#   ✔ appends to ask list (no duplicates)
+#   ✔ idempotent: safe to rerun
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+
+# define the permissions configuration to apply
+PERMISSIONS_CONFIG=$(cat <<'EOF'
+{
+  "permissions": {
+    "deny": [
+      "Bash(git commit:*)"
+    ],
+    "ask": [
+      "Bash(chmod:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm add:*)"
+    ],
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:hub.docker.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(THOROUGH=true npm run test:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npm run test:integration:*)",
+      "Bash(npm run fix:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npx jest:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npm run deploy:dev:*)",
+      "Bash(AWS_PROFILE=ahbode.dev STAGE=dev npm run test:acceptance:*)",
+      "Bash(npm run start:testdb:*)",
+      "Bash(cat:*)",
+      "Bash(unzip:*)",
+      "Bash(npm view:*)"
+    ]
+  }
+}
+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
+
+# apply permissions:
+# - replace allow entirely
+# - append to deny (unique)
+# - append to ask (unique)
+jq --argjson perms "$PERMISSIONS_CONFIG" '
+  # ensure .permissions exists
+  .permissions //= {} |
+
+  # replace allow entirely with our config
+  .permissions.allow = $perms.permissions.allow |
+
+  # append to deny (unique entries only)
+  .permissions.deny = ((.permissions.deny // []) + $perms.permissions.deny | unique) |
+
+  # append to ask (unique entries only)
+  .permissions.ask = ((.permissions.ask // []) + $perms.permissions.ask | unique)
+' "$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 permissions already configured"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔐 mechanic permissions configured successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ permissions applied:"
+echo "   • allow: replaced entirely"
+echo "   • deny: extended (no duplicates)"
+echo "   • ask: extended (no duplicates)"

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = initialize Claude settings for mechanic role
+#
+# .why  = mechanic needs both hooks and permissions configured to
+#         operate effectively. this script dispatches to both:
+#           • init.claude.hooks.sh - binds SessionStart hook
+#           • init.claude.permissions.sh - configures permissions
+#
+#         single entry point for full Claude configuration.
+#
+# .how  = runs both init scripts in sequence from the same directory.
+#
+# guarantee:
+#   ✔ runs both hooks and permissions initialization
+#   ✔ fail-fast on any error
+#   ✔ idempotent: safe to rerun
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "🔧 init claude config for mechanic role..."
+echo ""
+
+# initialize hooks
+"$SCRIPT_DIR/init.claude.hooks.sh"
+echo ""
+
+# initialize permissions
+"$SCRIPT_DIR/init.claude.permissions.sh"
+echo ""
+
+echo "👌 claude config ready"

package/dist/logic/roles/mechanic/.skills/link.claude.transcripts.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = link Claude transcripts into project-local structure
+#
+# .why  = Claude stores transcripts in ~/.claude/projects/<encoded-path>
+#         which makes them hard to browse, version-control, and sync.
+#
+#         this script creates a symlink so transcripts appear under:
+#           <project>/.rhachet/claude/transcripts
+#
+#         without altering, moving, or creating files in Claude storage.
+#
+# guarantee:
+#   ✔ zero mutation to Claude's storage
+#   ✔ fail-fast if transcripts don't exist yet
+#   ✔ safe to rerun (idempotent)
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+DEST="$PROJECT_ROOT/.rhachet/claude/transcripts"
+
+# Resolve where Claude stores transcripts for this project’s cwd
+ENCODED_PATH="$(echo "$PROJECT_ROOT" | sed 's#/#-#g')"
+CLAUDE_STORAGE="$HOME/.claude/projects/$ENCODED_PATH"
+
+# Fail if Claude hasn't created the storage dir yet
+if [[ ! -d "$CLAUDE_STORAGE" ]]; then
+  echo "❌ no Claude transcripts found for this project:"
+  echo "   $CLAUDE_STORAGE"
+  echo "➡️  first run 'claude' once in this directory to create them"
+  exit 1
+fi
+
+# Ensure our local parent folder exists (not Claude’s)
+mkdir -p "$(dirname "$DEST")"
+
+# Create symlink pointing into Claude-managed storage
+ln -sfn "$CLAUDE_STORAGE" "$DEST"
+
+echo "🔗 linked:"
+echo "  $DEST → $CLAUDE_STORAGE"