@pennyfarthing/core 11.2.1 → 11.3.1

package/pennyfarthing-dist/gates/reviewer-preflight-check.md

@@ -0,0 +1,90 @@
+<gate name="reviewer-preflight-check" model="haiku">
+
+<purpose>
+Composite gate for reviewer preflight. Extends tests-pass with code smell
+detection and error boundary checks. The reviewer-preflight subagent runs
+this gate before the Reviewer does critical analysis.
+</purpose>
+
+<ref gate="gates/tests-pass" />
+
+<check name="no-debug-code">
+No debug artifacts in changed files.
+Search changed files (`git diff --name-only develop...HEAD`) for:
+- `console.log` (not guarded by `process.env.NODE_ENV`)
+- `dangerouslySetInnerHTML`
+- `.skip(` (test skips)
+- `TODO` / `FIXME`
+Count by category. None found = pass.
+</check>
+
+<check name="error-boundaries">
+UI components have error boundaries (UI repos only).
+For React component files in diff, verify error boundary wrapping.
+Skip for non-UI repos.
+</check>
+
+<pass>
+Run all checks from `gates/tests-pass` (test-suite, working-tree, branch-status),
+then run no-debug-code and error-boundaries.
+
+If ALL pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: reviewer-preflight-check
+  message: "Preflight clear: tests green, no smells, boundaries present"
+  checks:
+    - name: test-suite
+      status: pass
+      detail: "{passed}/{total} passing ({source: cached|fresh})"
+    - name: working-tree
+      status: pass
+      detail: "No uncommitted changes"
+    - name: branch-status
+      status: pass
+      detail: "On branch {branch}"
+    - name: no-debug-code
+      status: pass
+      detail: "No debug patterns in {N} changed files"
+    - name: error-boundaries
+      status: pass
+      detail: "Error boundaries present (or N/A for non-UI)"
+```
+</pass>
+
+<fail>
+If ANY check fails, report all results. Note: code smells are advisory (YELLOW)
+rather than blocking (RED) — the Reviewer makes the final call.
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: reviewer-preflight-check
+  message: "Preflight issues: {summary}"
+  checks:
+    - name: test-suite
+      status: pass | fail
+      detail: "{test results or failure list}"
+    - name: working-tree
+      status: pass | fail
+      detail: "{clean or list of uncommitted files}"
+    - name: branch-status
+      status: pass | fail
+      detail: "{branch info}"
+    - name: no-debug-code
+      status: pass | fail
+      detail: "{clean or smell counts by category}"
+    - name: error-boundaries
+      status: pass | fail
+      detail: "{present, missing list, or N/A}"
+  recovery:
+    - "Fix failing tests before review"
+    - "Commit or stash uncommitted changes"
+    - "Remove debug code: {locations}"
+    - "Add error boundaries to: {components}"
+```
+</fail>
+
+</gate>

package/pennyfarthing-dist/gates/sm-setup-exit.md

@@ -0,0 +1,82 @@
+<gate name="sm-setup-exit" model="haiku">
+
+<purpose>
+Verify SM has completed story setup before handing off to the next agent.
+Without a properly configured session file, the next agent cannot function.
+Extracts the inline pre-handoff checklist from sm.md.
+</purpose>
+
+<pass>
+Run these checks in order:
+
+1. **session-exists:** Check `.session/{story-id}-session.md` exists.
+   ```bash
+   ls .session/{story-id}-session.md
+   ```
+
+2. **session-fields-set:** Read session file and verify:
+   - `**Workflow:**` field present and non-empty
+   - `**Phase:**` field present and set to `setup`
+
+3. **story-context-exists:** Verify:
+   - `sprint/context/context-epic-{N}.md` exists (extract epic number from story ID)
+   - Session file contains technical approach section
+   - Session file contains acceptance criteria
+
+4. **branch-created:** For each repo in session `**Repos:**`:
+   - Run `git branch --show-current`
+   - Confirm not on `main` or `develop`
+
+If ALL pass, return:
+
+```yaml
+GATE_RESULT:
+  status: pass
+  gate: sm-setup-exit
+  message: "Session {story-id} ready. Workflow: {workflow}, Branch: {branch}"
+  checks:
+    - name: session-exists
+      status: pass
+      detail: ".session/{story-id}-session.md exists"
+    - name: session-fields-set
+      status: pass
+      detail: "Workflow: {workflow}, Phase: setup"
+    - name: story-context-exists
+      status: pass
+      detail: "Epic context and story ACs present"
+    - name: branch-created
+      status: pass
+      detail: "Branch {branch} created in {repos}"
+```
+</pass>
+
+<fail>
+If ANY check fails, report all results:
+
+```yaml
+GATE_RESULT:
+  status: fail
+  gate: sm-setup-exit
+  message: "Setup incomplete: {summary}"
+  checks:
+    - name: session-exists
+      status: pass | fail
+      detail: "{exists or missing}"
+    - name: session-fields-set
+      status: pass | fail
+      detail: "{fields present or missing fields list}"
+    - name: story-context-exists
+      status: pass | fail
+      detail: "{context present or missing sections}"
+    - name: branch-created
+      status: pass | fail
+      detail: "{branch status per repo}"
+  recovery:
+    - "Run sm-setup to create session file"
+    - "Set Workflow and Phase fields in session"
+    - "Write story context with technical approach and ACs"
+    - "Create feature branch: git checkout -b feat/{story-slug}"
+```
+</fail>
+
+</gate>

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,109 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 
 ---
 
