@pennyfarthing/core 7.6.0 → 7.7.0

package/pennyfarthing-dist/scripts/jira/jira-claim-story.sh

@@ -1,164 +1,22 @@
 #!/usr/bin/env zsh
-# Check and claim a story in Jira for multi-developer coordination
-# Usage: ./scripts/jira-claim-story.sh <story_key_or_jira_key> [--claim]
+# Check and claim a story in Jira
+# Usage: jira-claim-story.sh <issue-key> [--claim]
 #
-# This script uses the `jira` CLI tool (https://github.com/ankitpokhrel/jira)
-#
-# Parameters:
-#   <story_key_or_jira_key>  Either:
-#                             - Story key format: 35-7-feedback-rule-delete-404
-#                             - Jira issue key format: MSSCI-10991
-#
-# Actions:
-#   (default)   Check if story is assigned and show status
-#   --claim     Assign story to current user and move to "In Progress"
+# Thin wrapper that delegates to Python CLI:
+#   python -m pennyfarthing_scripts.jira claim <issue-key> [--claim]
 #
 # Exit codes:
-#   0 - Story is available (unassigned) or successfully claimed
+#   0 - Story is available or successfully claimed
 #   1 - Story is assigned to someone else
-#   2 - Story not found or not synced to Jira
-#   3 - Error (jira CLI not installed, etc.)
+#   2 - Story not found or not synced
+#   3 - Error (CLI not installed, Python not found, etc.)
 
 set -e
 
-# Source common functions
+# Source common functions for Python discovery
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PARENT_DIR="$(dirname "$SCRIPT_DIR")"
 source "${PARENT_DIR}/lib/common.sh"
-source "${PARENT_DIR}/sprint/sprint-common.sh"
-source "${SCRIPT_DIR}/jira-lib.sh"
-
-# Check dependencies (using jira-lib's robust check)
-check_jira_cli
-
-# Check arguments
-if [ -z "$1" ]; then
-    error "Error: Story key or Jira issue key required"
-    echo "Usage: $0 <story_key_or_jira_key> [--claim]"
-    echo ""
-    echo "Examples:"
-    echo "  $0 35-7-feedback-rule-delete-404              # Using story key"
-    echo "  $0 35-7-feedback-rule-delete-404 --claim      # Claim using story key"
-    echo "  $0 MSSCI-10991                                # Using Jira issue key"
-    echo "  $0 MSSCI-10991 --claim                        # Claim using Jira key"
-    exit 3
-fi
-
-INPUT_KEY="$1"
-CLAIM_MODE=false
-[ "$2" = "--claim" ] && CLAIM_MODE=true
-
-# Detect input format: Jira key (MSSCI-12345) vs Story key (35-7-name)
-if [[ "$INPUT_KEY" =~ ^${JIRA_PROJECT}-[0-9]+$ ]]; then
-    # Input is Jira issue key format (e.g., MSSCI-10991)
-    JIRA_ISSUE_KEY="$INPUT_KEY"
-    info "🔍 Using Jira issue key: ${JIRA_ISSUE_KEY}"
-
-    # Skip story file lookup - we'll work directly with Jira
-    STORY_KEY=""
-
-else
-    # Input is story key format (e.g., 35-7-feedback-rule-delete-404)
-    STORY_KEY="$INPUT_KEY"
-
-    # Extract epic number from story key
-    EPIC_NUM=$(echo "$STORY_KEY" | cut -d'-' -f1)
-
-    info "🔍 Checking story ${STORY_KEY} in Jira..."
-
-    # Find the story
-    STORY_FILE=$(find_story_file "$STORY_KEY")
-    if [ -z "$STORY_FILE" ]; then
-        error "Error: Story ${STORY_KEY} not found in sprint files"
-        exit 2
-    fi
-
-    # Get Jira link
-    STORY_JIRA_LINK=$(get_story_field "$STORY_KEY" "jira")
-    if [ "$STORY_JIRA_LINK" = "null" ] || [ -z "$STORY_JIRA_LINK" ]; then
-        warn "⚠️  Story ${STORY_KEY} not synced to Jira yet"
-        echo ""
-        echo "Proceeding without Jira sync. Story will be synced later."
-        echo "To sync now, run: ./scripts/sync-epic-to-jira.sh ${EPIC_NUM}"
-        exit 0
-    fi
-
-    JIRA_ISSUE_KEY=$(extract_jira_key "$STORY_JIRA_LINK")
-    success "✅ Found Jira issue: ${JIRA_ISSUE_KEY}"
-fi
-
-# Get current user
-CURRENT_USER=$(jira me 2>/dev/null || echo "")
-if [ -z "$CURRENT_USER" ]; then
-    error "Error: Could not get current Jira user. Run 'jira init' to configure."
-    exit 3
-fi
-
-info "👤 Current user: ${CURRENT_USER}"
-
-# Get issue details (using --raw for JSON parsing)
-info "📋 Fetching issue details..."
-ISSUE_JSON=$(jira issue view "$JIRA_ISSUE_KEY" --raw 2>/dev/null || echo "{}")
-
-if [ "$ISSUE_JSON" = "{}" ]; then
-    error "Error: Could not fetch issue ${JIRA_ISSUE_KEY}"
-    exit 3
-fi
-
-# Parse assignee (use printf to avoid zsh echo interpreting \n in JSON)
-ASSIGNEE=$(printf '%s' "$ISSUE_JSON" | jq -r '.fields.assignee.displayName // "Unassigned"')
-ASSIGNEE_EMAIL=$(printf '%s' "$ISSUE_JSON" | jq -r '.fields.assignee.emailAddress // ""')
-STATUS=$(printf '%s' "$ISSUE_JSON" | jq -r '.fields.status.name // "Unknown"')
-SUMMARY=$(printf '%s' "$ISSUE_JSON" | jq -r '.fields.summary // "No summary"')
-
-echo ""
-echo "📋 Issue: ${JIRA_ISSUE_KEY}"
-echo "   Summary: ${SUMMARY}"
-echo "   Status: ${STATUS}"
-echo "   Assignee: ${ASSIGNEE}"
-
-# Check assignment status
-if [ "$ASSIGNEE" = "Unassigned" ]; then
-    success "✅ Story is UNASSIGNED - available to claim"
-    
-    if [ "$CLAIM_MODE" = true ]; then
-        info "🎯 Claiming story..."
-        
-        # Assign to self
-        if jira issue assign "$JIRA_ISSUE_KEY" "$(jira me)" --project "$JIRA_PROJECT" 2>/dev/null; then
-            success "✅ Assigned to you"
-        else
-            error "Failed to assign issue"
-            exit 3
-        fi
 
