@pennyfarthing/core 6.6.0

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

@@ -0,0 +1,169 @@
+---
+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
+
+## 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 portraits:**
+```bash
+python3 scripts/generate-portraits.py --theme {name}
+```
+
+**Dry run (preview):**
+```bash
+python3 scripts/generate-portraits.py --theme {name} --dry-run
+```
+
+**Requirements:**
+- Python 3 with diffusers, torch, pillow, pyyaml
+- Apple Silicon Mac (MPS) or NVIDIA GPU
+- ~6.5GB model download on first run
+
+**Output:** `pennyfarthing-dist/personas/portraits/{theme}/{role}.png` (100x100px woodcut style)
+
+## 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 `python3 scripts/generate-portraits.py --theme {name}`
+4. Edit YAML directly for fine-tuning

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

@@ -0,0 +1,160 @@
+---
+name: workflow
+description: List available workflows, show current workflow details, and switch workflows mid-session if needed. Use for all workflow-related operations.
+---
+
+# Workflow Management Skill
+
+## Overview
+
+Pennyfarthing uses YAML-defined workflows to control agent sequences. The default TDD workflow (SM → TEA → Dev → Reviewer) can be customized or replaced with alternative flows for documentation, debugging, devops, and more.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| List all workflows | `/workflow` |
+| Show current workflow | `/workflow show` |
+| Show specific workflow | `/workflow show <name>` |
+| Set active workflow | `/workflow set <name>` |
+
+## List Available Workflows
+
+To see all available workflows:
+
+```zsh
+for f in pennyfarthing-dist/workflows/*.yaml; do
+  name=$(grep "^  name:" "$f" | head -1 | cut -d: -f2 | tr -d ' "')
+  desc=$(grep "^  description:" "$f" | head -1 | cut -d: -f2- | sed 's/^ *//')
+  default=$(grep "default: true" "$f" >/dev/null && echo " (default)" || echo "")
+  echo "- $name$default: $desc"
+done
+```
+
+## Show Current Workflow
+
+To display the active workflow for the current session:
+
+```zsh
+# Get workflow from session file
+SESSION=$(ls .session/*-session.md 2>/dev/null | head -1)
+if [[ -n "$SESSION" ]]; then
+  WORKFLOW=$(grep "^workflow:" "$SESSION" | cut -d: -f2 | tr -d ' ')
+  PHASE=$(grep "^\*\*Phase:\*\*" "$SESSION" | sed 's/.*\*\* //')
+  echo "Current workflow: ${WORKFLOW:-tdd (default)}"
+  echo "Current phase: ${PHASE:-unknown}"
+fi
+```
+
+To show details of a specific workflow:
+
+```zsh
+cat pennyfarthing-dist/workflows/<name>.yaml
+```
+
+### Workflow Phase Visualization
+
+```zsh
+WORKFLOW_FILE="pennyfarthing-dist/workflows/<name>.yaml"
+echo "Phases:"
+grep -A1 "^    - name:" "$WORKFLOW_FILE" | grep -E "(name:|agent:)" | paste - - | while read line; do
+  name=$(echo "$line" | grep -o "name: [a-z]*" | cut -d: -f2 | tr -d ' ')
+  agent=$(echo "$line" | grep -o "agent: [a-z-]*" | cut -d: -f2 | tr -d ' ')
+  echo "  $name → $agent"
+done
+```
+
+## Set Active Workflow
+
+To switch workflows mid-session (use sparingly):
+
+1. Verify workflow exists:
+   ```zsh
+   ls pennyfarthing-dist/workflows/<name>.yaml
+   ```
+
+2. Update session file's workflow field:
+   ```zsh
+   # Edit .session/{story-id}-session.md
+   # Add or update: workflow: <name>
+   ```
+
+3. Continue with the new workflow's agent sequence
+
+**Note:** Switching workflows mid-session resets phase tracking. Only do this when the story requirements have fundamentally changed.
+
+## Workflow File Locations
+
+| Location | Purpose |
+|----------|---------|
+| `pennyfarthing-dist/workflows/` | Built-in workflows |
+| `.claude/workflows/` | User-created custom workflows (symlinked) |
+
+## Built-in Workflows
+
+### TDD (default for 3+ point features)
+
+```
+SM (setup) → TEA (red) → Dev (green) → Reviewer (review) → SM (finish)
+```
+
+- Full test-driven development cycle
+- TEA writes failing tests first
+- Dev implements to make tests pass
+- Triggers: `types: [feature, enhancement]`, `points.min: 3`
+
+### Trivial (for 1-2 point fixes)
+
+```
+SM (setup) → Dev (implement) → Reviewer (review) → SM (finish)
+```
+
+- Skips TEA phase for quick fixes
+- Dev ensures existing tests still pass
+- Triggers: `types: [chore, fix, refactor]`, `points.max: 2`
+
+## Creating Custom Workflows
+
+See `pennyfarthing-dist/guides/workflow-schema.md` for the full schema.
+
+Example documentation workflow:
+
+```yaml
+workflow:
+  name: docs
+  description: Documentation updates
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+    - name: write
+      agent: tech-writer
+      output: [documentation]
+    - name: review
+      agent: reviewer
+      gate:
+        type: approval
+    - name: finish
+      agent: sm
+
+  triggers:
+    types: [docs]
+    tags: [documentation]
+```
+
+## Routing Priority
+
+When multiple workflows match a story:
+
+1. **Explicit tag:** `workflow:docs` on story overrides everything
+2. **Trigger tags:** Story tags match workflow's `triggers.tags`
+3. **Type match:** Story type matches workflow's `triggers.types`
+4. **Points match:** Story points within `triggers.points` range
+5. **Default:** Workflow with `default: true`
+
+## Related
+
+- Workflow schema: `pennyfarthing-dist/guides/workflow-schema.md`
+- Workflow loader: `packages/core/src/workflow/workflow-loader.ts`
+- Workflow router: `packages/core/src/workflow/workflow-router.ts`

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

