@pennyfarthing/core 10.0.3 → 10.1.0

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

@@ -1,219 +1,27 @@
 ---
 name: story
 description: |
-  Story creation, sizing, and templates. Use when creating new stories,
-  determining story points, or getting the right template for bug/feature/refactor work.
-  For starting work on stories, use /sprint work instead.
+  DEPRECATED: Use /sprint story instead.
+  Story commands have been consolidated under /sprint.
 args: "[size|template|create|finish] [options]"
+deprecated: true
+redirect: sprint
 ---
 
-# /story - Story Management
+# /story - DEPRECATED
 
-Story creation and sizing utilities. For **starting work** on stories, use `/sprint work`.
+Story commands have been consolidated into `/sprint`. Use the new commands:
 
-## Commands
-
-### `/story size [points]`
-
-Display story sizing guidelines.
-
-<when>
-- Without argument: Show all sizing guidelines
-- With points: Show specific guidance for that point value
-</when>
-
-<run>
-.pennyfarthing/scripts/story/size-story.sh [points]
-</run>
-
-<example>
-.pennyfarthing/scripts/story/size-story.sh        # All guidelines
-.pennyfarthing/scripts/story/size-story.sh 3      # 3-point guidance
-.pennyfarthing/scripts/story/size-story.sh 13     # Split guidance
-</example>
-
-<output>
-Sizing characteristics, workflow suggestions, examples.
-</output>
-
----
-
-### `/story template [type]`
-
-Display story templates by type.
-
-<when>
-- Without argument: Show all templates
-- With type: Show specific template (bug, feature, refactor, chore)
-</when>
-
-<run>
-.pennyfarthing/scripts/story/story-template.sh [type]
-</run>
-
-<example>
-.pennyfarthing/scripts/story/story-template.sh           # All templates
-.pennyfarthing/scripts/story/story-template.sh bug       # Bug template
-.pennyfarthing/scripts/story/story-template.sh feature   # Feature template
-</example>
-
-<output>
-YAML template with acceptance criteria patterns.
-</output>
-
----
-
-### `/story create <epic-id> "<title>" <points> [options]`
-
-Generate a story YAML block for adding to sprint.
-
-<run>
-.pennyfarthing/scripts/story/create-story.sh <epic-id> "<title>" <points> [options]
-</run>
-
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `epic-id` | Yes | Parent epic (e.g., `MSSCI-11952`) |
-| `title` | Yes | Story title (quoted) |
-| `points` | Yes | Story points (1, 2, 3, 5, 8) |
-</args>
-
-<output>
-| Option | Values | Default | Description |
-|--------|--------|---------|-------------|
-| `--type` | bug, feature, refactor, chore | feature | Story type |
-| `--workflow` | (project-defined) | auto | Override auto-workflow |
-| `--priority` | P0, P1, P2, P3 | P2 | Priority level |
-| `--repos` | (project-defined) | - | Affected repos |
-| `--jira` | flag | - | Also show Jira create command |
-</output>
-
-<example>
-# Simple feature
-.pennyfarthing/scripts/story/create-story.sh MSSCI-11952 "Add error handling" 3
-
-# Bug fix
-.pennyfarthing/scripts/story/create-story.sh MSSCI-11952 "Fix null pointer" 2 --type bug
-
-# Chore with explicit workflow
-.pennyfarthing/scripts/story/create-story.sh MSSCI-11952 "Update deps" 1 --type chore
-
-# With Jira command
-.pennyfarthing/scripts/story/create-story.sh MSSCI-11952 "New feature" 5 --jira
-</example>
-
-<output>
-YAML block ready to paste into `sprint/current-sprint.yaml`
-</output>
-
----
-
-### `/story finish <story-id> [--dry-run]`
-
-Complete a story: archive session, merge PR, transition Jira, update sprint YAML.
-
-<critical>
-Prerequisites before running:
-- Session file exists at `.session/{story-id}-session.md`
-- PR is approved and mergeable
-- Reviewer has approved (phase: finish in session)
-</critical>
-
-<run>
-.pennyfarthing/scripts/workflow/finish-story.sh <story-id> [--dry-run]
-</run>
-
-<args>
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `story-id` | Yes | Story ID (e.g., `MSSCI-12052`) |
-| `--dry-run` | No | Show what would be done without executing |
-</args>
-
-<example>
-.pennyfarthing/scripts/workflow/finish-story.sh MSSCI-12052           # Finish story
-.pennyfarthing/scripts/workflow/finish-story.sh MSSCI-12052 --dry-run # Preview only
-</example>
-
-<output>
-1. Archives session file to `sprint/archive/{jira-key}-session.md`
-2. Squash merges PR and deletes remote branch
-3. Transitions Jira issue to Done
-4. Updates sprint YAML (status: done, completed date, removes assigned_to)
-5. Deletes local feature branch
-6. Removes session file
-
-Step-by-step progress with final summary and Jira link.
-</output>
-
----
-
-## Sizing Quick Reference
-
-| Points | Scale | Complexity | Examples |
-|--------|-------|------------|----------|
-| 1-2 | Trivial | Single file, minimal testing | Config, typo, simple fix |
-| 3 | Small | Few files, some testing | Validation, single component |
-| 5 | Medium | Multiple files, comprehensive testing | New page, API endpoint |
-| 8 | Large | Significant scope, extensive testing | Integration, major refactor |
-| 13+ | **SPLIT** | Too complex for single story | Break into smaller stories |
-
-## Workflow Selection
-
-Workflows define the development process for a story. Common patterns:
-
-| Workflow | When to Use |
-|----------|-------------|
-| `trivial` | Quick changes, no new tests needed |
-| `tdd` | Standard development with test coverage |
-| `agent-docs` | Documentation-focused work |
-| `bdd` | Behavior-driven development |
-
-<output>
-Auto-selection heuristics:
-- 1-2 point chores/bugs → `trivial`
-- 3+ point features → `tdd`
-- Documentation tasks → `agent-docs`
-</output>
-
-<when>
-Projects can define custom workflows in `pennyfarthing-dist/workflows/`.
-</when>
-
-## Acceptance Criteria Patterns
-
-### Good AC (SMART)
-
-<example>
-- "Admin users can access /admin/settings without 403"
-- "API returns 204 No Content on successful DELETE"
-- "Tests cover admin, manager, analyst roles"
-</example>
-
-### Bad AC (Vague)
-
-<critical>
-Avoid these patterns:
-- "Feature works correctly"
-- "No bugs"
-- "Good performance"
-</critical>
-
----
+| Old Command | New Command |
+|-------------|-------------|
+| `/story size [points]` | `/sprint story size [points]` |
+| `/story template [type]` | `/sprint story template [type]` |
+| `/story create <epic-id> ...` | `/sprint story add <epic-id> ...` |
+| `/story finish <story-id>` | `/sprint story finish <story-id>` |
 
 ## Related Skills
 
 | Skill | Purpose |
 |-------|---------|
-| `/sprint` | Sprint management, backlog, start work |
-| `/jira` | Jira operations (create in Jira, sync, claim) |
-| `/workflow` | View/set workflow definitions |
-
-## File Locations
-
-| File | Purpose |
-|------|---------|
-| `sprint/current-sprint.yaml` | Add new stories here |
-| `sprint/planning.yaml` | Future epics/stories |
-| `pennyfarthing-dist/workflows/` | Workflow definitions |
+| `/sprint` | All sprint, story, and epic operations |
+| `/jira` | Jira operations (create, sync, claim) |

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