-        # Move to In Progress (if not already)
-        if [ "$STATUS" != "In Progress" ]; then
-            info "📊 Moving to 'In Progress'..."
-            if jira issue move "$JIRA_ISSUE_KEY" "In Progress" --project "$JIRA_PROJECT" 2>/dev/null; then
-                success "✅ Moved to In Progress"
-            else
-                warn "⚠️  Could not transition to In Progress (may already be there or transition not available)"
-            fi
-        fi
-        
-        echo ""
-        success "🎉 Story ${JIRA_ISSUE_KEY} claimed successfully!"
-    else
-        echo ""
-        info "To claim this story, run:"
-        echo "  $0 $STORY_KEY --claim"
-    fi
-    exit 0
-    
-elif [ "$ASSIGNEE_EMAIL" = "$CURRENT_USER" ] || [ "$ASSIGNEE" = "$(jira me 2>/dev/null)" ]; then
-    success "✅ Story is assigned to YOU - proceed with work"
-    exit 0
-    
-else
-    warn "⚠️  Story is assigned to: ${ASSIGNEE}"
-    echo ""
-    echo "This story is already being worked on by someone else."
-    echo "Please choose a different story or coordinate with ${ASSIGNEE}."
-    exit 1
-fi
+# Delegate to Python CLI
+run_python_module jira claim "$@"

package/pennyfarthing-dist/scripts/jira/jira-sync-story.sh

@@ -1,8 +1,18 @@
 #!/usr/bin/env zsh
-# Thin wrapper for jira-sync-story.mjs
-# Usage: ./scripts/jira-sync-story.sh <story_key> [--transition] [--points] [--comment "message"]
+# Sync a single story between sprint YAML and Jira
+# Usage: jira-sync-story.sh <story_key> [--transition] [--points] [--comment "message"]
 #
