@pennyfarthing/core 10.0.5 → 10.2.0

package/pennyfarthing-dist/commands/close-epic.md

@@ -2,138 +2,31 @@
 description: Close an epic - verify completion, update status, and archive context
 ---
 
-# Close Epic Workflow
+# Close Epic
 
-**This command closes an epic by verifying all stories are done, updating status, and optionally archiving context.**
+<purpose>
+Closes an epic after all stories are done. Updates sprint YAML, transitions Jira, archives context.
+Counterpart to `/start-epic`. Idempotent — safe to run multiple times.
+</purpose>
 
-## What This Does
-
-1. **Verifies** all stories in the epic are status: done
-2. **Updates** epic status to `done` and completed_points
-3. **Updates** sprint summary totals
-4. **Optionally** transitions Jira epic to Done
-5. **Optionally** archives the epic context file
-
-## Prerequisites
-
-- Epic must exist in current sprint
-- All stories should be done (will warn if not)
-
-## Usage
-
-Provide the epic ID when invoking this command:
-- `/close-epic 9` - Close epic 9
-- `/close-epic epic-9` - Also accepts epic-N format
-
-## Workflow Steps
-
-### Step 1: Identify Epic
-
-If no epic ID provided, ask:
-> "Which epic would you like to close? (e.g., 9 or epic-9)"
-
-Parse the epic ID (strip "epic-" prefix if present).
-
-### Step 2: Verify Epic Exists
-
-Read `sprint/current-sprint.yaml` and find the epic block:
-- `id: epic-{N}`
-
-If not found, error: "Epic not found in current sprint"
-
-### Step 3: Check Story Completion
-
-For each story in the epic:
-1. Check `status` field
-2. Count done vs not-done
-
-**If all done:** Proceed to close
-**If some not done:** Warn user with list of incomplete stories, ask to confirm
-
-### Step 4: Update Epic Status
-
-Update the epic in `sprint/current-sprint.yaml`:
-```yaml
-status: done
-completed_points: {total of all story points}
-```
-
-### Step 5: Update Sprint Summary
-
-Recalculate and update the summary section:
-- `completed_points`: Sum of all done story points across all epics
-- `remaining_points`: total_points - completed_points
-- Update notes to reflect epic completion
-
-### Step 6: Jira Transition (Optional)
-
-If epic has `jira_key`, use `/jira move` skill:
+<usage>
 ```bash
-# Check if Jira CLI available
-if command -v jira &> /dev/null; then
-    echo "Transition Jira epic to Done? (y/n)"
-    # If yes, use /jira move skill:
-    # jira issue move $JIRA_KEY "Done" --project MSSCI
-fi
+/close-epic 79        # Close epic 79
+/close-epic epic-79   # Also accepts epic-N format
 ```
-
-**Note:** Always use `/jira` skill commands - see `.claude/skills/jira/skill.md` for syntax.
-
-### Step 7: Archive Context (Optional)
-
-If `.session/context-epic-{N}.md` exists:
-```bash
-# Ask user
-echo "Archive epic context file? (y/n)"
-# If yes: mv .session/context-epic-{N}.md sprint/archive/
-```
-
-### Step 8: Confirm Closure
-
-```
-Epic {N} closed successfully
-
-Summary:
-- Stories: {count} done
-- Points: {points} completed
-- Jira: {transitioned/skipped/no-key}
-- Context: {archived/kept/not-found}
-
-Sprint progress: {completed}/{total} points ({percentage}%)
-```
-
-## Example
-
-```bash
-# User invokes: /close-epic 9
-
-# Output:
-# Checking epic-9...
-# Found: Skill Discovery & Documentation Hub
-# Stories: 5/5 done (13 points)
-#
-# Updating epic status to done...
-# Updating sprint summary (31/45 points)...
-#
-# Jira key found: MSSCI-11512
-# Transition to Done? (y/n): y
-# Transitioning MSSCI-11512 to Done...
-#
-# Context file found: .session/context-epic-9.md
-# Archive to sprint/archive/? (y/n): n
-# Keeping context file in place.
-#
-# Epic 9 closed successfully!
-# Sprint progress: 31/45 points (69%)
-```
-
-## Notes
-
-- This is the counterpart to `/start-epic`
-- Safe to run multiple times (idempotent)
-- Does NOT delete any data, only updates status
-- Context archival is optional and reversible
-
----
-
-**Flow:** TDD cycle complete all stories `/close-epic` update sprint
+</usage>
+
+<workflow>
+1. Parse epic ID (strip `epic-` prefix if present). Ask if not provided.
+2. Read epic shard `sprint/epic-{JIRA_KEY}.yaml`, verify all stories `status: done`. Warn if incomplete.
+3. Update epic: `status: done`, `completed_points: {sum of story points}`
+4. Recalculate sprint summary totals in `sprint/current-sprint.yaml`
+5. If epic has `jira:` key → `pf jira move {JIRA_KEY} "Done"`
+6. If `sprint/context/context-epic-{N}.md` exists → move to `sprint/archive/`
+7. Commit and push sprint changes
+</workflow>
+
+<related>
+- `/start-epic` — Start an epic (move to current sprint, generate context)
+- `/sprint status` — View sprint progress
+</related>

