@pennyfarthing/core 11.2.0 → 11.2.2

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-dist/workflows/tdd.yaml

@@ -1,7 +1,7 @@
 # TDD Workflow - Test-Driven Development
 # Default workflow for feature development in Pennyfarthing
 #
-# Flow: SM → TEA → Dev → Reviewer → SM
+# Flow: SM → TEA → Dev → TEA (verify) → Reviewer → SM
 # Scale routing: 1-2 pts use 'trivial' workflow instead
 
 workflow:
@@ -32,9 +32,18 @@ workflow:
         type: tests_pass
         condition: All tests passing, no skipped tests
 
+    - name: verify
+      agent: tea
+      input: [implementation, passing_tests]
+      output: [quality_verified]
+      gate:
+        file: gates/quality-pass
+        type: quality_pass
+        condition: Lint, typecheck, and all tests passing
+
     - name: review
       agent: reviewer
-      input: [implementation, passing_tests]
+      input: [implementation, passing_tests, quality_verified]
       output: [approval]
       gate:
         file: gates/approval

package/pennyfarthing_scripts/CLAUDE.md

@@ -184,16 +184,25 @@ Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--qui
 | `pf debug deadcode exports` | Unused TypeScript exports | `deadcode/cli.py` |
 | `pf debug healthscore analyze` | Composite health score | `healthscore/cli.py` |
 
-## Hooks (non-CLI)
-
-| File | Hook Type | Purpose |
-|------|-----------|---------|
-| `hooks.py` | PostToolUse | Main hook dispatcher |
-| `bellmode_hook.py` | PostToolUse | Bell mode message injection |
-| `pretooluse_hook.py` | PreToolUse | Permission and safety gates |
-| `schema_validation_hook.py` | PreToolUse:Write | Schema validation on file writes |
-| `welcome_hook.py` | PostToolUse | Welcome message on session start |
-| `patch_mode.py` | PostToolUse | Patch mode interrupt handling |
+## Hooks (`pf hooks`)
+
+All hooks are in `hooks/` subpackage, invoked via `pf hooks <name>`.
+
+| Command | Hook Type | Purpose |
+|---------|-----------|---------|
+| `pf hooks session-start` | SessionStart | Session setup, checkpoint, WheelHub, welcome |
+| `pf hooks session-stop` | Stop | Save checkpoint for cross-session continuity |
+| `pf hooks reflector-check` | Stop | Enforce CYCLIST reflector markers |
+| `pf hooks pre-edit-check` | PreToolUse | Block edits to protected files |
+| `pf hooks context-warning` | PreToolUse | Warn when context usage is high |
+| `pf hooks context-breaker` | PreToolUse | Block tool execution at critical context |
+| `pf hooks cyclist-pretooluse` | PreToolUse | Route approval through WheelHub |
+| `pf hooks schema-validation` | PreToolUse:Write | Validate session/skill/step schema |
+| `pf hooks bell-mode` | PostToolUse | Bell queue + tandem injection |
+| `pf hooks sprint-yaml` | PostToolUse | Validate sprint YAML (YAML 1.2) |
+| `pf hooks statusline` | statusLine | Render Claude Code status bar |
+
+Legacy shims (`bellmode_hook.py`, `pretooluse_hook.py`, etc.) re-export from `hooks/` for backward compat.
 
 ## Architecture
 

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: