@pennyfarthing/core 11.2.1 → 11.3.1

package/pennyfarthing-dist/skills/pf-theme/examples.md

@@ -4,54 +4,54 @@
 
 ```bash
 # List all available themes with tiers
-pf theme list
+pf.sh theme list
 
 # Show current theme
-pf theme show
+pf.sh theme show
 
 # Show specific theme
-pf theme show blade-runner
+pf.sh theme show blade-runner
 
 # Show full details (OCEAN, quirks, catchphrases)
-pf theme show blade-runner --full
-pf theme show fifth-element --full
+pf.sh theme show blade-runner --full
+pf.sh theme show fifth-element --full
 ```
 
 ## Changing Theme
 
 ```bash
 # Set theme
-pf theme set blade-runner
+pf.sh theme set blade-runner
 
 # Preview without changing
-pf theme set blade-runner --dry-run
+pf.sh theme set blade-runner --dry-run
 
 # Refresh agent persona after change
-pf agent start "sm"
+pf.sh agent start "sm"
 ```
 
 ## Creating Custom Themes
 
 ```bash
 # Create from current theme
-pf theme create my-team
+pf.sh theme create my-team
 
 # Create from specific base
-pf theme create my-team --base blade-runner
+pf.sh theme create my-team --base blade-runner
 
 # Create as user-level (available across projects)
-pf theme create my-team --user
+pf.sh theme create my-team --user
 
 # Create from specific base as user-level
-pf theme create my-team --base fifth-element --user
+pf.sh theme create my-team --base fifth-element --user
 
 # Preview
-pf theme create my-team --base blade-runner --dry-run
+pf.sh theme create my-team --base blade-runner --dry-run
 ```
 
 After creation:
 1. Edit the theme file to customize agents
-2. Run `pf theme set my-team` to activate
+2. Run `pf.sh theme set my-team` to activate
 
 ## Theme Maker (Interactive)
 
@@ -73,7 +73,7 @@ Specify character name, style, and quote for each agent. Skip agents for default
 ### After Creation
 ```bash
 # Activate the new theme
-pf theme set my-universe
+pf.sh theme set my-universe
 
 # Generate portraits (optional, requires GPU)
 ./scripts/generate-portraits.sh --theme my-universe

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

@@ -12,18 +12,18 @@ Manage persona themes for agent characters.
 
 | Command | CLI | Purpose |
 |---------|-----|---------|
-| `/theme` | `pf theme show` | Show current theme |
-| `/theme list` | `pf theme list` | List all available themes |
-| `/theme show [name]` | `pf theme show [name] [--full]` | Show theme details |
-| `/theme set <name>` | `pf theme set <name> [--dry-run]` | Set active theme |
-| `/theme create <name>` | `pf theme create <name> [--base X] [--user] [--dry-run]` | Create from base theme |
+| `/theme` | `pf.sh theme show` | Show current theme |
+| `/theme list` | `pf.sh theme list` | List all available themes |
+| `/theme show [name]` | `pf.sh theme show [name] [--full]` | Show theme details |
+| `/theme set <name>` | `pf.sh theme set <name> [--dry-run]` | Set active theme |
+| `/theme create <name>` | `pf.sh theme create <name> [--base X] [--user] [--dry-run]` | Create from base theme |
 | `/theme maker` | *(interactive wizard)* | AI-driven theme creation |
 
 ### After Setting a Theme
 
 Refresh the current agent persona:
 ```bash
-pf agent start "sm"
+pf.sh agent start "sm"
 ```
 Adopt the new character immediately.
 

package/pennyfarthing-dist/skills/pf-theme/usage.md

@@ -5,7 +5,7 @@
 ### List Themes
 
 ```bash
-pf theme list
+pf.sh theme list
 ```
 
 No arguments. Shows all available themes with:
@@ -17,7 +17,7 @@ Copy output into response text — Bash tool output may be collapsed in the UI.
 ### Show Theme
 
 ```bash
-pf theme show [NAME] [--full]
+pf.sh theme show [NAME] [--full]
 ```
 
 | Arg/Option | Required | Description |
@@ -30,7 +30,7 @@ Copy output into response text.
 ### Set Theme
 
 ```bash
-pf theme set <NAME> [--dry-run]
+pf.sh theme set <NAME> [--dry-run]
 ```
 
 | Arg/Option | Required | Description |
@@ -42,14 +42,14 @@ Updates `.pennyfarthing/config.local.yaml` with theme name and character map.
 
 After setting, refresh agent persona:
 ```bash
