@pennyfarthing/core 11.2.1 → 11.2.2

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

@@ -243,15 +243,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 +278,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 +287,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 +324,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 +341,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 +350,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 +365,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/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-team.yaml

@@ -0,0 +1,89 @@
+# BDD Team Workflow - BDD with Native Team Collaboration
+#
+# When to use: Best for UI/UX-heavy stories where sustained parallel
+# collaboration during design and implementation provides more value than
+# periodic tandem consultation. Use this instead of bdd-tandem when the
+# designer-architect and dev-tester pairings need continuous interaction
+# throughout their respective phases.
+#
+# Compared to bdd-tandem: Tandem spawns a Haiku subagent for a single
+# request/response exchange. Team mode spawns full teammate sessions that
+# work in parallel with the lead for the entire phase duration.
+#
+# Team pairings:
+#   - DESIGN phase: UX-Designer (lead) + Architect — Architect validates
+#     technical feasibility of design decisions in real-time
+#   - GREEN phase: Dev (lead) + TEA — TEA verifies tests stay green and
+#     flags regressions as Dev implements
+#
+# Fallback: When native teams are unavailable (non-interactive mode, feature
+# flag off, or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set), phases with
+# team blocks fall back to solo execution. The lead agent works alone —
+# consider using bdd-tandem as an alternative that works in all modes.
+#
+# Flow: SM → UX-Designer (+Architect) → TEA → Dev (+TEA) → Reviewer → SM
+
+workflow:
+  name: bdd-team
+  description: BDD with native team collaboration — architect on design, TEA on green phase
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: design
+      agent: ux-designer
+      input: [session_file, story_context]
+      output: [design_spec, user_flows, wireframes, behavior_scenarios]
+      gate:
+        file: gates/design-review
+        type: design_review
+        condition: UX spec defines user flows and acceptance behaviors
+      team:
+        teammates:
+          - agent: architect
+            task: "Validate technical feasibility of design decisions. Flag constraints via SendMessage."
+
+    - name: red
+      agent: tea
+      input: [design_spec, behavior_scenarios, story_context]
+      output: [failing_tests]
+      gate:
+        file: gates/tests-fail
+        type: tests_fail
+        condition: Behavior scenarios have test coverage
+
+    - name: green
+      agent: dev
+      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
+      team:
+        teammates:
+          - agent: tea
+            task: "Verify tests stay green and flag regressions as Dev implements."
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests, design_spec]
+      output: [approval]
+      gate:
+        file: gates/approval
+        type: approval
+        condition: Code review approved, UX requirements met
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [team, bdd-team]
+    points:
+      min: 3
+    default: false

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-05-import-to-future.md

@@ -170,7 +170,7 @@ Display completion message:
 
 Next steps:
 - Use `/pf-sprint` to view the backlog
-- Use `pf sprint epic promote` to move to a sprint when ready
+- Use `pf.sh sprint epic promote` to move to a sprint when ready
 ```
 
 ## SUCCESS CRITERIA:

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-01-analyze.md

@@ -32,7 +32,7 @@ Build a complete picture of uncommitted changes across ALL repos defined in `.cl
 **CRITICAL: Use the multi-repo script, not plain `git status`.**
 
 ```bash
-pf git status
+pf.sh git status
 ```
 
 This shows branch, staged/unstaged changes, and unpushed commits for **all repos** defined in the project configuration.

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-04-verify.md

@@ -34,7 +34,7 @@ Git cleanup summary report including:
 ### 4.1 Final Git Status (All Repos)
 
 ```bash
-pf git status
+pf.sh git status
 ```
 
 Expected: Clean working directory in all repos, or only intentionally skipped files.

package/pennyfarthing-dist/workflows/git-cleanup/steps/step-05-complete.md

@@ -68,7 +68,7 @@ To run git-cleanup again:
 Or for a quick status check across all repos:
 
 ```bash
-pf git status
+pf.sh git status
 ```
 
 ---

package/pennyfarthing-dist/workflows/project-setup/steps/step-01-discover.md

@@ -20,6 +20,53 @@ Discover the project structure, detect repositories, identify tech stack, and ga
 - User-confirmed discovery ready for repos.yaml generation
 </output>
 
