@pennyfarthing/core 10.0.5 → 10.2.0

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

@@ -1,107 +1,335 @@
 ---
 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.
+description: Manage persona themes - list available themes, show current/specific theme details, set active theme, create themes, and run the interactive theme maker wizard.
+args: "[list|show|set|create|maker] [options]"
 ---
 
 # 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
+Route based on arguments:
+- No args or `show` → Show current theme
+- `list` → List available themes
+- `show [name]` → Show theme details
+- `set <name>` → Set active theme
+- `create <name>` → Create theme from base
+- `maker` → Interactive AI-driven theme wizard
 </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) |
+| Invocation | CLI Command | Purpose |
+|------------|-------------|---------|
+| `/theme` | `pf theme show` | Show current theme |
+| `/theme list` | `pf theme list` | List all available themes |
+| `/theme show [name]` | `pf theme show [name]` | Show theme details |
+| `/theme show [name] --full` | `pf theme show [name] --full` | Extended details (OCEAN, quirks) |
+| `/theme set <name>` | `pf theme set <name>` | Set active theme |
+| `/theme create <name>` | `pf theme create <name>` | Create from base theme |
+| `/theme create <name> --base X` | `pf theme create <name> --base X` | Create from specific base |
+| `/theme create <name> --user` | `pf theme create <name> --user` | Create as user-level theme |
+| `/theme maker` | *(interactive wizard)* | AI-driven theme creation |
+
+---
 
-## List Available Themes
+## `/theme list`
 
-To see all available themes:
+Run `pf theme list` and display the output directly to the user.
 
 ```bash
-ls pennyfarthing-dist/personas/themes/*.yaml | xargs -I{} basename {} .yaml | sort
+pf theme list
 ```
 
-To show the current theme:
+**IMPORTANT:** Copy the command output into your response text so the user sees it in the console. Bash tool output may be collapsed in the UI.
+
+The output shows:
+- Current theme marked with `*`
+- Tier in brackets: `[S]` elite, `[A]` excellent, `[B]` strong, `[C]` good, `[D]` below average, `[U]` unbenchmarked
+
+---
+
+## `/theme show [name]`
 
 ```bash
-cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "No theme configured"
+# Show current theme
+pf theme show
+
+# Show specific theme
+pf theme show blade-runner
+
+# Show full details (OCEAN scores, quirks, catchphrases, helpers)
+pf theme show blade-runner --full
 ```
 
-## Show Theme Details
+**IMPORTANT:** Copy the command output into your response text so the user sees it in the console.
 
-To display a theme's agent mappings:
+---
+
+## `/theme set <name>`
 
 ```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
+pf theme set <name>
+```
+
+If no theme name provided, run `pf theme list` first, then ask the user which theme they want.
+
+After setting, refresh the current agent's persona:
+```bash
+pf agent start "sm"
 ```
+**Adopt the new character immediately** - do not continue using the old persona.
+
+---
+
+## `/theme create <name> [--base <theme>] [--user]`
 
-Or for a specific theme:
+Create a new custom theme by copying from a base.
 
 ```bash
-cat pennyfarthing-dist/personas/themes/<theme-name>.yaml
+# Create from default base (minimalist)
+pf theme create my-theme
+
+# Create from specific base
+pf theme create my-theme --base blade-runner
+
+# Create as user-level theme (available across all projects)
+pf theme create my-theme --user
 ```
 
-## Set Active Theme
+After creation, guide the user:
+- Edit the theme file to customize agents
+- Run `pf theme set <name>` to activate
+
+---
+
+## `/theme maker`
+
+Interactive wizard for creating custom persona themes with AI-driven generation. Unlike `/theme create` which copies from a base, this walks through the full creation process.
 
-To change the active theme:
+### Step 1: Theme Name
 
-1. Verify theme exists:
-   ```bash
-   ls pennyfarthing-dist/personas/themes/<name>.yaml
-   ```
+Ask the user for a theme name.
 
-2. Read current config:
-   ```bash
-   cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "FILE_NOT_FOUND"
-   ```
+**Validation rules:**
+- Lowercase letters only
+- Must start with a letter
+- Hyphens allowed (no underscores or spaces)
+- No conflicts with existing themes
+
+### Step 2: Mode Selection
+
+Use AskUserQuestion:
+
+```yaml
+questions:
+  - question: "How would you like to create your theme?"
+    header: "Mode"
+    options:
+      - label: "AI-Driven (Recommended)"
+        description: "Describe a concept or universe, I generate all 10 agent personas"
+      - label: "Guided"
+        description: "I suggest character options per agent, you pick"
+      - label: "Manual"
+        description: "You specify character, style, and quote for each agent"
+    multiSelect: false
+```
 