+<team-mode>
+## Team Mode — Phase-Scoped Native Teams
+
+Team mode enables parallel agent collaboration within a single workflow phase using Claude Code's native Agent Teams. The phase agent is always the **team lead**; spawned agents are **teammates**. Teams are created at phase start and destroyed before handoff.
+
+**Prerequisites:**
+- Workflow phase has a `team:` block in its YAML definition
+- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set
+- Interactive session (not `-p` mode)
+- Feature detection passes (`pf detect teams` or equivalent)
+
+**If prerequisites are not met:** Fall back to solo execution (optionally with tandem consultation). No error — team mode is always optional.
+
+### Detection
+
+On activation, check the workflow YAML for a `team:` block on your phase:
+
+```yaml
+phases:
+  - name: green
+    agent: dev
+    team:
+      teammates:
+        - agent: architect
+          task: "Review implementation approach and patterns"
+        - agent: tea
+          task: "Verify tests stay green, flag regressions"
+```
+
+If `team:` is present and prerequisites are met, you are the **team lead** for this phase.
+
+### Team Lead Responsibilities
+
+**On phase entry:**
+
+1. **Create the team:**
+   ```
+   TeamCreate("phase-{PHASE}-{STORY_ID}")
+   ```
+
+2. **Spawn teammates** per workflow YAML config. Each teammate gets a spawn prompt:
+   ```
+   Task(team_name="phase-{PHASE}-{STORY_ID}", name="{agent}",
+        prompt="Run `pf agent start {agent}`. Story: {STORY_ID}.
+                {task assignment from YAML}")
+   ```
+   Teammates auto-load CLAUDE.md, MCP servers, and skills from the working directory. Spawn prompts only need the activation command and task assignment — keep under 500 tokens.
+
+3. **Coordinate via SendMessage.** Use `SendMessage` for all intra-phase communication with teammates:
+   - Assign work: `SendMessage(to="{teammate}", message="Implement the adapter pattern for...")`
+   - Check status: `SendMessage(to="{teammate}", message="Status on your review?")`
+   - Broadcast: `SendMessage(message="Shifting approach — using strategy pattern instead")`
+
+4. **Do your own work.** You are still the primary implementer. Teammates assist — they don't replace you.
+
+**Before exit protocol:**
+
+5. **Shut down all teammates.** This is mandatory before starting the normal exit protocol:
+   ```
+   SendMessage(to="{teammate}", message="Phase complete. Shut down.")
+   ```
+   Wait for teammates to go idle, then:
+   ```
+   TeamDelete("phase-{PHASE}-{STORY_ID}")
+   ```
+
+6. **Proceed with normal exit protocol** (assessment → resolve-gate → complete-phase → marker).
+
+### Teammate Responsibilities
+
+When spawned as a teammate (you receive a task via spawn prompt, not a phase handoff):
+
+1. **Recognize you are a teammate, not the lead.** You do not own the phase. You do not run the exit protocol. You do not emit handoff markers.
+
+2. **Activate normally** via `pf agent start {agent}`. Read the session file for story context.
+
+3. **Communicate via SendMessage.** All collaboration with the lead and other teammates uses `SendMessage`:
+   - Report findings: `SendMessage(to="lead", message="Found coupling issue in...")`
+   - Ask questions: `SendMessage(to="lead", message="Should I use the existing adapter?")`
+   - Share status: `SendMessage(to="lead", message="Review complete. 2 issues found.")`
+
+4. **Go idle when your task is done.** Once your assigned task is complete, send a final status message and wait. Do not start new work unprompted.
+
+5. **Respond to shutdown requests.** When the lead sends a shutdown message, wrap up immediately. Save any observations to the session file or sidecar, then stop.
+
+### Communication Channels
+
+| Channel | Scope | Used For |
+|---------|-------|----------|
+| `SendMessage` | Intra-phase (within team) | Lead ↔ teammate collaboration, status updates, task assignment |
+| Reflector markers (`<!-- CYCLIST:... -->`) | Inter-phase (between phases) | Handoff from one phase agent to the next — **unchanged** |
+| Session file | Cross-phase persistence | Story state, assessments, ACs — written by lead only in team mode |
+| Sidecar files | Agent learning | Teammates may write to their own sidecar with file locking |
+
+<critical>
+**Never use SendMessage for inter-phase handoff.** Markers and `pf handoff` are the only way to transition between phases. SendMessage is for real-time collaboration within a phase.
+
+**Never use markers for intra-phase communication.** Markers are routing signals for Cyclist UI and the handoff system. They have no meaning inside a team.
+</critical>
+</team-mode>
+
+---
+
 ## Reflector
 
 <critical>
@@ -117,20 +225,21 @@ See `.pennyfarthing/guides/tandem-protocol.md` for full protocol details.
 ## Exit Protocol
 
 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)
+2. **If team mode active:** Shut down all teammates via `SendMessage`, then `TeamDelete`. Wait for cleanup before proceeding.
+3. Terminate tandem backseat (if active)
+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 +250,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