@pennyfarthing/core 11.1.1 → 11.2.1

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

@@ -11,25 +11,22 @@ Pennyfarthing uses YAML-defined workflows to control agent sequences. The defaul
 
 ## Quick Reference
 
-### Shell Script Commands
-
-| Command | Script | Purpose |
-|---------|--------|---------|
-| `/pf-workflow` or `/pf-workflow list` | `.pennyfarthing/scripts/workflow/list-workflows.sh` | List all workflows |
-| `/pf-workflow show [name]` | `.pennyfarthing/scripts/workflow/show-workflow.sh [name]` | Show workflow details |
-| `/pf-workflow set <name>` | Edit session file `**Workflow:**` line | Switch workflow mid-session |
-| `/pf-workflow start <name>` | `.pennyfarthing/scripts/workflow/start-workflow.sh <name> [--mode M]` | Start stepped workflow |
-| `/pf-workflow resume [name]` | `.pennyfarthing/scripts/workflow/resume-workflow.sh [name]` | Resume interrupted workflow |
-| `/pf-workflow status` | `.pennyfarthing/scripts/workflow/workflow-status.sh` | Show stepped workflow progress |
-| `/pf-workflow fix-phase <id> <phase>` | `.pennyfarthing/scripts/workflow/fix-session-phase.sh <id> <phase> [--dry-run]` | Repair session phase |
-
 ### Python CLI Commands
 
 | 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 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 |
 
 ### Built-in Workflows
 

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

@@ -1,11 +1,11 @@
 # Workflow — Detailed Usage
 
-## Shell Script Commands
+## Commands
 
 ### List Workflows
 
 ```bash
-.pennyfarthing/scripts/workflow/list-workflows.sh
+pf 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
-.pennyfarthing/scripts/workflow/show-workflow.sh [NAME]
+pf 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
-.pennyfarthing/scripts/workflow/start-workflow.sh <NAME> [--mode <MODE>]
+pf 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
-.pennyfarthing/scripts/workflow/resume-workflow.sh [NAME]
+pf workflow resume [NAME]
 ```
 
 | Arg | Required | Description |
@@ -54,7 +54,7 @@ Creates a new session and begins at step 1.
 ### Workflow Status
 
 ```bash
-.pennyfarthing/scripts/workflow/workflow-status.sh
+pf 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
-.pennyfarthing/scripts/workflow/fix-session-phase.sh <STORY_ID> <TARGET_PHASE> [--dry-run]
+pf workflow fix-phase <STORY_ID> <TARGET_PHASE> [--dry-run]
 ```
 
 | Arg/Option | Required | Description |
@@ -80,9 +80,22 @@ Valid phases by workflow:
 
 Updates `**Phase:**` field, `**Phase Started:**` timestamp, and handoff history table.
 
+### Complete Step
+
+```bash
+pf workflow complete-step [NAME] [--step N]
+```
+
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Workflow name (auto-detects from session) |
+| `--step N` | No | Complete specific step number instead of current |
+
+Advances session: increments step, updates completed list, recalculates percentage.
+
 ---
 
-## Python CLI Commands
+## State & Phase Commands
 
 ### Check Workflow State
 
@@ -109,6 +122,18 @@ pf workflow phase-check <WORKFLOW_NAME> <PHASE>
 
 Returns the agent name that owns the phase.
 