-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>
-     ```
+### Step 3: Dispatch to Mode
 
-4. Verify the write succeeded:
-   ```bash
-   cat .pennyfarthing/config.local.yaml
-   ```
+Based on selection, follow the appropriate mode below.
 
-5. Start a new agent session to use the new theme
+---
+
+### AI-Driven Mode
+
+Best for: Users who describe a concept and want the AI to generate everything.
+
+**Flow:**
+1. Ask for universe/concept description
+2. Generate all 10 agent personas
+3. Preview and confirm
+4. Write theme file
+5. Optionally generate portraits
+
+**For each agent, generate:**
+- `character`: Name fitting the universe
+- `shortName`: Display name for UI (see Short Name Generation below)
+- `visual`: Visual description for portrait generation (see Visual Descriptions below)
+- `ocean`: OCEAN personality profile (see Role-Appropriate OCEAN Profiles below)
+- `style`: 1-2 sentence communication style
+- `expertise`: Areas of expertise in the universe context
+- `role`: Role description within the universe
+- `trait`: Character traits
+- `quote`: Signature quote
+- `emoji`: Single representative emoji
+- `helper`: Assistant with name and communication style
+
+---
+
+### Guided Mode
+
+Best for: Users who want to pick characters from suggestions.
+
+**Flow:**
+1. Ask for universe/concept description
+2. For each agent, suggest 3-4 character options via AskUserQuestion
+3. Generate remaining details (style, OCEAN, quote, etc.) for selected characters
+4. Preview and confirm
+5. Write theme file
+
+**Agent Order:** orchestrator, sm, tea, dev, reviewer, architect, pm, tech-writer, ux-designer, devops
+
+---
+
+### Manual Mode
+
+Best for: Users who know exactly what they want.
+
+**Flow:**
+1. Ask for theme description
+2. For each agent, collect character name, style, and quote via free text
+3. Offer OCEAN auto-generation or manual entry
+4. Generate remaining fields (expertise, emoji, helper)
+5. Preview and confirm
+6. Write theme file
+
+**Skip Handling:** If user types "skip" for an agent, use defaults (generic role name, "Professional and direct" style).
+
+---
+
+## Agent Roles Reference
+
+| 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 |
+
+## Short Name Generation
+
+Priority for `shortName`:
+1. **Quoted nicknames first**: "Hannibal", "Starbuck" → use the nickname
+2. **Unique first name**: If unique among all characters in the theme
+3. **Unique surname**: If surname distinguishes the character
+4. **First + Last**: If needed for disambiguation
+5. **Iconic names**: Keep full for iconic two-word names (e.g., "Big Brother", "Sun Tzu")
+
+Skip titles like "Dr.", "Captain", "President" when extracting shortName.
+
+## Visual Descriptions
+
+The `visual` field provides a portrait prompt for `./scripts/generate-portraits.sh`.
+
+**Guidelines:**
+- Focus on physical appearance, distinctive features, and visual props
+- Include clothing, expression, and setting elements
+- Be specific and visual - describe what a portrait would show
+
+## Role-Appropriate OCEAN Profiles
+
+| Agent | Recommended Profile | Rationale |
+|-------|---------------------|-----------|
+| orchestrator | High O (4-5), Moderate C (3-4) | Pattern-seer needs openness |
+| sm | High A (4-5), Moderate C (3-4) | Coordination requires agreeableness |
+| tea | High C (4-5), High O (4-5) | Testing needs conscientiousness + creativity |
+| dev | High C (4-5), Moderate O (3-4) | Building needs discipline + problem-solving |
+| reviewer | High C (4-5), Low A (2-3) | Critical review prioritizes standards |
+| architect | High O (4-5), High C (4-5) | Design needs vision + structure |
+| pm | High E (4-5), High A (4-5) | Stakeholder mgmt needs sociability |
+| tech-writer | High C (4-5), Low N (1-2) | Documentation needs precision + calm |
+| ux-designer | High A (4-5), High O (4-5) | User advocacy needs empathy + creativity |
+| devops | High C (4-5), Low N (1-2) | Operations needs reliability |
+
+## Theme File Output
+
+Write to `.claude/pennyfarthing/themes/{name}.yaml`:
+
+```yaml
+# Custom theme: {name}
+# Created by /theme maker
+
+theme:
+  name: {Name}
+  description: "{description}"
+  source: "{source}"
+  default_emoji_use: minimal
+  default_humor: enabled
+  character_immersion: high
+  user_title: {title}
+  pennyfarthing_version: "{current version from VERSION file}"
+  created: {date}
+
+agents:
+  orchestrator:
+    character: {generated}
+    shortName: {generated}
+    visual: "{generated}"
+    ocean:
+      O: {1-5}  # {rationale}
+      C: {1-5}  # {rationale}
+      E: {1-5}  # {rationale}
+      A: {1-5}  # {rationale}
+      N: {1-5}  # {rationale}
+    style: {generated}
+    expertise: {generated}
+    role: {generated}
+    trait: {generated}
+    quote: "{generated}"
+    emoji: "{generated}"
+    helper:
+      name: {generated}
+      style: "{generated}"
+  # ... all 10 agents
+```
+
+**OCEAN Validation:** Before writing, verify:
+- All 10 agents have `ocean:` blocks with O, C, E, A, N keys
+- All scores are integers 1-5
+- Each score has a rationale comment
+
+**Important:** Read `VERSION` file at project root to set `pennyfarthing_version`.
+
+## Portrait Generation (Optional)
+
+After creating a theme, offer to generate portraits:
+
+```bash
+# Generate all portraits
+./scripts/generate-portraits.sh --theme {name}
+
+# Single agent
+./scripts/generate-portraits.sh --theme {name} --role {role}
+
+# Dry run preview
+./scripts/generate-portraits.sh --theme {name} --dry-run
+```
+
+**Requirements:** Python 3 venv with diffusers, transformers, accelerate, torch, pillow, pyyaml, tqdm. Apple Silicon (MPS) or NVIDIA GPU (CUDA).
+
+**Output:** `pennyfarthing-dist/personas/portraits/{theme}/{shortName}-{OCEAN}.png`
 
 ## Theme File Locations
 
 | Location | Purpose |
 |----------|---------|
 | `pennyfarthing-dist/personas/themes/` | Built-in themes (96+) |
-| `.claude/pennyfarthing/themes/` | User-created custom themes |
+| `.claude/pennyfarthing/themes/` | Project-level custom themes |
+| `~/.claude/pennyfarthing/themes/` | User-level custom themes |
 | `.pennyfarthing/config.local.yaml` | Theme selection (agent-writable, gitignored) |
 
 ## Theme Structure
 
-Each theme YAML defines agents with:
-
 ```yaml
 theme:
   name: theme-name