-# Delegates to Node script for cleaner, more maintainable implementation.
+# Thin wrapper that delegates to Python CLI:
+#   python -m pennyfarthing_scripts.jira create story <story_key> [options]
+#
+# Note: The subcommand is 'create story' but it handles sync, not creation.
+
+set -e
 
+# Source common functions for Python discovery
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec node "${SCRIPT_DIR}/jira/jira-sync-story.mjs" "$@"
+PARENT_DIR="$(dirname "$SCRIPT_DIR")"
+source "${PARENT_DIR}/lib/common.sh"
+
+# Delegate to Python CLI
+run_python_module jira create story "$@"

package/pennyfarthing-dist/scripts/jira/jira-sync.sh

@@ -1,8 +1,16 @@
 #!/usr/bin/env zsh
-# Thin wrapper for jira-sync.mjs
-# Usage: ./scripts/jira-sync.sh <epic_number> [--dry-run] [--transition] [--points]
+# Sync an epic and its stories to Jira
+# Usage: jira-sync.sh <epic_number> [--dry-run] [--transition] [--points]
 #
-# Delegates to Node script for cleaner, more maintainable implementation.
+# Thin wrapper that delegates to Python CLI:
+#   python -m pennyfarthing_scripts.jira sync <epic_number> [options]
 
+set -e
+
+# Source common functions for Python discovery
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-exec node "${SCRIPT_DIR}/jira/jira-sync.mjs" "$@"
+PARENT_DIR="$(dirname "$SCRIPT_DIR")"
+source "${PARENT_DIR}/lib/common.sh"
+
+# Delegate to Python CLI
+run_python_module jira sync "$@"

package/pennyfarthing-dist/scripts/jira/sync-epic-jira.sh

@@ -1,104 +1,16 @@
-#!/bin/bash
+#!/usr/bin/env zsh
 # Sync an epic and its stories to Jira
-# Usage: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh <epic-id> [--dry-run] [--transition] [--points] [--all]
+# Usage: sync-epic-jira.sh <epic-id> [--dry-run] [--transition] [--points] [--all]
 #
-# Example: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh MSSCI-11952
-# Example: .pennyfarthing/scripts/core/run.sh sync-epic-jira.sh MSSCI-11952 --all
-#
-# This script syncs status and story points from sprint YAML to Jira.
-# It wraps the existing jira-sync.mjs for better integration with /sprint skill.
-
-set -euo pipefail
-
-EPIC_ID="${1:-}"
-
-if [[ -z "$EPIC_ID" ]]; then
-  echo "Usage: sync-epic-jira.sh <epic-id> [options]"
-  echo ""
-  echo "Syncs an epic and its stories from sprint YAML to Jira."
-  echo ""
-  echo "Options:"
-  echo "  --dry-run      Show what would be done without making changes"
-  echo "  --transition   Transition Jira issues to match sprint YAML status"
-  echo "  --points       Sync story points from sprint YAML to Jira"
-  echo "  --all          Equivalent to --transition --points"
-  echo ""
-  echo "Examples:"
-  echo "  sync-epic-jira.sh MSSCI-11952              # Show sync status"
-  echo "  sync-epic-jira.sh MSSCI-11952 --dry-run    # Preview changes"
-  echo "  sync-epic-jira.sh MSSCI-11952 --all        # Sync status and points"
-  exit 1
-fi
-
-# PROJECT_ROOT should be set by run.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
-
-SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
-
-if [[ ! -f "$SPRINT_FILE" ]]; then
-  echo "Error: Sprint file not found at $SPRINT_FILE"
-  exit 1
-fi
-
-if ! command -v yq &> /dev/null; then
-  echo "Error: yq is required but not installed"
-  echo "Install with: brew install yq"
-  exit 1
-fi
-
-# Check if epic exists in sprint YAML
-EPIC_EXISTS=$(yq ".epics[] | select(.id == \"$EPIC_ID\") | .id" "$SPRINT_FILE" 2>/dev/null || echo "")
-
-if [[ -z "$EPIC_EXISTS" ]]; then
-  echo "Error: Epic $EPIC_ID not found in $SPRINT_FILE"
-  echo ""
-  echo "Available epics:"
-  yq '.epics[].id' "$SPRINT_FILE" 2>/dev/null || echo "  None found"
-  exit 1
-fi
-
-# Extract epic number for jira-sync.mjs compatibility
-# jira-sync.mjs expects epic number (e.g., 35) not full ID
-# But it also accepts Jira keys directly
-# Let's check if this is a Jira key (MSSCI-XXXXX) or local ID
-
-# Pass through to jira-sync.mjs with remaining arguments
-JIRA_SYNC_SCRIPT="$PROJECT_ROOT/.pennyfarthing/scripts/utils/jira/jira-sync.mjs"
-
-if [[ ! -f "$JIRA_SYNC_SCRIPT" ]]; then
-  # Try alternate location
-  JIRA_SYNC_SCRIPT="$PROJECT_ROOT/pennyfarthing-dist/scripts/utils/jira/jira-sync.mjs"
-fi
-
-if [[ ! -f "$JIRA_SYNC_SCRIPT" ]]; then
-  echo "Error: jira-sync.mjs not found"
-  exit 1
-fi
-
-# Build arguments for jira-sync.mjs
-shift  # Remove epic-id from arguments
-SYNC_ARGS=("$EPIC_ID")
+# Thin wrapper that delegates to Python CLI:
+#   python -m pennyfarthing_scripts.jira sync <epic-id> [options]
 
-# Handle --all flag
-for arg in "$@"; do
-  case "$arg" in
-    --all)
-      SYNC_ARGS+=("--transition" "--points")
-      ;;
-    *)
-      SYNC_ARGS+=("$arg")
-      ;;
-  esac
-done
+set -e
 
-echo "Syncing epic $EPIC_ID to Jira..."
-echo ""
+# Source common functions for Python discovery
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PARENT_DIR="$(dirname "$SCRIPT_DIR")"
+source "${PARENT_DIR}/lib/common.sh"
 
-# Run jira-sync.mjs
-exec node "$JIRA_SYNC_SCRIPT" "${SYNC_ARGS[@]}"
+# Delegate to Python CLI
+run_python_module jira sync "$@"

package/pennyfarthing-dist/scripts/lib/common.sh

@@ -155,3 +155,58 @@ check_dependencies() {
     fi
     return 0
 }
+
+#############################################
+# Python Execution
+#############################################
+
+# get_python
+# Find the best Python interpreter (venv preferred, fallback to system)
+# Sets PYTHON_CMD variable
+#
+# Priority:
+#   1. PROJECT_ROOT/.venv/bin/python (project venv)
+#   2. python3 (system)
+#   3. python (legacy fallback)
+#
+# Usage:
+#   get_python
+#   $PYTHON_CMD -m pennyfarthing_scripts.jira view MSSCI-12345
+#
+get_python() {
+    # Find project root if not set
+    if [[ -z "${PROJECT_ROOT:-}" ]]; then
+        local d="$PWD"
+        while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+            d="$(dirname "$d")"
+        done
+        PROJECT_ROOT="$d"
+    fi
+
+    # Check for project venv first
+    if [[ -x "${PROJECT_ROOT}/.venv/bin/python" ]]; then
+        PYTHON_CMD="${PROJECT_ROOT}/.venv/bin/python"
+    elif command -v python3 &> /dev/null; then
+        PYTHON_CMD="python3"
+    elif command -v python &> /dev/null; then
+        PYTHON_CMD="python"
+    else
+        error "Python not found. Install Python 3.11+ or create .venv"
+        return 1
+    fi
+}
+
+# run_python_module MODULE [ARGS...]
+# Run a pennyfarthing_scripts Python module with proper venv handling
+#
+# Usage:
+#   run_python_module jira view MSSCI-12345
+#   run_python_module sprint status
+#   run_python_module story size 3
+#
+run_python_module() {
+    get_python || return 1
+    local module="$1"
+    shift
+    exec $PYTHON_CMD -m "pennyfarthing_scripts.${module}" "$@"
+}

