@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: systematic-debugging
+description: Systematic debugging approach for isolating and fixing issues. Use when debugging failures, investigating errors, bisecting regressions, or validating fixes.
+---
+
+# Systematic Debugging Skill
+
+**Purpose:** Guide methodical debugging to find root causes, not just symptoms.
+
+**Use when:** Bug reports, test failures, unexpected behavior, regressions.
+
+---
+
+## When to Use This Skill
+
+- Debugging test failures or unexpected behavior
+- Investigating error messages or stack traces
+- Bisecting to find when a regression was introduced
+- Validating that a fix addresses root cause, not just symptoms
+- Intermittent failures that are hard to reproduce
+
+---
+
+## The Debugging Cycle
+
+```
+1. REPRODUCE  → Make the failure happen reliably
+2. ISOLATE    → Narrow down to minimal reproducer
+3. HYPOTHESIZE → Form theory about root cause
+4. TEST       → Validate or invalidate hypothesis
+5. FIX        → Implement solution
+6. VERIFY     → Confirm fix addresses root cause
+```
+
+### Quick Reference
+
+| Phase | Question to Answer | Output |
+|-------|-------------------|--------|
+| REPRODUCE | Can I make it fail consistently? | Reliable reproduction steps |
+| ISOLATE | What's the minimal code/input that triggers it? | Minimal reproducer |
+| HYPOTHESIZE | What could cause this behavior? | Ranked list of theories |
+| TEST | Does evidence support my theory? | Confirmed or refuted hypothesis |
+| FIX | What's the minimal change to fix it? | Working code |
+| VERIFY | Does the fix address root cause? | Regression test |
+
+---
+
+## Phase 1: REPRODUCE
+
+**Goal:** Make the failure happen reliably.
+
+### Steps
+
+1. **Document exact error** - Copy the full error message, stack trace, logs
+2. **Capture environment** - Versions, configuration, system state
+3. **Create reproduction steps** - Exact commands/actions to trigger
+4. **Test reproduction** - Run it 3+ times to confirm consistency
+
+### For Intermittent Failures
+
+| Pattern | Approach |
+|---------|----------|
+| Race condition | Add delays, run in tight loop, stress test |
+| State-dependent | Reset to clean state, document preconditions |
+| Environment-specific | Compare working vs failing environments |
+| Timing-dependent | Add timestamps, check for timeouts |
+
+### Example
+
+```bash
+# Document the failure
+$ npm test -- -t "user authentication"
+# Error: Expected 200 but got 401
+
+# Capture environment
+$ node --version  # v18.17.0
+$ npm --version   # 9.6.7
+
+# Reproduction steps
+1. Start fresh database: docker-compose down -v && docker-compose up -d
+2. Run: npm test -- -t "user authentication"
+3. Observe: 401 error on third test
+
+# Verify reproduction
+$ npm test -- -t "user authentication"  # Fails
+$ npm test -- -t "user authentication"  # Fails
+$ npm test -- -t "user authentication"  # Fails - consistent!
+```
+
+---
+
+## Phase 2: ISOLATE
+
+**Goal:** Narrow down to the smallest code/input that triggers the bug.
+
+### Techniques
+
+#### Binary Search (Code)
+
+```
+1. Find a known-good commit
+2. Find the failing commit
+3. git bisect between them
+4. Each step: test, mark good/bad
+5. Arrive at first bad commit
+```
+
+```bash
+git bisect start
+git bisect bad HEAD
+git bisect good v1.2.0
+# Git checks out middle commit
+npm test -- -t "failing test"
+git bisect bad  # or good
+# Repeat until found
+git bisect reset
+```
+
+#### Minimal Reproducer
+
+1. Start with failing test/code
+2. Remove components one at a time
+3. Stop when removal fixes the bug
+4. The last removed component is involved
+
+#### Variable Elimination
+
+| Remove | Still fails? | Conclusion |
+|--------|--------------|------------|
+| External API calls | Yes | Not API-related |
+| Database queries | No | Database-related |
+| Specific table | Yes | Not that table |
+| Auth middleware | No | Auth is involved |
+
+### Example
+
+```typescript
+// Full failing code
+async function createUser(data) {
+  validateInput(data);
+  const hash = await hashPassword(data.password);
+  const user = await db.insert({ ...data, password: hash });
+  await sendWelcomeEmail(user.email);
+  return user;
+}
+
+// Minimal reproducer (isolated the issue)
+async function createUser(data) {
+  const user = await db.insert(data);  // Fails here!
+  return user;
+}
+// Conclusion: Issue is in db.insert, not validation/email
+```
+
+---
+
+## Phase 3: HYPOTHESIZE
+
+**Goal:** Form testable theories about root cause.
+
+### Common Root Causes
+
+| Category | Examples |
+|----------|----------|
+| State | Uninitialized variable, stale cache, leftover data |
+| Timing | Race condition, timeout, async ordering |
+| Input | Edge case, null/undefined, empty collection, boundary |
+| Environment | Missing env var, wrong version, config mismatch |
+| Logic | Off-by-one, wrong operator, incorrect condition |
+
+### Hypothesis Formation
+
+1. **Read the error message carefully** - Often tells you exactly what's wrong
+2. **Check recent changes** - `git log --oneline -20`, `git diff HEAD~5`
+3. **Consider edge cases** - What if null? Empty? Max value?
+4. **Look for patterns** - When does it fail vs succeed?
+
+### Rank Hypotheses
+
+```
+Hypothesis 1 (HIGH): Database connection timing out
+- Evidence: Error mentions timeout, happens under load
+- Test: Check connection pool settings
+
+Hypothesis 2 (MEDIUM): Invalid input not validated
+- Evidence: Stack trace shows null pointer in parser
+- Test: Add input validation logging
+
+Hypothesis 3 (LOW): Bug in library
+- Evidence: Nothing obvious in our code
+- Test: Check library issues, try downgrade
+```
+
+---
+
+## Phase 4: TEST
+
+**Goal:** Validate or invalidate each hypothesis.
+
+### Testing Approaches
+
+| Approach | When to Use |
+|----------|-------------|
+| Add logging | Need to see values at runtime |
+| Debugger breakpoint | Need to inspect state interactively |
+| Unit test | Can isolate the specific function |
+| Print statements | Quick check in specific location |
+| Assertion | Verify assumption holds |
+
+### Logging Strategy
+
+```typescript
+// Add strategic logging
+console.log('[DEBUG] Input:', JSON.stringify(data));
+console.log('[DEBUG] Before DB call, user:', user?.id);
+console.log('[DEBUG] After DB call, result:', result);
+console.log('[DEBUG] Query took:', endTime - startTime, 'ms');
+```
+
+### Hypothesis Testing
+
+```
+HYPOTHESIS: Connection pool exhausted under load
+
+TEST 1: Check pool stats
+> db.pool.stats()
+{ active: 50, idle: 0, waiting: 12 }  // Pool full!
+
+TEST 2: Increase pool size
+> config.pool.max = 100
+> Rerun test
+> PASS
+
+CONCLUSION: Hypothesis confirmed. Pool too small.
+```
+
+### When Hypothesis is Wrong
+
+If evidence doesn't support your theory:
+1. Don't force-fit the evidence
+2. Return to HYPOTHESIZE phase
+3. Form new theory based on new observations
+4. Repeat until you find the cause
+
+---
+
+## Phase 5: FIX
+
+**Goal:** Implement the minimal change that fixes the issue.
+
+### Fix Principles
+
+1. **Fix the root cause, not the symptom**
+   - BAD: Add try/catch to hide the error
+   - GOOD: Fix why the error occurs
+
+2. **Minimal change**
+   - Change only what's necessary
+   - Don't refactor while fixing bugs
+
+3. **One fix per bug**
+   - Don't bundle unrelated changes
+   - Makes it clear what fixed what
+
+### Fix Template
+
+```typescript
+// BEFORE: Bug - pool exhaustion under load
+const pool = new Pool({ max: 10 });
+
+// AFTER: Fix - increase pool size based on expected load
+const pool = new Pool({
+  max: 50,  // Increased from 10 to handle peak load
+  idleTimeoutMillis: 30000,
+});
+```
+
+---
+
+## Phase 6: VERIFY
+
+**Goal:** Confirm the fix addresses root cause and doesn't break anything else.
+
+### Verification Checklist
+
+- [ ] Original reproduction steps now pass
+- [ ] New test case covers the bug (regression test)
+- [ ] Existing tests still pass
+- [ ] Fix doesn't introduce new issues
+- [ ] Fix addresses root cause, not just symptom
+
+### Write a Regression Test
+
+```typescript
+// This test should have caught the bug
+test('handles concurrent requests without pool exhaustion', async () => {
+  const requests = Array(100).fill(null).map(() => api.createUser());
+  const results = await Promise.all(requests);
+  expect(results.every(r => r.status === 201)).toBe(true);
+});
+```
+
+### Symptom vs Root Cause Check
+
+Ask yourself:
+- "Would this bug happen again in a different form?"
+- "Did I fix WHY it happened, or just WHAT happened?"
+
+| Fix | Symptom or Root Cause? |
+|-----|------------------------|
+| Add null check | Symptom (why is it null?) |
+| Initialize variable properly | Root cause |
+| Increase timeout | Symptom (why is it slow?) |
+| Fix N+1 query | Root cause |
+
+---
+
+## Debugging Anti-Patterns
+
+### What NOT to Do
+
+| Anti-Pattern | Why It's Bad | Instead |
+|--------------|--------------|---------|
+| Random changes | Introduces new bugs, wastes time | Follow the cycle |
+| Fix without reproducing | Can't verify fix works | Always reproduce first |
+| Blame external factors | Delays finding real cause | Assume it's your code |
+| Skip verification | Bug may not be fixed | Always verify |
+| Big refactor as "fix" | Hides what actually fixed it | Minimal changes |
+
+### Common Traps
+
+1. **Confirmation bias** - Looking for evidence that supports your theory
+2. **Premature optimization** - Fixing performance before correctness
+3. **Tunnel vision** - Fixating on one hypothesis
+4. **Solution jumping** - Skipping to fix before understanding
+
+---
+
+## Quick Debugging Commands
+
+### Git Bisect (Find Regression)
+
+```bash
+git bisect start
+git bisect bad                 # Current commit is bad
+git bisect good v1.0.0         # Known good commit
+# Run test, then:
+git bisect good  # or bad
+# Repeat until found
+git bisect reset
+```
+
+### Find Recent Changes
+
+```bash
+# What changed recently?
+git log --oneline -20
+git diff HEAD~5
+
+# Who changed this file?
+git blame path/to/file.ts
+
+# When did this line change?
+git log -p -S "problematic code" -- path/to/file.ts
+```
+
+### Check Running Processes
+
+```bash
+# What's using resources?
+ps aux | grep node
+lsof -i :3000
+
+# Check memory/CPU
+top -l 1 | head -20
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | How It Complements |
+|-------|-------------------|
+| `/testing` | Run tests to verify fixes |
+| `/dev-patterns` | Avoid common pitfalls |
+| `/agentic-patterns` | ReAct pattern for systematic investigation |
+
+---
+
+**Remember:** Debugging is detective work. Follow the evidence, test your theories, and fix the root cause. Rushing leads to band-aid fixes that break later.

package/pennyfarthing-dist/skills/theme/skill.md

@@ -1,6 +1,6 @@
 ---
 name: theme
-description: Manage persona themes - list available themes, show current/specific theme details, and set active theme. Use for all theme-related operations.
+description: Manage persona themes - list available themes, show current/specific theme details, and set active theme. Use when switching persona themes, viewing available characters, or checking which theme is currently active.
 ---
 
 # Theme Management Skill

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

@@ -0,0 +1,91 @@
+#!/bin/bash
+# List all available workflows with type indicators
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/list-workflows.sh
+#    or: Invoked with PROJECT_ROOT already set
+#
+# MSSCI-12083: Added type, steps, and modes columns
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+
+if [[ ! -d "$WORKFLOWS_DIR" ]]; then
+  echo "Error: Workflows directory not found at $WORKFLOWS_DIR"
+  exit 1
+fi
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+echo "# Available Workflows"
+echo ""
+echo "| Workflow | Type | Default | Steps/Phases | Modes | Description |"
+echo "|----------|------|---------|--------------|-------|-------------|"
+
+for f in "$WORKFLOWS_DIR"/*.yaml; do
+  [[ -f "$f" ]] || continue
+
+  name=$(yq eval '.workflow.name' "$f")
+  desc=$(yq eval '.workflow.description' "$f" | head -1)
+  is_default=$(yq eval '.workflow.triggers.default // false' "$f")
+
+  # Detect workflow type (stepped vs phased)
+  # Stepped workflows have .workflow.type == "stepped" or .workflow.steps
+  workflow_type=$(yq eval '.workflow.type // "phased"' "$f")
+  has_steps=$(yq eval '.workflow.steps != null' "$f")
+
+  if [[ "$has_steps" == "true" ]] || [[ "$workflow_type" == "stepped" ]]; then
+    type_col="stepped"
+    # Count step files if steps.path is defined
+    steps_path=$(yq eval '.workflow.steps.path // ""' "$f")
+    steps_pattern=$(yq eval '.workflow.steps.pattern // "step-*.md"' "$f")
+    if [[ -n "$steps_path" ]] && [[ -d "$PROJECT_ROOT/$steps_path" ]]; then
+      step_count=$(find "$PROJECT_ROOT/$steps_path" -name "$steps_pattern" 2>/dev/null | wc -l | tr -d ' ')
+      steps_col="${step_count} steps"
+    else
+      steps_col="-"
+    fi
+  else
+    type_col="phased"
+    # Count phases for phased workflows
+    phase_count=$(yq eval '.workflow.phases | length' "$f")
+    steps_col="${phase_count} phases"
+  fi
+
+  # Default column
+  if [[ "$is_default" == "true" ]]; then
+    default_col="yes"
+  else
+    default_col="no"
+  fi
+
+  # Modes column (for tri-modal workflows)
+  modes=$(yq eval '.workflow.modes.available // []' "$f")
+  if [[ "$modes" != "[]" ]] && [[ "$modes" != "null" ]]; then
+    # Format as comma-separated list
+    modes_col=$(yq eval '.workflow.modes.available | join(",")' "$f")
+  else
+    modes_col="-"
+  fi
+
+  echo "| $name | $type_col | $default_col | $steps_col | $modes_col | $desc |"
+done
+
+echo ""
+echo "**Legend:**"
+echo "- **phased**: Agent-driven workflow (SM → TEA → Dev → Reviewer)"
+echo "- **stepped**: Step-by-step guided workflow with progressive disclosure"
+echo ""
+echo "Use \`/workflow show <name>\` for workflow details."

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

@@ -0,0 +1,163 @@
+#!/bin/bash
+# Resume a stepped workflow from last completed step
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/resume-workflow.sh [name]
+#
+# If no name provided, detects from active session
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+SESSION_DIR="$PROJECT_ROOT/.session"
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+WORKFLOW_NAME="${1:-}"
+
+# If no name, try to detect from session
+if [[ -z "$WORKFLOW_NAME" ]]; then
+  # Look for workflow session files
+  SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-workflow-session.md" 2>/dev/null | head -1)
+
+  if [[ -z "$SESSION_FILE" ]]; then
+    echo "# Resume Stepped Workflow"
+    echo ""
+    echo "No active workflow session found."
+    echo ""
+    echo "Use \`/workflow start <name>\` to begin a new workflow."
+    exit 1
+  fi
+
+  # Extract workflow name from session
+  WORKFLOW_NAME=$(grep -E "^\*\*Workflow:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/\*\*Workflow:\*\* //' | tr -d ' ')
+
+  if [[ -z "$WORKFLOW_NAME" ]]; then
+    # Try extracting from filename
+    WORKFLOW_NAME=$(basename "$SESSION_FILE" | sed 's/-workflow-session.md//')
+  fi
+else
+  SESSION_FILE="$SESSION_DIR/${WORKFLOW_NAME}-workflow-session.md"
+fi
+
+if [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: No session found for workflow '$WORKFLOW_NAME'"
+  echo ""
+  echo "Use \`/workflow start $WORKFLOW_NAME\` to begin."
+  exit 1
+fi
+
+# Find workflow file
+WORKFLOW_FILE=""
+if [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml"
+elif [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml"
+else
+  echo "Error: Workflow definition '$WORKFLOW_NAME' not found"
+  exit 1
+fi
+
+WORKFLOW_DIR=$(dirname "$WORKFLOW_FILE")
+
+# Parse session state
+CURRENT_STEP=$(grep -E "^\- \*\*Current Step:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "1")
+MODE=$(grep -E "^\- \*\*Mode:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "create")
+STATUS=$(grep -E "^\- \*\*Status:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "in_progress")
+STEPS_COMPLETED=$(grep -E "^\- \*\*Steps Completed:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "[]")
+
+# Check if workflow is complete
+if [[ "$STATUS" == "completed" ]]; then
+  echo "# Workflow Complete: $WORKFLOW_NAME"
+  echo ""
+  echo "This workflow has already been completed."
+  echo ""
+  echo "To start a new session, delete the session file:"
+  echo "\`\`\`bash"
+  echo "rm \"$SESSION_FILE\""
+  echo "\`\`\`"
+  echo ""
+  echo "Then run \`/workflow start $WORKFLOW_NAME\`"
+  exit 0
+fi
+
+# Resolve steps path based on mode
+MODE_PATH=$(yq eval ".workflow.modes.$MODE // \"\"" "$WORKFLOW_FILE")
+if [[ -n "$MODE_PATH" && "$MODE_PATH" != "null" ]]; then
+  STEPS_PATH="$MODE_PATH"
+else
+  STEPS_PATH=$(yq eval '.workflow.steps.path' "$WORKFLOW_FILE")
+fi
+
+# Resolve relative path
+if [[ "$STEPS_PATH" == ./* ]]; then
+  STEPS_PATH="$WORKFLOW_DIR/${STEPS_PATH#./}"
+elif [[ "$STEPS_PATH" != /* ]]; then
+  STEPS_PATH="$PROJECT_ROOT/$STEPS_PATH"
+fi
+
+# Count steps
+STEP_COUNT=$(find "$STEPS_PATH" -maxdepth 1 -name "step-0*.md" -o -name "step-1*.md" 2>/dev/null | wc -l | tr -d ' ')
+
+# Find the current step file
+# Handle various naming: step-01.md, step-01-name.md, step-1-name.md
+PADDED_STEP=$(printf "%02d" "$CURRENT_STEP")
+STEP_FILE=$(find "$STEPS_PATH" -maxdepth 1 \( -name "step-${PADDED_STEP}*.md" -o -name "step-${CURRENT_STEP}-*.md" \) 2>/dev/null | sort | head -1)
+
+if [[ -z "$STEP_FILE" ]]; then
+  echo "Error: Could not find step $CURRENT_STEP file in $STEPS_PATH"
+  exit 1
+fi
+
+# Update last updated timestamp
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+sed -i '' "s/^\- \*\*Last Updated:\*\*.*/- **Last Updated:** $NOW/" "$SESSION_FILE" 2>/dev/null || true
+
+# Calculate completion percentage
+COMPLETED_COUNT=$(echo "$STEPS_COMPLETED" | tr -cd ',' | wc -c | tr -d ' ')
+if [[ "$STEPS_COMPLETED" != "[]" ]]; then
+  COMPLETED_COUNT=$((COMPLETED_COUNT + 1))
+fi
+if [[ "$STEP_COUNT" -gt 0 ]]; then
+  COMPLETION_PCT=$((COMPLETED_COUNT * 100 / STEP_COUNT))
+else
+  COMPLETION_PCT=0
+fi
+
+# Output resume info
+echo "# Resuming Workflow: $WORKFLOW_NAME"
+echo ""
+echo "**Mode:** $MODE"
+echo "**Progress:** Step $CURRENT_STEP of $STEP_COUNT ($COMPLETION_PCT% complete)"
+echo "**Steps Completed:** $STEPS_COMPLETED"
+echo "**Session:** $SESSION_FILE"
+echo ""
+echo "---"
+echo ""
+echo "## Step $CURRENT_STEP of $STEP_COUNT"
+echo ""
+
+# Output step content (strip frontmatter if present)
+if head -1 "$STEP_FILE" | grep -q "^---$"; then
+  awk '/^---$/{if(++c==2){p=1;next}}p' "$STEP_FILE"
+else
+  cat "$STEP_FILE"
+fi
+
+echo ""
+echo "---"
+echo ""
+echo "**Controls:**"
+echo "- \`C\` - Continue to next step"
+echo "- \`/workflow status\` - Check progress"