@@ -0,0 +1,264 @@
+---
+name: yq
+description: yq is a YAML processor. Use this skill when reading, modifying, or querying YAML files from the command line.
+---
+
+# yq - YAML Processor Skill
+
+## Overview
+
+`yq` is a lightweight and portable command-line YAML processor. It's like `jq` but for YAML. This skill covers the mikefarah/yq version (v4+).
+
+## Installation
+
+```bash
+# macOS
+brew install yq
+
+# Check version (should be v4+)
+yq --version
+```
+
+## Basic Operations
+
+### Read a Value
+
+```bash
+# Read a top-level key
+yq '.theme' config.yaml
+# Output: discworld
+
+# Read nested value
+yq '.agents.sm.character' personas.yaml
+# Output: Captain Carrot Ironfoundersson
+
+# Read with default if missing
+yq '.missing // "default"' config.yaml
+# Output: default
+```
+
+### Read Entire Section
+
+```bash
+# Get all properties of a key
+yq '.agents.sm' personas.yaml
+# Output: the entire sm object as YAML
+
+# Output as JSON
+yq -o json '.agents.sm' personas.yaml
+```
+
+### Check if Key Exists
+
+```bash
+# Returns "true" or "false"
+yq '.agents.sm | has("helper")' personas.yaml
+
+# Returns null if doesn't exist
+yq '.agents.missing' personas.yaml
+# Output: null
+```
+
+## Modifying YAML
+
+### In-Place Edit
+
+```bash
+# Edit file in place
+yq -i '.theme = "startrek"' config.yaml
+
+# Add a new key
+yq -i '.newkey = "value"' config.yaml
+
+# Delete a key
+yq -i 'del(.unwanted)' config.yaml
+```
+
+### Output to Stdout (Non-Destructive)
+
+```bash
+# Modify and output to stdout (file unchanged)
+yq '.count = 42' config.yaml
+
+# Pipe to new file
+yq '.theme = "newtheme"' config.yaml > new-config.yaml
+```
+
+## Common Patterns
+
+### Iterate Over Arrays
+
+```bash
+# List all items
+yq '.stories[]' sprint.yaml
+
+# Get specific field from each item
+yq '.stories[].title' sprint.yaml
+
+# Filter items
+yq '.stories[] | select(.status == "in-progress")' sprint.yaml
+```
+
+### Iterate Over Object Keys
+
+```bash
+# Get all agent names
+yq '.agents | keys' personas.yaml
+# Output:
+# - sm
+# - tea
+# - dev
+# - reviewer
+
+# Iterate with key-value
+yq '.agents | to_entries | .[] | .key + ": " + .value.character' personas.yaml
+```
+
+### Merge Files
+
+```bash
+# Merge two YAML files (second overwrites first)
+yq '. *= load("overrides.yaml")' base.yaml
+
+# Merge specific key
+yq '.agents.sm *= load("sm-overrides.yaml")' personas.yaml
+```
+
+### Extract to Environment Variables
+
+```bash
+# Export as shell variables
+eval $(yq -o shell '.database' config.yaml)
+# Creates: $host, $port, $name
+
+# Specific format
+yq '.theme' config.yaml | xargs -I{} echo "THEME={}"
+```
+
+## Working with Multi-Document YAML
+
+```bash
+# Select specific document (0-indexed)
+yq 'select(document_index == 0)' multi.yaml
+
+# Process all documents
+yq '... | select(has("kind"))' k8s-manifests.yaml
+```
+
+## String Operations
+
+```bash
+# Uppercase
+yq '.name | upcase' config.yaml
+
+# String contains
+yq '.agents | to_entries | .[] | select(.value.style | contains("honest"))' personas.yaml
+
+# String interpolation
+yq '"Theme is: " + .theme' config.yaml
+```
+
+## Conditional Logic
+
+```bash
+# If-then-else
+yq 'if .count > 10 then "many" else "few" end' config.yaml
+
+# Select with condition
+yq '.stories[] | select(.points >= 5)' sprint.yaml
+
+# Null coalescing
+yq '.optional // "default"' config.yaml
+```
+
+## Output Formats
+
+```bash
+# YAML (default)
+yq '.data' file.yaml
+
+# JSON
+yq -o json '.data' file.yaml
+
+# Properties format
+yq -o props '.data' file.yaml
+
+# CSV (for arrays)
+yq -o csv '.items' file.yaml
+```
+
+## Common Use Cases in Pennyfarthing
+
+### Read Persona Config
+
+```bash
+# Get current theme
+yq '.theme' .claude/persona-config.yaml
+
+# Get agent persona
+THEME=$(yq '.theme' .claude/persona-config.yaml)
+yq ".agents.sm" personas/themes/${THEME}.yaml
+```
+
+### Query Sprint Data
+
+```bash
+# Get current sprint stories
+yq '.stories[] | select(.status == "todo")' sprint/current-sprint.yaml
+
+# Count stories by status
+yq '[.stories[].status] | group_by(.) | map({(.[0]): length}) | add' sprint/current-sprint.yaml
+```
+
+### Update Session Files
+
+```bash
+# Update status in YAML frontmatter (if using YAML)
+yq -i '.status = "in-progress"' .session/current_work.yaml
+```
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Read value | `yq '.key' file.yaml` |
+| Read nested | `yq '.parent.child' file.yaml` |
+| Set value | `yq -i '.key = "value"' file.yaml` |
+| Delete key | `yq -i 'del(.key)' file.yaml` |
+| Array length | `yq '.array | length' file.yaml` |
+| Filter array | `yq '.array[] \| select(.field == "value")' file.yaml` |
+| Output JSON | `yq -o json '.' file.yaml` |
+| Merge files | `yq '. *= load("other.yaml")' base.yaml` |
+| Default value | `yq '.key // "default"' file.yaml` |
+
+## Troubleshooting
+
+### "null" Output
+
+The key doesn't exist. Use `// "default"` for fallback:
+```bash
+yq '.missing // "not found"' file.yaml
+```
+
+### Quotes in Output
+
+yq preserves YAML formatting. Use `-r` (raw) for unquoted strings:
+```bash
+yq -r '.theme' config.yaml
+```
+
+### Boolean as String
+
+YAML booleans (`true`/`false`) are parsed as booleans. Compare accordingly:
+```bash
+# CORRECT
+yq '.enabled == true' config.yaml
+
+# WRONG (comparing to string)
+yq '.enabled == "true"' config.yaml
+```
+
+## Reference
+
+- **Official Docs:** https://mikefarah.gitbook.io/yq/
+- **GitHub:** https://github.com/mikefarah/yq