@pennyfarthing/core 11.2.1 → 11.2.2

package/pennyfarthing-dist/guides/agent-behavior.md

@@ -3,23 +3,28 @@
 
 **Tests:** Use `testing-runner` subagent, never run directly.
 
-**Handoff:** Run `pf handoff resolve-gate` → gate check → `pf handoff complete-phase` → `pf handoff marker` → EXIT. See `<agent-exit-protocol>`.
+**Handoff:** Run pf.sh `handoff resolve-gate` → gate check → pf.sh `handoff complete-phase` → pf.sh `handoff marker` → EXIT. See `<agent-exit-protocol>`.
 
 **Sidecars:** Write learnings BEFORE starting exit protocol.
 
 **Scripts:** Pennyfarthing scripts are Python-based (`pennyfarthing_scripts/`), not shell—check before assuming `.sh`.
+
+**pf CLI:** Never call bare `pf` — it is not globally installed. Always use the wrapper:
+```bash
+"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh <command> [args...]
+```
 </critical>
 
 <critical>
 **Story completion is MANDATORY.** A story is NOT done until:
 1. Reviewer approves and merges the PR
-2. SM runs `pf sprint story finish` (archive session, update Jira, clean up)
+2. SM runs pf.sh `sprint story finish` (archive session, update Jira, clean up)
 
 **Never** start new work while stories have open PRs. The merge gate blocks `/pf-sprint work` if open PRs exist.
 
 **If stuck in incomplete state:**
-- Open PRs? → Run `/reviewer` to complete reviews and merge
-- Merged but not finished? → Run `/sm` to trigger finish flow
+- Open PRs? → Run `/pf-reviewer` to complete reviews and merge
+- Merged but not finished? → Run `/pf-sm` to trigger finish flow
 </critical>
 
 ---
@@ -49,7 +54,7 @@ On activation, check session file for a `**Tandem:**` line (e.g., `**Tandem:** a
 
 **If tandem is configured:**
 
-1. **Resolve backseat persona** from theme using the `pf theme`
+1. **Resolve backseat persona** from theme using the `pf.sh theme`
    ```bash
    THEME=$(yq '.theme' .pennyfarthing/config.local.yaml)
    PARTNER_CHARACTER=$(yq ".agents.{PARTNER}.character" .pennyfarthing/personas/themes/${THEME}.yaml)
@@ -95,6 +100,51 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 
 ---
 
+<team-mode>
+## Team Mode Protocol
+
+When a workflow phase has a `team:` configuration block, the phase agent acts as
+**team lead** and spawns teammates for parallel collaboration within that phase.
+
+### Team Creation
+
+On phase entry, detect the `team:` block in workflow YAML. Use `TeamCreate`
+to create a phase-scoped team named after the phase (e.g., `"green-phase"`).
+
+### Teammate Spawning
+
+Spawn teammates via the Task tool with `team_name` parameter. Each teammate
+runs `pf agent start {agent}` for full Prime activation. Keep spawn prompts
+under 500 tokens — teammates auto-load CLAUDE.md, MCP servers, and skills.
+
+### Communication
+
+- **Inter-phase handoff:** Use Reflector markers (`<!-- CYCLIST:HANDOFF -->`)
+  for phase transitions — unchanged from sequential mode.
+- **Intra-phase collaboration:** Use `SendMessage` for real-time teammate
+  communication. Never use markers for intra-phase messaging.
+
+### Teammate Behavior
+
+Teammates know they are NOT the lead. They:
+- Communicate via SendMessage (DMs to lead or other teammates)
+- Go idle when their assigned task is complete
+- Respond to shutdown requests with shutdown_response
+
+### Cleanup Before Handoff
+
+Before starting the exit protocol, the lead MUST:
+1. Send `shutdown_request` to all teammates via SendMessage
+2. Wait for `shutdown_response` from each teammate
+3. Run `TeamDelete` to clean up the team
+4. Then proceed with normal handoff (resolve-gate → complete-phase → marker)
+
+Teams are **phase-scoped** — created at phase start, destroyed at phase end.
+Handoff between phases is unchanged.
+</team-mode>
+
+---
+
 ## Reflector
 
 <critical>
@@ -118,19 +168,20 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 
 1. Write assessment to session
 2. Terminate tandem backseat (if active)
-3. `pf handoff resolve-gate {story-id} {workflow} {phase}` → RESOLVE_RESULT
-4. If blocked → report error, STOP
-5. If skip → jump to step 7
-6. If ready → spawn gate subagent with gate file → GATE_RESULT
-   - If fail → fix issues, retry from step 3 (max 3 retries)
+3. **If team is active:** Shut down all teammates → `TeamDelete` to clean up
+4. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff resolve-gate {story-id} {workflow} {phase}` → RESOLVE_RESULT
+5. If blocked → report error, STOP
+6. If skip → jump to step 8
+7. If ready → spawn gate subagent with gate file → GATE_RESULT
+   - If fail → fix issues, retry from step 4 (max 3 retries)
    - If pass → continue
-7. `pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}`
-8. `pf handoff marker {next_agent}` → AGENT_COMMAND block
-9. **Act on AGENT_COMMAND:**
-   - Has `marker:` field → emit the CYCLIST marker (Cyclist path)
-   - `action: "inline_handoff"` → run `activation_command` via Bash, output result, adopt new agent identity
-   - `action: "tirepump_handoff"` → tell user: "Context is high. Run `/clear` then `{fallback}`"
-   - No action, no marker → output `fallback` text and EXIT
+8. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}`
+9. `"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff marker {next_agent}` → AGENT_COMMAND block
+10. **Act on AGENT_COMMAND:**
+    - Has `marker:` field → emit the CYCLIST marker (Cyclist path)
+    - `action: "inline_handoff"` → run `activation_command` via Bash, output result, adopt new agent identity
+    - `action: "tirepump_handoff"` → tell user: "Context is high. Run `/clear` then `{fallback}`"
+    - No action, no marker → output `fallback` text and EXIT
 
 **Agents drive exit directly — no handoff subagent.** Scripts handle routing and session updates atomically.
 </agent-exit-protocol>
@@ -141,12 +192,12 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 On activation, check if story phase belongs to you:
 
 ```bash
-pf handoff phase-check {your_agent_name}
+"$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh handoff phase-check {your_agent_name}
 ```
 
 If result has `action: "redirect"`:
 
 - **Cyclist:** Emit `<!-- CYCLIST:HANDOFF:/{phase_owner} -->` and EXIT
-- **CLI + relay ON:** Run `pf agent start {phase_owner} --tier handoff --quiet` via Bash, adopt new identity
+- **CLI + relay ON:** Run `source .pennyfarthing/scripts/lib/env.sh && source "$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/lib/run-pf.sh" && run_pf agent start {phase_owner} --tier handoff --quiet` via Bash, adopt new identity
 - **CLI + relay OFF:** Output `Run /pf-{phase_owner} to continue` and EXIT
 </wrong-phase-detection>

package/pennyfarthing-dist/guides/agent-coordination.md

@@ -4,7 +4,7 @@
 
 This document describes how Pennyfarthing agents are coordinated. The framework supports both single-repo and multi-repo projects.
 
-**Key Principle:** Single entry point (`/pf-session new` or `/work`), state detection via session files, handoffs via Haiku subagents.
+**Key Principle:** Single entry point (`/pf-session new` or `/pf-work`), state detection via session files, handoffs via Haiku subagents.
 
 ## The TDD Flow
 
