@pennyfarthing/core 7.4.0 → 7.4.1

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

@@ -0,0 +1,90 @@
+#!/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}"
+
+# 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 [[ "$USE_TIREPUMP" == "true" ]]; then
+  # Cyclist + TirePump - context clear marker
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:CONTEXT_CLEAR:/${NEXT_AGENT} -->"
+  fallback: "Run \`/${NEXT_AGENT}\` to continue"
+---
+EOF
+else
+  # Cyclist, no TirePump - handoff marker
+  cat <<EOF
+---
+AGENT_COMMAND:
+  marker: "<!-- CYCLIST:HANDOFF:/${NEXT_AGENT} -->"
+  fallback: "Run \`/${NEXT_AGENT}\` to continue"
+---
+EOF
+fi

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env zsh
+# prime.sh - Load essential project context at agent activation
+# Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]
+#
+# Loads context in priority order (CLAUDE.md skipped - already in system prompt):
+# 1. Sprint summary (current-sprint.yaml key fields)
+# 2. Active session (.session/*-session.md)
+# 3. Agent sidecar (if --agent provided)
+# 4. Agent behavior guide (combined protocols for all agents)
+# 5. Domain docs (--full only)
+
+set -euo pipefail
+
+# Load shared functions
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/../sprint/sprint-common.sh"
+
+# Defaults
+QUIET=false
+MINIMAL=false
+FULL=false
+AGENT_NAME=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --quiet) QUIET=true; shift ;;
+        --minimal) MINIMAL=true; shift ;;
+        --full) FULL=true; shift ;;
+        --agent) AGENT_NAME="$2"; shift 2 ;;
+        -h|--help)
+            echo "Usage: prime.sh [--minimal] [--full] [--quiet] [--agent <name>]"
+            echo "  --minimal      Skip all context (fastest)"
+            echo "  --full         Include domain docs from .claude/project/"
+            echo "  --quiet        Suppress section headers"
+            echo "  --agent <name> Load agent's sidecar patterns"
+            exit 0
+            ;;
+        *) shift ;;
+    esac
+done
+
+# Helper to print headers (respects --quiet)
+print_header() {
+    if [[ "$QUIET" != "true" ]]; then
+        echo ""
+        echo "# $1"
+    fi
+}
+
+# CLAUDE.md is already loaded by Claude Code system prompt - skip it
+
+# Stop here for minimal mode
+if [[ "$MINIMAL" == "true" ]]; then
+    exit 0
+fi
+
+# 1. Sprint summary (uses shared functions from sprint-common.sh)
+if [[ -f "$(get_sprint_file)" ]]; then
+    print_header "Sprint Context"
+
+    # Use shared functions for consistent output
+    summary=$(get_sprint_summary)
+    if [[ -n "$summary" ]]; then
+        echo "$summary"
+    fi
+
+    progress=$(get_sprint_progress)
+    if [[ -n "$progress" ]]; then
+        echo "$progress"
+    fi
+fi
+
+# 2. Active session (if exists) - extract header metadata + current assessment
+SESSION_FILE=""
+if [[ -d "$PROJECT_ROOT/.session" ]]; then
+    # Find a session file (typically only one active at a time)
+    SESSION_FILE=$(find "$PROJECT_ROOT/.session" -maxdepth 1 -name "*-session.md" -type f 2>/dev/null | head -1)
+fi
+
+if [[ -n "$SESSION_FILE" && -f "$SESSION_FILE" ]]; then
+    print_header "Active Session: $(basename "$SESSION_FILE")"
+
+    # Extract header (everything before first ## heading)
+    # This includes: title, metadata fields (Phase, Workflow, Repos, Branch, etc.)
+    awk '/^## / {exit} {print}' "$SESSION_FILE"
+
+    # Find the most recent assessment section (workflow-agnostic)
+    # Assessment sections are named: "## {Agent} Assessment" (TEA, Dev, Reviewer, SM, etc.)
+    # Show the LAST one in the file as it represents current state
+    last_assessment=$(grep -n '^## .*Assessment' "$SESSION_FILE" | tail -1 | cut -d: -f1)
+
+    if [[ -n "$last_assessment" ]]; then
+        echo ""
+        echo "---"
+        # Extract from that line to next ## or EOF
+        awk -v start="$last_assessment" '
+            NR >= start {
+                if (NR > start && /^## /) exit
+                print
+            }
+        ' "$SESSION_FILE"
+    fi
+fi
+
+# 3. Agent sidecar (if --agent provided)
+if [[ -n "$AGENT_NAME" ]]; then
+    SIDECAR_DIR="$PROJECT_ROOT/.pennyfarthing/sidecars/${AGENT_NAME}"
+    if [[ -d "$SIDECAR_DIR" ]]; then
+        for pattern_file in "$SIDECAR_DIR"/*.md; do
+            if [[ -f "$pattern_file" ]]; then
+                print_header "Agent Sidecar: $(basename "$pattern_file")"
+                cat "$pattern_file"
+            fi
+        done
+    fi
+fi
+
+# 4. Agent behavior guide (combined protocols for all agents)
+if [[ -n "$AGENT_NAME" ]]; then
+    BEHAVIOR_GUIDE="$PROJECT_ROOT/.pennyfarthing/guides/agent-behavior.md"
+    if [[ -f "$BEHAVIOR_GUIDE" ]]; then
+        print_header "Agent Behavior Guide"
+        cat "$BEHAVIOR_GUIDE"
+    fi
+fi
+
+# 5. Domain docs (--full only)
+if [[ "$FULL" == "true" ]]; then
+    for doc in "$PROJECT_ROOT/.claude/project"/CLAUDE-*.md; do
+        if [[ -f "$doc" ]]; then
+            print_header "$(basename "$doc")"
+            cat "$doc"
+        fi
+    done
+fi

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

@@ -0,0 +1,75 @@
+#!/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 .claude/ 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 .claude/ marker
+find_project_root() {
+    local dir="$PWD"
+    while [[ ! -d "$dir/.claude" ]] && [[ "$dir" != "/" ]]; do
+        dir="$(dirname "$dir")"
+    done
+    if [[ -d "$dir/.claude" ]]; then
+        echo "$dir"
+    else
+        echo "Error: Could not find project root (no .claude/ 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
+
+# Full path required - script must include category
+SCRIPT_PATH="$SCRIPTS_DIR/$SCRIPT_NAME"
+
+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

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

@@ -0,0 +1,226 @@
+#!/usr/bin/env zsh
+# Create or checkout feature branches in Pennyfarthing repos
+# Idempotent, worktree-aware, branches from develop
+
+set -e
+
+# Load environment
+if [ -f .env ]; then
+    set -a; source .env; set +a
+elif [ -f ../.env ]; then
+    set -a; source ../.env; set +a
+fi
+
+show_help() {
+    cat << EOF
+Create Feature Branches - Idempotent branch creation/checkout
+
+Usage: ./create-feature-branches.sh <branch-name> [repos]
+
+Arguments:
+  branch-name    Branch name (e.g., feat/11-2-file-preview)
+  repos          Which repos to branch (default: all)
+                 Options: api, ui, all
+
+Repo Options:
+  api     - Pennyfarthing-api only
+  ui      - Pennyfarthing-ui only
+  all     - both repos (default)
+
+Examples:
+  # All repos (default)
+  ./create-feature-branches.sh feat/cross-repo-feature
+
+  # Pennyfarthing UI only
+  ./create-feature-branches.sh feat/11-2-ui-component ui
+
+  # Pennyfarthing API only
+  ./create-feature-branches.sh fix/validation-bug api
+
+Behavior:
+  - Idempotent: Checks out existing branches or creates new ones
+  - Worktree-aware: Detects main checkout vs worktree
+  - Always branches from develop
+  - Fetches latest develop before branching
+
+EOF
+}
+
+if [ -z "$1" ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+    show_help
+    exit 0
+fi
+
+BRANCH_NAME="$1"
+REPOS="${2:-all}"
+
+# Validate repos parameter
+if [[ ! "$REPOS" =~ ^(api|ui|all)$ ]]; then
+    echo "❌ Error: repos must be one of: api, ui, all"
+    echo "   Got: $REPOS"
+    echo ""
+    echo "Options:"
+    echo "  api     - Pennyfarthing-api only"
+    echo "  ui      - Pennyfarthing-ui only"
+    echo "  all     - both repos (default)"
+    exit 1
+fi
+
+# Detect if we're in a worktree
+CURRENT_DIR=$(pwd)
+if [[ "$CURRENT_DIR" == *"/worktrees/"* ]]; then
+    # Extract worktree name from path
+    WORKTREE_NAME=$(echo "$CURRENT_DIR" | sed -E 's|.*/worktrees/([^/]+).*|\1|')
+    REPO_BASE="$PROJECT_ROOT/worktrees/$WORKTREE_NAME"
+    echo "📂 Detected worktree: $WORKTREE_NAME"
+else
+    REPO_BASE="$PROJECT_ROOT"
+    echo "📂 Using main checkout"
+fi
+
+# Array to track processed repos for verification
+declare -a PROCESSED_REPOS
+
+# Function to create or checkout branch in a repo
+create_or_checkout_branch() {
+    local repo_path=$1
+    local repo_name=$2
+
+    if [ ! -d "$repo_path" ]; then
+        echo "⚠️  Skipping $repo_name: directory not found at $repo_path"
+        return
+    fi
+
+    cd "$repo_path"
+
+    echo ""
+    echo "🔧 Processing $repo_name..."
+
+    # Fetch latest from remote
+    echo "   Fetching from origin..."
+    git fetch origin --quiet
+
+    # Check if branch exists locally
+    if git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
+        echo "   ✅ Branch exists locally, checking out: $BRANCH_NAME"
+        git checkout "$BRANCH_NAME"
+    # Check if branch exists on remote
+    elif git show-ref --verify --quiet "refs/remotes/origin/$BRANCH_NAME"; then
+        echo "   ✅ Branch exists on remote, checking out and tracking: $BRANCH_NAME"
+        git checkout -b "$BRANCH_NAME" "origin/$BRANCH_NAME"
+    else
+        # Branch doesn't exist, create from develop
+        echo "   🌿 Creating new branch from develop: $BRANCH_NAME"
+
+        # Make sure we have latest develop
+        git fetch origin develop:develop --quiet 2>/dev/null || true
+
+        # Checkout develop first
+        if git show-ref --verify --quiet "refs/heads/develop"; then
+            git checkout develop --quiet
+            git pull origin develop --quiet
+        else
+            echo "   ⚠️  Local develop doesn't exist, fetching from remote"
+            git fetch origin develop:develop --quiet
+            git checkout develop --quiet
+        fi
+
+        # Create new branch
+        git checkout -b "$BRANCH_NAME"
+        echo "   ✅ Created: $BRANCH_NAME"
+    fi
+
+    # Show current status
+    CURRENT_BRANCH=$(git branch --show-current)
+    echo "   📍 Now on: $CURRENT_BRANCH"
+
+    # Track this repo for verification
+    PROCESSED_REPOS+=("$repo_path:$repo_name")
+}
+
+echo "🌿 Creating/checking out feature branches..."
+echo "   Branch: $BRANCH_NAME"
+echo "   Repos: $REPOS"
+
+# Process repos based on selection
+case "$REPOS" in
+    api)
+        create_or_checkout_branch "$REPO_BASE/Pennyfarthing-api" "Pennyfarthing-api"
+        ;;
+    ui)
+        create_or_checkout_branch "$REPO_BASE/Pennyfarthing-ui" "Pennyfarthing-ui"
+        ;;
+    all)
+        create_or_checkout_branch "$REPO_BASE/Pennyfarthing-api" "Pennyfarthing-api"
+        create_or_checkout_branch "$REPO_BASE/Pennyfarthing-ui" "Pennyfarthing-ui"
+        ;;
+esac
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔍 Verification Summary"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Verify each processed repo
+for repo_info in "${PROCESSED_REPOS[@]}"; do
+    repo_path="${repo_info%%:*}"
+    repo_name="${repo_info##*:}"
+
+    if [ -d "$repo_path" ]; then
+        cd "$repo_path"
+
+        echo ""
+        echo "📦 $repo_name"
+        echo "   Path: $repo_path"
+
+        # Current branch
+        CURRENT_BRANCH=$(git branch --show-current)
+        echo "   Branch: $CURRENT_BRANCH"
+
+        # Check if branch matches expected
+        if [ "$CURRENT_BRANCH" = "$BRANCH_NAME" ]; then
+            echo "   ✅ Branch matches: $BRANCH_NAME"
+        else
+            echo "   ⚠️  Branch mismatch! Expected: $BRANCH_NAME, Got: $CURRENT_BRANCH"
+        fi
+
+        # Latest commit
+        COMMIT_INFO=$(git log -1 --format="%h - %s" 2>/dev/null)
+        echo "   Commit: $COMMIT_INFO"
+
+        # Check remote tracking
+        UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "none")
+        if [ "$UPSTREAM" != "none" ]; then
+            echo "   Remote: $UPSTREAM"
+
+            # Check if up to date with remote
+            git fetch origin "$CURRENT_BRANCH" --quiet 2>/dev/null || true
+            LOCAL=$(git rev-parse @ 2>/dev/null)
+            REMOTE=$(git rev-parse @{u} 2>/dev/null || echo "none")
+
+            if [ "$LOCAL" = "$REMOTE" ]; then
+                echo "   Status: ✅ Up to date with remote"
+            elif [ "$REMOTE" = "none" ]; then
+                echo "   Status: ⚠️  No remote branch yet (push needed)"
+            else
+                BEHIND=$(git rev-list --count HEAD..@{u} 2>/dev/null || echo "0")
+                AHEAD=$(git rev-list --count @{u}..HEAD 2>/dev/null || echo "0")
+                if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then
+                    echo "   Status: ⚠️  Diverged ($AHEAD ahead, $BEHIND behind)"
+                elif [ "$AHEAD" -gt 0 ]; then
+                    echo "   Status: ⬆️  $AHEAD commit(s) ahead of remote"
+                elif [ "$BEHIND" -gt 0 ]; then
+                    echo "   Status: ⬇️  $BEHIND commit(s) behind remote"
+                fi
+            fi
+        else
+            echo "   Remote: none (local branch only)"
+            echo "   Status: ⚠️  Not tracking remote (push with -u needed)"
+        fi
+    fi
+done
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ Done! All branches verified and ready."
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"