@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/skills/pf-ux-tandem/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: pf-ux-tandem
+description: Live UX review tandem — spawn a UX designer to watch a tmux pane and suggest improvements in real time
+---
+
+# UX Tandem Skill
+
+<run>
+Spawn a UX designer teammate that watches a tmux pane and provides real-time usability feedback via Agent Teams.
+
+This is NOT the standard tandem-backseat protocol (observation files + PostToolUse injection). This uses native Agent Teams with `SendMessage` for real-time two-way collaboration, and `tmux capture-pane` for visual observation.
+
+## Step 1: Identify the Target Pane
+
+Find the tmux pane to observe:
+
+```bash
+tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_title} #{pane_current_command} [#{pane_width}x#{pane_height}]'
+```
+
+Pick the pane running the target UI (e.g., a TUI, dev server output, or running application). Note the pane address in `{session}:{window}.{pane}` format.
+
+If the user specified a pane, use that. If not, choose the pane that most likely contains the UI under review.
+
+## Step 2: Resolve Persona
+
+Read the active theme to get the UX designer character:
+
+```bash
+THEME=$(yq '.theme' .pennyfarthing/config.local.yaml 2>/dev/null || echo "discworld")
+```
+
+Then read the theme file to find the UX designer character name.
+
+## Step 3: Create the Team
+
+```
+TeamCreate:
+  team_name: "ux-tandem"
+  description: "Live UX review — observer watches tmux pane and suggests improvements"
+```
+
+## Step 4: Create Tasks
+
+Create two tasks:
+
+1. **"Observe tmux pane and provide UX feedback"** — assigned to the UX observer
+2. **"Implement UX suggestions from observer"** — assigned to self (the lead)
+
+## Step 5: Spawn the UX Observer
+
+Use the Task tool to spawn the observer teammate:
+
+```
+Task:
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  team_name: "ux-tandem"
+  name: "ux-observer"
+  prompt: |
+    You are a UX designer reviewing a live terminal UI. Your role is to watch a tmux pane
+    and send usability suggestions to the lead agent.
+
+    CHARACTER: {resolved character name from theme}
+    TARGET_PANE: {session}:{window}.{pane}
+
+    ## Your Workflow
+
+    **Loop** (repeat until told to stop):
+
+    1. **Capture** the current pane state:
+       ```bash
+       tmux capture-pane -t '{TARGET_PANE}' -p
+       ```
+
+    2. **Analyze** what you see. Focus on:
+       - Layout and visual hierarchy — is the information easy to scan?
+       - Alignment and spacing — are elements consistently aligned?
+       - Color usage and contrast — is text readable? Are colors meaningful?
+       - Information density — too cluttered or too sparse?
+       - Labels and terminology — clear and consistent?
+       - Navigation cues — can the user tell where they are and what they can do?
+       - Error states — are errors visible and actionable?
+       - Empty states — what shows when there's no data?
+
+    3. **Send suggestions** via SendMessage to the lead:
+       - One suggestion per message
+       - Be specific: reference exact text, positions, or elements you see
+       - Categorize as [LAYOUT], [COLOR], [COPY], [INTERACTION], or [ACCESSIBILITY]
+       - Include a concrete fix, not just the problem
+       - Priority: focus on high-impact issues first
+
+    4. **Wait** for the lead to confirm implementation or ask questions, then re-capture
+       to verify the change and continue.
+
+    ## Communication Protocol
+
+    - Use `SendMessage` with `type: "message"` to send suggestions
+    - Keep messages concise — one issue per message
+    - If you see no issues, say so and wait before re-capturing
+    - If the lead sends you a message, respond via SendMessage
+    - When told to wrap up, acknowledge and stop
+
+    ## Example Message
+
+    ```
+    [LAYOUT] The status indicators in the top-right are misaligned — "Sprint: 4"
+    sits 2 chars higher than "Stories: 12/15". Suggestion: pad the Sprint label
+    with a leading space or align both to the same row baseline.
+    ```
+
+    Stay in character as {CHARACTER}. Begin by capturing the pane and sending
+    your first observation.
+```
+
+## Step 6: Implement Suggestions
+
+As the lead agent, receive suggestions via automatic message delivery.
+For each suggestion:
+
+1. Read the suggestion
+2. Decide whether to implement (confirm to the observer via `SendMessage`)
+3. Make the code change
+4. Let the observer re-capture and verify
+
+## Step 7: Teardown
+
+When the review session is complete:
+
+1. Send a shutdown request to the observer:
+   ```
+   SendMessage:
+     type: "shutdown_request"
+     recipient: "ux-observer"
+     content: "UX review complete, shutting down"
+   ```
+
+2. After the observer confirms, delete the team:
+   ```
+   TeamDelete
+   ```
+</run>
+
+<output>
+Real-time UX feedback loop between the lead agent and a UX observer teammate. The observer captures the target tmux pane, analyzes it for usability issues, and sends categorized suggestions ([LAYOUT], [COLOR], [COPY], [INTERACTION], [ACCESSIBILITY]) via SendMessage. The lead confirms, implements, and the observer re-captures to verify. Continues until the lead triggers teardown.
+</output>
+
+## When to Use
+
+- Reviewing a TUI for usability issues while actively developing it
+- Getting real-time UX feedback on a running application in another tmux pane
+- Polishing visual output (tables, panels, status bars, progress indicators)
+- Pre-release UI review of terminal tools
+
+## When NOT to Use
+
+- **Code-only review** — use the standard tandem-backseat protocol or `/pf-code-review`
+- **Non-visual targets** — if there's no UI to look at, this skill adds nothing
+- **No tmux** — requires tmux for pane capture; won't work in plain terminal sessions
+
+## Customizing the Observer Role
+
+The observer doesn't have to be a UX designer. Swap the role and analysis criteria:
+
+| Observer Role | Focus Areas |
+|---------------|-------------|
+| **UX Designer** (default) | Layout, color, copy, interaction, accessibility |
+| **Architect** | Component structure, separation of concerns, data flow visible in UI |
+| **TEA** | Error states, edge cases, missing validation feedback |
+| **PM** | Feature completeness, user story coverage, workflow gaps |
+
+To use a different observer, modify the spawn prompt's analysis criteria and character resolution to match the desired role.
+
+## Customizing the Observation Target
+
+The `tmux capture-pane` command can be replaced with other observation methods:
+
+| Target | Capture Method |
+|--------|---------------|
+| **tmux pane** (default) | `tmux capture-pane -t '{pane}' -p` |
+| **Browser** | Screenshot via Playwright MCP / `browser_take_screenshot` |
+| **Log file** | `tail -n 50 /path/to/logfile` |
+| **API response** | `curl -s http://localhost:3000/api/status` |
+
+## Differences from Tandem-Backseat
+
+| Aspect | Tandem-Backseat | UX Tandem (this skill) |
+|--------|----------------|----------------------|
+| Communication | One-way (observation file + hook injection) | Two-way (`SendMessage`) |
+| Infrastructure | PostToolUse hook, observation files | Agent Teams (`TeamCreate`/`SendMessage`) |
+| Model | Haiku (background) | Sonnet (teammate) |
+| Observation | git diff, file reads | `tmux capture-pane` (visual) |
+| Lifecycle | Background task, auto-injected | Interactive team, manual confirm/reject |
+| Use case | Code-level observation during workflow | Visual/UX review of running UI |

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