package/pennyfarthing-dist/commands/create-theme.md

@@ -1,29 +1,19 @@
 ---
-description: Create a new custom persona theme
+description: |
+  DEPRECATED: Use /theme create or /theme maker instead.
+  Theme commands have been consolidated under /theme.
+deprecated: true
+redirect: theme
 ---
 
-# Create Theme
+# /create-theme - DEPRECATED
 
-Create a new custom theme, optionally based on an existing theme.
+Theme commands have been consolidated into `/theme`. Use:
 
-## Arguments
-
-- `<name>` - Name for the new theme (lowercase, hyphens allowed)
-
-## Options
-
-- `--base <theme>` - Base theme to copy from (default: minimalist)
-- `--user` - Create as user-level theme (available across all projects)
-
-## Instructions
-
-1. If no theme name provided, ask the user what they want to call their theme.
-
-2. Create the theme:
-   ```bash
-   pennyfarthing theme create <name> [--base <theme>] [--user]
-   ```
-
-3. Guide the user on next steps:
-   - Edit the theme file to customize agents
-   - Run `/set-theme <name>` to activate
+| Old Command | New Command |
+|-------------|-------------|
+| `/create-theme <name>` | `/theme create <name>` |
+| `/theme-maker` | `/theme maker` |
+| `/list-themes` | `/theme list` |
+| `/show-theme [name]` | `/theme show [name]` |
+| `/set-theme <name>` | `/theme set <name>` |

package/pennyfarthing-dist/commands/dev.md

@@ -2,8 +2,16 @@
 description: Developer - Feature implementation and coding
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "dev"
+pf agent start "dev"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the Dev agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/devops.md

@@ -2,8 +2,16 @@
 description: DevOps Engineer - Infrastructure and deployment automation
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "devops"
+pf agent start "devops"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the DevOps agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/health-check.md

