@pennyfarthing/core 11.2.0 → 11.2.2

package/pennyfarthing-dist/guides/hooks.md

@@ -4,7 +4,7 @@ Pennyfarthing uses Claude Code hooks to integrate with session lifecycle events
 
 ## Overview
 
-Hooks are shell scripts that Claude Code runs at specific events:
+Hooks are commands that Claude Code runs at specific events:
 
 | Hook Type | When It Runs | Purpose |
 |-----------|--------------|---------|
@@ -16,18 +16,18 @@ Hooks are shell scripts that Claude Code runs at specific events:
 
 ### SessionStart Hooks
 
-#### session-start.sh
+#### pf.sh hooks session-start
 
-**Location:** `.pennyfarthing/scripts/hooks/session-start.sh`
+**Location:** `pf.sh hooks session-start`
 
 Initializes the Pennyfarthing environment:
 - Creates `.session/` directory structure
 - Clears stale agent state from previous sessions
 - Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
 
-#### session-stop.sh
+#### pf.sh hooks session-stop
 
-**Location:** `.pennyfarthing/scripts/hooks/session-stop.sh`
+**Location:** `pf.sh hooks session-stop`
 
 Cleans up session state when Claude Code exits.
 
@@ -44,68 +44,68 @@ Project-specific environment setup. Edit this file to:
 
 **Location:** `.pennyfarthing/scripts/hooks/otel-auto-config.sh`
 
-Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.wheelhub-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
+Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.bikerack-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
 
-#### welcome-hook.sh
+#### pf.sh hooks session-start (welcome)
 
-**Location:** `.pennyfarthing/scripts/hooks/welcome-hook.sh`
+**Location:** `pf.sh hooks session-start`
 
-Displays a welcome message on session start. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
+Welcome display is now folded into `pf.sh hooks session-start`. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
 
 ### PreToolUse Hooks
 
-#### pre-edit-check.sh
+#### pf.sh hooks pre-edit-check
 
-**Location:** `.pennyfarthing/scripts/hooks/pre-edit-check.sh`
+**Location:** `pf.sh hooks pre-edit-check`
 
 Protects sensitive files from accidental edits:
 - Blocks: `.env`, `.pem`, `.key`, credentials, secrets
 - Blocks: `.git/`, `node_modules/`, `vendor/`
 - Blocks: `.pennyfarthing/*` (managed files)
 
-#### cyclist-pretooluse-hook.sh
+#### pf.sh hooks cyclist-pretooluse
 
-**Location:** `.pennyfarthing/scripts/hooks/cyclist-pretooluse-hook.sh`
+**Location:** `pf.sh hooks cyclist-pretooluse`
 
 Cyclist-specific pre-tool validation. Runs additional safety checks when operating inside Cyclist.
 
-#### context-warning.sh
+#### pf.sh hooks context-warning
 
-**Location:** `.pennyfarthing/scripts/hooks/context-warning.sh`
+**Location:** `pf.sh hooks context-warning`
 
 Warns agents when context usage is high. Outputs a warning at 60% usage and a critical warning at 85%. Never blocks — warning only (always exits 0).
 
-#### context-circuit-breaker.sh
+#### pf.sh hooks context-breaker
 
-**Location:** `.pennyfarthing/scripts/hooks/context-circuit-breaker.sh`
+**Location:** `pf.sh hooks context-breaker`
 
-Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `context-warning.sh`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
+Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `pf.sh hooks context-warning`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
 
-#### schema-validation.sh
+#### pf.sh hooks schema-validation
 
-**Location:** `.pennyfarthing/scripts/hooks/schema-validation.sh`
+**Location:** `pf.sh hooks schema-validation`
 
 Validates file writes against XML schema rules for agent definitions, workflow files, and other structured content.
 
-#### sprint-yaml-validation.sh
+#### pf.sh hooks sprint-yaml
 
-**Location:** `.pennyfarthing/scripts/hooks/sprint-yaml-validation.sh`
+**Location:** `pf.sh hooks sprint-yaml`
 
 Validates sprint YAML files on write to prevent structural corruption.
 
 ### PostToolUse Hooks
 
-#### bell-mode-hook.sh
+#### pf.sh hooks bell-mode
 
-**Location:** `.pennyfarthing/scripts/hooks/bell-mode-hook.sh`
+**Location:** `pf.sh hooks bell-mode`
 
 Bell mode message injection. Checks the bell mode queue and injects queued messages into the agent's context at the next tool execution. Also handles tandem observation injection.
 
-#### question-reflector-check.sh / question_reflector_check.py
+#### pf.sh hooks reflector-check
 
-**Location:** `.pennyfarthing/scripts/hooks/question-reflector-check.sh`
+**Location:** `pf.sh hooks reflector-check`
 
-Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode. The `.sh` file wraps the Python implementation.
+Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode.
 
 ### Git Hooks
 
@@ -133,7 +133,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/session-start.sh"
+            "command": "pf.sh hooks session-start"
           }
         ]
       }
@@ -144,7 +144,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/pre-edit-check.sh"
+            "command": "pf.sh hooks pre-edit-check"
           }
         ]
       }

package/pennyfarthing-dist/guides/prime.md

@@ -53,7 +53,7 @@ Prime selects a context tier based on session state to manage token overhead:
 
 ```bash
 # From agent commands (via pf CLI)
-pf agent start "<agent>" --quiet
+pf.sh agent start "<agent>" --quiet
 
 # TypeScript API (from Cyclist)
 getPrimeContext(agentName, projectDir)
@@ -63,7 +63,7 @@ getPrimeContextJson(agentName, projectDir, tier)  # JSON for Cyclist
 
 ## Integration Points
 
-- **Agent commands** (`/sm`, `/dev`, `/tea`) invoke prime on activation
+- **Agent commands** (`/pf-sm`, `/pf-dev`, `/pf-tea`) invoke prime on activation
 - **TirePump** calls prime to reload agent context after clearing
 - **Cyclist** uses JSON output for context display and token tracking
 

package/pennyfarthing-dist/guides/reflector.md

@@ -41,7 +41,7 @@ Marker pattern: /<!--\s*CYCLIST:(\w+)(?::([^>]+?))?\s*-->/gi
 | `packages/cyclist/src/public/components/QuickActions.tsx` | Renders action buttons from detected markers |
 | `packages/cyclist/src/public/hooks/useMarkerActions.ts` | Detects markers, builds action metadata |
 | `pennyfarthing-dist/scripts/hooks/question_reflector_check.py` | Stop hook — enforces marker presence |
-| `pennyfarthing-dist/scripts/hooks/question-reflector-check.sh` | Bash wrapper for stop hook |
+| `pf.sh hooks reflector-check` | CLI entry point for stop hook |
 
 ## Enforcement Hook
 

package/pennyfarthing-dist/guides/skill-schema.md

@@ -146,7 +146,7 @@ args: "[arg1|arg2]"       # Optional: argument summary
 **Example:**
 ```xml
 <run>
-pf sprint status [filter]
+pf.sh sprint status [filter]
 </run>
 ```
 
@@ -195,7 +195,7 @@ pf sprint status [filter]
 **Example:**
 ```xml
 <example>