@@ -1,170 +1,93 @@
-# Workflow — Detailed Usage
+# Workflow CLI — Detailed Usage
 
 ## Commands
 
-### List Workflows
+### `pf.sh workflow check`
 
-```bash
-pf.sh workflow list
-```
-
-No arguments. Returns table of workflows with type, phases/steps count, modes, default flag, description.
-
-### Show Workflow
-
-```bash
-pf.sh workflow show [NAME]
-```
-
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `NAME` | No | Workflow name (`tdd`, `trivial`, etc.). Omit for current session's workflow. |
-
-Returns workflow description, phase flow diagram, phases table, trigger conditions.
-
-### Switch Workflow
-
-Manual edit of `.session/{story-id}-session.md` — change the `**Workflow:**` line.
-
-Warning: Only do this when story requirements have fundamentally changed. Switching resets phase tracking.
-
-### Start Stepped Workflow
-
-```bash
-pf.sh workflow start <NAME> [--mode <MODE>]
-```
+Check current workflow state.
 
 | Arg/Option | Required | Description |
 |------------|----------|-------------|
-| `NAME` | Yes | Workflow name (e.g., `architecture`) |
-| `--mode` | No | `create` (default), `validate`, or `edit` |
+| `--json` | No | Output as JSON |
 
-Creates a new session and begins at step 1.
+### `pf.sh workflow complete-step`
 