@@ -111,31 +339,18 @@ agents:
   sm:
     character: Character Name
     style: Communication style description
-    quote: Signature quote
     trait: Key personality trait
     helper: Helper/assistant description
+    ocean: { O: 3, C: 4, E: 2, A: 3, N: 2 }
+    quirks: [...]
+    catchphrases: [...]
   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.
+## Validation Rules for Theme Names
 
-Run the list command to see all 96+ available themes.
+- Lowercase letters only
+- Must start with a letter
+- Hyphens allowed (no underscores or spaces)
+- No conflicts with existing themes

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

@@ -1,178 +1,35 @@
 ---
 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.
+description: |
+  DEPRECATED: Use /theme maker instead.
+  Theme creation has been consolidated under /theme.
+deprecated: true
+redirect: theme
 ---
 
-# Theme Creation Skill
+# /theme-creation - DEPRECATED
 
-<run>/theme-maker</run>
+<run>
+This skill is deprecated. Use `/theme maker` instead.
+</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>
+<output>
+Redirects to the consolidated `/theme` skill.
+</output>
 
-## Overview
+Theme creation has been consolidated into the `/theme` skill. Use:
 
-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.
+| Old Command | New Command |
+|-------------|-------------|
+| `/theme-maker` | `/theme maker` |
+| `/create-theme <name>` | `/theme create <name>` |
 
-## 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
+The `/theme` skill now handles all theme operations:
 
 | 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
+| `/theme list` | List available themes |
+| `/theme show [name]` | Show theme details |
+| `/theme set <name>` | Set active theme |
+| `/theme create <name>` | Create from base theme |
+| `/theme maker` | Interactive AI-driven wizard |