@pennyfarthing/core 9.2.0 → 9.3.0

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

@@ -1,121 +0,0 @@
----
-name: testing
-description: Test commands and patterns for TDD workflow. This skill should be used when running tests, debugging test failures, setting up test infrastructure, or writing new tests. Provides framework-agnostic patterns that projects customize.
----
-
-# Testing Skill
-
-<run>
-Main test commands for running the test suite:
-
-```bash
-just test              # If using just
-npm test               # If using npm
-go test ./...          # If using Go directly
-```
-
-These commands execute the full test suite and are the primary entry point for validating code changes.
-</run>
-
-<output>
-Test output varies by framework:
-
-- **Go tests:** Display pass/fail status for each test, summary of tests run, coverage reports (if enabled), and PASS/FAIL result code
-- **Node/npm tests (Vitest/Jest):** Shows test file results, individual test names, execution time, coverage percentages (if enabled), and pass/fail summary
-- **Just:** Delegates to underlying test runner, output depends on what test command is configured
-
-Output includes execution time and a final summary line indicating total tests passed/failed.
-</output>
-
-## When to Use This Skill
-
-- Running tests (backend, frontend, or all)
-- Debugging test failures
-- Setting up test containers/infrastructure
-- Writing new tests
-- Pre-commit verification
-- Understanding TDD workflow
-
-## TDD Workflow (RED → GREEN → REFACTOR)
-
-```
-1. TEA writes failing tests (RED)
-2. Dev implements code to pass tests (GREEN)
-3. Dev refactors while keeping tests GREEN
-4. Reviewer validates quality
-```
-
-## Quick Reference
-
-```bash
-# Setup test infrastructure (run once per session)
-# Project-specific: check your justfile or package.json
-
-# Run all tests
-just test              # If using just
-npm test               # If using npm
-go test ./...          # If using Go directly
-
-# Run specific test patterns
-just test-api -run "TestName"     # Go pattern
-npm test -- -t "test name"        # Jest/Vitest pattern
-```
-
-## Test Command Patterns
-
-### Go (Backend)
-
-```bash
-# Run all tests
-go test ./...
-
-# Run tests in specific package
-go test ./internal/handlers
-
-# Run tests matching pattern
-go test -run "TestCreate" ./...
-
-# Verbose output
-go test -v ./internal/handlers
-
-# With coverage
-go test -cover ./...
-```
-
-### Node/React (Frontend)
-
-```bash
-# Run all tests (Vitest)
-npm test
-
-# Run tests matching pattern
-npm test -- -t "button"
-
-# Watch mode
-npm test -- --watch
-
-# Coverage
-npm test -- --coverage
-```
-
-## Test File Naming Conventions
-
-| Type | Go Pattern | TypeScript Pattern |
-|------|------------|-------------------|
-| Unit test | `*_test.go` | `*.test.ts`, `*.test.tsx` |
-| Integration | `*_integration_test.go` | `*.integration.test.ts` |
-| E2E | N/A | `*.e2e.test.ts` |
-
-## Reference Documentation
-
-- **Troubleshooting:** See `references/troubleshooting.md`
-- **TDD Policy:** See `references/tdd-policy.md` (project-specific)
-- **Backend Patterns:** See `references/backend-patterns.md` (project-specific)
-- **Frontend Patterns:** See `references/frontend-patterns.md` (project-specific)
-
-## Project Customization
-
-Projects should create their own testing skill in `.claude/project/skills/testing/` with:
-- Project-specific test commands
-- Custom patterns and conventions
-- Infrastructure setup instructions

package/pennyfarthing-dist/skills/testing/references/troubleshooting.md