-### Resume Stepped Workflow
+Complete the current step of a stepped workflow.
 
-```bash
-pf.sh workflow resume [NAME]
-```
-
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `NAME` | No | Workflow to resume. Detects from active session if omitted. |
-
-### Workflow Status
-
-```bash
-pf.sh workflow status
-```
-
-No arguments. Shows current step, progress percentage, mode.
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Workflow name (auto-detects from session if omitted) |
+| `--step` | No | Complete a specific step number instead of current step |
 
-### Fix Session Phase
+### `pf.sh workflow fix-phase`
 
-```bash
-pf.sh workflow fix-phase <STORY_ID> <TARGET_PHASE> [--dry-run]
-```
+Repair session phase tracking when handoffs didn't update properly.
 
 | Arg/Option | Required | Description |
 |------------|----------|-------------|
-| `STORY_ID` | Yes | Story ID (e.g., `56-1` or `MSSCI-12190`) |
-| `TARGET_PHASE` | Yes | Target phase to set |
+| `STORY_ID` | Yes | Story ID (e.g., 56-1 or MSSCI-12190) |
+| `TARGET_PHASE` | Yes | Target phase to set (e.g., review, approved, finish) |
 | `--dry-run` | No | Preview without making changes |
 
-Valid phases by workflow:
-
-| Workflow | Phases |
-|----------|--------|
-| `tdd` | setup, red, green, review, approved, finish |
-| `trivial` | setup, implement, review, approved, finish |
-
-Updates `**Phase:**` field, `**Phase Started:**` timestamp, and handoff history table.
-
-### Complete Step
+### `pf.sh workflow handoff`
 
-```bash
-pf.sh workflow complete-step [NAME] [--step N]
-```
+Emit an environment-aware handoff marker.
 
 | Arg/Option | Required | Description |
 |------------|----------|-------------|
-| `NAME` | No | Workflow name (auto-detects from session) |
-| `--step N` | No | Complete specific step number instead of current |
+| `NEXT_AGENT` | Yes | The agent to hand off to (tea, dev, reviewer, etc.) |
 
-Advances session: increments step, updates completed list, recalculates percentage.
+### `pf.sh workflow list`
 
----
+List all available workflows.
 
-## State & Phase Commands
+### `pf.sh workflow phase-check`
 
-### Check Workflow State
+Check which agent owns a workflow phase.
 
-```bash
-pf.sh workflow check [--json]
-```
-
-| Option | Description |
-|--------|-------------|
-| `--json` | Output as JSON |
-
-Returns current story ID, phase, workflow, and state.
-
-### Check Phase Owner
-
-```bash
-pf.sh workflow phase-check <WORKFLOW_NAME> <PHASE>
-```
-
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `WORKFLOW_NAME` | Yes | Workflow type (`tdd`, `trivial`, etc.) |
-| `PHASE` | Yes | Phase to check (`red`, `implement`, `review`, etc.) |
-
-Returns the agent name that owns the phase.
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `WORKFLOW_NAME` | Yes | The workflow type (tdd, trivial, etc.) |
+| `PHASE` | Yes | The phase to check (red, implement, review, etc.) |
 
-### Get Workflow Type
+### `pf.sh workflow resume`
 
-```bash
-pf.sh workflow type <WORKFLOW_NAME>
-```
+Resume a stepped workflow from the current step.
 
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `WORKFLOW_NAME` | Yes | Workflow name (e.g., `tdd`, `architecture`) |
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Workflow name (auto-detects from active session if omitted) |
 