-pf sprint check MSSCI-12038
+pf.sh sprint check MSSCI-12038
 # Returns: {"type": "story", "available": true, "title": "...", ...}
 </example>
 ```
@@ -292,7 +292,7 @@ Never manually edit sprint YAML. Use the provided commands.
 Add a new story to an epic.
 
 <run>
-pf sprint story add <epic-id> "<title>" <points>
+pf.sh sprint story add <epic-id> "<title>" <points>
 </run>
 
 <args>
@@ -304,7 +304,7 @@ pf sprint story add <epic-id> "<title>" <points>
 </args>
 
 <example>
-pf sprint story add epic-76 "Add user authentication" 3
+pf.sh sprint story add epic-76 "Add user authentication" 3
 </example>
 
 <output>
@@ -322,7 +322,7 @@ After creating, use `/pf-sprint story size` for sizing guidelines.
 Complete a story after PR merge.
 
 <run>
-pf sprint story finish <story-id>
+pf.sh sprint story finish <story-id>
 </run>
 
 <args>
@@ -332,7 +332,7 @@ pf sprint story finish <story-id>
 </args>
 
 <example>
-pf sprint story finish MSSCI-12052
+pf.sh sprint story finish MSSCI-12052
 # Archives story, updates Jira, cleans session files
 </example>
 

package/pennyfarthing-dist/guides/tandem-protocol.md

@@ -13,7 +13,7 @@ Primary Agent (Opus)          Backseat Agent (Haiku, background)
      │                              │   .session/{story}-tandem-{partner}.md
      │                              │
      ├── PostToolUse hook fires ────┤
-     │   bell-mode-hook.sh detects  │
+     │   pf.sh hooks bell-mode detects │
      │   new observation, injects   │
      │   "[Tandem] Character: ..."  │
      │                              │
@@ -163,8 +163,8 @@ For active, synchronous agent-to-agent questions (as opposed to passive observat
 | `observation-writer.ts` | Built | TypeScript API for observation file I/O |
 | `file-watch.ts` | Built | File system change detection |
 | `tool-watch.ts` | Built | Tool call log monitoring |
-| `bell-mode-hook.sh` | Built | PostToolUse hook with tandem injection |
+| `pf.sh hooks bell-mode` | Built | PostToolUse hook with tandem injection |
 | `bellmode_hook.py` | Built | Python implementation of bell mode hook |
-| `statusline.sh` | Built | CLI statusline with tandem indicator |
+| `pf.sh hooks statusline` | Built | CLI statusline with tandem indicator |
 | `tandem-backseat.md` | Built | Backseat agent prompt template |
 | `agent-behavior.md` | Built | Shared agent behavior with tandem protocol |

package/pennyfarthing-dist/guides/workflow-schema.md

@@ -253,5 +253,5 @@ Error: workflow.triggers.points min (10) cannot be greater than max (5)
 
 - Story 31-2: Workflow loader and validator
 - Story 31-3: Story-to-workflow routing engine
-- Story 31-5: /workflow skill for listing and switching
+- Story 31-5: /pf-workflow skill for listing and switching
 - Story MSSCI-11710: Permission presets by workflow

package/pennyfarthing-dist/guides/worktree-mode.md

@@ -86,8 +86,8 @@ Ports are stored in the session file and passed to agents.
 | Command | Purpose |
 |---------|---------|
 | `/pf-session parallel` | Start a new parallel work session |
-| `pf git worktree list` | Show active worktrees |
-| `pf git worktree remove <name>` | Clean up a worktree |
+| `pf.sh git worktree list` | Show active worktrees |
+| `pf.sh git worktree remove <name>` | Clean up a worktree |
 
 ## TDD Flow in Worktrees
 
@@ -104,7 +104,7 @@ Agents use worktree paths from session file for all operations.
 When story is complete, SM archives the session and the worktree can be removed:
 
 ```bash
-pf git worktree remove wt-5-3a
+pf.sh git worktree remove wt-5-3a
 ```
 
 This removes:

package/pennyfarthing-dist/guides/xml-tags.md

@@ -124,7 +124,7 @@ Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Revie
 
 **Purpose:** Verify agent owns the current workflow phase before proceeding. Prevents agents from acting on stories they shouldn't own.
 
-**Usage:** SM, TEA, Dev, Reviewer - runs `pf workflow phase-check` on activation to determine correct owner.
+**Usage:** SM, TEA, Dev, Reviewer - runs `pf.sh workflow phase-check` on activation to determine correct owner.
 
 ```markdown
 <phase-check>
