@pennyfarthing/core 7.9.2 → 7.9.5

package/pennyfarthing-dist/scripts/core/check-context.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+# check-context.sh - Check current Claude Code context usage
+# Returns: percentage and recommendation for handoff
+#
+# Usage:
+#   ./check-context.sh                    # Output env vars (most recent transcript)
+#   ./check-context.sh --human            # Human-readable output
+#   ./check-context.sh --session <id>     # Check specific session transcript
+#   SESSION_ID=<id> ./check-context.sh    # Alternative: session via env var
+#   eval $(./check-context.sh)            # Load vars into shell
+
+# Parse command line arguments
+HUMAN_MODE=false
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --human)
+            HUMAN_MODE=true
+            shift
+            ;;
+        --session)
+            SESSION_ID="$2"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Derive Claude project path from current directory
+# Claude Code stores transcripts at ~/.claude/projects/<path-with-dashes>
+# The path format is: -Users-name-Projects-project (leading dash, all slashes become dashes)
+PROJECT_DIR="${PROJECT_ROOT:-$(pwd)}"
+CLAUDE_PROJECT_PATH="$HOME/.claude/projects/$(echo "$PROJECT_DIR" | tr '/' '-')"
+
+# Default thresholds (can be overridden by settings.local.json or config.local.yaml)
+DEFAULT_IMMINENT_THRESHOLD=65
+DEFAULT_WARNING_THRESHOLD=60
+DEFAULT_CRITICAL_THRESHOLD=85
+DEFAULT_MAX_TOKENS=200000
+DEFAULT_TIREPUMP_THRESHOLD=60
+
+# Load thresholds and permission_mode from .pennyfarthing/config.local.yaml (preferred) or settings.local.json (fallback)
+PENNYFARTHING_CONFIG="${CLAUDE_PROJECT_DIR:-$PROJECT_DIR}/.pennyfarthing/config.local.yaml"
+SETTINGS_FILE="${CLAUDE_PROJECT_DIR:-$PROJECT_DIR}/.claude/settings.local.json"
+CONFIG=$(python3 -c "
+import json
+import sys
+
+imminent_threshold = $DEFAULT_IMMINENT_THRESHOLD
+warning_threshold = $DEFAULT_WARNING_THRESHOLD
+critical_threshold = $DEFAULT_CRITICAL_THRESHOLD
+max_tokens = $DEFAULT_MAX_TOKENS
+tirepump_threshold = $DEFAULT_TIREPUMP_THRESHOLD
+permission_mode = 'manual'  # Default to manual
+relay_mode = False  # MSSCI-12395: Independent auto-handoff toggle
+
+# First try .pennyfarthing/config.local.yaml (preferred location)
+try:
+    import yaml
+    with open('$PENNYFARTHING_CONFIG', 'r') as f:
+        config = yaml.safe_load(f)
+        if config:
+            if 'context_budget' in config:
+                cb = config['context_budget']
+                imminent_threshold = cb.get('imminent_threshold', imminent_threshold)
+                warning_threshold = cb.get('warning_threshold', warning_threshold)
+                critical_threshold = cb.get('critical_threshold', critical_threshold)
+                max_tokens = cb.get('max_tokens', max_tokens)
+                tirepump_threshold = cb.get('tirepump_threshold', tirepump_threshold)
+            # Read permission_mode and relay_mode from workflow section
+            if 'workflow' in config:
+                if 'permission_mode' in config['workflow']:
+                    permission_mode = config['workflow']['permission_mode']
+                # MSSCI-12395: relay_mode for auto-handoff (independent of permission_mode)
+                if 'relay_mode' in config['workflow']:
+                    relay_mode = config['workflow']['relay_mode'] == True
+except:
+    # Fallback to settings.local.json (legacy location)
+    try:
+        with open('$SETTINGS_FILE', 'r') as f:
+            settings = json.load(f)
+            if 'context_budget' in settings:
+                cb = settings['context_budget']
+                imminent_threshold = cb.get('imminent_threshold', imminent_threshold)
+                warning_threshold = cb.get('warning_threshold', warning_threshold)
+                critical_threshold = cb.get('critical_threshold', critical_threshold)
+                max_tokens = cb.get('max_tokens', max_tokens)
+                tirepump_threshold = cb.get('tirepump_threshold', tirepump_threshold)
+            if 'workflow' in settings:
+                if 'permission_mode' in settings['workflow']:
+                    permission_mode = settings['workflow']['permission_mode']
+                # MSSCI-12395: relay_mode for auto-handoff (independent of permission_mode)
+                if 'relay_mode' in settings['workflow']:
+                    relay_mode = settings['workflow']['relay_mode'] == True
+    except:
+        pass
+
+print(f'IMMINENT_THRESHOLD={imminent_threshold}')
+print(f'WARNING_THRESHOLD={warning_threshold}')
+print(f'CRITICAL_THRESHOLD={critical_threshold}')
+print(f'MAX_TOKENS={max_tokens}')
+print(f'TIREPUMP_THRESHOLD={tirepump_threshold}')
+print(f'PERMISSION_MODE={permission_mode}')
+print(f'RELAY_MODE={str(relay_mode).lower()}')
+" 2>/dev/null)
+
+# Apply config or use defaults
+eval "$CONFIG" 2>/dev/null || {
+    IMMINENT_THRESHOLD=$DEFAULT_IMMINENT_THRESHOLD
+    WARNING_THRESHOLD=$DEFAULT_WARNING_THRESHOLD
+    CRITICAL_THRESHOLD=$DEFAULT_CRITICAL_THRESHOLD
+    MAX_TOKENS=$DEFAULT_MAX_TOKENS
+    TIREPUMP_THRESHOLD=$DEFAULT_TIREPUMP_THRESHOLD
+}
+
+# Find transcript - either specific session or most recent
+if [ -n "$SESSION_ID" ]; then
+    # Session-specific: look for transcript with matching session ID
+    TRANSCRIPT="$CLAUDE_PROJECT_PATH/${SESSION_ID}.jsonl"
+    if [ ! -f "$TRANSCRIPT" ]; then
+        if [ "$HUMAN_MODE" = "true" ]; then
+            echo "⚠️  Context: unknown (session transcript not found: $SESSION_ID)"
+        else
+            echo "CONTEXT_ERROR=session_not_found"
+            echo "CONTEXT_SESSION=$SESSION_ID"
+        fi
+        exit 1
+    fi
+else
+    # Default: find most recent transcript (current session)
+    TRANSCRIPT=$(ls -t "$CLAUDE_PROJECT_PATH"/*.jsonl 2>/dev/null | grep -v "agent-" | head -1)
+    if [ -z "$TRANSCRIPT" ]; then
+        if [ "$HUMAN_MODE" = "true" ]; then
+            echo "⚠️  Context: unknown (no transcript found)"
+        else
+            echo "CONTEXT_ERROR=no_transcript"
+        fi
+        exit 1
+    fi
+fi
+
+# Parse transcript for baseline (first turn) and current (last turn) usage data
+# Baseline = system prompt overhead, cached per session
+# Usable = current - baseline (what the user's conversation has consumed)
+RESULT=$(python3 -c "
+import sys
+import json
+
+warning_threshold = $WARNING_THRESHOLD
+max_tokens = $MAX_TOKENS
+permission_mode = '$PERMISSION_MODE'
+relay_mode = '$RELAY_MODE' == 'true'  # MSSCI-12395: Independent auto-handoff toggle
+tirepump_threshold = $TIREPUMP_THRESHOLD  # Threshold for TirePump auto-handoff (configurable)
+
+with open('$TRANSCRIPT', 'r') as f:
+    lines = f.readlines()
+
+# Find first and last lines with usage data
+first_total = None
+last_total = None
+
+for line in lines:
+    try:
+        data = json.loads(line.strip())
+        if 'message' in data and 'usage' in data['message']:
+            usage = data['message']['usage']
+            input_t = usage.get('input_tokens', 0)
+            cache_read = usage.get('cache_read_input_tokens', 0)
+            cache_create = usage.get('cache_creation_input_tokens', 0)
+            total = cache_read + cache_create + input_t
+
+            if first_total is None:
+                first_total = total
+            last_total = total
+    except:
+        continue
+
+if last_total is not None:
+    # Baseline is first turn's total (system prompt + tools + CLAUDE.md etc)
+    baseline = first_total if first_total is not None else 0
+
+    # Usable tokens = what user's conversation has consumed
+    usable_tokens = last_total - baseline
+
+    # Available capacity = max minus baseline overhead
+    available_capacity = max_tokens - baseline
+
+    # Usable percent = conversation usage as % of available capacity
+    usable_pct = (usable_tokens / available_capacity * 100) if available_capacity > 0 else 0
+
+    # Total percent (for backwards compatibility)
+    total_pct = (last_total / max_tokens) * 100
+
+    # Output all values
+    print(f'CONTEXT_TOKENS={last_total}')
+    print(f'CONTEXT_PERCENT={total_pct:.0f}')
+    print(f'CONTEXT_BASELINE={baseline}')
+    print(f'CONTEXT_USABLE_TOKENS={usable_tokens}')
+    print(f'CONTEXT_USABLE_PERCENT={usable_pct:.0f}')
+    print(f'CONTEXT_AVAILABLE={available_capacity}')
+    print(f'PERMISSION_MODE={permission_mode}')
+
+    # Use usable percent for status decisions (more accurate for user)
+    if usable_pct > warning_threshold:
+        print('CONTEXT_STATUS=HIGH')
+    else:
+        print('CONTEXT_STATUS=OK')
+
+    # RELAY_MODE: Output for handoff-marker.sh to use
+    print(f'RELAY_MODE={str(relay_mode).lower()}')
+
+    # HANDOFF_MODE: 'auto' if relay_mode enabled, 'ask' otherwise
+    # MSSCI-12395: relay_mode controls autohandoff independent of context level
+    if relay_mode:
+        print('HANDOFF_MODE=auto')
+    else:
+        print('HANDOFF_MODE=ask')
+
+    # TirePump: Use CONTEXT_CLEAR (clear + load next agent) when:
+    # 1. relay_mode is true (auto-handoff enabled) - MSSCI-12395
+    # 2. context > 60% (tirepump_threshold)
+    # This enables continuous autonomous runs without manual intervention
+    # Legacy: also support permission_mode == 'turbo' for backwards compatibility
+    use_tirepump = (relay_mode or permission_mode == 'turbo') and usable_pct > tirepump_threshold
+    print(f'USE_TIREPUMP={str(use_tirepump).lower()}')
+
+    # Cyclist detection: Multiple methods for robustness
+    # 1. CYCLIST env var set to '1' (Electron mode - Cyclist spawns Claude)
+    # 2. .cyclist-port file exists (Web mode - Claude connects to running Cyclist)
+    import os
+    from pathlib import Path
+    is_cyclist = os.environ.get('CYCLIST', '') == '1'
+    if not is_cyclist:
+        # Check for .cyclist-port file in packages/cyclist directory
+        # This indicates Cyclist is running in web mode
+        project_dir = os.environ.get('CYCLIST_PROJECT_DIR', os.getcwd())
+        port_file = Path(project_dir) / 'packages' / 'cyclist' / '.cyclist-port'
+        if not port_file.exists():
+            # Also check cwd in case we're already in cyclist dir
+            port_file = Path(os.getcwd()) / '.cyclist-port'
+        is_cyclist = port_file.exists()
+    print(f'IS_CYCLIST={str(is_cyclist).lower()}')
+" 2>/dev/null)
+
+if [ "$HUMAN_MODE" = "true" ]; then
+    eval "$RESULT"
+    if [ "$USE_TIREPUMP" = "true" ]; then
+        echo "🔄 Context: ${CONTEXT_USABLE_PERCENT}% used (${CONTEXT_USABLE_TOKENS} of ${CONTEXT_AVAILABLE} available) - TIREPUMP (clear + next agent)"
+    elif [ "$CONTEXT_STATUS" = "HIGH" ]; then
+        echo "⚠️  Context: ${CONTEXT_USABLE_PERCENT}% used (${CONTEXT_USABLE_TOKENS} of ${CONTEXT_AVAILABLE} available) - AUTO-HANDOFF"
+    else
+        echo "✅ Context: ${CONTEXT_USABLE_PERCENT}% used (${CONTEXT_USABLE_TOKENS} of ${CONTEXT_AVAILABLE} available)"
+    fi
+    echo "   Overhead: ${CONTEXT_BASELINE} tokens (system prompt + tools)"
+    echo "   Mode: ${PERMISSION_MODE}"
+
+    # Output warning messages at configurable thresholds (use usable percent)
+    if [ -n "$CONTEXT_USABLE_PERCENT" ]; then
+        if [ "$CONTEXT_USABLE_PERCENT" -ge "$CRITICAL_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING: Critical (${CONTEXT_USABLE_PERCENT}%) - checkpoint and handoff recommended"
+        elif [ "$CONTEXT_USABLE_PERCENT" -ge "$WARNING_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING: High (${CONTEXT_USABLE_PERCENT}%) - consider handoff soon"
+        fi
+    fi
+else
+    echo "$RESULT"
+
+    # Also output warnings in non-human mode for scripting (use usable percent)
+    eval "$RESULT" 2>/dev/null || true
+    if [ -n "$CONTEXT_USABLE_PERCENT" ]; then
+        if [ "$CONTEXT_USABLE_PERCENT" -ge "$CRITICAL_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING=Critical"
+            echo "CONTEXT_RECOMMENDATION='checkpoint and handoff recommended'"
+        elif [ "$CONTEXT_USABLE_PERCENT" -ge "$WARNING_THRESHOLD" ] 2>/dev/null; then
+            echo "CONTEXT_WARNING=High"
+            echo "CONTEXT_RECOMMENDATION='consider handoff soon'"
+        fi
+    fi
+fi

package/pennyfarthing-dist/scripts/core/handoff-marker.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# Generate complete AGENT_COMMAND block with pre-rendered marker
+# Usage: handoff-marker.sh <next-agent> [--error <message>]
+#
+# Outputs a complete AGENT_COMMAND block that subagents can emit verbatim.
+# Handles IS_CYCLIST and USE_TIREPUMP detection automatically.
+#
+# Single source of truth for marker format - both agents and quick-actions.js
+# should reference this script's output format.
+
+set -euo pipefail
+
+NEXT_AGENT=""
+IS_ERROR=false
+ERROR_MSG=""
+
+# Parse args
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --error)
+      IS_ERROR=true
+      ERROR_MSG="${2:-Error occurred}"
+      shift 2
+      ;;
+    *)
+      if [[ -z "$NEXT_AGENT" ]]; then
+        NEXT_AGENT="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$NEXT_AGENT" && "$IS_ERROR" != "true" ]]; then
+  echo "Usage: handoff-marker.sh <next-agent> [--error <message>]" >&2
+  echo "" >&2
+  echo "Examples:" >&2
+  echo "  handoff-marker.sh dev               # Normal handoff to dev" >&2
+  echo "  handoff-marker.sh tea               # Normal handoff to tea" >&2
+  echo "  handoff-marker.sh --error 'Tests failing'  # Error case" >&2
+  exit 1
+fi
+
+# Get environment from check-context.sh
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+eval "$("$SCRIPT_DIR/check-context.sh" 2>/dev/null)" || true
+
+# Default values if check-context.sh failed
+IS_CYCLIST="${IS_CYCLIST:-false}"
+USE_TIREPUMP="${USE_TIREPUMP:-false}"
+RELAY_MODE="${RELAY_MODE:-false}"
+
+# Generate marker based on environment
+if [[ "$IS_ERROR" == "true" ]]; then
+  # Error case - no marker
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: ""
+  fallback: "$ERROR_MSG"
+  error: true
+---
+EOF
+elif [[ "$IS_CYCLIST" != "true" ]]; then
+  # Not in Cyclist - no marker
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: ""
+  fallback: "Run \`/${NEXT_AGENT}\` to continue"
+---
+EOF
+elif [[ "$RELAY_MODE" != "true" ]]; then
+  # Cyclist + Relay OFF - emit question marker for manual handoff confirmation
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:QUESTION:yesno -->"
+  question: "Ready to hand off to /${NEXT_AGENT}?"
+  fallback: "Run \`/${NEXT_AGENT}\` to continue"
+---
+EOF
+elif [[ "$USE_TIREPUMP" == "true" ]]; then
+  # Cyclist + Relay ON + high context - context clear marker
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:CONTEXT_CLEAR:/${NEXT_AGENT} -->"
+  fallback: "Run \`/${NEXT_AGENT}\` to continue"
+---
+EOF
+else
+  # Cyclist + Relay ON + low context - handoff marker
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:HANDOFF:/${NEXT_AGENT} -->"
+  fallback: "Run \`/${NEXT_AGENT}\` to continue"
+---
+EOF
+fi

package/pennyfarthing-dist/scripts/core/phase-check-start.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# Start an agent with phase check
+# If the current story's phase belongs to a different agent, emit handoff marker instead
+#
+# Usage: phase-check-start.sh <agent>
+# Example: phase-check-start.sh dev
+
+set -euo pipefail
+
+AGENT="${1:-}"
+
+if [[ -z "$AGENT" ]]; then
+  echo "Usage: phase-check-start.sh <agent>" >&2
+  exit 1
+fi
+
+# Find project root
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SCRIPT_DIR="$PROJECT_ROOT/.pennyfarthing/scripts/core"
+SESSION_DIR="$PROJECT_ROOT/.session"
+
+# Find active session file
+SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-session.md" 2>/dev/null | head -1)
+
+if [[ -z "$SESSION_FILE" || ! -f "$SESSION_FILE" ]]; then
+  # No session - just start the agent normally
+  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+fi
+
+# Extract workflow and phase from session (handles multiple formats)
+# Format 1: **Workflow:** value
+# Format 2: - **Workflow**: value
+WORKFLOW=$(grep -E "\*\*Workflow\*?\*?:" "$SESSION_FILE" 2>/dev/null | head -1 | sed 's/.*\*\*Workflow\*\*[:\*]* *//' | tr -d ' ' || echo "")
+PHASE=$(grep -E "\*\*Phase\*?\*?:" "$SESSION_FILE" 2>/dev/null | head -1 | sed 's/.*\*\*Phase\*\*[:\*]* *//' | tr -d ' ' || echo "")
+
+if [[ -z "$WORKFLOW" ]]; then
+  # Can't determine workflow - start normally
+  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+fi
+
+# If no Phase field, try to infer from status patterns
+if [[ -z "$PHASE" ]]; then
+  # Check for approval status (story is done, needs SM to close)
+  if grep -qE "\*\*Status\*\*:.*APPROVED" "$SESSION_FILE" 2>/dev/null; then
+    PHASE="approved"
+  # Check for review status
+  elif grep -qE "Reviewer Assessment|Review.*REJECTED\|Review.*APPROVED" "$SESSION_FILE" 2>/dev/null; then
+    PHASE="review"
+  # Check for green/implementation complete
+  elif grep -qE "Dev Assessment|\*\*Status\*\*:.*GREEN" "$SESSION_FILE" 2>/dev/null; then
+    # Has dev assessment - could be in review or approved
+    if grep -qE "Reviewer Assessment" "$SESSION_FILE" 2>/dev/null; then
+      PHASE="approved"  # Reviewer already assessed
+    else
+      PHASE="review"    # Needs reviewer
+    fi
+  # Check for red/test phase
+  elif grep -qE "TEA Assessment|\*\*Status\*\*:.*RED" "$SESSION_FILE" 2>/dev/null; then
+    PHASE="green"  # TEA done, Dev's turn
+  else
+    # Can't determine phase - start normally
+    exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+  fi
+fi
+
+# Get the owner of this phase
+OWNER=$("$SCRIPT_DIR/run.sh" workflow/phase-owner.sh "$WORKFLOW" "$PHASE" 2>/dev/null || echo "")
+
+if [[ -z "$OWNER" ]]; then
+  # Phase owner lookup failed - start normally
+  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+fi
+
+# Check if this agent owns the phase
+if [[ "$OWNER" == "$AGENT" ]]; then
+  # Correct agent - start normally
+  exec "$SCRIPT_DIR/run.sh" core/agent-session.sh start "$AGENT"
+fi
+
+# Wrong agent! Output the handoff marker and info
+STORY_ID=$(basename "$SESSION_FILE" -session.md)
+
+echo "Phase check: Story $STORY_ID is in '$PHASE' phase (workflow: $WORKFLOW)"
+echo "Phase owner: $OWNER (you requested: $AGENT)"
+echo ""
+
+# Generate and output the handoff marker
+"$SCRIPT_DIR/handoff-marker.sh" "$OWNER"

package/pennyfarthing-dist/scripts/core/prime.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# prime.sh - Load essential project context at agent activation
+# Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
+#
+# Thin wrapper around python -m pennyfarthing_scripts.prime
+
+# Find the package root (where pennyfarthing_scripts lives)
+# Works for both npm installs (node_modules/@pennyfarthing/core) and local dev
+# Use pwd -P to resolve symlinks in the path (handles symlinked parent dirs)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd -P)"
+
+# Fallback: if pennyfarthing_scripts not found at expected location,
+# look in node_modules (handles edge cases like stale copies)
+if [[ ! -d "$PACKAGE_ROOT/pennyfarthing_scripts" ]]; then
+    # Find project root by looking for .pennyfarthing marker
+    PROJECT_ROOT="$PWD"
+    while [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]] && [[ "$PROJECT_ROOT" != "/" ]]; do
+        PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+    done
+    # Try node_modules location
+    if [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pennyfarthing_scripts" ]]; then
+        PACKAGE_ROOT="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
+    fi
+fi
+
+# Set PYTHONPATH so Python can find pennyfarthing_scripts
+export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
+
+exec python3 -m pennyfarthing_scripts.prime "$@"

package/pennyfarthing-dist/scripts/core/run.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env zsh
+# Bootstrap script - finds PROJECT_ROOT and runs the requested script
+# Usage: ./scripts/run.sh <category/script-name> [args...]
+#
+# Scripts are organized in categorical subdirectories:
+#   core/     - Essential scripts (agent-session.sh, check-context.sh)
+#   workflow/ - Workflow mechanics (finish-story.sh, check.sh)
+#   sprint/   - Sprint operations (sprint-status.sh, archive-story.sh)
+#   story/    - Story operations (create-story.sh, size-story.sh)
+#   jira/     - Jira integration (jira-claim-story.sh, jira-reconcile.sh)
+#   git/      - Git operations (create-feature-branches.sh, release.sh)
+#   theme/    - Theme operations (list-themes.sh)
+#   test/     - Test infrastructure (test-setup.sh)
+#   lib/      - Shared libraries (common.sh, logging.sh)
+#   misc/     - Uncategorized utilities
+#   hooks/    - Git and Claude hooks
+#
+# Full paths are REQUIRED to avoid ambiguity:
+#   ./scripts/run.sh core/agent-session.sh start sm
+#   ./scripts/run.sh jira/jira-claim-story.sh MSSCI-12345
+#
+# This solves the absolute path problem by:
+# 1. Finding PROJECT_ROOT by looking for the .pennyfarthing/ directory
+# 2. Exporting PROJECT_ROOT for the script to use
+# 3. Running the script with full absolute paths
+
+set -euo pipefail
+
+# Find PROJECT_ROOT by looking for .pennyfarthing/ marker
+find_project_root() {
+    local dir="$PWD"
+    while [[ ! -d "$dir/.pennyfarthing" ]] && [[ "$dir" != "/" ]]; do
+        dir="$(dirname "$dir")"
+    done
+    if [[ -d "$dir/.pennyfarthing" ]]; then
+        echo "$dir"
+    else
+        echo "Error: Could not find project root (no .pennyfarthing/ directory found)" >&2
+        exit 1
+    fi
+}
+
+PROJECT_ROOT="$(find_project_root)"
+export PROJECT_ROOT
+
+# Get the script to run
+if [[ $# -lt 1 ]]; then
+    echo "Usage: ./scripts/run.sh <category/script-name> [args...]" >&2
+    echo "Example: ./scripts/run.sh core/agent-session.sh start sm" >&2
+    echo "Example: ./scripts/run.sh jira/jira-claim-story.sh MSSCI-12345" >&2
+    exit 1
+fi
+
+SCRIPT_NAME="$1"
+shift
+
+# Single source of truth: .pennyfarthing/scripts
+SCRIPTS_DIR="$PROJECT_ROOT/.pennyfarthing/scripts"
+if [[ ! -d "$SCRIPTS_DIR" ]]; then
+    echo "Error: Scripts directory not found: $SCRIPTS_DIR" >&2
+    exit 1
+fi
+
+# Set PYTHONPATH to find pennyfarthing_scripts module
+# Resolve symlink and go up to package root (pennyfarthing-dist/scripts -> package root)
+SCRIPTS_REAL_PATH="$(cd "$SCRIPTS_DIR" && pwd -P)"
+PENNYFARTHING_PKG_ROOT="$(dirname "$(dirname "$SCRIPTS_REAL_PATH")")"
+if [[ -d "$PENNYFARTHING_PKG_ROOT/pennyfarthing_scripts" ]]; then
+    export PYTHONPATH="${PENNYFARTHING_PKG_ROOT}${PYTHONPATH:+:$PYTHONPATH}"
+fi
+
+# Full path required - script must include category
+SCRIPT_PATH="$SCRIPTS_DIR/$SCRIPT_NAME"
+
+# Python-first dispatch: prefer .py over .sh when available
+# This enables transparent migration of shell scripts to Python
+SCRIPT_BASE="${SCRIPT_NAME%.sh}"
+PYTHON_PATH="$SCRIPTS_DIR/${SCRIPT_BASE}.py"
+
+if [[ -f "$PYTHON_PATH" ]] && command -v python3 &>/dev/null; then
+    exec python3 "$PYTHON_PATH" "$@"
+fi
+
+if [[ -f "$SCRIPT_PATH" ]]; then
+    exec "$SCRIPT_PATH" "$@"
+else
+    echo "Error: Script not found: $SCRIPT_NAME" >&2
+    echo "Full path required. Available categories:" >&2
+    echo "  core/, workflow/, sprint/, story/, jira/, git/, theme/, test/, lib/, misc/, hooks/, cyclist/" >&2
+    echo "Example: run.sh core/agent-session.sh start sm" >&2
+    exit 1
+fi

package/pennyfarthing-dist/scripts/cyclist/is-cyclist.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Check if running inside Cyclist visual terminal
+# Usage: .pennyfarthing/scripts/core/run.sh cyclist/is-cyclist.sh
+#
+# Exit codes:
+#   0 - Running in Cyclist
+#   1 - Not running in Cyclist
+#
+# Output (JSON):
+#   {"cyclist": true/false}
+
+set -euo pipefail
+
+# Check the CYCLIST environment variable (set by ClaudeService.ensureProcess)
+if [[ "${CYCLIST:-}" == "1" ]]; then
+  echo '{"cyclist": true}'
+  exit 0
+else
+  echo '{"cyclist": false}'
+  exit 1
+fi

package/pennyfarthing-dist/scripts/git/README.md

@@ -0,0 +1,25 @@
+# Git Scripts
+
+Scripts for Git operations, branching, and release management.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `create-feature-branches.sh` | Create feature branches in repos |
+| `git-status-all.sh` | Show git status across all repos |
+| `worktree-manager.sh` | Manage git worktrees for parallel work |
+| `install-git-hooks.sh` | Install git hooks in project |
+| `release.sh` | Release workflow (merge develop to main) |
+
+## Usage
+
+```bash
+.pennyfarthing/scripts/core/run.sh git/create-feature-branches.sh feat/my-feature
+.pennyfarthing/scripts/core/run.sh git/release.sh
+```
+
+## Ownership
+
+- **Primary users:** SM agent, DevOps agent
+- **Maintained by:** Core Pennyfarthing team