@@ -12,7 +12,7 @@ SM → TEA → Dev → Reviewer → SM (setup → red → green → review → f
 
 Handoffs between agents are managed by Haiku subagents.
 
-**Entry points:** `/pf-session new` (new story) or `/work` (smart resume/start)
+**Entry points:** `/pf-session new` (new story) or `/pf-work` (smart resume/start)
 **State detection:** Agents read session file on activation
 **Handoffs:** Agents spawn Haiku subagents to update session file
 **Finish:** SM handles when status = `approved`
@@ -263,7 +263,7 @@ User: @/pm
 ### Tactical Agent Workflow (Dev Example)
 
 ```
-User: @/dev
+User: @/pf-dev
 
 1. Load Dev agent definition (.pennyfarthing/agents/dev.md)
 2. Load base context:
@@ -428,7 +428,7 @@ Dev Agent Example (API story):
 - No subagent extraction
 
 ### Current Architecture (January 2026)
-- Smart entry point: `/work` (resumes or starts new)
+- Smart entry point: `/pf-work` (resumes or starts new)
 - Alternative: `/pf-session new` (explicitly start new story)
 - State detection via session file in `.session/`
 - Handoffs via Haiku subagents in `.pennyfarthing/agents/`
@@ -447,17 +447,17 @@ sprint/                            # Sprint tracking
 ### Commands Reference
 ```bash
 # Entry points
-/work          # Smart entry - resume or start new
+/pf-work        # Smart entry - resume or start new
 /pf-session new # Explicitly start new story
 
 # TDD Flow agents
-/sm            # Scrum Master (setup + finish)
-/tea           # Test Engineer (RED phase)
-/dev           # Developer (GREEN phase)
-/reviewer      # Code Reviewer
+/pf-sm          # Scrum Master (setup + finish)
+/pf-tea         # Test Engineer (RED phase)
+/pf-dev         # Developer (GREEN phase)
+/pf-reviewer    # Code Reviewer
 
 # Support agents
-/architect     # Architecture design
+/pf-architect   # Architecture design
 /tech-writer   # Documentation
 /ux-designer   # UI/UX design
 /devops        # Infrastructure

package/pennyfarthing-dist/guides/agent-tag-taxonomy.md

@@ -106,7 +106,7 @@ High-priority instruction that MUST be followed.
 ```xml
 <critical>
 **HANDOFF REQUIRES MARKER OUTPUT.** After exit protocol completes:
-Run `pf handoff marker {next_agent}` as ABSOLUTE LAST ACTION, output result, EXIT.
+Run `pf.sh handoff marker {next_agent}` as ABSOLUTE LAST ACTION, output result, EXIT.
 </critical>
 ```
 - **Validation:** First `<critical>` should be within line 30
@@ -175,10 +175,10 @@ Logic for checking if this agent owns the current phase.
 
 Read `**Workflow:**` and `**Phase:**` from session. Query:
 ```bash
-OWNER=$(pf workflow phase-check {workflow} {phase})
+OWNER=$("$CLAUDE_PROJECT_DIR"/.pennyfarthing/scripts/core/pf.sh workflow phase-check {workflow} {phase})
 ```
 
-**If OWNER != "dev":** Run `pf handoff marker $OWNER`, output result, tell user.
+**If OWNER != "dev":** Run `pf.sh handoff marker $OWNER`, output result, tell user.
 </phase-check>
 ```
 
@@ -250,9 +250,9 @@ Tags that contain checklists with `- [ ]` items.
 ## MANDATORY: Complete Before Exiting
 
 - [ ] Write Dev Assessment to session file
-- [ ] Run `pf handoff resolve-gate` — verify gate status
-- [ ] Run `pf handoff complete-phase` — atomic session update
-- [ ] Run `pf handoff marker {next_agent}` — emit marker and EXIT
+- [ ] Run `pf.sh handoff resolve-gate` — verify gate status
+- [ ] Run `pf.sh handoff complete-phase` — atomic session update
+- [ ] Run `pf.sh handoff marker {next_agent}` — emit marker and EXIT
 </handoff-gate>
 ```
 

package/pennyfarthing-dist/guides/agent-template-tactical.md

@@ -38,7 +38,7 @@ Auto-loaded by `agent-session.sh start` from theme config. See output above.
 </persona>
 
 <role>
-**Primary:** {When this agent is invoked, e.g., "via /tea for TDD test writing"}
+**Primary:** {When this agent is invoked, e.g., "via /pf-tea for TDD test writing"}
 **Position:** {Where in TDD flow, e.g., "SM → **TEA** → Dev → Reviewer"}
 </role>
 

package/pennyfarthing-dist/guides/bell-mode.md

@@ -26,7 +26,7 @@ User queues message in Editor
 |------|---------|
 | `packages/cyclist/src/bell-mode.ts` | State management: `isBellModeEnabled()`, `setBellMode()`, `toggleBellMode()` |
 | `packages/cyclist/src/api/bell.ts` | WebSocket broadcast of bell-consumed events |
-| `pf hooks bell-mode` | PostToolUse hook — reads queue, returns `additionalContext` |
+| `pf.sh hooks bell-mode` | PostToolUse hook — reads queue, returns `additionalContext` |
 | `packages/cyclist/src/public/hooks/useMessageQueue.ts` | React hook: `queueMessage()`, `dequeueMessage()`, `injectMessage()`, `handleTurnComplete()` |
 | `packages/cyclist/src/public/contexts/MessageQueueContext.tsx` | Shared React context (single queue instance across components) |
 | `packages/cyclist/src/public/components/ControlBar.tsx` | Bell mode toggle button |

package/pennyfarthing-dist/guides/bikerack.md

@@ -28,7 +28,7 @@ Cyclist bundles the conversation UI and dashboard panels into one Electron app.
 
 ```bash
 # Launch BikeRack + Claude CLI together
-pf bikerack start
+pf.sh bikerack start
 
 # Or via just recipe
 just bikerack
@@ -37,10 +37,10 @@ just bikerack
 just bikerack dir=/path/to/project
 
 # Stop a running instance
-pf bikerack stop
+pf.sh bikerack stop
 
 # Check status
-pf bikerack status
+pf.sh bikerack status
 ```
 
 BikeRack opens a browser with the Dockview panel layout. Claude CLI runs in the foreground. When Claude exits, BikeRack shuts down automatically via `trap EXIT`.
@@ -71,7 +71,7 @@ BikeRack supports two modes:
 
 ## How It Works
 
-1. **Launcher** (`pf bikerack start`) starts WheelHub with `IS_BIKERACK=1`
+1. **Launcher** (`pf.sh bikerack start`) starts WheelHub with `IS_BIKERACK=1`
 2. **WheelHub** listens on port 2898 (separate from Cyclist's 1898)
 3. **ClaudeService is skipped** — no `/ws/claude` WebSocket channel
 4. **OTEL telemetry** flows from Claude CLI to WheelHub's OTLP receiver
@@ -92,8 +92,8 @@ Client-side detection is URL-based: the presence of `?panel=X` triggers standalo
 
 | File | Purpose |
 |------|---------|
-| `.wheelhub-port` | Port number, written after `server.listen()` — readiness signal |
-| `.wheelhub-pid` | WheelHub PID, written by launcher — enables `pf bikerack stop` |
+| `.bikerack-port` | Port number, written after `server.listen()` — readiness signal |
+| `.wheelhub-pid` | WheelHub PID, written by launcher — enables `pf.sh bikerack stop` |
 
 Both are deleted on shutdown. Shared with Cyclist (single WheelHub namespace).
 
@@ -102,9 +102,9 @@ Both are deleted on shutdown. Shared with Cyclist (single WheelHub namespace).
 Save and restore BikeRack panel layouts:
 
 ```bash
-pf bc save my-layout      # Save current layout
-pf bc load my-layout      # Restore a saved layout
-pf bc list                 # List saved layouts
+pf.sh bc save my-layout      # Save current layout
+pf.sh bc load my-layout      # Restore a saved layout
+pf.sh bc list                 # List saved layouts
 ```
 
 ## Key Files
@@ -115,7 +115,7 @@ pf bc list                 # List saved layouts
 | `packages/core/src/public/components/BikeRackWorkspace.tsx` | Dockview layout for BikeRack |
 | `packages/core/src/public/components/BikeRackIndex.tsx` | Panel listing index page |
 | `packages/core/src/public/components/StandalonePanel.tsx` | `?panel=X` routing + `PANEL_REGISTRY` |
-| `pennyfarthing_scripts/bikerack/cli.py` | `pf bikerack` launcher CLI |
+| `pennyfarthing_scripts/bikerack/cli.py` | `pf.sh bikerack` launcher CLI |
 
 ## Constraints
 

package/pennyfarthing-dist/guides/brownfield-tools.md

@@ -6,7 +6,7 @@ CLI tools for analyzing existing codebases. Identify change hotspots, complexity
 
 ## Overview
 
-All tools are available under `pf debug` and share a consistent interface: `--format` (table/json/csv), `--output` (file), `--top` (result count), `--exclude` (patterns), and `--repo` (target).
+All tools are available under `pf.sh debug` and share a consistent interface: `--format` (table/json/csv), `--output` (file), `--top` (result count), `--exclude` (patterns), and `--repo` (target).
 
 ## Tools
 
@@ -16,19 +16,19 @@ Find files that change most frequently — high churn often correlates with bugs
 
 ```bash
 # Full analysis (files + directories)
-pf debug hotspots analyze
+pf.sh debug hotspots analyze
 
 # File-level only
-pf debug hotspots files
+pf.sh debug hotspots files
 
 # Directory-level only
-pf debug hotspots dirs
+pf.sh debug hotspots dirs
 
 # Options
-pf debug hotspots analyze --days 90 --top 20 --repo pennyfarthing
-pf debug hotspots analyze --format json --output hotspots.json
-pf debug hotspots analyze --exclude "*.test.ts" --branch main
-pf debug hotspots analyze --skip-type orchestrator
+pf.sh debug hotspots analyze --days 90 --top 20 --repo pennyfarthing
+pf.sh debug hotspots analyze --format json --output hotspots.json
+pf.sh debug hotspots analyze --exclude "*.test.ts" --branch main
+pf.sh debug hotspots analyze --skip-type orchestrator
 ```
 
 ### Complexity
@@ -36,9 +36,9 @@ pf debug hotspots analyze --skip-type orchestrator
 Measure code complexity metrics across files.
 
 ```bash
-pf debug complexity analyze
-pf debug complexity analyze --path ./packages/core/src
-pf debug complexity analyze --top 30 --format csv
+pf.sh debug complexity analyze
+pf.sh debug complexity analyze --path ./packages/core/src
+pf.sh debug complexity analyze --top 30 --format csv
 ```
 
 ### Dead Code
@@ -47,12 +47,12 @@ Find unused code: stale files with no recent commits, and unused TypeScript expo
 
 ```bash
 # Files with no recent commits (default: 180 days)
-pf debug deadcode stale
-pf debug deadcode stale --days 90 --repo pennyfarthing
+pf.sh debug deadcode stale
+pf.sh debug deadcode stale --days 90 --repo pennyfarthing
 
 # Unused TypeScript exports (via ts-prune)
-pf debug deadcode exports
-pf debug deadcode exports --repo pennyfarthing --format json
+pf.sh debug deadcode exports
+pf.sh debug deadcode exports --repo pennyfarthing --format json
 ```
 
 ### Code Markers
@@ -61,16 +61,16 @@ Detect TODO, FIXME, HACK, and XXX comments with git blame data.
 
 ```bash
 # Full analysis with blame data
-pf debug codemarkers analyze
+pf.sh debug codemarkers analyze
 
 # Only stale markers (older than threshold)
-pf debug codemarkers stale --days 90
+pf.sh debug codemarkers stale --days 90
 
 # Summary counts by type
-pf debug codemarkers summary
+pf.sh debug codemarkers summary
 
 # Deprecated symbol detection
-pf debug codemarkers deprecations
+pf.sh debug codemarkers deprecations
 ```
 
 ### Dependencies
@@ -78,8 +78,8 @@ pf debug codemarkers deprecations
 Analyze dependency staleness and security advisories.
 
 ```bash
-pf debug dependencies analyze
-pf debug dependencies analyze --path ./pennyfarthing --format json
+pf.sh debug dependencies analyze
+pf.sh debug dependencies analyze --path ./pennyfarthing --format json
 ```
 
 ### Health Score
@@ -87,9 +87,9 @@ pf debug dependencies analyze --path ./pennyfarthing --format json
 Composite health score across all dimensions (hotspots, complexity, dead code, dependencies, markers).
 
 ```bash
-pf debug healthscore analyze
-pf debug healthscore analyze --no-cache   # Bypass cache
-pf debug healthscore analyze --format json --output health.json
+pf.sh debug healthscore analyze
+pf.sh debug healthscore analyze --no-cache   # Bypass cache
+pf.sh debug healthscore analyze --format json --output health.json
 ```
 
 ## Common Options

package/pennyfarthing-dist/guides/command-tag-taxonomy.md

@@ -61,7 +61,7 @@
 
 ### Conditional by Type
 
-**Workflow/Agent Commands (e.g., /sm, /dev, /tea)**
+**Workflow/Agent Commands (e.g., /pf-sm, /pf-dev, /pf-tea)**
 - `<agent-activation>` — Required to show activation
 - `<instructions>` — Required for agent behavior
 

package/pennyfarthing-dist/guides/gate-schema.md

@@ -181,7 +181,7 @@ The `gate.file` value is resolved by the gate file discovery algorithm (project-
 Validate gate files before use:
 
 ```bash
-pf gate validate path/to/gate-file.md
+pf.sh gate validate path/to/gate-file.md
 ```
 
 The validator checks:
@@ -215,7 +215,7 @@ Gate 'tests-pass' is valid
 
 6. **Add recovery steps.** The `recovery` array in failed results gives the agent a clear path to fix issues and retry.
 
-7. **Test with the validator.** Run `pf gate validate` on your gate file before referencing it in a workflow.
+7. **Test with the validator.** Run `pf.sh gate validate` on your gate file before referencing it in a workflow.
 
 ## Related
 

package/pennyfarthing-dist/guides/gates.md

@@ -78,14 +78,14 @@ Agents interact with gates through the handoff CLI during their exit sequence:
 
 ```
 1. Agent writes assessment to session file
-2. pf handoff resolve-gate {story-id} {workflow} {phase}
+2. pf.sh handoff resolve-gate {story-id} {workflow} {phase}
    → Reads workflow YAML, finds gate for current phase
    → Returns RESOLVE_RESULT: {status: ready|skip|blocked, gate_file: ...}
 3. If ready → spawn Haiku subagent with gate file → GATE_RESULT
 4. If GATE_RESULT.status == fail → fix issues, retry (max 3)
 5. If GATE_RESULT.status == pass → continue to complete-phase
-6. pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
-7. pf handoff marker {next-agent}
+6. pf.sh handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
+7. pf.sh handoff marker {next-agent}
 ```
 
 If a phase has no `gate:` block, `resolve-gate` returns `status: skip` and the agent proceeds directly to `complete-phase`.

package/pennyfarthing-dist/guides/handoff-cli.md

@@ -1,7 +1,7 @@
 # Handoff CLI
 
 <info>
-Python CLI for managing workflow phase transitions. Agents use `pf handoff` to resolve gates, complete phase transitions, and generate handoff markers during their exit protocol.
+Python CLI for managing workflow phase transitions. Agents use `pf.sh handoff` to resolve gates, complete phase transitions, and generate handoff markers during their exit protocol.
 </info>
 
 ## Commands
@@ -11,7 +11,7 @@ Python CLI for managing workflow phase transitions. Agents use `pf handoff` to r
 Check whether the current phase has a gate and what state it's in.
 
 ```bash
-pf handoff resolve-gate STORY_ID WORKFLOW PHASE
+pf.sh handoff resolve-gate STORY_ID WORKFLOW PHASE
 ```
 
 **Arguments:**
@@ -39,7 +39,7 @@ RESOLVE_RESULT:
 Atomically update the session file to record a phase transition.
 
 ```bash
-pf handoff complete-phase STORY_ID WORKFLOW FROM_PHASE TO_PHASE GATE_TYPE
+pf.sh handoff complete-phase STORY_ID WORKFLOW FROM_PHASE TO_PHASE GATE_TYPE
 ```
 
 **Arguments:**
@@ -66,8 +66,8 @@ Updates the session file: `**Phase:**` line, timestamps, and phase history table
 Generate an environment-aware handoff marker block.
 
 ```bash
-pf handoff marker NEXT_AGENT
-pf handoff marker --error "Tests failing"
+pf.sh handoff marker NEXT_AGENT
+pf.sh handoff marker --error "Tests failing"
 ```
 
 **Arguments:**
@@ -88,14 +88,14 @@ The handoff CLI is used in sequence during agent exit:
 
 ```
 1. Write assessment to session file
-2. pf handoff resolve-gate {story-id} {workflow} {phase}
+2. pf.sh handoff resolve-gate {story-id} {workflow} {phase}
    ├── blocked → report error, STOP
    ├── skip → jump to step 4
    └── ready → spawn gate subagent → GATE_RESULT
        ├── fail → fix issues, retry (max 3)
        └── pass → continue
-3. pf handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
-4. pf handoff marker {next-agent} → emit marker → EXIT
+3. pf.sh handoff complete-phase {story-id} {workflow} {from} {to} {gate-type}
+4. pf.sh handoff marker {next-agent} → emit marker → EXIT
 ```
 
 See `guides/gates.md` for gate file format and evaluation details.

package/pennyfarthing-dist/guides/hooks.md

@@ -16,18 +16,18 @@ Hooks are commands that Claude Code runs at specific events:
 
 ### SessionStart Hooks
 
-#### pf hooks session-start
+#### pf.sh hooks session-start
 
-**Location:** `pf hooks session-start`
+**Location:** `pf.sh hooks session-start`
 
 Initializes the Pennyfarthing environment:
 - Creates `.session/` directory structure
 - Clears stale agent state from previous sessions
 - Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
 
-#### pf hooks session-stop
+#### pf.sh hooks session-stop
 
-**Location:** `pf hooks session-stop`
+**Location:** `pf.sh hooks session-stop`
 
 Cleans up session state when Claude Code exits.
 
@@ -44,66 +44,66 @@ Project-specific environment setup. Edit this file to:
 
 **Location:** `.pennyfarthing/scripts/hooks/otel-auto-config.sh`
 
-Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.wheelhub-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
+Auto-configures OTEL telemetry for Cyclist web mode. Checks for a `.bikerack-port` file and sets `OTEL_EXPORTER_OTLP_PROTOCOL` and `OTEL_EXPORTER_OTLP_ENDPOINT` to route Claude Code telemetry to the running Cyclist/BikeRack server.
 
-#### pf hooks session-start (welcome)
+#### pf.sh hooks session-start (welcome)
 
-**Location:** `pf hooks session-start`
+**Location:** `pf.sh hooks session-start`
 
-Welcome display is now folded into `pf hooks session-start`. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
+Welcome display is now folded into `pf.sh hooks session-start`. In CLI mode, shows ASCII art. In Cyclist mode, sends a WebSocket message to display the logo. Runs once per session (lock file guard).
 
 ### PreToolUse Hooks
 
-#### pf hooks pre-edit-check
+#### pf.sh hooks pre-edit-check
 
-**Location:** `pf hooks pre-edit-check`
+**Location:** `pf.sh hooks pre-edit-check`
 
 Protects sensitive files from accidental edits:
 - Blocks: `.env`, `.pem`, `.key`, credentials, secrets
 - Blocks: `.git/`, `node_modules/`, `vendor/`
 - Blocks: `.pennyfarthing/*` (managed files)
 
-#### pf hooks cyclist-pretooluse
+#### pf.sh hooks cyclist-pretooluse
 
-**Location:** `pf hooks cyclist-pretooluse`
+**Location:** `pf.sh hooks cyclist-pretooluse`
 
 Cyclist-specific pre-tool validation. Runs additional safety checks when operating inside Cyclist.
 
-#### pf hooks context-warning
+#### pf.sh hooks context-warning
 
-**Location:** `pf hooks context-warning`
+**Location:** `pf.sh hooks context-warning`
 
 Warns agents when context usage is high. Outputs a warning at 60% usage and a critical warning at 85%. Never blocks — warning only (always exits 0).
 
-#### pf hooks context-breaker
+#### pf.sh hooks context-breaker
 
-**Location:** `pf hooks context-breaker`
+**Location:** `pf.sh hooks context-breaker`
 
-Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `pf hooks context-warning`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
+Hard stop when context reaches 80% (configurable via `CRITICAL_THRESHOLD`). Unlike `pf.sh hooks context-warning`, this **blocks tool execution** (exit 2). Auto-saves the active agent to a checkpoint so `/pf-session continue` can restore it with FULL tier context.
 
-#### pf hooks schema-validation
+#### pf.sh hooks schema-validation
 
-**Location:** `pf hooks schema-validation`
+**Location:** `pf.sh hooks schema-validation`
 
 Validates file writes against XML schema rules for agent definitions, workflow files, and other structured content.
 
-#### pf hooks sprint-yaml
+#### pf.sh hooks sprint-yaml
 
-**Location:** `pf hooks sprint-yaml`
+**Location:** `pf.sh hooks sprint-yaml`
 
 Validates sprint YAML files on write to prevent structural corruption.
 
 ### PostToolUse Hooks
 
-#### pf hooks bell-mode
+#### pf.sh hooks bell-mode
 
-**Location:** `pf hooks bell-mode`
+**Location:** `pf.sh hooks bell-mode`
 
 Bell mode message injection. Checks the bell mode queue and injects queued messages into the agent's context at the next tool execution. Also handles tandem observation injection.
 
-#### pf hooks reflector-check
+#### pf.sh hooks reflector-check
 
-**Location:** `pf hooks reflector-check`
+**Location:** `pf.sh hooks reflector-check`
 
 Stop hook enforcing that every agent turn ends with a CYCLIST marker. Detects questions, handoff phrases, and validates marker presence. Blocks turns without valid markers in Cyclist mode.
 
@@ -133,7 +133,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks session-start"
+            "command": "pf.sh hooks session-start"
           }
         ]
       }
@@ -144,7 +144,7 @@ Hooks are configured in `.claude/settings.local.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "pf hooks pre-edit-check"
+            "command": "pf.sh hooks pre-edit-check"
           }
         ]
       }