@pennyfarthing/core 8.0.4 → 9.0.0

package/pennyfarthing-dist/scripts/lib/find-root.sh

@@ -1,61 +1,33 @@
 #!/usr/bin/env bash
-# Shared utility: Find project root via BASH_SOURCE self-location
-#
-# Core principle: Scripts derive paths from their own location, not from $PWD.
-# A script in pennyfarthing-dist/scripts/<category>/ is always 3 levels below
-# the package root. This works regardless of where the user invoked it from.
+# Shared utility: Find project root by walking up to .pennyfarthing/
 #
 # Usage:
-#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 #   source "$SCRIPT_DIR/../lib/find-root.sh"
 #   # PROJECT_ROOT is now set
+#
+# Or simply:
+#   source /path/to/find-root.sh
+#   # PROJECT_ROOT is now set
 
-# Require SCRIPT_DIR to be set by caller
-if [[ -z "${SCRIPT_DIR:-}" ]]; then
-    echo "Error: SCRIPT_DIR must be set before sourcing find-root.sh" >&2
-    echo "Add this before sourcing:" >&2
-    echo '  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"' >&2
-    exit 1
-fi
-
-# Allow explicit override via PENNYFARTHING_ROOT (avoids conflict with orchestrator's PROJECT_ROOT)
-if [[ -n "${PENNYFARTHING_ROOT:-}" ]]; then
-    PROJECT_ROOT="$PENNYFARTHING_ROOT"
+# Allow explicit override
+if [[ -n "${PROJECT_ROOT:-}" ]]; then
     export PROJECT_ROOT
     return 0 2>/dev/null || exit 0
 fi
 