@@ -132,10 +132,10 @@ Tags used by agents participating in the TDD workflow cycle (SM, TEA, Dev, Revie
 
 Read `**Workflow:**` and `**Phase:**` from session. Query:
 ```bash
-OWNER=$(pf workflow phase-check {workflow} {phase})
+OWNER=$("$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh workflow phase-check {workflow} {phase})
 ```
 
-**If OWNER != "dev":** Run `pf handoff marker $OWNER`, output result, tell user.
+**If OWNER != "dev":** Run `pf.sh handoff marker $OWNER`, output result, tell user.
 </phase-check>
 ```
 
@@ -150,9 +150,9 @@ OWNER=$(pf workflow phase-check {workflow} {phase})
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Assessment to session file
-- [ ] Run `pf handoff resolve-gate` — verify gate status
-- [ ] Run `pf handoff complete-phase` — atomic session update
-- [ ] Run `pf handoff marker {next_agent}` — emit marker and EXIT
+- [ ] Run `pf.sh handoff resolve-gate` — verify gate status
+- [ ] Run `pf.sh handoff complete-phase` — atomic session update
+- [ ] Run `pf.sh handoff marker {next_agent}` — emit marker and EXIT
 </handoff-gate>
 ```
 
@@ -448,7 +448,7 @@ Tags used in skill files (`skills/{name}/SKILL.md`) for command documentation.
 
 ```markdown
 <run>
-pf sprint status [filter]
+pf.sh sprint status [filter]
 </run>
 ```
 
@@ -474,7 +474,7 @@ pf sprint status [filter]
 
 ```markdown
 <example>
-pf sprint check MSSCI-12038
+pf.sh sprint check MSSCI-12038
 # Returns: {"type": "story", "available": true}
 </example>
 ```

package/pennyfarthing-dist/scripts/README.md

@@ -8,10 +8,10 @@ Scripts are organized into categorical subdirectories. **Full paths are required
 scripts/
 ├── core/       # Essential scripts (agent-session.sh)
 ├── workflow/   # Workflow mechanics (finish-story.sh, check.sh)
-├── sprint/     # Sprint YAML operations (migrated to pf sprint CLI)
+├── sprint/     # Sprint YAML operations (migrated to pf.sh sprint CLI)
 ├── story/      # Story operations (create-story.sh)
 ├── jira/       # Jira integration (jira-claim-story.sh)
-├── git/        # Git operations (deprecated shims → pf git CLI)
+├── git/        # Git operations (deprecated shims → pf.sh git CLI)
 ├── theme/      # Theme operations (list-themes.sh)
 ├── test/       # Test infrastructure (test-setup.sh)
 ├── lib/        # Shared bash libraries (common.sh, logging.sh)
@@ -27,9 +27,9 @@ Scripts are invoked directly with **full category paths**:
 ```bash
 # From project root
 .pennyfarthing/scripts/core/agent-session.sh start sm
-pf sprint status
+pf.sh sprint status
 .pennyfarthing/scripts/jira/jira-claim-story.sh MSSCI-12345
-pf sprint story finish MSSCI-12345
+pf.sh sprint story finish MSSCI-12345
 ```
 
 ## Distributed Scripts

package/pennyfarthing-dist/scripts/core/agent-session.sh

@@ -232,11 +232,8 @@ case "$1" in
       PRIME_ARGS+=(--no-persona)
     fi
 
-    if command -v pf &>/dev/null; then
-      pf prime "${PRIME_ARGS[@]}"
-    else
-      python3 -m pennyfarthing_scripts.prime "${PRIME_ARGS[@]}"
-    fi
+    source "$SCRIPT_DIR/../lib/run-pf.sh"
+    run_pf prime "${PRIME_ARGS[@]}"
     ;;
   stop)
     # Use provided session ID, fall back to SESSION_ID env var

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

@@ -12,6 +12,8 @@
 
 set -euo pipefail
 
+echo "DEPRECATED: check-context.sh — use 'pf context' instead" >&2
+
 # Find project root (where pennyfarthing_scripts lives)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 
@@ -154,7 +156,7 @@ if last_total:
     status = 'HIGH' if usable_pct > $WARNING_THRESHOLD else 'OK'
     relay = '$RELAY_MODE' == 'true'
     tirepump = (relay or '$PERMISSION_MODE' == 'turbo') and usable_pct > $TIREPUMP_THRESHOLD
