@pennyfarthing/core 8.1.0 → 9.0.3

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

@@ -19,13 +19,7 @@ if [[ -z "$EPIC_ID" ]]; 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"
 
 SPRINT_FILE="$PROJECT_ROOT/sprint/current-sprint.yaml"
 SCRIPTS_DIR="$PROJECT_ROOT/.pennyfarthing/scripts"

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

@@ -14,14 +14,8 @@ if [[ -z "$EPIC_JIRA_KEY" || -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"
 JIRA_PROJECT="${JIRA_PROJECT_KEY:-MSSCI}"

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

@@ -13,14 +13,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"
 FIX_MODE="${1:-}"

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

@@ -1,61 +1,58 @@
 #!/usr/bin/env bash
-# Shared utility: Find project root via BASH_SOURCE self-location
+# Shared utility: Find project root
 #
-# 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.
+# Resolution order:
+# 1. Honor explicit PROJECT_ROOT override (from Claude Code or user)
+# 2. BASH_SOURCE derivation (auto-detect caller's location)
+# 3. PWD walk looking for .pennyfarthing/ (fallback)
 #
 # Usage:
-#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-#   source "$SCRIPT_DIR/../lib/find-root.sh"
+#   source "$(dirname "${BASH_SOURCE[0]}")/../lib/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)"
+# BASH_SOURCE approach: derive from caller's location
+# BASH_SOURCE[1] is the script that sourced us, BASH_SOURCE[0] is this file
+_caller_script="${BASH_SOURCE[1]:-}"
+if [[ -n "$_caller_script" ]]; then
+    _real_dir="$(cd "$(dirname "$_caller_script")" && pwd -P)"
+    if [[ "$_real_dir" == */pennyfarthing-dist/scripts/* ]] || \
+       [[ "$_real_dir" == */.pennyfarthing/scripts/* ]]; then
+        # Extract package root from path
+        _pkg="${_real_dir%/scripts/*}"
+        _pkg="${_pkg%/pennyfarthing-dist}"
+        _pkg="${_pkg%/.pennyfarthing}"
+        if [[ "$_pkg" == */node_modules/* ]]; then
+            PROJECT_ROOT="${_pkg%/node_modules/*}"
+        else
+            PROJECT_ROOT="$_pkg"
+        fi
+        unset _real_dir _pkg _caller_script
+        export PROJECT_ROOT
+        return 0 2>/dev/null || exit 0
+    fi
+    unset _real_dir
+fi
+unset _caller_script
 
-# 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/*}"
+# Fallback: 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/agentic-patterns/SKILL.md

@@ -6,6 +6,10 @@ allowed_tools: [Read, Glob, Grep, Task]
 
 # Agentic Patterns Skill
 
+<run>When designing agent behavior, debugging agent failures, improving agent reliability.</run>
+
+<output>Core reasoning patterns for building effective LLM agents. Includes ReAct, Plan-and-Execute, Self-Reflection, confidence calibration, error recovery, multi-agent coordination, and context management strategies.</output>
+
 **Purpose:** Core reasoning patterns for building effective LLM agents.
 
 **Use when:** Designing agent behavior, debugging agent failures, improving agent reliability.

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

@@ -3,6 +3,24 @@ name: changelog
 description: Maintain changelogs following Keep a Changelog format. Use when creating release notes, parsing conventional commits for changelog entries, auto-generating changelog sections from git history, or preparing CHANGELOG.md for releases.
 ---
 
+<run>
+Commands for changelog maintenance:
+- Parse conventional commits for changelog entries
+- Auto-generate changelog sections from git history
+- Version bump decisions using semantic versioning
+- Create release notes and CHANGELOG.md updates
+</run>
+
+<output>
+Changelog entries in Keep a Changelog format:
+- Added (new features from `feat:` commits)
+- Changed (changes from `perf:` commits, breaking changes)
+- Deprecated (features marked for removal)
+- Removed (removed features)
+- Fixed (bug fixes from `fix:` commits)
+- Security (vulnerability fixes)
+</output>
+
 # Changelog Management Skill
 
 ## When to Use This Skill

package/pennyfarthing-dist/skills/code-review/SKILL.md

@@ -3,7 +3,11 @@ name: code-review
 description: Code review checklists and patterns for Pennyfarthing. Use when reviewing PRs, self-reviewing code, or checking for common issues before commit.
 ---
 
-# Code Review Skill 
+# Code Review Skill
+
+<run>Review code against the checklists below. Focus on authorization, error handling, TypeScript/React patterns, and performance.</run>
+
+<output>Code review comments using [MUST FIX], [SUGGESTION], [QUESTION], [NICE] prefixes</output>
 
 ## Overview
 

package/pennyfarthing-dist/skills/context-engineering/SKILL.md

@@ -6,6 +6,9 @@ allowed_tools: [Read, Glob, Grep, Task]
 
 # Context Engineering Skill
 
+<run>context-engineering</run>
+<output>strategies for managing context windows in long-running agent sessions</output>
+
 **Purpose:** Strategies for managing context windows efficiently in long-running agent sessions.
 
 **Use when:** Working on complex tasks, approaching context limits, designing subagent prompts.

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

@@ -15,7 +15,7 @@ args: "[check|status]"
 Check if running inside Cyclist visual terminal.
 
 <run>
-.pennyfarthing/scripts cyclist/is-cyclist.sh
+.pennyfarthing/scripts/cyclist/is-cyclist.sh
 </run>
 
 <output>
@@ -23,7 +23,7 @@ JSON: `{"cyclist": true}` with exit 0 if in Cyclist, `{"cyclist": false}` with e
 </output>
 
 <example>
-.pennyfarthing/scripts cyclist/is-cyclist.sh
+.pennyfarthing/scripts/cyclist/is-cyclist.sh
 # Returns: {"cyclist": true}
 </example>
 

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

@@ -4,6 +4,30 @@ description: Common development patterns, fixes, and gotchas. Use when implement
 allowed_tools: [Read, Glob, Grep, Task]
 ---
 
+<run>
+Reference this skill when implementing features, debugging issues, or avoiding known pitfalls in development. Use these patterns to guide:
+- Working directory management in bash commands
+- TypeScript type system decisions
+- Error handling in Go
+- Test structure and isolation
+- HTTP status code selection
+- Turn-efficient coding practices
+- Background task execution
+
+The patterns capture common gotchas and solutions across multiple languages and frameworks.
+</run>
+
+<output>
+Following these patterns produces:
+- Reliable bash commands that work regardless of current directory
+- TypeScript builds that pass verbatimModuleSyntax validation
+- Go code with proper error handling and validation
+- Well-isolated, maintainable test suites
+- Consistent HTTP API behavior
+- Faster task completion through turn-efficient techniques
+- Properly tracked background operations
+</output>
+
 # Dev Patterns Skill
 
 ## Overview
@@ -381,7 +405,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/finalize-run/SKILL.md

@@ -5,6 +5,9 @@ description: Validate and save benchmark run results. Use when completing a benc
 
 # Finalize Run Skill
 
+<run>Validates and saves benchmark run results</run>
+<output>JSON with validation success status and saved file path</output>
+
 All runs MUST pass through this skill before saving. This is the guardrail.
 
 ## Invocation