+## PRE-FLIGHT: Environment Check
+
+Before discovery, verify the environment is clean.
+
+### Check for Global `pf` Installation
+
+A globally installed `pf` CLI causes version drift between projects. All `pf`
+invocations should go through `uv run` via the shell shims in `.pennyfarthing/scripts/`.
+
+```bash
+# Check for global pf binary
+which pf 2>/dev/null
+```
+
+**If `which pf` returns a path**, the user has a stale global install. Guide them through removal:
+
+1. **Check the source** of the global install:
+   ```bash
+   which pf
+   head -3 "$(which pf)" 2>/dev/null
+   pip3 show pennyfarthing-scripts 2>/dev/null | grep -E "^(Version|Location|Editable)"
+   uv tool list 2>/dev/null | grep pennyfarthing
+   ```
+
+2. **Remove based on source:**
+
+   | Source | Command |
+   |--------|---------|
+   | `uv tool` | `uv tool uninstall pennyfarthing-scripts` |
+   | `pip` (Homebrew Python) | `pip3 uninstall pennyfarthing-scripts --break-system-packages -y` |
+   | `pip` (venv/system) | `pip3 uninstall pennyfarthing-scripts -y` |
+   | `pipx` | `pipx uninstall pennyfarthing-scripts` |
+
+3. **Verify removal:**
+   ```bash
+   hash -r  # Clear shell cache
+   which pf 2>/dev/null && echo "STILL INSTALLED — check for multiple installs" || echo "Clean"
+   ```
+
+4. **Explain to user:** Pennyfarthing hooks use `uv run` to resolve `pf` from the
+   local project's `pyproject.toml`. This ensures each project runs its own version
+   of the CLI without cross-project contamination. No global install is needed.
+
+**If `which pf` returns nothing**, the environment is clean — continue to discovery.
+
+---
+
 ## DISCOVERY TASKS
 
 ### 1. Detect Repository Structure

package/pennyfarthing-dist/workflows/tdd-team.yaml

@@ -0,0 +1,80 @@
+# TDD Team Workflow - TDD with Native Team Collaboration
+#
+# When to use: Best for 5+ point feature stories where sustained parallel
+# collaboration provides more value than periodic tandem consultation.
+# Use this instead of tdd-tandem when teammates need to work alongside the
+# lead for the full phase — e.g., Architect reviewing patterns as Dev
+# implements, not just answering a single question.
+#
+# Compared to tdd-tandem: Tandem spawns a Haiku subagent for a single
+# request/response exchange. Team mode spawns full teammate sessions that
+# work in parallel with the lead for the entire phase duration.
+#
+# Team pairings:
+#   - GREEN phase: Dev (lead) + Architect — Architect reviews implementation
+#     approach and patterns in real-time via SendMessage
+#   - REVIEW phase: Reviewer (lead) + Architect — Architect validates
+#     architectural patterns during code review
+#
+# Fallback: When native teams are unavailable (non-interactive mode, feature
+# flag off, or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set), phases with
+# team blocks fall back to solo execution. The lead agent works alone —
+# consider using tdd-tandem as an alternative that works in all modes.
+#
+# Flow: SM → TEA → Dev (+Architect) → Reviewer (+Architect) → SM
+
+workflow:
+  name: tdd-team
+  description: TDD with native team collaboration — architect pairing on green and review phases
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: red
+      agent: tea
+      input: [session_file, story_context]
+      output: [failing_tests]
+      gate:
+        file: gates/tests-fail
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        file: gates/tests-pass
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+      team:
+        teammates:
+          - agent: architect
+            task: "Review implementation approach and patterns. Send observations via SendMessage as Dev works."
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        file: gates/approval
+        type: approval
+        condition: Code review approved, no blocking issues
+      team:
+        teammates:
+          - agent: architect
+            task: "Validate architectural patterns and coupling. Flag concerns via SendMessage."
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [team, tdd-team]
+    points:
+      min: 5
+    default: false

package/pennyfarthing_scripts/__init__.py

@@ -14,4 +14,4 @@ Modules:
     swebench: SWE-bench patch parsing and scenario utilities
 """
 
-__version__ = "7.6.1"
+__version__ = "8.1.0"

package/pennyfarthing_scripts/bc/cli.py

@@ -34,7 +34,7 @@ from pennyfarthing_scripts.bc.focus import (
 def _get_current_layout() -> dict | None:
     """Fetch the current layout from a running Cyclist or BikeRack server.
 
-    Reads .wheelhub-port (shared by both Cyclist and BikeRack) and fetches
+    Reads .bikerack-port (shared by both Cyclist and BikeRack) and fetches
     the layout endpoint.
 
     Returns:
@@ -45,7 +45,7 @@ def _get_current_layout() -> dict | None:
     root = _get_root()
 
     candidates = [
-        (root / ".wheelhub-port", "/api/settings/bikerack-layout"),
+        (root / ".bikerack-port", "/api/settings/bikerack-layout"),
     ]
 
     for port_file, endpoint in candidates:

package/pennyfarthing_scripts/bellmode_hook.py

@@ -7,11 +7,8 @@ This file will be removed in a future version.
 # Re-export public API from new location for existing tests/imports
 from pennyfarthing_scripts.hooks.bell_mode import (  # noqa: F401
     _check_tandem_files as check_tandem_files,
-    _get_latest_observation as get_latest_observation,
-    _get_tandem_mtime as get_tandem_mtime,
-    _read_bell_queue as read_bell_queue,
-    _read_tandem_observations as read_tandem_observations,
-    _save_tandem_mtime as save_tandem_mtime,
+)
+from pennyfarthing_scripts.hooks.bell_mode import (
     main,
 )