-    is_cyclist = os.environ.get('CYCLIST') == '1' or Path('$PROJECT_DIR/packages/cyclist/.wheelhub-port').exists()
+    is_cyclist = os.environ.get('CYCLIST') == '1' or Path('$PROJECT_DIR/packages/cyclist/.bikerack-port').exists()
 
     print(f'CONTEXT_TOKENS={last_total}')
     print(f'CONTEXT_PERCENT={total_pct}')

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

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Wrapper: run `pf` CLI via uv run — no global pf install needed.
+# Usage: "$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh <command> [args...]
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf "$@"

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

@@ -1,90 +1,5 @@
 #!/bin/bash
-# Start an agent with phase check
-# If the current story's phase belongs to a different agent, emit handoff marker instead
-#
-# Usage: .pennyfarthing/scripts/core/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
-
-# Self-locate and set up PROJECT_ROOT
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-source "$SCRIPT_DIR/../lib/find-root.sh"
-
-SCRIPTS_DIR="$SCRIPT_DIR/.."
-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 "$SCRIPTS_DIR/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 "$SCRIPTS_DIR/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 "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-  fi
-fi
-
-# Get the owner of this phase
-OWNER=$("$SCRIPTS_DIR/workflow/phase-owner.sh" "$WORKFLOW" "$PHASE" 2>/dev/null || echo "")
-
-if [[ -z "$OWNER" ]]; then
-  # Phase owner lookup failed - start normally
-  exec "$SCRIPTS_DIR/core/agent-session.sh" start "$AGENT"
-fi
-
-# Check if this agent owns the phase
-if [[ "$OWNER" == "$AGENT" ]]; then
-  # Correct agent - start normally
-  exec "$SCRIPTS_DIR/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
-pf handoff marker "$OWNER"
+# DEPRECATED: Use `pf handoff phase-check <agent>` instead.
+echo "DEPRECATED: phase-check-start.sh — use 'pf handoff phase-check $1' instead" >&2
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf handoff phase-check "$@"

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

@@ -1,28 +1,5 @@
 #!/usr/bin/env bash
 # prime.sh - Load essential project context at agent activation
 # Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