@@ -1,124 +0,0 @@
-# Test Troubleshooting Guide
-
-## Tests Timing Out
-
-```bash
-# Ensure test infrastructure is running
-just test-setup        # Or project-specific setup command
-
-# Check container status
-docker ps
-
-# Increase timeout if needed
-go test -timeout 60s ./...
-```
-
-## "No Tests to Run" Message
-
-### Go Tests
-
-The `-run` flag filters by **test function name**, not by file or domain:
-- `-run "User"` matches `TestUserCreate` but NOT `TestCreateAccount`
-- The pattern is a regex, case-sensitive
-
-```bash
-# Run ALL tests in a package (no name filter)
-go test ./internal/handlers/...
-
-# Run tests with "Create" in name in specific package
-go test -run "Create" ./internal/handlers
-```
-
-### JavaScript/TypeScript Tests
-
-The `-t` flag filters by test description:
-
-```bash
-# Run tests matching description
-npm test -- -t "should create user"
-
-# Run all tests in a file
-npm test -- path/to/file.test.ts
-```
-
-## Case Sensitivity
-
-### Go
-- `-run "User"` - Correct (matches TestUser...)
-- `-run "user"` - Won't match (Go regex is case-sensitive)
-
-### Jest/Vitest
-- `-t "user"` - Case-insensitive by default
-
-## Package/Path Format
-
-### Go
-```bash
-./internal/handlers      # Correct - relative with ./
-internal/handlers        # May not work without ./
-./internal/handlers/...  # Include subpackages
-```
-
-### Node
-```bash
-src/components           # Relative path
-./src/components         # Also works
-```
-
-## Tests Passing Locally but Failing in CI
-
-1. **Environment differences** - Check env vars
-2. **Race conditions** - Run tests multiple times locally
-3. **Database state** - Ensure clean state between tests
-
-```bash
-# Run full test suite to catch integration issues
-just test
-
-# Run tests with race detection (Go)
-go test -race ./...
-```
-
-## Container Issues
-
-```bash
-# Restart test containers
-docker-compose -f docker-compose.test.yml down
-docker-compose -f docker-compose.test.yml up -d
-
-# Check container logs
-docker logs <container-name>
-
-# Verify connectivity
-docker exec <container-name> pg_isready  # Postgres
-docker exec <container-name> redis-cli ping  # Redis
-```
-
-## Database Connection Errors
-
-```bash
-# Check environment variables
-echo $TEST_DATABASE_URL
-
-# Verify database is accepting connections
-psql $TEST_DATABASE_URL -c "SELECT 1"
-```
-
-## Common Patterns
-
-### Flaky Tests
-
-1. Check for timing dependencies
-2. Look for shared state between tests
-3. Ensure proper cleanup in teardown
-4. Consider using test isolation
-
-### Memory Issues
-
-```bash
-# Run with memory limit (Go)
-go test -memprofile mem.out ./...
-
-# Check for goroutine leaks
-go test -race ./...
-```

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

@@ -1,141 +0,0 @@
----
-name: theme
-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
-
-<run>
-To manage persona themes, use the following commands:
-- `/list-themes` - List all available themes
-- `/show-theme` - Show current theme or specific theme details
-- `/set-theme <name>` - Set the active theme
-- `/theme-maker` - Create a new custom theme interactively
-</run>
-
-<output>
-Theme commands return theme names, descriptions, agent mappings, and confirmation of theme changes. Current theme is stored in `.pennyfarthing/config.local.yaml`.
-</output>
-
-## Overview
-
-Pennyfarthing uses themed personas to give each agent a unique character. This skill provides commands to list, view, and change themes.
-
-## Quick Reference
-
-| Action | Command |
-|--------|---------|
-| List all themes | `/list-themes` or see below |
-| Show current theme | `/show-theme` |
-| Show specific theme | `/show-theme <name>` |
-| Set active theme | `/set-theme <name>` |
-| Create new theme | `/theme-maker` (interactive) |
-
-## List Available Themes
-
-To see all available themes:
-
-```bash
-ls pennyfarthing-dist/personas/themes/*.yaml | xargs -I{} basename {} .yaml | sort
-```
-
-To show the current theme:
-
-```bash
-cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "No theme configured"
-```
-
-## Show Theme Details
-
-To display a theme's agent mappings:
-
-```bash
-# Show current theme
-THEME=$(cat .pennyfarthing/config.local.yaml 2>/dev/null | grep "^theme:" | cut -d'"' -f2)
-cat pennyfarthing-dist/personas/themes/${THEME}.yaml
-```
-
-Or for a specific theme:
-
-```bash
-cat pennyfarthing-dist/personas/themes/<theme-name>.yaml
-```
-
-## Set Active Theme
-
-To change the active theme:
-
-1. Verify theme exists:
-   ```bash
-   ls pennyfarthing-dist/personas/themes/<name>.yaml
-   ```
-
-2. Read current config:
-   ```bash
-   cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "FILE_NOT_FOUND"
-   ```
-
-3. Update `.pennyfarthing/config.local.yaml`:
-   - If file exists with `theme:` line: Use Edit tool to replace `theme: <old>` with `theme: <new>`
-   - If file missing or no theme line: Use Write tool to create:
-     ```yaml
-     # Pennyfarthing Local Configuration
-     theme: <name>
-     ```
-
-4. Verify the write succeeded:
-   ```bash
-   cat .pennyfarthing/config.local.yaml
-   ```
-
-5. Start a new agent session to use the new theme
-
-## Theme File Locations
-
-| Location | Purpose |
-|----------|---------|
-| `pennyfarthing-dist/personas/themes/` | Built-in themes (96+) |
-| `.claude/pennyfarthing/themes/` | User-created custom themes |
-| `.pennyfarthing/config.local.yaml` | Theme selection (agent-writable, gitignored) |
-
-## Theme Structure
-
-Each theme YAML defines agents with:
-
-```yaml
-theme:
-  name: theme-name
-  description: Brief description
-
-agents:
-  sm:
-    character: Character Name
-    style: Communication style description
-    quote: Signature quote
-    trait: Key personality trait
-    helper: Helper/assistant description
-  tea:
-    # ...same structure...
-  dev:
-    # ...
-```
-
-## Creating Custom Themes
-
-For creating new themes, use `/theme-maker` which provides:
-- **AI-Driven Mode**: Describe a concept, AI generates all personas
-- **Guided Mode**: Pick from AI-suggested characters
-- **Manual Mode**: Specify every detail yourself
-
-See the `theme-creation` skill for full documentation.
-
-## Common Theme Categories
-
-Themes are available across many categories:
-- **TV/Film**: star-trek-tos, star-trek-tng, breaking-bad, the-wire, firefly, etc.
-- **Literature**: shakespeare, jane-austen, dickens, discworld, dune, etc.
-- **Historical**: ancient-philosophers, military-commanders, renaissance-masters, etc.
-- **Mythology**: greek-mythology, norse-mythology, arthurian-mythos, etc.
-- **Animated**: futurama, the-simpsons, avatar-the-last-airbender, etc.
-
-Run the list command to see all 96+ available themes.