+### Get Workflow Type
+
+```bash
+pf workflow type <WORKFLOW_NAME>
+```
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `WORKFLOW_NAME` | Yes | Workflow name (e.g., `tdd`, `architecture`) |
+
+Returns `phased`, `stepped`, or `procedural`.
+
 ### Emit Handoff Marker
 
 ```bash

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

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

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

@@ -1,14 +1,23 @@
 # BDD Tandem Workflow - BDD with Full Tandem Chain
-# Extends standard BDD with tandem observers:
-#   - Architect backseats UX-Designer during design
-#   - UX-Designer backseats Dev during implementation
-#   - PM backseats Reviewer during review
 #
-# Flow: SM → UX-Designer (+Architect) → TEA → Dev (+UX-Designer) → Reviewer (+PM) → SM
+# When to use: Best for UI/UX-heavy stories where designer-architect pairing
+# shapes implementation. Use this instead of base bdd when the story involves
+# complex user flows, new component patterns, or cross-domain UI integration.
+#
+# Tandem pairings:
+#   - DESIGN phase: UX-Designer + Architect (file-watch) — Architect validates technical feasibility
+#   - RED phase: TEA + Dev (file-watch) — Dev provides implementation context for test strategy
+#   - GREEN phase: Dev + UX-Designer (file-watch) — UX-Designer ensures design fidelity
+#   - REVIEW phase: Reviewer + PM (file-watch) — PM validates business requirements
+#
+# Compared to base bdd: Adds tandem observers on every working phase.
+# Designer-developer pairing ensures UX intent survives implementation.
+#
+# Flow: SM → UX-Designer (+Architect) → TEA (+Dev) → Dev (+UX-Designer) → Reviewer (+PM) → SM
 
 workflow:
   name: bdd-tandem
-  description: BDD with full tandem chain across design, implementation, and review
+  description: BDD with full tandem chain — designer and architect consultation across phases
   version: "1.0.0"
 
   phases:
@@ -36,6 +45,9 @@ workflow:
         file: gates/tests-fail
         type: tests_fail
         condition: Behavior scenarios have test coverage
+      tandem:
+        partner: dev
+        scope: file-watch
 
     - name: green
       agent: dev

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
-.pennyfarthing/scripts/git/git-status-all.sh
+pf 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
-.pennyfarthing/scripts/git/git-status-all.sh
+pf 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
-.pennyfarthing/scripts/git/git-status-all.sh
+pf git status
 ```
 
 ---

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

@@ -0,0 +1,65 @@
+# Review Tandem Workflow - TDD with Focused Architectural Review
+#
+# When to use: Best for stories that primarily need architectural review during
+# the review phase. Use this for large refactors (10+ pts), cross-cutting
+# infrastructure changes, or stories where an architect audit catches issues
+# that a standard code review might miss.
+#
+# Tandem pairings:
+#   - REVIEW phase: Reviewer + Architect (file-watch) — Architect provides
+#     focused architectural audit alongside standard code review
+#
+# Compared to base tdd: Same phase flow, but adds architect consultation
+# during review only. Lighter than tdd-tandem (no tandem on red/green phases).
+#
+# Flow: SM → TEA → Dev → Reviewer (+Architect) → SM
+
+workflow:
+  name: review-tandem
+  description: TDD with tandem architect consultation on review phase
+  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
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        file: gates/approval
+        type: approval
+        condition: Code review approved, architecture validated
+      tandem:
+        partner: architect
+        scope: file-watch
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    tags: [review-tandem, tandem]
+    points:
+      min: 8

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

@@ -1,14 +1,22 @@
 # TDD Tandem Workflow - TDD with Full Tandem Chain
-# Extends standard TDD with tandem observers on every phase:
-#   - Architect backseats TEA during red phase
-#   - TEA backseats Dev during green phase
-#   - PM backseats Reviewer during review phase
 #
-# Flow: SM → TEA (+Architect) → Dev (+TEA) → Reviewer (+PM) → SM
+# When to use: Best for 5+ point feature stories where architectural alignment
+# during implementation provides high value. Use this instead of base tdd when
+# the story involves cross-cutting concerns, new patterns, or complex integrations.
+#
+# Tandem pairings:
+#   - RED phase: TEA + Architect (file-watch) — Architect reviews test strategy
+#   - GREEN phase: Dev + Architect (file-watch) — Architect guides implementation patterns
+#   - REVIEW phase: Reviewer + PM (file-watch) — PM validates business requirements
+#
+# Compared to base tdd: Adds tandem observers on every working phase.
+# The extra context from partner agents helps catch architectural drift early.
+#
+# Flow: SM → TEA (+Architect) → Dev (+Architect) → Reviewer (+PM) → SM
 
 workflow:
   name: tdd-tandem
-  description: TDD with full tandem chain across all phases
+  description: TDD with full tandem chain — architect and PM consultation across phases
   version: "2.0.0"
 
   phases:
@@ -37,7 +45,7 @@ workflow:
         type: tests_pass
         condition: All tests passing, no skipped tests
       tandem:
-        partner: tea
+        partner: architect
         scope: file-watch
 
     - name: review
@@ -60,5 +68,5 @@ workflow:
   triggers:
     tags: [tandem]
     points:
-      min: 3
+      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