package/pennyfarthing-dist/scripts/maintenance/sidecar-health.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# sidecar-health.sh - Check sidecar files for bloat and staleness
+#
+# Usage: sidecar-health.sh [--fix]
+#   --fix    Offer to archive bloated files
+#
+# Thresholds:
+#   gotchas.md: 50 lines max
+#   patterns.md: 50 lines max
+#   decisions.md: 40 lines max
+
+set -euo pipefail
+
+# Find project root
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+SIDECAR_DIR="$PROJECT_ROOT/.pennyfarthing/sidecars"
+FIX_MODE="${1:-}"
+
+# Thresholds
+GOTCHAS_MAX=50
+PATTERNS_MAX=50
+DECISIONS_MAX=40
+
+# Colors
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+echo "Sidecar Health Check"
+echo "===================="
+echo ""
+
+issues_found=0
+
+check_file() {
+  local file="$1"
+  local max_lines="$2"
+  local agent=$(basename "$(dirname "$file")")
+  local filename=$(basename "$file")
+
+  if [[ ! -f "$file" ]]; then
+    return
+  fi
+
+  local lines=$(wc -l < "$file" | tr -d ' ')
+
+  if [[ $lines -gt $max_lines ]]; then
+    echo -e "${RED}BLOATED${NC}: $agent/$filename ($lines lines, max $max_lines)"
+    issues_found=$((issues_found + 1))
+
+    if [[ "$FIX_MODE" == "--fix" ]]; then
+      local archive_dir="$PROJECT_ROOT/.pennyfarthing/sidecars/.archive"
+      local timestamp=$(date +%Y%m%d)
+      mkdir -p "$archive_dir"
+
+      echo "  → Archiving to .archive/${agent}-${filename%.md}-${timestamp}.md"
+      cp "$file" "$archive_dir/${agent}-${filename%.md}-${timestamp}.md"
+      echo "  → Original preserved. Manually prune $file to <$max_lines lines."
+    fi
+  elif [[ $lines -gt $((max_lines * 80 / 100)) ]]; then
+    echo -e "${YELLOW}WARNING${NC}: $agent/$filename ($lines lines, approaching $max_lines limit)"
+  else
+    echo -e "${GREEN}OK${NC}: $agent/$filename ($lines lines)"
+  fi
+}
+
+# Check all agent sidecars
+for agent_dir in "$SIDECAR_DIR"/*/; do
+  if [[ -d "$agent_dir" ]]; then
+    agent=$(basename "$agent_dir")
+    [[ "$agent" == ".archive" ]] && continue
+
+    check_file "$agent_dir/gotchas.md" $GOTCHAS_MAX
+    check_file "$agent_dir/patterns.md" $PATTERNS_MAX
+    check_file "$agent_dir/decisions.md" $DECISIONS_MAX
+  fi
+done
+
+echo ""
+if [[ $issues_found -gt 0 ]]; then
+  echo "Found $issues_found bloated file(s)."
+  if [[ "$FIX_MODE" != "--fix" ]]; then
+    echo "Run with --fix to archive and prepare for pruning."
+  fi
+  exit 1
+else
+  echo "All sidecar files within limits."
+  exit 0
+fi

package/pennyfarthing-dist/scripts/misc/deploy.sh

@@ -223,6 +223,7 @@ if $DRY_RUN; then
     log_dry "git tag -a $TAG_NAME -m 'Release $NEW_VERSION'"
     log_dry "git push origin develop main --tags"
     log_dry "gh release create $TAG_NAME --title 'Release $NEW_VERSION' --notes-from-tag --verify-tag"
+    log_dry "source .env && npm publish --access public"
     log_dry "git checkout develop"
 else
     log_info "Merging develop to main..."
@@ -261,7 +262,16 @@ else
         log_warn "Create release manually at: https://github.com/1898andCo/pennyfarthing/releases/new"
     fi
 
-    # Step 8: Return to develop
+    # Step 8: Publish to npm
+    log_info "Publishing to npm..."
+    if [[ -f "$PROJECT_ROOT/.env" ]]; then
+        source "$PROJECT_ROOT/.env"
+        npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
+    fi
+    (cd "$PROJECT_ROOT" && npm publish --access public)
+    log_info "Published @pennyfarthing/core@$NEW_VERSION to npm"
+
+    # Step 9: Return to develop
     log_info "Returning to develop..."
     git -C "$PROJECT_ROOT" checkout develop
 fi
@@ -273,12 +283,14 @@ if $DRY_RUN; then
     echo "  Would release version: $NEW_VERSION"
     echo "  Would create tag: $TAG_NAME"
     echo "  Would create GitHub release: $TAG_NAME"
+    echo "  Would publish: @pennyfarthing/core@$NEW_VERSION"
 else
     log_info "Deploy complete!"
     echo ""
     echo "  Version: $NEW_VERSION"
     echo "  Tag: $TAG_NAME"
     echo "  GitHub release: https://github.com/1898andCo/pennyfarthing/releases/tag/$TAG_NAME"
+    echo "  npm: @pennyfarthing/core@$NEW_VERSION"
     echo "  Branches pushed: develop, main"
 fi
 echo ""

package/pennyfarthing-dist/scripts/misc/statusline.sh

@@ -90,8 +90,8 @@ elif [ -d "$PROJECT_ROOT/.session/agents" ]; then
     fi
 fi
 
-# Get character name from config for current agent
-# Config now includes theme_characters baked in (no symlink chasing needed)
+# Get character name from theme file (single source of truth)
+# Priority: .pennyfarthing/config.local.yaml > .claude/persona-config.yaml for theme name
 config_file=""
 if [ -f "$PROJECT_ROOT/.pennyfarthing/config.local.yaml" ]; then
     config_file="$PROJECT_ROOT/.pennyfarthing/config.local.yaml"
@@ -101,28 +101,33 @@ fi
 
 character_display=""
 if [ -n "$config_file" ] && [ -n "$agent_name" ]; then
-    # Try baked theme_characters first (self-contained, no symlinks)
-    full_name=$(yq ".theme_characters.${agent_name}" "$config_file" 2>/dev/null)
-
-    if [ -n "$full_name" ] && [ "$full_name" != "null" ]; then
-        # Smart character name extraction:
-        # 1. Remove parenthetical content: "Breq (Justice of Toren)" → "Breq"
-        # 2. Strip common titles: "Captain Kirk" → "Kirk"
-        # 3. If single word remains, use it; otherwise take last word
-        clean_name=$(echo "$full_name" | sed 's/ *([^)]*)//g' | xargs)
-        clean_name=$(echo "$clean_name" | sed -E 's/^(Captain|Lieutenant|Dr\.|Doc|Mr\.|Mrs\.|Ms\.|Admiral|Commander|Chief|Ensign|Translator|Agent|Colonel|Major|Sergeant|Professor|Lord|Lady|Sir|The) +//i')
-        word_count=$(echo "$clean_name" | wc -w | tr -d ' ')
-        if [ "$word_count" -eq 1 ]; then
-            character_display="$clean_name"
-        else
-            character_display=$(echo "$clean_name" | awk '{print $NF}')
+    # Get theme name from config
+    theme=$(yq '.theme' "$config_file" 2>/dev/null)
+
+    if [ -n "$theme" ] && [ "$theme" != "null" ]; then
+        # Read character directly from theme file (matches agent-session.sh behavior)
+        theme_file="$PROJECT_ROOT/.pennyfarthing/personas/themes/${theme}.yaml"
+        if [ -f "$theme_file" ]; then
+            full_name=$(yq ".agents.${agent_name}.character" "$theme_file" 2>/dev/null)
+
+            if [ -n "$full_name" ] && [ "$full_name" != "null" ]; then
+                # Smart character name extraction:
+                # 1. Remove parenthetical content: "Breq (Justice of Toren)" → "Breq"
+                # 2. Strip common titles: "Captain Kirk" → "Kirk"
+                # 3. If single word remains, use it; otherwise take last word
+                clean_name=$(echo "$full_name" | sed 's/ *([^)]*)//g' | xargs)
+                clean_name=$(echo "$clean_name" | sed -E 's/^(Captain|Lieutenant|Dr\.|Doc|Mr\.|Mrs\.|Ms\.|Admiral|Commander|Chief|Ensign|Translator|Agent|Colonel|Major|Sergeant|Professor|Lord|Lady|Sir|The) +//i')
+                word_count=$(echo "$clean_name" | wc -w | tr -d ' ')
+                if [ "$word_count" -eq 1 ]; then
+                    character_display="$clean_name"
+                else
+                    character_display=$(echo "$clean_name" | awk '{print $NF}')
+                fi
+            fi
         fi
-    fi
 
-    # Fallback to theme name if no character found
-    if [ -z "$character_display" ]; then
-        theme=$(yq '.theme' "$config_file" 2>/dev/null)
-        if [ -n "$theme" ] && [ "$theme" != "null" ]; then
+        # Fallback to theme name if no character found
+        if [ -z "$character_display" ]; then
             character_display="$(echo "${theme:0:1}" | tr '[:lower:]' '[:upper:]')${theme:1}"
         fi
     fi