@@ -3,9 +3,7 @@ description: Check Pennyfarthing installation health and apply updates
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "devops"
+pf agent start "devops"
 ```
 
 <agent-activation>

package/pennyfarthing-dist/commands/help.md

@@ -132,14 +132,10 @@ SM → TEA → Dev → Reviewer → SM (finish)
 | `/prime` | Load essential project context at agent activation |
 | `/health-check` | Check Pennyfarthing installation health and apply updates |
 
-### Theme Management (5)
+### Theme Management (1)
 | Command | Description |
 |---------|-------------|
-| `/list-themes` | List all available persona themes |
-| `/show-theme` | Show details of a theme including all agent personas |
-| `/set-theme` | Set the active persona theme |
-| `/create-theme` | Create a new custom persona theme |
-| `/theme-maker` | Interactive wizard for creating custom persona themes |
+| `/theme [list\|show\|set\|create\|maker]` | Manage persona themes — list, show, set, create, or interactive wizard |
 
 ### Creative & Brainstorm (4)
 | Command | Description |
@@ -192,17 +188,17 @@ Pennyfarthing agents adopt personas from themed character sets. There are **102
 | `breaking-bad` | Breaking Bad characters |
 | `battlestar-galactica` | Battlestar Galactica characters |
 
-Run `/list-themes` to see all 102 available themes.
+Run `/theme list` to see all 102 available themes.
 
 ### Theme Commands
 
 | Command | Description |
 |---------|-------------|
-| `/list-themes` | See all available themes |
-| `/show-theme` | View current theme with character mappings |
-| `/set-theme <name>` | Change to a different theme |
-| `/create-theme` | Create a custom theme |
-| `/theme-maker` | Interactive theme creation wizard |
+| `/theme list` | See all available themes |
+| `/theme show [name]` | View current theme with character mappings |
+| `/theme set <name>` | Change to a different theme |
+| `/theme create <name>` | Create a custom theme |
+| `/theme maker` | Interactive theme creation wizard |
 
 ### Current Theme
 

package/pennyfarthing-dist/commands/list-themes.md

@@ -1,21 +1,19 @@
 ---
-description: List all available persona themes
+description: |
+  DEPRECATED: Use /theme list instead.
+  Theme commands have been consolidated under /theme.
+deprecated: true
+redirect: theme
 ---
 
-# List Themes
+# /list-themes - DEPRECATED
 
-Show all available persona themes with the current theme highlighted.
+Theme commands have been consolidated into `/theme`. Use:
 
-## Instructions
-
-Run the list-themes script and display the output directly to the user:
-
-```bash
-$CLAUDE_PROJECT_DIR/pennyfarthing-dist/scripts/list-themes.sh
-```
-
-**IMPORTANT:** Copy the script 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
+| Old Command | New Command |
+|-------------|-------------|
+| `/list-themes` | `/theme list` |
+| `/show-theme [name]` | `/theme show [name]` |
+| `/set-theme <name>` | `/theme set <name>` |
+| `/create-theme <name>` | `/theme create <name>` |
+| `/theme-maker` | `/theme maker` |

package/pennyfarthing-dist/commands/orchestrator.md

@@ -2,8 +2,16 @@
 description: Orchestrator - Coordinator of all agents and meta operations
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "orchestrator"
+pf agent start "orchestrator"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the Orchestrator agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/parallel-work.md

@@ -3,9 +3,7 @@ description: Start parallel work in a new worktree
 ---
 
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "sm"
+pf agent start "sm"
 ```
 
 <parallel-work-flow>

package/pennyfarthing-dist/commands/pm.md

@@ -2,8 +2,16 @@
 description: Product Manager - Strategic planning and prioritization
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "pm"
+pf agent start "pm"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the PM agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/prime.md

@@ -17,23 +17,23 @@ Automatically invoked on agent activation via `pf agent start`.
 
 ## Running /prime
 
-Use the Python CLI:
+Use the `pf` CLI:
 
 ```bash
 # Load all essential context (default)
-python3 -m pennyfarthing_scripts.cli agent start "sm"
+pf agent start "sm"
 
 # Minimal mode - fastest startup
-python3 -m pennyfarthing_scripts.cli agent start "sm" --minimal
+pf agent start "sm" --minimal
 
 # Full mode - include domain docs
-python3 -m pennyfarthing_scripts.cli agent start "sm" --full
+pf agent start "sm" --full
 
 # Skip persona loading
-python3 -m pennyfarthing_scripts.cli agent start "sm" --no-persona
+pf agent start "sm" --no-persona
 
 # JSON output (for Cyclist integration)
-python3 -m pennyfarthing_scripts.cli agent start "sm" --json
+pf agent start "sm" --json
 ```
 
 ## Options

package/pennyfarthing-dist/commands/reviewer.md

@@ -2,8 +2,16 @@
 description: Code Reviewer - Critical code review and quality enforcement
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "reviewer"
+pf agent start "reviewer"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the Reviewer agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/run-ci.md

@@ -111,6 +111,6 @@ If a required tool is not installed, the script will show a warning.
 </requirements>
 
 <reference>
-- **Script:** `.pennyfarthing/scripts/run-ci.sh`
+- **Script:** `.pennyfarthing/scripts/misc/run-ci.sh`
 - **Story:** 21-4 (Command & Skill Expansion)
 </reference>

package/pennyfarthing-dist/commands/set-theme.md

@@ -1,56 +1,19 @@
 ---
-description: Set the active persona theme
+description: |
+  DEPRECATED: Use /theme set instead.
+  Theme commands have been consolidated under /theme.
+deprecated: true
+redirect: theme
 ---
 
-# Set Theme
+# /set-theme - DEPRECATED
 
-Change the active persona theme for all agents.
+Theme commands have been consolidated into `/theme`. Use:
 