-pf agent start "sm"
+pf.sh agent start "sm"
 ```
 Adopt the new character immediately.
 
 ### Create Theme
 
 ```bash
-pf theme create <NAME> [--base <THEME>] [--user] [--dry-run]
+pf.sh theme create <NAME> [--base <THEME>] [--user] [--dry-run]
 ```
 
 | Arg/Option | Required | Description |

package/pennyfarthing-dist/skills/pf-workflow/examples.md

@@ -4,86 +4,86 @@
 
 ```bash
 # List all available workflows
-pf workflow list
+pf.sh workflow list
 
 # Show TDD workflow details
-pf workflow show tdd
+pf.sh workflow show tdd
 
 # Show current session's workflow
-pf workflow show
+pf.sh workflow show
 
 # Show trivial workflow
-pf workflow show trivial
+pf.sh workflow show trivial
 ```
 
 ## Checking State
 
 ```bash
 # Check current workflow state
-pf workflow check
-pf workflow check --json
+pf.sh workflow check
+pf.sh workflow check --json
 
 # Who owns the "review" phase in TDD?
-pf workflow phase-check tdd review
+pf.sh workflow phase-check tdd review
 # Returns: reviewer
 
 # Who owns the "implement" phase in trivial?
-pf workflow phase-check trivial implement
+pf.sh workflow phase-check trivial implement
 # Returns: dev
 
 # Get workflow type
-pf workflow type tdd
+pf.sh workflow type tdd
 # Returns: phased
 
-pf workflow type architecture
+pf.sh workflow type architecture
 # Returns: stepped
 
 # Emit handoff marker for Cyclist
-pf workflow handoff reviewer
+pf.sh workflow handoff reviewer
 ```
 
 ## Stepped Workflows (BikeLane)
 
 ```bash
 # Start architecture workflow in create mode (default)
-pf workflow start architecture
+pf.sh workflow start architecture
 
 # Start in validate mode
-pf workflow start architecture --mode validate
+pf.sh workflow start architecture --mode validate
 
 # Check progress
-pf workflow status
+pf.sh workflow status
 
 # Resume after interruption
-pf workflow resume
-pf workflow resume architecture
+pf.sh workflow resume
+pf.sh workflow resume architecture
 
 # Complete current step and advance
-pf workflow complete-step
-pf workflow complete-step architecture --step 3
+pf.sh workflow complete-step
+pf.sh workflow complete-step architecture --step 3
 ```
 
 ## Phase Repair
 
 ```bash
 # Preview phase fix
-pf workflow fix-phase 56-1 review --dry-run
+pf.sh workflow fix-phase 56-1 review --dry-run
 
 # Fix phase to review (after Dev completed)
-pf workflow fix-phase 56-1 review
+pf.sh workflow fix-phase 56-1 review
 
 # Fix phase to approved (after Reviewer approved)
-pf workflow fix-phase 56-1 approved
+pf.sh workflow fix-phase 56-1 approved
 
 # Using Jira key
-pf workflow fix-phase MSSCI-12190 approved
+pf.sh workflow fix-phase MSSCI-12190 approved
 ```
 
 ## Switching Workflow Mid-Session
 
 1. Verify the target workflow exists:
    ```bash
-   pf workflow show trivial
+   pf.sh workflow show trivial
    ```
 
 2. Edit the session file:
@@ -97,16 +97,16 @@ pf workflow fix-phase MSSCI-12190 approved
 ### Story upgraded from trivial to TDD
 ```bash
 # Check current state
-pf workflow check --json
+pf.sh workflow check --json
 # Edit session to change workflow from trivial to tdd
 # Fix phase to match where you are
-pf workflow fix-phase 56-1 red
+pf.sh workflow fix-phase 56-1 red
 ```
 
 ### Agent activated on wrong phase
 ```bash
 # Check who owns the current phase
-pf workflow phase-check tdd review
+pf.sh workflow phase-check tdd review
 # Returns: reviewer — hand off if you're not the reviewer