-# Resolve SCRIPT_DIR (follow symlinks to real location)
-_real_script_dir="$(cd "$SCRIPT_DIR" && pwd -P)"
-
-# Derive package root from script location
-# Scripts can be in:
-# - pennyfarthing-dist/scripts/<category>/ (npm package or framework dev)
-# - .pennyfarthing/scripts/<category>/ (consumer project after init)
-if [[ "$_real_script_dir" == */pennyfarthing-dist/scripts/* ]]; then
-    # Extract everything before /pennyfarthing-dist/scripts/
-    _pkg_root="${_real_script_dir%/pennyfarthing-dist/scripts/*}"
+# Walk up from PWD looking for .pennyfarthing/
+_d="$PWD"
+while [[ ! -d "$_d/.pennyfarthing" ]] && [[ "$_d" != "/" ]]; do
+    _d="$(dirname "$_d")"
+done
 
-    # Determine context: framework dev or consumer?
-    # Check node_modules FIRST - if we're in node_modules, we're always a consumer
-    if [[ "$_pkg_root" == */node_modules/* ]]; then
-        # Consumer context: walk up from node_modules to project
-        PROJECT_ROOT="${_pkg_root%/node_modules/*}"
-    elif [[ -d "$_pkg_root/pennyfarthing-dist" && ! -L "$_pkg_root/pennyfarthing-dist" ]]; then
-        # Framework context: package root IS project root
-        PROJECT_ROOT="$_pkg_root"
-    else
-        PROJECT_ROOT="$_pkg_root"
-    fi
-elif [[ "$_real_script_dir" == */.pennyfarthing/scripts/* ]]; then
-    # Consumer project context: scripts copied to .pennyfarthing/scripts/
-    # Extract everything before /.pennyfarthing/scripts/
-    PROJECT_ROOT="${_real_script_dir%/.pennyfarthing/scripts/*}"
+if [[ -d "$_d/.pennyfarthing" ]]; then
+    PROJECT_ROOT="$_d"
 else
-    echo "Error: Script not in expected location (pennyfarthing-dist/scripts/ or .pennyfarthing/scripts/)" >&2
-    echo "SCRIPT_DIR=$_real_script_dir" >&2
+    echo "Error: Could not find .pennyfarthing/ directory" >&2
+    echo "Are you in a Pennyfarthing-enabled project?" >&2
     exit 1
 fi
 
-unset _real_script_dir _pkg_root
+unset _d
 export PROJECT_ROOT

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

@@ -12,13 +12,7 @@
 set -euo pipefail
 
 # Find project root
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SIDECAR_DIR="$PROJECT_ROOT/.pennyfarthing/sidecars"
 FIX_MODE="${1:-}"

package/pennyfarthing-dist/scripts/sprint/archive-story.sh

@@ -40,14 +40,8 @@ if [[ -z "$STORY_ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/sprint/available-stories.sh

@@ -6,14 +6,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/sprint/check-story.sh

@@ -18,14 +18,8 @@ if [[ -z "$ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/sprint/get-epic-field.sh

@@ -32,14 +32,8 @@ if [[ ! "$EPIC_ID" =~ ^epic- ]]; then
   EPIC_ID="epic-$EPIC_ID"
 fi
 
-# PROJECT_ROOT should be set by find-root.sh
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/sprint/get-story-field.sh

@@ -27,14 +27,8 @@ if [[ -z "$STORY_ID" || -z "$FIELD" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/sprint/list-future.sh

@@ -7,14 +7,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 FUTURE_FILE="$PROJECT_ROOT/sprint/future.yaml"
 

package/pennyfarthing-dist/scripts/sprint/new-sprint.sh

@@ -27,14 +27,8 @@ if [[ -z "$SPRINT_YYWW" || -z "$JIRA_ID" || -z "$START_DATE" || -z "$END_DATE" |
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 TEMPLATE_FILE="$PROJECT_ROOT/sprint/sprint-template.yaml"
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 ARCHIVE_FILE="$PROJECT_ROOT/sprint/archive/sprint-${SPRINT_YYWW}-completed.yaml"

package/pennyfarthing-dist/scripts/sprint/promote-epic.sh

@@ -21,14 +21,8 @@ if [[ -z "$EPIC_ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 FUTURE_FILE="$PROJECT_ROOT/sprint/future.yaml"
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"

package/pennyfarthing-dist/scripts/sprint/sprint-info.sh

@@ -6,14 +6,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 

package/pennyfarthing-dist/scripts/tests/test-character-voice.sh

@@ -28,8 +28,9 @@ mkdir -p "$TEST_DIR/scripts"
 
 # Copy core scripts (including agent-session.sh)
 mkdir -p "$TEST_DIR/scripts/core"
+mkdir -p "$TEST_DIR/scripts/lib"
 cp "$PROJECT_ROOT/scripts/core/agent-session.sh" "$TEST_DIR/scripts/core/"
-cp "$PROJECT_ROOT/scripts/core/run.sh" "$TEST_DIR/scripts/"
+cp "$PROJECT_ROOT/scripts/lib/find-root.sh" "$TEST_DIR/scripts/lib/"
 
 # Create minimal theme file
 cat > "$TEST_DIR/.pennyfarthing/personas/themes/test-theme.yaml" << 'EOF'

package/pennyfarthing-dist/scripts/workflow/finish-story.sh

@@ -40,14 +40,8 @@ if [[ -z "$STORY_ID" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 SESSION_FILE="$PROJECT_ROOT/.session/${STORY_ID}-session.md"
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
@@ -63,7 +57,8 @@ if [[ ! -f "$SESSION_FILE" ]]; then
 fi
 
 # Extract metadata from session file (handle both "**Jira:**" and "- **Jira:**" formats)
-JIRA_KEY=$(grep -E '\*\*Jira:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Jira:\*\* //' | tr -d ' ' || echo "")
+# Also handle markdown link format: [MSSCI-12721](https://...)
+JIRA_KEY=$(grep -E '\*\*Jira:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Jira:\*\* //' | sed 's/\[//' | sed 's/\].*//' | tr -d ' ' || echo "")
 # Extract branch - strip any trailing annotations like "(pushed)"
 BRANCH=$(grep -E '\*\*Branch:\*\*' "$SESSION_FILE" | sed 's/.*\*\*Branch:\*\* //' | sed 's/ *(.*//' | tr -d ' ' || echo "")
 

package/pennyfarthing-dist/scripts/workflow/fix-session-phase.sh

@@ -46,14 +46,8 @@ if [[ -z "$STORY_ID" ]] || [[ -z "$TARGET_PHASE" ]]; then
   exit 1
 fi
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 # Try multiple session file naming patterns
 SESSION_FILE=""

package/pennyfarthing-dist/scripts/workflow/list-workflows.sh

@@ -7,14 +7,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 WORKFLOWS_DIR="$PROJECT_ROOT/.pennyfarthing/workflows"
 

package/pennyfarthing-dist/scripts/workflow/phase-owner.sh

@@ -14,13 +14,7 @@ if [[ -z "$WORKFLOW" || -z "$PHASE" ]]; then
 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
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 WORKFLOW_FILE="$PROJECT_ROOT/.pennyfarthing/workflows/${WORKFLOW}.yaml"
 

package/pennyfarthing-dist/scripts/workflow/resume-workflow.sh

@@ -6,14 +6,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 WORKFLOWS_DIR="$PROJECT_ROOT/.pennyfarthing/workflows"
 SESSION_DIR="$PROJECT_ROOT/.session"

package/pennyfarthing-dist/scripts/workflow/show-workflow.sh

@@ -8,14 +8,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 WORKFLOWS_DIR="$PROJECT_ROOT/.pennyfarthing/workflows"
 SESSION_DIR="$PROJECT_ROOT/.session"

package/pennyfarthing-dist/scripts/workflow/start-workflow.sh

@@ -7,14 +7,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 WORKFLOWS_DIR="$PROJECT_ROOT/.pennyfarthing/workflows"
 SESSION_DIR="$PROJECT_ROOT/.session"

package/pennyfarthing-dist/scripts/workflow/workflow-status.sh

@@ -6,14 +6,8 @@
 
 set -euo pipefail
 
-# PROJECT_ROOT should be set by find-root.sh, but find it if not
-if [[ -z "${PROJECT_ROOT:-}" ]]; then
-  d="$PWD"
-  while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do
-    d="$(dirname "$d")"
-  done
-  PROJECT_ROOT="$d"
-fi
+# Find project root
+source "$(dirname "${BASH_SOURCE[0]}")/../lib/find-root.sh"
 
 WORKFLOWS_DIR="$PROJECT_ROOT/.pennyfarthing/workflows"
 SESSION_DIR="$PROJECT_ROOT/.session"

package/pennyfarthing-dist/skills/dev-patterns/SKILL.md

@@ -381,7 +381,7 @@ TaskOutput tool:
 Use the background task tracking utilities to manage session file entries:
 
 ```bash
-source $CLAUDE_PROJECT_DIR/scripts/utils/background-tasks.sh
+source $CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/background-tasks.sh
 SESSION_FILE="$CLAUDE_PROJECT_DIR/.session/${STORY_ID}-session.md"
 
 # After spawning background task, record it:

package/pennyfarthing-dist/skills/jira/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: jira
 description: Jira CLI commands for sprint management. Use when viewing, assigning, or updating Jira issues from the command line.
-args: "[view|claim|move|assign|create|sync|reconcile|link|search|sprint]"
+args: "[view|check|claim|move|assign|create|sync|reconcile|link|search|sprint]"
 ---
 
 # /jira - Jira Issue Management
@@ -34,36 +34,60 @@ jira issue view MSSCI-12038 --raw
 
 ---
 
-### `/jira claim <issue-key> [--claim]`
+### `/jira check <issue-key>`
 
-Check availability and claim a story for work.
+Check if a story is available to claim (not assigned to someone else).
 
 <run>
-.pennyfarthing/scripts jira/jira-claim-story.sh <issue-key> [--claim]
+.pennyfarthing/scripts/jira/jira-claim-story.sh <issue-key>
 </run>
 
 <args>
 | Arg | Required | Description |
 |-----|----------|-------------|
 | `issue-key` | Yes | Jira key `MSSCI-XXXXX` or story key `35-7-name` |
-| `--claim` | No | Actually claim (assign + move to In Progress) |
 </args>
 
 <exit-codes>
 | Code | Meaning |
 |------|---------|
-| `0` | Available or successfully claimed |
+| `0` | Available (unassigned or assigned to you) |
 | `1` | Assigned to someone else |
 | `2` | Not found or not synced |
 | `3` | Error (CLI not installed, etc.) |
 </exit-codes>
 
 <example>
-# Check if available
-.pennyfarthing/scripts jira/jira-claim-story.sh MSSCI-12038
+.pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12038
+</example>
+
+---
+
+### `/jira claim <issue-key>`
+
+Claim a story for work (assign to self + move to In Progress).
+
+<run>
+.pennyfarthing/scripts/jira/jira-claim-story.sh <issue-key> --claim
+</run>
+
+<args>
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `issue-key` | Yes | Jira key `MSSCI-XXXXX` or story key `35-7-name` |
+</args>
 
-# Claim it (assign to self + In Progress)
-.pennyfarthing/scripts jira/jira-claim-story.sh MSSCI-12038 --claim
+<exit-codes>
+| Code | Meaning |
+|------|---------|
+| `0` | Successfully claimed |
+| `1` | Assigned to someone else (BLOCKED) |
+| `2` | Not found or not synced |
+| `3` | Error (CLI not installed, etc.) |
+</exit-codes>
+
+<example>
+.pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12038 --claim
 </example>
 
 ---
@@ -135,7 +159,7 @@ jira issue assign MSSCI-12038 x --project MSSCI
 Create a single Jira story under an epic from sprint YAML.
 
 <run>
-.pennyfarthing/scripts jira/create-jira-story.sh <epic-key> <story-id>
+.pennyfarthing/scripts/jira/create-jira-story.sh <epic-key> <story-id>
 </run>
 
 <args>
@@ -150,7 +174,7 @@ Creating a single story that's missing from Jira but exists in sprint YAML.
 </when>
 
 <example>
-.pennyfarthing/scripts jira/create-jira-story.sh MSSCI-12077 MSSCI-12066
+.pennyfarthing/scripts/jira/create-jira-story.sh MSSCI-12077 MSSCI-12066
 </example>
 
 <output>
@@ -169,7 +193,7 @@ Creating a single story that's missing from Jira but exists in sprint YAML.
 Create a Jira epic and all its child stories from sprint YAML.
 
 <run>
-.pennyfarthing/scripts jira/create-jira-epic.sh <epic-id> [--dry-run]
+.pennyfarthing/scripts/jira/create-jira-epic.sh <epic-id> [--dry-run]
 </run>
 
 <args>
@@ -181,10 +205,10 @@ Create a Jira epic and all its child stories from sprint YAML.
 
 <example>
 # Preview what would be created
-.pennyfarthing/scripts jira/create-jira-epic.sh epic-41 --dry-run
+.pennyfarthing/scripts/jira/create-jira-epic.sh epic-41 --dry-run
 
 # Create epic and stories
-.pennyfarthing/scripts jira/create-jira-epic.sh epic-41
+.pennyfarthing/scripts/jira/create-jira-epic.sh epic-41
 </example>
 
 <output>
@@ -202,7 +226,7 @@ Create a Jira epic and all its child stories from sprint YAML.
 Sync an epic and its stories from sprint YAML to Jira.
 
 <run>
-.pennyfarthing/scripts jira/sync-epic-jira.sh <epic-id> [options]
+.pennyfarthing/scripts/jira/sync-epic-jira.sh <epic-id> [options]
 </run>
 
 <args>
@@ -217,13 +241,13 @@ Sync an epic and its stories from sprint YAML to Jira.
 
 <example>
 # Show sync status
-.pennyfarthing/scripts jira/sync-epic-jira.sh MSSCI-11952
+.pennyfarthing/scripts/jira/sync-epic-jira.sh MSSCI-11952
 
 # Preview changes
-.pennyfarthing/scripts jira/sync-epic-jira.sh MSSCI-11952 --dry-run
+.pennyfarthing/scripts/jira/sync-epic-jira.sh MSSCI-11952 --dry-run
 
 # Full sync
-.pennyfarthing/scripts jira/sync-epic-jira.sh MSSCI-11952 --all
+.pennyfarthing/scripts/jira/sync-epic-jira.sh MSSCI-11952 --all
 </example>
 
 <output>
@@ -240,7 +264,7 @@ Sync an epic and its stories from sprint YAML to Jira.
 Generate a reconciliation report comparing sprint YAML against Jira.
 
 <run>
-.pennyfarthing/scripts jira/jira-reconcile.sh [--fix]
+.pennyfarthing/scripts/jira/jira-reconcile.sh [--fix]
 </run>
 
 <args>
@@ -251,10 +275,10 @@ Generate a reconciliation report comparing sprint YAML against Jira.
 
 <example>
 # Report only
-.pennyfarthing/scripts jira/jira-reconcile.sh
+.pennyfarthing/scripts/jira/jira-reconcile.sh
 
 # Report and fix
-.pennyfarthing/scripts jira/jira-reconcile.sh --fix
+.pennyfarthing/scripts/jira/jira-reconcile.sh --fix
 </example>
 
 <output>
@@ -402,8 +426,8 @@ Sprint field reference:
 | Command | Script/Action |
 |---------|---------------|
 | `/jira view MSSCI-XXX` | `jira issue view MSSCI-XXX` |
-| `/jira claim MSSCI-XXX` | `jira-claim-story.sh MSSCI-XXX` |
-| `/jira claim MSSCI-XXX --claim` | `jira-claim-story.sh MSSCI-XXX --claim` |
+| `/jira check MSSCI-XXX` | `jira-claim-story.sh MSSCI-XXX` |
+| `/jira claim MSSCI-XXX` | `jira-claim-story.sh MSSCI-XXX --claim` |
 | `/jira move MSSCI-XXX "Done"` | `jira issue move MSSCI-XXX "Done" -p MSSCI` |
 | `/jira assign MSSCI-XXX "user"` | `jira issue assign MSSCI-XXX "user" -p MSSCI` |
 | `/jira create story E-KEY S-ID` | `create-jira-story.sh E-KEY S-ID` |

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

@@ -10,6 +10,13 @@
 
 set -euo pipefail
 
+# Find package root (where pennyfarthing_scripts lives) from script location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd -P)"
+
+# Set PYTHONPATH so Python can find pennyfarthing_scripts
+export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
+
 EPIC_ID="${1:-}"
 
 if [[ -z "$EPIC_ID" ]]; then