-Returns `phased`, `stepped`, or `procedural`.
+### `pf.sh workflow show`
 
-### Emit Handoff Marker
+Show workflow details including phase flow, triggers, and gates.
 
-```bash
-pf.sh workflow handoff <NEXT_AGENT>
-```
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Workflow name (defaults to current session's workflow or tdd) |
 
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `NEXT_AGENT` | Yes | Agent to hand off to (`tea`, `dev`, `reviewer`, etc.) |
+### `pf.sh workflow start`
 
-Outputs CYCLIST-formatted YAML marker.
+Start a stepped workflow from step 1.
 
----
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | Yes | Workflow name (e.g., architecture, release) |
+| `-m, --mode` | No | Mode: create, validate, or edit |
 
-## Workflow Routing Priority
+### `pf.sh workflow status`
 
-When multiple workflows match a story:
+Show current stepped workflow progress.
 
-1. **Explicit tag:** `workflow: docs` on story overrides everything
-2. **Trigger tags:** Story tags match workflow's `triggers.tags`
-3. **Type match:** Story type matches workflow's `triggers.types`
-4. **Points match:** Story points within `triggers.points` range
-5. **Default:** Workflow with `default: true` (tdd)
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `NAME` | No | Workflow name (auto-detects from active session if omitted) |
 
-## File Locations
+### `pf.sh workflow type`
 
-| Location | Purpose |
-|----------|---------|
-| `pennyfarthing-dist/workflows/` | Built-in workflow YAML definitions |
-| `.session/{story-id}-session.md` | Current story's workflow assignment |
+Get workflow type (phased, stepped, or procedural).
 
-## Creating Custom Workflows
+| Arg/Option | Required | Description |
+|------------|----------|-------------|
+| `WORKFLOW_NAME` | Yes | Workflow name (e.g., tdd, architecture) |
 
-See `pennyfarthing-dist/guides/workflow-schema.md` for the full YAML schema and `pennyfarthing-dist/guides/bikelane.md` for BikeLane stepped workflows.

package/pennyfarthing-dist/skills/skill-registry.yaml

@@ -214,27 +214,6 @@ skills:
     related_skills: [pf-cyclist]
     keywords: [opentelemetry, spans, traces, enrichment, correlation]
 
-  pf-permissions:
-    name: pf-permissions
-    description: Manage runtime permission grants - list, grant, and revoke tool access
-    category: project-management
-    tags: [permissions, security, tools]
-    version: "1.0.0"
-    command_group: permissions
-    prerequisites: []
-    examples:
-      - context: Viewing active grants
-        invocation: /permissions
-      - context: Granting WebFetch access
-        invocation: /permissions grant WebFetch "*.github.com"
-      - context: Revoking tool access
-        invocation: /permissions revoke Bash
-    anti_patterns:
-      - Don't manually edit settings.local.json permissions - use skill
-      - Don't grant overly broad scope patterns
-    related_skills: []
-    keywords: [grants, scopes, tools, runtime, security]
-
   pf-settings:
     name: pf-settings
     description: View and manage .pennyfarthing/config.local.yaml settings
@@ -389,6 +368,23 @@ skills:
     related_skills: [pf-theme]
     keywords: [personas, custom, generation, wizard]
 
+  pf-ux-tandem:
+    name: pf-ux-tandem
+    description: Live UX review tandem — spawn a UX designer to watch a tmux pane and suggest improvements in real time
+    category: development
+    tags: [ux, tandem, review, tmux, collaboration, team]
+    version: "1.0.0"
+    prerequisites: []
+    examples:
+      - context: Watch a TUI for usability issues
+        invocation: /pf-ux-tandem
+      - context: Watch a running app in another pane
+        invocation: /pf-ux-tandem
+    anti_patterns:
+      - Don't use for non-visual targets (use standard tandem-backseat for code review)
+    related_skills: [pf-code-review]
+    keywords: [ux, design, review, tandem, tmux, visual, usability, team]
+
   pf-workflow:
     name: pf-workflow
     description: Manage workflows - list, show, set, start, resume, and check status

package/pennyfarthing-dist/src/pf/CLAUDE.md

@@ -0,0 +1,213 @@
+# CLAUDE.md — pf CLI
+
+Python Click CLI for Pennyfarthing. Entry point: `pf/cli.py`. Invoked as `pf`.
+
+## Command Index
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint` | Sprint status and story operations | `sprint/cli.py` |
+| `pf jira` | Jira issue management | `jira/cli.py` |
+| `pf theme` | Persona theme management | `theme/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 | `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
+
+| Shortcut | Expands To |
+|----------|------------|
+| `pf status` | `pf sprint status` |
+| `pf backlog` | `pf sprint backlog` |
+| `pf work` | `pf sprint work` |
+| `pf story` | `pf sprint story` |
+
+## pf sprint
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint status [FILTER]` | Show sprint status. Filter: `all`, `backlog`, `in-progress`, `done`, `in-review` | `sprint/status.py` |
+| `pf sprint backlog` | Available stories grouped by epic | `sprint/cli.py` |
+| `pf sprint work [STORY_ID]` | Start work on a story (`next` for auto-select) | `sprint/work.py` |
+| `pf sprint check IDENTIFIER` | Check story/epic availability (JSON output) | `sprint/cli.py` |
+| `pf sprint info` | Sprint header as JSON | `sprint/cli.py` |
+| `pf sprint metrics` | Sprint metrics and velocity | `sprint/cli.py` |
+| `pf sprint future [EPIC_ID]` | Future initiatives overview | `sprint/cli.py` |
+| `pf sprint new` | Initialize a new sprint | `sprint/cli.py` |
+| `pf sprint archive STORY_ID PR` | Archive a completed story | `sprint/archive.py` |
+| `pf sprint standalone TITLE` | Wrap changes into standalone Jira story + PR | `sprint/cli.py` |
+| `pf sprint validate` | Validate sprint YAML | `sprint/validate_cmd.py` |
+
+### pf sprint story
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint story show ID` | Show story details | `sprint/cli.py` |
+| `pf sprint story add EPIC_ID TITLE POINTS` | Add story to epic | `sprint/story_add.py` |
+| `pf sprint story update ID [OPTIONS]` | Update story fields | `sprint/story_update.py` |
+| `pf sprint story field ID FIELD` | Get single field value | `sprint/cli.py` |
+| `pf sprint story size [POINTS]` | Sizing guidelines | `sprint/cli.py` |
+| `pf sprint story template [TYPE]` | Story templates | `sprint/cli.py` |
+| `pf sprint story finish ID` | Complete story (archive, merge, Jira) | `sprint/story_finish.py` |
+| `pf sprint story claim JIRA_KEY` | Claim/unclaim in Jira | `sprint/cli.py` |
+
+### pf sprint epic
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint epic show ID` | Show epic details | `sprint/cli.py` |
+| `pf sprint epic add ID TITLE` | Add new epic | `sprint/epic_add.py` |
+| `pf sprint epic update ID [OPTIONS]` | Update epic fields | `sprint/epic_update.py` |
+| `pf sprint epic field ID FIELD` | Get single field value | `sprint/cli.py` |
+| `pf sprint epic promote ID` | Move from future to current sprint | `sprint/cli.py` |
+| `pf sprint epic archive [ID]` | Archive completed epics | `sprint/archive_epic.py` |
+| `pf sprint epic cancel ID` | Cancel epic and all stories | `sprint/cli.py` |
+| `pf sprint epic import FILE` | Import BMAD epics to future.yaml | `sprint/import_epic.py` |
+| `pf sprint epic remove ID` | Remove from future.yaml | `sprint/cli.py` |
+
+### pf sprint initiative
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf sprint initiative show ID` | Show initiative details | `sprint/cli.py` |
+| `pf sprint initiative cancel ID` | Cancel initiative and all children | `sprint/cli.py` |
+
+## pf jira
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf jira view KEY` | View issue details | `jira/cli.py` |
+| `pf jira check KEY` | Check if story is available | `jira/cli.py` |
+| `pf jira claim KEY` | Assign to self + In Progress | `jira/claim.py` |
+| `pf jira assign KEY USER` | Assign to user (email or GitHub username) | `jira/cli.py` |
+| `pf jira move KEY STATUS` | Transition issue status | `jira/cli.py` |
+| `pf jira link KEY1 KEY2 [TYPE]` | Link two issues | `jira/cli.py` |
+| `pf jira search JQL` | Search by JQL | `jira/cli.py` |
+| `pf jira create epic EPIC_ID` | Create epic + children from YAML | `jira/epic.py` |
+| `pf jira create story EPIC_KEY STORY_ID` | Create single story under epic | `jira/story.py` |
+| `pf jira create standalone TITLE` | Create standalone story, add to sprint, Done | `jira/create.py` |
+| `pf jira sync EPIC_ID` | Sync YAML to Jira | `jira/sync.py` |
+| `pf jira bidirectional` | Bidirectional sync (Jira wins by default) | `jira/bidirectional.py` |
+| `pf jira reconcile` | Report mismatches between YAML and Jira | `jira/reconcile.py` |
+| `pf jira sprint add SPRINT_ID KEY` | Add issue to sprint | `jira/cli.py` |
+
+## pf theme
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf theme list` | All available themes | `theme/cli.py` |
+| `pf theme show [NAME]` | Theme details (current if no name) | `theme/cli.py` |
+| `pf theme set NAME` | Set active theme | `theme/cli.py` |
+| `pf theme create NAME` | Create custom theme from base | `theme/cli.py` |
+
+## pf bc
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf bc <panel>` | Focus panel (sprint, git, diffs, todo, workflow, background, audit-log, changed, ac, debug, settings, tty) | `bc/cli.py` |
+| `pf bc reset` | Clear focus | `bc/cli.py` |
+| `pf bc save NAME` | Save current layout | `bc/cli.py` |
+| `pf bc load NAME` | Load saved layout | `bc/cli.py` |
+| `pf bc list` | List saved layouts | `bc/cli.py` |
+| `pf bc clear NAME` | Delete layout | `bc/cli.py` |
+| `pf bc clear-all` | Delete all layouts | `bc/cli.py` |
+
+## pf validate
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf validate` | Run all validators | `validate/cli.py` |
+| `pf validate sprint` | Sprint YAML validation | `validate/cli.py` |
+| `pf validate schema` | XML schema validation | `validate/cli.py` |
+| `pf validate agent` | Agent definition validation | `validate/cli.py` |
+| `pf validate workflow` | Workflow definition validation | `validate/cli.py` |
+
+Options: `--fix` (auto-fix), `--strict` (warnings as errors)
+
+## pf agent
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf agent start NAME` | Start agent session with context | `prime/` |
+
+Options: `--session-id`, `--no-persona`, `--json`, `--minimal`, `--full`, `--quiet`, `--tier {full,refresh,handoff,minimal}`
+
+## pf workflow
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `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
+
+| Command | Description | Source |
+|---------|-------------|--------|
+| `pf bikerack start` | Start BikeRack + Claude CLI | `bikerack/cli.py` |
+| `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 |
+|---------|-------------|--------|
+| `pf debug hotspots analyze` | Full hotspot analysis | `hotspots/analyze.py` |
+| `pf debug hotspots files` | File-level hotspot report | `hotspots/cli.py` |
+| `pf debug hotspots dirs` | Directory-level hotspot report | `hotspots/cli.py` |
+| `pf debug deadcode stale` | Files with no recent commits | `deadcode/analyze.py` |
+| `pf debug deadcode exports` | Unused TypeScript exports | `deadcode/cli.py` |
+| `pf debug healthscore analyze` | Composite health score | `healthscore/cli.py` |
+
+## 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
+
+- **Framework:** Click (lazy-loaded groups for <200ms startup)
+- **Entry point:** `cli.py` registers all groups, `pyproject.toml` maps `pf` to `pf.cli:main`
+- **Pattern:** Each command group is a subpackage with `cli.py` defining Click commands and sibling modules for logic
+- **Output:** JSON for machine consumption (`--json`), formatted text for humans
+- **Dry run:** Most mutating commands support `--dry-run` to preview changes