-pf workflow handoff reviewer
+pf.sh workflow handoff reviewer
 ```

package/pennyfarthing-dist/skills/pf-workflow/skill.md

@@ -15,18 +15,18 @@ Pennyfarthing uses YAML-defined workflows to control agent sequences. The defaul
 
 | Command | CLI | Purpose |
 |---------|-----|---------|
-| `/pf-workflow` or `/pf-workflow list` | `pf workflow list` | List all workflows |
-| `/pf-workflow show [name]` | `pf workflow show [name]` | Show workflow details |
+| `/pf-workflow` or `/pf-workflow list` | `pf.sh workflow list` | List all workflows |
+| `/pf-workflow show [name]` | `pf.sh workflow show [name]` | Show workflow details |
 | `/pf-workflow set <name>` | Edit session file `**Workflow:**` line | Switch workflow mid-session |
-| `/pf-workflow start <name>` | `pf workflow start <name> [--mode M]` | Start stepped workflow |
-| `/pf-workflow resume [name]` | `pf workflow resume [name]` | Resume interrupted workflow |
-| `/pf-workflow status` | `pf workflow status` | Show stepped workflow progress |
-| `/pf-workflow fix-phase <id> <phase>` | `pf workflow fix-phase <id> <phase> [--dry-run]` | Repair session phase |
-| Check workflow state | `pf workflow check [--json]` | Current story, phase, state |
-| Check phase owner | `pf workflow phase-check <workflow> <phase>` | Which agent owns a phase |
-| Get workflow type | `pf workflow type <workflow>` | phased/stepped/procedural |
-| Emit handoff marker | `pf workflow handoff <next-agent>` | CYCLIST handoff marker |
-| Complete step | `pf workflow complete-step [name] [--step N]` | Advance stepped workflow |
+| `/pf-workflow start <name>` | `pf.sh workflow start <name> [--mode M]` | Start stepped workflow |
+| `/pf-workflow resume [name]` | `pf.sh workflow resume [name]` | Resume interrupted workflow |
+| `/pf-workflow status` | `pf.sh workflow status` | Show stepped workflow progress |
+| `/pf-workflow fix-phase <id> <phase>` | `pf.sh workflow fix-phase <id> <phase> [--dry-run]` | Repair session phase |
+| Check workflow state | `pf.sh workflow check [--json]` | Current story, phase, state |
+| Check phase owner | `pf.sh workflow phase-check <workflow> <phase>` | Which agent owns a phase |
+| Get workflow type | `pf.sh workflow type <workflow>` | phased/stepped/procedural |
+| Emit handoff marker | `pf.sh workflow handoff <next-agent>` | CYCLIST handoff marker |
+| Complete step | `pf.sh workflow complete-step [name] [--step N]` | Advance stepped workflow |
 
 ### Built-in Workflows
 

package/pennyfarthing-dist/skills/pf-workflow/usage.md

@@ -5,7 +5,7 @@
 ### List Workflows
 
 ```bash
-pf workflow list
+pf.sh workflow list
 ```
 
 No arguments. Returns table of workflows with type, phases/steps count, modes, default flag, description.
@@ -13,7 +13,7 @@ No arguments. Returns table of workflows with type, phases/steps count, modes, d
 ### Show Workflow
 
 ```bash
-pf workflow show [NAME]
+pf.sh workflow show [NAME]
 ```
 
 | Arg | Required | Description |
@@ -31,7 +31,7 @@ Warning: Only do this when story requirements have fundamentally changed. Switch
 ### Start Stepped Workflow
 
 ```bash
-pf workflow start <NAME> [--mode <MODE>]
+pf.sh workflow start <NAME> [--mode <MODE>]
 ```
 
 | Arg/Option | Required | Description |
@@ -44,7 +44,7 @@ Creates a new session and begins at step 1.
 ### Resume Stepped Workflow
 
 ```bash
-pf workflow resume [NAME]
+pf.sh workflow resume [NAME]
 ```
 
 | Arg | Required | Description |
@@ -54,7 +54,7 @@ pf workflow resume [NAME]
 ### Workflow Status
 
 ```bash
-pf workflow status
+pf.sh workflow status
 ```
 
 No arguments. Shows current step, progress percentage, mode.
@@ -62,7 +62,7 @@ No arguments. Shows current step, progress percentage, mode.
 ### Fix Session Phase
 
 ```bash
-pf workflow fix-phase <STORY_ID> <TARGET_PHASE> [--dry-run]
+pf.sh workflow fix-phase <STORY_ID> <TARGET_PHASE> [--dry-run]
 ```
 
 | Arg/Option | Required | Description |
@@ -83,7 +83,7 @@ Updates `**Phase:**` field, `**Phase Started:**` timestamp, and handoff history
 ### Complete Step
 
 ```bash