-## Arguments
-
-- `<name>` - Theme name to activate (required)
-
-## Instructions
-
-1. If no theme name provided, list available themes:
-   ```bash
-   ls pennyfarthing-dist/personas/themes/*.yaml | xargs -I{} basename {} .yaml | sort
-   ```
-   Then ask the user which theme they want to use.
-
-2. Validate theme exists:
-   ```bash
-   ls pennyfarthing-dist/personas/themes/<name>.yaml
-   ```
-   If not found, show error and list available themes.
-
-3. Read the current config file to prepare for editing:
-   ```bash
-   cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "FILE_NOT_FOUND"
-   ```
-
-4. Set the theme in `.pennyfarthing/config.local.yaml`:
-
-   **If the file exists and has a `theme:` line:**
-   - Use the Edit tool to replace `theme: <old>` with `theme: <new>`
-
-   **If the file doesn't exist or lacks the theme line:**
-   - Use the Write tool to create/overwrite the file:
-   ```yaml
-   # Pennyfarthing Local Configuration
-   # This file is gitignored - your personal preferences
-
-   theme: <name>
-   ```
-
-5. Verify the change was written:
-   ```bash
-   cat .pennyfarthing/config.local.yaml
-   ```
-   Confirm the theme line shows the new value.
-
-6. Refresh the current agent's persona to apply the new theme:
-   ```bash
-   python3 -m pennyfarthing_scripts.cli agent start "sm"
-   ```
-   This outputs the updated persona. **Adopt the new character immediately** - do not continue using the old persona.
+| Old Command | New Command |
+|-------------|-------------|
+| `/set-theme <name>` | `/theme set <name>` |
+| `/show-theme [name]` | `/theme show [name]` |
+| `/list-themes` | `/theme list` |
+| `/create-theme <name>` | `/theme create <name>` |
+| `/theme-maker` | `/theme maker` |

package/pennyfarthing-dist/commands/setup.md

@@ -1,3 +1,7 @@
+---
+description: /setup - Interactive Project Setup
+---
+
 # /setup - Interactive Project Setup
 
 <command>setup</command>
@@ -59,7 +63,7 @@ cat .pennyfarthing/workflows/project-setup/steps/step-01-discover.md
 
 <related>
 - `/sprint` - Sprint management after setup
-- `/theme` - Change themes after setup
+- `/theme set` - Change themes after setup
 - `/workflow` - View available workflows
 - `pennyfarthing doctor` - Validate installation
 </related>

package/pennyfarthing-dist/commands/show-theme.md

@@ -1,21 +1,19 @@
 ---
-description: Show details of a theme including all agent personas
+description: |
+  DEPRECATED: Use /theme show instead.
+  Theme commands have been consolidated under /theme.
+deprecated: true
+redirect: theme
 ---
 
-# Show Theme
+# /show-theme - DEPRECATED
 
-Display full details of a theme including all agent character mappings.
+Theme commands have been consolidated into `/theme`. Use:
 
-## Arguments
-
-- `[name]` - Theme name to show (optional, defaults to current theme)
-
-## Instructions
-
-Run the pennyfarthing CLI to show theme details:
-
-```bash
-pennyfarthing theme show [name]
-```
-
-Present the theme information clearly, showing each agent's character, style, and quote.
+| Old Command | New Command |
+|-------------|-------------|
+| `/show-theme [name]` | `/theme show [name]` |
+| `/set-theme <name>` | `/theme set <name>` |
+| `/list-themes` | `/theme list` |
+| `/create-theme <name>` | `/theme create <name>` |
+| `/theme-maker` | `/theme maker` |

package/pennyfarthing-dist/commands/sm.md

@@ -2,8 +2,16 @@
 description: Scrum Master - Story coordination and sprint management
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "sm"
+pf agent start "sm"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the SM agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/tea.md

@@ -2,8 +2,16 @@
 description: Test Engineer/Architect - Test strategy and TDD
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "tea"
+pf agent start "tea"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the TEA agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>

package/pennyfarthing-dist/commands/tech-writer.md

@@ -2,8 +2,16 @@
 description: Technical Writer - Documentation creation and maintenance
 ---
 
+<agent-activation>
+**FIRST:** Use Bash tool to run:
 ```bash
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
-python3 -m pennyfarthing_scripts.cli agent start "tech-writer"
+pf agent start "tech-writer"
 ```
+This loads your persona and agent context. Adopt the character shown in the output.
+</agent-activation>
+
+<instructions>
+You are now the Tech Writer agent. Follow your agent instructions from the activation output.
+
+The activation output begins with a `# Workflow State` section containing `state`, `story_id`, `phase`, `phase_owner`, and `backlog_count`. Act on this state per your agent definition.
+</instructions>