-#
-# Uses the `pf` CLI (installed via uv/pipx during pennyfarthing init).
-# Falls back to python3 -m with PYTHONPATH if pf is not available.
-
-# Prefer pf CLI if available
-if command -v pf &>/dev/null; then
-    exec pf prime "$@"
-fi
-
-# Fallback: find pennyfarthing_scripts via PYTHONPATH
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-PACKAGE_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd -P)"
-
-if [[ ! -d "$PACKAGE_ROOT/pennyfarthing_scripts" ]]; then
-    PROJECT_ROOT="$PWD"
-    while [[ ! -d "$PROJECT_ROOT/.pennyfarthing" ]] && [[ "$PROJECT_ROOT" != "/" ]]; do
-        PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
-    done
-    if [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core/pennyfarthing_scripts" ]]; then
-        PACKAGE_ROOT="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
-    fi
-fi
-
-export PYTHONPATH="${PACKAGE_ROOT}:${PYTHONPATH:-}"
-exec python3 -m pennyfarthing_scripts.prime "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf prime "$@"

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

@@ -4,29 +4,29 @@ Scripts for Git operations, branching, and worktree management.
 
 ## CLI Commands (preferred)
 
-All git operations are available via the `pf git` CLI:
+All git operations are available via the `pf.sh git` CLI:
 
 | Command | Purpose |
 |---------|---------|
-| `pf git status [--brief]` | Show git status across all repos |
-| `pf git branches <name> [--repos all\|api\|ui]` | Create feature branches in repos |
-| `pf git worktree create <name> <branch>` | Create worktrees for parallel work |
-| `pf git worktree remove <name>` | Remove worktree and clean up |
-| `pf git worktree list` | List all active worktrees |
-| `pf git worktree status` | Show detailed worktree status |
-| `pf git install-hooks` | Install git hooks with .d/ dispatcher |
-| `pf git cleanup` | Organize changes into commits/branches |
+| `pf.sh git status [--brief]` | Show git status across all repos |
+| `pf.sh git branches <name> [--repos all\|api\|ui]` | Create feature branches in repos |
+| `pf.sh git worktree create <name> <branch>` | Create worktrees for parallel work |
+| `pf.sh git worktree remove <name>` | Remove worktree and clean up |
+| `pf.sh git worktree list` | List all active worktrees |
+| `pf.sh git worktree status` | Show detailed worktree status |
+| `pf.sh git install-hooks` | Install git hooks with .d/ dispatcher |
+| `pf.sh git cleanup` | Organize changes into commits/branches |
 
 ## Legacy Scripts (deprecated shims)
 
-These scripts now forward to `pf git` commands:
+These scripts now forward to `pf.sh git` commands:
 
 | Script | Forwards to |
 |--------|-------------|
-| `git-status-all.sh` | `pf git status` |
-| `create-feature-branches.sh` | `pf git branches` |
-| `worktree-manager.sh` | `pf git worktree` |
-| `install-git-hooks.sh` | `pf git install-hooks` |
+| `git-status-all.sh` | `pf.sh git status` |
+| `create-feature-branches.sh` | `pf.sh git branches` |
+| `worktree-manager.sh` | `pf.sh git worktree` |
+| `install-git-hooks.sh` | `pf.sh git install-hooks` |
 | `release.sh` | Release workflow (use `/pf-workflow start release`) |
 
 ## Ownership

package/pennyfarthing-dist/scripts/git/create-feature-branches.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git branches` instead.
-# This shim forwards to the Python CLI.
-set -e
 echo "DEPRECATED: create-feature-branches.sh — use 'pf git branches' instead" >&2
-exec pf git branches "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf git branches "$@"

package/pennyfarthing-dist/scripts/git/git-status-all.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git status` instead.
-# This shim forwards to the Python CLI.
-set -e
 echo "DEPRECATED: git-status-all.sh — use 'pf git status' instead" >&2
-exec pf git status "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf git status "$@"

package/pennyfarthing-dist/scripts/git/install-git-hooks.sh

@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git install-hooks` instead.
-# This shim forwards to the Python CLI.
-set -e
 echo "DEPRECATED: install-git-hooks.sh — use 'pf git install-hooks' instead" >&2
-exec pf git install-hooks "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf git install-hooks "$@"

package/pennyfarthing-dist/scripts/git/worktree-manager.sh

@@ -1,6 +1,4 @@
 #!/usr/bin/env bash
 # DEPRECATED: Use `pf git worktree` instead.
-# This shim forwards to the Python CLI.
-set -e
-echo "DEPRECATED: worktree-manager.sh — use 'pf git worktree' instead" >&2
-exec pf git worktree "$@"
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)/../lib/run-pf.sh"
+exec_pf git worktree "$@"

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

@@ -6,22 +6,22 @@ Git hooks and Claude Code hooks.
 
 | Script | Purpose |
 |--------|---------|
-| `context-circuit-breaker.sh` | Claude hook: halt at context limit |
-| `context-warning.sh` | Claude hook: warn on high context |
+| `pf.sh hooks context-breaker` | Claude hook: halt at context limit |
+| `pf.sh hooks context-warning` | Claude hook: warn on high context |
 | `otel-auto-config.sh` | Claude hook: configure OTEL |
 | `post-merge.sh` | Git hook: post-merge actions |
 | `pre-commit.sh` | Git hook: branch protection, agent validation, sprint YAML validation |
-| `pre-edit-check.sh` | Claude hook: validate before edit |
+| `pf.sh hooks pre-edit-check` | Claude hook: validate before edit |
 | `pre-push.sh` | Git hook: pre-push validation |
-| `session-start.sh` | Claude hook: session start |
-| `session-stop.sh` | Claude hook: session stop |
+| `pf.sh hooks session-start` | Claude hook: session start |
+| `pf.sh hooks session-stop` | Claude hook: session stop |
 
 ## Installation
 
 Git hooks are installed via:
 
 ```bash
-pf git install-hooks
+pf.sh git install-hooks
 ```
 
 Claude hooks are configured in `.claude/settings.json`.