@@ -12,8 +12,9 @@ Python Click CLI for Pennyfarthing. Entry point: `pennyfarthing_scripts/cli.py`.
 | `pf bc` | Panel focus and layout management | `bc/cli.py` |
 | `pf validate` | Project validators | `validate/cli.py` |
 | `pf agent` | Agent session management | `cli.py` (inline) |
-| `pf workflow` | Workflow state and phase management | `cli.py` (inline) |
+| `pf workflow` | Workflow state and phase management | `workflow/cli.py` |
 | `pf bikerack` | BikeRack dashboard launcher | `bikerack/cli.py` |
+| `pf git` | Repository operations (status, branches, worktree, hooks) | `git_group/cli.py` |
 | `pf debug` | Analysis tools (hotspots, deadcode, healthscore) | `cli.py` (inline group) |
 
 ### Sugar Shortcuts
@@ -139,9 +140,17 @@ Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--qui
 
 | Command | Description | Source |
 |---------|-------------|--------|
-| `pf workflow check` | Current workflow state | `workflow.py` |
-| `pf workflow phase-check WORKFLOW PHASE` | Check phase owner | `workflow.py` |
-| `pf workflow handoff AGENT` | Emit handoff marker | `cli.py` (inline) |
+| `pf workflow check [--json]` | Current workflow state | `workflow/cli.py` |
+| `pf workflow phase-check WORKFLOW PHASE` | Check phase owner | `workflow/cli.py` |
+| `pf workflow handoff AGENT` | Emit handoff marker | `workflow/cli.py` |
+| `pf workflow type WORKFLOW` | Get workflow type (phased/stepped/procedural) | `workflow/cli.py` |
+| `pf workflow list` | List all available workflows | `workflow/cli.py` |
+| `pf workflow show [NAME]` | Show workflow details | `workflow/cli.py` |
+| `pf workflow start NAME [--mode M]` | Start stepped workflow | `workflow/cli.py` |
+| `pf workflow resume [NAME]` | Resume interrupted workflow | `workflow/cli.py` |
+| `pf workflow status [NAME]` | Show stepped workflow progress | `workflow/cli.py` |
+| `pf workflow fix-phase ID PHASE [--dry-run]` | Repair session phase | `workflow/cli.py` |
+| `pf workflow complete-step [NAME] [--step N]` | Complete current step | `workflow/cli.py` |
 
 ## pf bikerack
 
@@ -151,6 +160,19 @@ Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--qui
 | `pf bikerack stop` | Stop running instance | `bikerack/cli.py` |
 | `pf bikerack status` | Show running state | `bikerack/cli.py` |
 
+## pf git
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf git status [--brief]` | Check git status of all repos | `git/status_all.py` |
+| `pf git branches BRANCH [--repos all\|api\|ui]` | Create feature branches | `git/create_branches.py` |
+| `pf git cleanup` | Start git-cleanup workflow | `git_group/cli.py` |
+| `pf git worktree create NAME BRANCH` | Create worktree(s) | `git/worktree.py` |
+| `pf git worktree remove NAME` | Remove worktree | `git/worktree.py` |
+| `pf git worktree list` | List active worktrees | `git/worktree.py` |
+| `pf git worktree status` | Show worktree status | `git/worktree.py` |
+| `pf git install-hooks` | Install git hooks with .d/ dispatcher | `git/hooks_installer.py` |
+
 ## pf debug
 
 | Command | Description | Source |
@@ -162,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/bc/cli.py

@@ -34,8 +34,8 @@ from pennyfarthing_scripts.bc.focus import (
 def _get_current_layout() -> dict | None:
     """Fetch the current layout from a running Cyclist or BikeRack server.
 
-    Checks .bikerack-port first, then .cyclist-port, and fetches the
-    appropriate layout endpoint.
+    Reads .wheelhub-port (shared by both Cyclist and BikeRack) and fetches
+    the layout endpoint.
 
     Returns:
         Layout dict, or None if no server is running or fetch fails.
@@ -44,10 +44,8 @@ def _get_current_layout() -> dict | None:
 
     root = _get_root()
 
-    # Try BikeRack first (bikerack-layout), then Cyclist (layout)
     candidates = [
-        (root / ".bikerack-port", "/api/settings/bikerack-layout"),
-        (root / ".cyclist-port", "/api/settings/bikerack-layout"),
+        (root / ".wheelhub-port", "/api/settings/bikerack-layout"),
     ]
 
     for port_file, endpoint in candidates: