@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing-dist/scripts/hooks/session-start.sh

@@ -1,97 +1,33 @@
-#!/usr/bin/env zsh
-# Session start hook: Initialize environment for Claude Code session
-# Called by Claude Code when a new session starts
+#!/usr/bin/env bash
 #
-# Uses CLAUDE_ENV_FILE to persist environment variables for the session.
-# Projects using pennyfarthing can add their own hooks for project-specific vars.
+# Session Start Hook - Shell wrapper for Python implementation
 #
-# Also validates previous session checkpoint to detect cross-session state changes.
+# Initializes environment for Claude Code session:
+# - Session directory setup and logging
+# - Checkpoint validation (cross-session drift)
+# - WheelHub auto-start
+# - OTEL auto-configuration
+#
+# Input (stdin): JSON with session_id, source, cwd, etc.
+# Output: Writes to CLAUDE_ENV_FILE
 
 set -euo pipefail
 
-# Load shared functions
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$SCRIPT_DIR/../lib/checkpoint.sh"
-
-# Read input from stdin (contains session_id, source, cwd, etc.)
-input=$(cat)
-session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
-source_type=$(echo "$input" | jq -r '.source // "unknown"')
-
-# Ensure .session directory exists
-mkdir -p "$CLAUDE_PROJECT_DIR/.session"
-mkdir -p "$CLAUDE_PROJECT_DIR/.session/agents"
-
-# Note: Agent cleanup is handled by agent-session.sh (7-day TTL) to preserve multi-session state
-# DO NOT clear .session/agents/* here - it breaks parallel sessions
-
-# Create session log entry
-echo "$(date -Iseconds) | Session $source_type: $session_id" >> "$CLAUDE_PROJECT_DIR/.session/session-log.txt"
-
-# Validate previous session checkpoint (cross-session continuity)
-validate_checkpoint() {
-    local prev_state
-    prev_state=$(checkpoint_restore "session_state")
-
-    if [[ -z "$prev_state" ]]; then
-        # No previous checkpoint - fresh start
-        return 0
-    fi
-
-    # Parse checkpoint data (format: key=value;key=value;...)
-    local prev_sha prev_agent prev_story prev_phase prev_session
-    prev_sha=$(echo "$prev_state" | tr ';' '\n' | grep '^sha=' | cut -d= -f2)
-    prev_agent=$(echo "$prev_state" | tr ';' '\n' | grep '^agent=' | cut -d= -f2)
-    prev_story=$(echo "$prev_state" | tr ';' '\n' | grep '^story=' | cut -d= -f2)
-    prev_phase=$(echo "$prev_state" | tr ';' '\n' | grep '^phase=' | cut -d= -f2)
-    prev_session=$(echo "$prev_state" | tr ';' '\n' | grep '^session=' | cut -d= -f2)
-
-    # Get current git SHA
-    local current_sha=""
-    if command -v git &>/dev/null && git rev-parse --git-dir &>/dev/null; then
-        current_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "")
-    fi
-
-    # Compare git state
-    if [[ -n "$prev_sha" && -n "$current_sha" && "$prev_sha" != "$current_sha" ]]; then
-        # Git state changed between sessions - write warning to session log
-        local warning="CROSS_SESSION_DRIFT: Git changed since last session (was: $prev_sha, now: $current_sha)"
-        if [[ -n "$prev_story" ]]; then
-            warning="$warning | Story: $prev_story"
-        fi
-        if [[ -n "$prev_agent" ]]; then
-            warning="$warning | Agent: $prev_agent"
-        fi
-        echo "$(date -Iseconds) | $warning" >> "$CLAUDE_PROJECT_DIR/.session/session-log.txt"
-
-        # Also write to a dedicated drift log for easy scanning
-        echo "$(date -Iseconds) | prev_sha=$prev_sha | current_sha=$current_sha | story=$prev_story | agent=$prev_agent | phase=$prev_phase" >> "$CLAUDE_PROJECT_DIR/.session/drift-log.txt"
-    fi
-}
-
-# Run checkpoint validation (don't fail if it errors)
-validate_checkpoint 2>/dev/null || true
-
-# Write environment variables to CLAUDE_ENV_FILE (persists for session)
-if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
-    cat >> "$CLAUDE_ENV_FILE" << EOF
-# Pennyfarthing core environment
-export PROJECT_ROOT="$CLAUDE_PROJECT_DIR"
-export SESSION_ID="$session_id"
-EOF
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+source "$SCRIPT_DIR/../lib/find-root.sh"
+
+# Set PYTHONPATH for pennyfarthing_scripts
+PENNYFARTHING_SCRIPTS=""
+if [[ -d "$PROJECT_ROOT/pennyfarthing" ]]; then
+    # Dogfooding: framework inlined in orchestrator
+    PENNYFARTHING_SCRIPTS="$PROJECT_ROOT/pennyfarthing"
+elif [[ -d "$PROJECT_ROOT/node_modules/@pennyfarthing/core" ]]; then
+    # Normal install
+    PENNYFARTHING_SCRIPTS="$PROJECT_ROOT/node_modules/@pennyfarthing/core"
+fi
 
-    # Auto-configure OTEL if Cyclist is running (Story 20-1)
-    PORT_FILE="$CLAUDE_PROJECT_DIR/.cyclist-port"
-    if [[ -f "$PORT_FILE" ]]; then
-        CYCLIST_PORT=$(cat "$PORT_FILE" 2>/dev/null)
-        if [[ "$CYCLIST_PORT" =~ ^[0-9]+$ ]]; then
-            cat >> "$CLAUDE_ENV_FILE" << EOF
-# OTEL auto-configuration for Cyclist (Story 20-1)
-export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
-export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:$CYCLIST_PORT"
-EOF
-        fi
-    fi
+if [[ -n "$PENNYFARTHING_SCRIPTS" ]]; then
+    export PYTHONPATH="$PENNYFARTHING_SCRIPTS:${PYTHONPATH:-}"
 fi
 
-exit 0
+python3 -m pennyfarthing_scripts.session_start_hook

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

@@ -32,5 +32,5 @@ Core logic lives in `pennyfarthing_scripts/jira/`:
 
 ## Ownership
 
-- **Primary users:** SM agent, `/jira` skill
+- **Primary users:** SM agent, `/pf-jira` skill
 - **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/scripts/portraits/generate-portraits.py

@@ -2,16 +2,18 @@
 """
 Individual Portrait Generator for Pennyfarthing Themes
 
-Generates 10 individual portraits per theme using Stable Diffusion SDXL on M3 Max (MPS).
-Reads visual prompts from theme YAML files in two locations:
-  - Built-in: pennyfarthing-dist/personas/themes/
-  - Custom:   .claude/pennyfarthing/themes/ (takes precedence)
+Generates individual portraits per theme using Stable Diffusion SDXL on M3 Max (MPS).
+Reads visual prompts from theme YAML files in three locations:
+  - Package:  packages/themes-*/themes/ (output to packages/themes-*/portraits/)
+  - Built-in: pennyfarthing-dist/personas/themes/ (output to pennyfarthing-dist/personas/portraits/)
+  - Custom:   .claude/pennyfarthing/themes/ (takes precedence, output to built-in portraits dir)
 
-Output: pennyfarthing-dist/personas/portraits/{theme}/{slug}-{OCEAN}.png (512x512px each)
+Output: {portraits-dir}/{theme}/{slug}-{OCEAN}.png (512x512px each)
 
 Usage:
     python3 scripts/generate-portraits.py [--dry-run] [--theme THEME]
     python3 scripts/generate-portraits.py --theme gilligans-island --dry-run
+    python3 scripts/generate-portraits.py --role ba --skip-existing
 """
 
 import argparse
@@ -77,7 +79,8 @@ def _find_project_root() -> Path:
 PROJECT_ROOT = _find_project_root()
 BUILTIN_THEMES_DIR = PROJECT_ROOT / "pennyfarthing-dist" / "personas" / "themes"
 CUSTOM_THEMES_DIR = PROJECT_ROOT / ".claude" / "pennyfarthing" / "themes"
-OUTPUT_DIR = PROJECT_ROOT / "pennyfarthing-dist" / "personas" / "portraits"
+BUILTIN_OUTPUT_DIR = PROJECT_ROOT / "pennyfarthing-dist" / "personas" / "portraits"
+PACKAGES_DIR = PROJECT_ROOT / "packages"
 MODEL_ID = "stabilityai/stable-diffusion-xl-base-1.0"
 
 # SDXL generates at 1024x1024, we'll resize to 512x512
@@ -272,46 +275,64 @@ def main():
     parser.add_argument("--output-dir", type=str, help="Output to different directory (default: pennyfarthing-dist/personas/portraits)")
     args = parser.parse_args()
 
-    # Determine output directory
-    output_base = Path(args.output_dir) if args.output_dir else OUTPUT_DIR
-
-    # Find theme files from both built-in and custom directories
-    # Custom themes take precedence over built-in themes with same name
-    theme_map = {}
-
-    # First add built-in themes
+    # Determine output directory override
+    output_override = Path(args.output_dir) if args.output_dir else None
+
+    # Find theme files from package, built-in, and custom directories
+    # Each entry tracks its own output directory
+    # Priority: custom > built-in > package (later entries override earlier)
+    theme_map: dict[str, dict] = {}
+
+    # 1. Package themes (packages/themes-*/themes/ -> packages/themes-*/portraits/)
+    pkg_sources = []
+    if PACKAGES_DIR.exists():
+        for pkg_dir in sorted(PACKAGES_DIR.glob("themes-*")):
+            themes_dir = pkg_dir / "themes"
+            portraits_dir = pkg_dir / "portraits"
+            if themes_dir.exists():
+                pkg_sources.append(themes_dir)
+                for tf in themes_dir.glob("*.yaml"):
+                    theme_map[tf.stem] = {"path": tf, "output_dir": portraits_dir}
+
+    # 2. Built-in themes (override packages if same name)
     if BUILTIN_THEMES_DIR.exists():
         for tf in BUILTIN_THEMES_DIR.glob("*.yaml"):
-            theme_map[tf.stem] = tf
+            theme_map[tf.stem] = {"path": tf, "output_dir": BUILTIN_OUTPUT_DIR}
 
-    # Then add/override with custom themes
+    # 3. Custom themes (override everything)
     if CUSTOM_THEMES_DIR.exists():
         for tf in CUSTOM_THEMES_DIR.glob("*.yaml"):
-            theme_map[tf.stem] = tf
+            theme_map[tf.stem] = {"path": tf, "output_dir": BUILTIN_OUTPUT_DIR}
 
-    theme_files = sorted(theme_map.values(), key=lambda p: p.stem)
+    theme_entries = sorted(theme_map.values(), key=lambda e: e["path"].stem)
 
     if args.theme:
         if args.theme in theme_map:
-            theme_files = [theme_map[args.theme]]
+            theme_entries = [theme_map[args.theme]]
         else:
             print(f"Theme '{args.theme}' not found")
             print(f"  Searched: {BUILTIN_THEMES_DIR}")
+            for src in pkg_sources:
+                print(f"  Searched: {src}")
             print(f"  Searched: {CUSTOM_THEMES_DIR}")
             sys.exit(1)
 
     print(f"Theme sources:")
     print(f"  Built-in: {BUILTIN_THEMES_DIR}")
+    for src in pkg_sources:
+        print(f"  Package:  {src}")
     print(f"  Custom:   {CUSTOM_THEMES_DIR}")
-    print(f"Found {len(theme_files)} themes")
-    print(f"Output: {output_base}/{{theme}}/{{slug}}-{{OCEAN}}.png")
+    print(f"Found {len(theme_entries)} themes")
 
     if args.dry_run:
         print(f"\nCLIP token limit: {CLIP_MAX_TOKENS} tokens")
         print(f"Tokenizer: {'CLIP (accurate)' if HAS_CLIP_TOKENIZER else 'word estimate (fallback)'}")
-        print("\nDry run - portraits to generate:")
+        roles_to_show = [args.role] if args.role else ROLES
+        print(f"\nDry run - portraits to generate (roles: {', '.join(roles_to_show)}):")
         truncation_warnings = []
-        for tf in theme_files:
+        for entry in theme_entries:
+            tf = entry["path"]
+            output_base = output_override or entry["output_dir"]
             parsed = parse_theme_file(tf)
             theme_dir = output_base / parsed["theme"]
             char_count = len(parsed["characters"])
@@ -319,7 +340,8 @@ def main():
             style_display = style_desc if style_desc else "(default woodcut)"
             print(f"\n  {parsed['theme']}/ ({char_count} characters with visual)")
             print(f"    Style: {style_display}")
-            for role in ROLES:
+            print(f"    Output: {output_base}")
+            for role in roles_to_show:
                 if role in parsed["characters"]:
                     char = parsed["characters"][role]
                     out_path = theme_dir / char["filename"]
@@ -362,8 +384,10 @@ def main():
     truncated = []
     start_time = datetime.now()
 
-    total_themes = len(theme_files)
-    for theme_idx, tf in enumerate(theme_files, 1):
+    total_themes = len(theme_entries)
+    for theme_idx, entry in enumerate(theme_entries, 1):
+        tf = entry["path"]
+        output_base = output_override or entry["output_dir"]
         parsed = parse_theme_file(tf)
         theme = parsed["theme"]
         theme_dir = output_base / theme

package/pennyfarthing-dist/scripts/portraits/generate-portraits.sh

@@ -20,18 +20,30 @@ while [[ ! -d "$_dir/.pennyfarthing" ]] && [[ ! -d "$_dir/pennyfarthing-dist" ]]
 done
 PROJECT_ROOT="$_dir"
 
-# If we're in the pennyfarthing repo itself, look for .venv there
-# If we're in a user project, .venv should be at project root
-VENV_DIR="$PROJECT_ROOT/.venv"
+# Find Python venv - check multiple locations
+# Priority: VENV_DIR env var > project .venv > ~/.venvs/sd > ~/.venv
 PYTHON_SCRIPT="$SCRIPT_DIR/generate-portraits.py"
 
+if [[ -z "${VENV_DIR:-}" ]]; then
+    if [[ -d "$PROJECT_ROOT/.venv" ]]; then
+        VENV_DIR="$PROJECT_ROOT/.venv"
+    elif [[ -d "$HOME/.venvs/sd" ]]; then
+        VENV_DIR="$HOME/.venvs/sd"
+    elif [[ -d "$HOME/.venv" ]]; then
+        VENV_DIR="$HOME/.venv"
+    fi
+fi
+
 # Check venv exists
-if [[ ! -d "$VENV_DIR" ]]; then
-    echo "Error: Virtual environment not found at $VENV_DIR"
-    echo "Create it with: python3 -m venv .venv"
+if [[ -z "${VENV_DIR:-}" ]] || [[ ! -d "$VENV_DIR" ]]; then
+    echo "Error: Virtual environment not found"
+    echo "Searched: $PROJECT_ROOT/.venv, ~/.venvs/sd, ~/.venv"
+    echo "Or set VENV_DIR=/path/to/venv"
+    echo "Create with: python3 -m venv .venv"
     echo "Then install: pip install diffusers transformers accelerate torch pillow pyyaml"
     exit 1
 fi
+echo "Using venv: $VENV_DIR"
 
 # Check Python script exists
 if [[ ! -f "$PYTHON_SCRIPT" ]]; then

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

@@ -34,7 +34,7 @@ pf sprint epic promote epic-41
 
 ## Ownership
 
-- **Primary users:** SM agent, `/sprint` skill
+- **Primary users:** SM agent, `/pf-sprint` skill
 - **Maintained by:** Core Pennyfarthing team
 
 ## Migration Note

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

@@ -19,5 +19,5 @@ Scripts for story creation and management.
 
 ## Ownership
 
-- **Primary users:** SM agent, `/sprint story` commands
+- **Primary users:** SM agent, `/pf-sprint story` commands
 - **Maintained by:** Core Pennyfarthing team

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

@@ -24,5 +24,5 @@ pf sprint story finish MSSCI-12345
 
 ## Ownership
 
-- **Primary users:** SM agent, `/workflow` skill
+- **Primary users:** SM agent, `/pf-workflow` skill
 - **Maintained by:** Core Pennyfarthing team

package/pennyfarthing-dist/skills/pf-bc/examples.md

@@ -0,0 +1,83 @@
+# BC (Panel Focus) — Examples
+
+## Setting Focus
+
+```bash
+# Focus on Sprint panel
+pf bc sprint
+
+# Focus on Diffs panel
+pf bc diffs
+
+# Focus on Acceptance Criteria
+pf bc ac
+
+# Focus on Git panel
+pf bc git
+
+# Preview without changing
+pf bc sprint --dry-run
+```
+
+## Clearing Focus
+
+```bash
+# Remove focus setting
+pf bc reset
+
+# Preview
+pf bc reset --dry-run
+```
+
+## Named Layouts
+
+```bash
+# Save current layout as "normal"
+pf bc save normal
+
+# Save current layout as "review"
+pf bc save review
+
+# Save current layout as "debug"
+pf bc save debug
+
+# List all saved layouts
+pf bc list
+
+# Switch to review layout
+pf bc load review
+
+# Switch back to normal
+pf bc load normal
+
+# Delete a specific layout
+pf bc clear review
+
+# Delete all layouts
+pf bc clear-all
+```
+
+## Common Workflows
+
+### During code review
+```bash
+pf bc save normal          # Save current layout first
+pf bc diffs                # Focus on diffs
+# ... do review ...
+pf bc load normal          # Restore normal layout
+```
+
+### Debugging session
+```bash
+pf bc save normal
+pf bc debug                # Focus debug panel
+# ... debug ...
+pf bc reset                # Clear focus
+```
+
+### Sprint planning
+```bash
+pf bc sprint               # Focus sprint panel
+# ... review backlog ...
+pf bc reset
+```

package/pennyfarthing-dist/skills/pf-bc/skill.md

@@ -0,0 +1,51 @@
+---
+name: bc
+description: |
+  Panel focus management for Cyclist. Set which panel BikeRack/Cyclist should focus on,
+  or clear the focus setting. Save and load named layouts. Writes to `.pennyfarthing/config.local.yaml`.
+args: "[panel|reset|save|load|list|clear|clear-all] [name]"
+---
+
+# /bc - Panel Focus & Layout Management
+
+Set or clear the focused panel in Cyclist/BikeRack. Save and restore named layouts.
+
+## Quick Reference
+
+### Panel Focus
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/bc sprint` | `pf bc sprint [--dry-run]` | Focus Sprint panel |
+| `/bc git` | `pf bc git [--dry-run]` | Focus Git panel |
+| `/bc diffs` | `pf bc diffs [--dry-run]` | Focus Diffs panel |
+| `/bc todo` | `pf bc todo [--dry-run]` | Focus Todo panel |
+| `/bc workflow` | `pf bc workflow [--dry-run]` | Focus Workflow panel |
+| `/bc background` | `pf bc background [--dry-run]` | Focus Background panel |
+| `/bc audit-log` | `pf bc audit-log [--dry-run]` | Focus Audit Log panel |
+| `/bc changed` | `pf bc changed [--dry-run]` | Focus Changed panel |
+| `/bc ac` | `pf bc ac [--dry-run]` | Focus Acceptance Criteria panel |
+| `/bc debug` | `pf bc debug [--dry-run]` | Focus Debug panel |
+| `/bc settings` | `pf bc settings [--dry-run]` | Focus Settings panel |
+| `/bc reset` | `pf bc reset [--dry-run]` | Clear focus setting |
+
+### Named Layouts
+
+| Command | CLI | Purpose |
+|---------|-----|---------|
+| `/bc save <name>` | `pf bc save <name> [--dry-run]` | Save current layout from running server |
+| `/bc load <name>` | `pf bc load <name> [--dry-run]` | Load a saved layout |
+| `/bc list` | `pf bc list` | List all saved layouts |
+| `/bc clear <name>` | `pf bc clear <name> [--dry-run]` | Delete a saved layout |
+| `/bc clear-all` | `pf bc clear-all [--dry-run]` | Delete all saved layouts |
+
+### Notes
+
+- The `message` panel (sacred center) is not focusable
+- Config written to `.pennyfarthing/config.local.yaml` under `focus` / `named_layouts` keys
+- `save` requires a running Cyclist/BikeRack server
+
+---
+
+**Detailed options and behavior:** [usage.md](usage.md)
+**Practical examples:** [examples.md](examples.md)