-pf workflow complete-step [NAME] [--step N]
+pf.sh workflow complete-step [NAME] [--step N]
 ```
 
 | Arg/Option | Required | Description |
@@ -100,7 +100,7 @@ Advances session: increments step, updates completed list, recalculates percenta
 ### Check Workflow State
 
 ```bash
-pf workflow check [--json]
+pf.sh workflow check [--json]
 ```
 
 | Option | Description |
@@ -112,7 +112,7 @@ Returns current story ID, phase, workflow, and state.
 ### Check Phase Owner
 
 ```bash
-pf workflow phase-check <WORKFLOW_NAME> <PHASE>
+pf.sh workflow phase-check <WORKFLOW_NAME> <PHASE>
 ```
 
 | Arg | Required | Description |
@@ -125,7 +125,7 @@ Returns the agent name that owns the phase.
 ### Get Workflow Type
 
 ```bash
-pf workflow type <WORKFLOW_NAME>
+pf.sh workflow type <WORKFLOW_NAME>
 ```
 
 | Arg | Required | Description |
@@ -137,7 +137,7 @@ Returns `phased`, `stepped`, or `procedural`.
 ### Emit Handoff Marker
 
 ```bash
-pf workflow handoff <NEXT_AGENT>
+pf.sh workflow handoff <NEXT_AGENT>
 ```
 
 | Arg | Required | Description |

package/pennyfarthing-dist/skills/skill-registry.yaml

@@ -216,6 +216,21 @@ skills:
     related_skills: []
     keywords: [grants, scopes, tools, runtime, security]
 
+  pf-settings:
+    name: pf-settings
+    description: View and manage .pennyfarthing/config.local.yaml settings
+    category: tools
+    tags: [configuration, settings, config]
+    version: "1.0.0"
+    command_group: settings
+    examples:
+      - context: View all settings
+        invocation: /pf-settings show
+      - context: Get a specific setting
+        invocation: /pf-settings get workflow.relay_mode
+    related_skills: [pf-theme, pf-bc]
+    keywords: [theme, relay, bell, permission, display, config]
+
   pf-persona-benchmark:
     name: pf-persona-benchmark
     description: Run benchmarks to compare persona effectiveness
@@ -243,15 +258,15 @@ skills:
     prerequisites: []
     examples:
       - context: Checking sprint status
-        invocation: /sprint
+        invocation: /pf-sprint
       - context: Finding available stories
-        invocation: /sprint backlog
+        invocation: /pf-sprint backlog
       - context: Adding a story
-        invocation: /sprint story add epic-76 "My story" 3
+        invocation: /pf-sprint story add epic-76 "My story" 3
       - context: Sizing guidelines
-        invocation: /sprint story size
+        invocation: /pf-sprint story size
       - context: Adding an epic
-        invocation: /sprint epic add epic-85 "New epic"
+        invocation: /pf-sprint epic add epic-85 "New epic"
     anti_patterns:
       - Don't manually edit sprint YAML - use scripts
     related_skills: [pf-jira]
@@ -278,7 +293,7 @@ skills:
 
   pf-story:
     name: pf-story
-    description: "DEPRECATED: Use /sprint story instead. Story commands consolidated under /sprint."
+    description: "DEPRECATED: Use /pf-sprint story instead. Story commands consolidated under /pf-sprint."
     category: project-management
     tags: [stories, sizing, workflow, deprecated]
     version: "2.0.0"
@@ -287,12 +302,12 @@ skills:
     prerequisites: []
     examples:
       - context: Creating new stories
-        invocation: /sprint story add
+        invocation: /pf-sprint story add
       - context: Sizing stories
-        invocation: /sprint story size
+        invocation: /pf-sprint story size
     anti_patterns:
       - Don't create stories without acceptance criteria
-      - Don't use /story directly - use /sprint story instead
+      - Don't use /story directly - use /pf-sprint story instead
     related_skills: [pf-sprint, pf-jira]
     keywords: [user-stories, estimation, points, acceptance-criteria]
 
@@ -324,15 +339,15 @@ skills:
     prerequisites: []
     examples:
       - context: Listing available themes
-        invocation: /theme list
+        invocation: /pf-theme list
       - context: Showing current theme
-        invocation: /theme show
+        invocation: /pf-theme show
       - context: Setting active theme
-        invocation: /theme set discworld
+        invocation: /pf-theme set discworld
       - context: Creating a new theme
-        invocation: /theme create my-theme --base discworld
+        invocation: /pf-theme create my-theme --base discworld
       - context: Interactive AI-driven theme wizard
-        invocation: /theme maker
+        invocation: /pf-theme maker
     anti_patterns:
       - Don't edit config.local.yaml directly - use skill
       - Don't use deprecated /set-theme, /show-theme, /list-themes, /create-theme, /theme-maker
@@ -341,7 +356,7 @@ skills:
 
   pf-theme-creation:
     name: pf-theme-creation
-    description: "DEPRECATED: Use /theme maker instead"
+    description: "DEPRECATED: Use /pf-theme maker instead"
     category: theming
     tags: [personas, themes, creation]
     version: "2.0.0"
@@ -350,7 +365,7 @@ skills:
     prerequisites: []
     examples:
       - context: Interactive theme wizard
-        invocation: /theme maker
+        invocation: /pf-theme maker
     anti_patterns: []
     related_skills: [pf-theme]
     keywords: [personas, custom, generation, wizard]
@@ -365,11 +380,11 @@ skills:
     prerequisites: []
     examples:
       - context: Listing available workflows
-        invocation: /workflow
+        invocation: /pf-workflow
       - context: Showing current workflow
-        invocation: /workflow show
+        invocation: /pf-workflow show
       - context: Starting stepped workflow
-        invocation: /workflow start architecture
+        invocation: /pf-workflow start architecture
     anti_patterns:
       - Don't switch workflows mid-story unless requirements fundamentally changed
     related_skills: [pf-sprint]

package/pennyfarthing-dist/templates/pyproject.toml

@@ -0,0 +1,27 @@
+# Auto-generated by pennyfarthing init — provides Python dependencies for hooks.
+# This file enables `uv run --project` to resolve pennyfarthing_scripts.
+# Safe to customize: init/update will not overwrite this file once created.
+
+[project]
+name = "pennyfarthing-scripts"
+version = "0.0.0"
+description = "Python utilities for Pennyfarthing agent orchestration"
+requires-python = ">=3.11"
+
+dependencies = [
+    "pyyaml>=6.0",
+    "ruamel.yaml>=0.18",
+    "httpx>=0.28",
+    "click>=8.0",
+    "pydriller>=2.6",
+]
+
+[project.scripts]
+pf = "pennyfarthing_scripts.cli:main"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["pennyfarthing_scripts*"]

package/pennyfarthing-dist/templates/settings.local.json.template

@@ -40,7 +40,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks session-start"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks session-start"
           }
         ]
       },
@@ -68,7 +68,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks reflector-check"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks reflector-check"
           }
         ]
       },
@@ -77,7 +77,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks session-stop"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks session-stop"
           }
         ]
       }
@@ -88,7 +88,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks bell-mode"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks bell-mode"
           }
         ]
       },
@@ -97,7 +97,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks sprint-yaml"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks sprint-yaml"
           }
         ]
       }
@@ -108,7 +108,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks pre-edit-check"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks pre-edit-check"
           }
         ]
       },
@@ -117,7 +117,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks schema-validation"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks schema-validation"
           }
         ]
       },
@@ -126,7 +126,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks context-warning"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks context-warning"
           }
         ]
       },
@@ -135,7 +135,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks context-breaker"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks context-breaker"
           }
         ]
       },
@@ -143,7 +143,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks cyclist-pretooluse"
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks cyclist-pretooluse"
           }
         ]
       }
@@ -151,6 +151,6 @@
   },
   "statusLine": {
     "type": "command",
-    "command": "pf hooks statusline"
+    "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/core/pf.sh hooks statusline"
   }
 }

package/pennyfarthing-dist/workflows/bdd-tandem.yaml

@@ -24,6 +24,10 @@ workflow:
     - name: setup
       agent: sm
       output: [session_file, branches, story_context]
+      gate:
+        file: gates/sm-setup-exit
+        type: sm_setup_exit
+        condition: Session file created with workflow, phase, context, and branch
 
     - name: design
       agent: ux-designer
@@ -54,9 +58,9 @@ workflow:
       input: [failing_tests, design_spec, story_context]
       output: [implementation, passing_tests]
       gate:
-        file: gates/tests-pass
-        type: tests_pass
-        condition: All tests passing, UX spec implemented
+        file: gates/dev-exit
+        type: dev_exit
+        condition: Tests green, tree clean, no debug code, correct branch
       tandem:
         partner: ux-designer
         scope: file-watch