@pennyfarthing/core 10.0.1 → 10.0.2

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

@@ -0,0 +1,121 @@
+---
+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

@@ -0,0 +1,124 @@
+# 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

@@ -0,0 +1,141 @@
+---
+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

@@ -0,0 +1,178 @@
+---
+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

@@ -0,0 +1,91 @@
+#!/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."