package/pennyfarthing-dist/skills/theme-creation/SKILL.md

@@ -1,178 +0,0 @@
----
-name: theme-creation
-description: Create custom persona themes for Pennyfarthing. Use when users want to create, generate, or customize agent personas/themes, especially with AI-driven generation.
----
-
-# Theme Creation Skill
-
-<run>/theme-maker</run>
-
-<output>Interactive wizard that guides users through AI-driven, Guided, or Manual theme creation modes to build custom persona themes for Pennyfarthing agents</output>
-
-## Overview
-
-This skill covers creating custom persona themes for Pennyfarthing agents. Themes define how each agent (SM, TEA, Dev, Reviewer, etc.) presents themselves with character names, styles, quotes, and personality traits.
-
-## When to Use This Skill
-
-**Invoke `/theme-maker` when the user:**
-- Asks to "create a theme" or "make a theme"
-- Wants "AI-driven theme generation"
-- Says "generate personas" or "generate characters"
-- Mentions a fictional universe and wants agents based on it
-- Asks for "custom personas" or "themed agents"
-- Wants to "customize agent characters"
-- Mentions any fictional universe + "theme" (e.g., "Star Wars theme", "pirates theme")
-
-**Trigger phrases:**
-- "create a [X] theme"
-- "make a theme based on [X]"
-- "generate [X] personas"
-- "I want [X] themed agents"
-- "AI-driven theme generation"
-- "custom theme for [universe]"
-
-## Available Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/theme-maker` | Interactive wizard with AI-driven, Guided, or Manual modes |
-| `/create-theme <name>` | Quick CLI-based theme creation (copies from base) |
-| `/set-theme <name>` | Activate an existing theme |
-| `/list-themes` | Show available themes |
-| `/show-theme <name>` | Display theme details |
-
-## Theme Creation Modes
-
-### AI-Driven Mode (Recommended)
-
-Best for: Users who describe a concept and want the AI to generate everything.
-
-**Flow:**
-1. User provides universe/concept (e.g., "Gilligan's Island, humorous")
-2. AI generates all 10 agent personas automatically
-3. User previews and confirms or regenerates
-4. Theme file written to `.claude/pennyfarthing/themes/`
-
-**What gets generated:**
-- Character names fitting the universe
-- OCEAN personality profiles (O/C/E/A/N scores 1-5)
-- Communication styles
-- Signature quotes
-- Emojis and visual descriptions
-- Helper assistants for each agent
-
-### Guided Mode
-
-Best for: Users who want to pick characters from suggestions.
-
-**Flow:**
-1. User provides universe/concept
-2. AI suggests 3-4 character options per agent
-3. User picks (or enters custom) for each
-4. AI fills in remaining details (style, quote, OCEAN)
-
-### Manual Mode
-
-Best for: Users who know exactly what they want.
-
-**Flow:**
-1. User provides theme description
-2. User enters character, style, quote for each agent
-3. Optional: Specify OCEAN scores or let AI generate
-4. Theme file created with user's exact specifications
-
-## Agent Roles Reference
-
-When generating or suggesting characters, match to these roles:
-
-| Agent | Role | Character Should Be |
-|-------|------|---------------------|
-| orchestrator | Meta-coordinator | Pattern-seer, guide, overseer |
-| sm | Scrum Master | Leader, coordinator, keeps team together |
-| tea | Test Engineer | Analyst, detail-oriented, finds flaws |
-| dev | Developer | Builder, practical, gets things done |
-| reviewer | Code Reviewer | Critical, honest, high standards |
-| architect | System Architect | Big-picture thinker, systems designer |
-| pm | Product Manager | Strategic, stakeholder manager |
-| tech-writer | Documentation | Clear communicator, precise |
-| ux-designer | UX Design | User advocate, feels the experience |
-| devops | Infrastructure | Reliable, keeps systems running |
-
-## Theme File Location
-
-- **User themes:** `.claude/pennyfarthing/themes/{name}.yaml`
-- **Built-in themes:** `pennyfarthing-dist/personas/themes/`
-
-## OCEAN Personality Profiles
-
-Each agent gets an OCEAN profile (Big Five personality traits):
-
-| Dimension | Low (1-2) | High (4-5) |
-|-----------|-----------|------------|
-| **O**penness | Traditional, practical | Creative, curious |
-| **C**onscientiousness | Flexible, spontaneous | Organized, disciplined |
-| **E**xtraversion | Reserved, reflective | Outgoing, energetic |
-| **A**greeableness | Competitive, skeptical | Cooperative, trusting |
-| **N**euroticism | Calm, stable | Emotional, reactive |
-
-## Examples
-
-### Example 1: AI-Driven Theme Creation
-
-**User:** "Create a Gilligan's Island theme, make it humorous"
-
-**Action:** Invoke `/theme-maker`, select AI-Driven mode, generate 10 agents based on the show's characters.
-
-### Example 2: Quick Theme from Base
-
-**User:** "Create a theme called my-team based on discworld"
-
-**Action:** Run `/create-theme my-team --base discworld`
-
-### Example 3: List and Switch Themes
-
-**User:** "What themes are available? Switch to star-trek."
-
-**Action:** Run `/list-themes`, then `/set-theme star-trek`
-
-## Validation Rules for Theme Names
-
-- Lowercase letters only
-- Must start with a letter
-- Hyphens allowed (no underscores or spaces)
-- No conflicts with existing themes
-
-## Portrait Generation
-
-Each agent can have a `visual` field that describes their appearance for portrait generation.
-
-**Generate all portraits for a theme:**
-```bash
-./scripts/generate-portraits.sh --theme {name}
-```
-
-**Generate a single agent's portrait:**
-```bash
-./scripts/generate-portraits.sh --theme {name} --role {role}
-```
-
-**Dry run (preview):**
-```bash
-./scripts/generate-portraits.sh --theme {name} --dry-run
-```
-
-**Requirements:**
-- Python 3 venv at `.venv/` with: `pip install diffusers transformers accelerate torch pillow pyyaml tqdm`
-- Apple Silicon Mac (MPS) or NVIDIA GPU (CUDA)
-- ~6.5GB model download on first run
-
-**Output:** `pennyfarthing-dist/personas/portraits/{theme}/{shortName}-{OCEAN}.png`
-
-## Post-Creation Steps
-
-After creating a theme:
-1. Theme file at `.claude/pennyfarthing/themes/{name}.yaml`
-2. Activate with `/set-theme {name}`
-3. Generate portraits with `./scripts/generate-portraits.sh --theme {name}`
-4. Edit YAML directly for fine-tuning

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

@@ -1,91 +0,0 @@
-#!/bin/bash
-# List all available workflows with type indicators
-# Usage: .pennyfarthing/scripts/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 find-root.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/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."