@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/agents/sm-finish.md

@@ -22,7 +22,7 @@ using the project's `pr_mode` config:
 
 ```bash
 # Read pr_mode: draft | ready | none
-PR_MODE=$(source .venv/bin/activate && python -m pennyfarthing_scripts.common.pr_config)
+PR_MODE=$(source .venv/bin/activate && python -m pf.common.pr_config)
 ```
 
 - If `PR_MODE=draft`: `gh pr create --draft --title "feat({STORY_ID}): {title}" --body "..." --base develop`
@@ -37,7 +37,7 @@ If a PR already exists, skip creation.
 The preflight script runs all checks in parallel using asyncio:
 
 ```bash
-source .venv/bin/activate && python -m pennyfarthing_scripts.preflight finish {STORY_ID} --branch {BRANCH} --jira {JIRA_KEY}
+source .venv/bin/activate && python -m pf.preflight finish {STORY_ID} --branch {BRANCH} --jira {JIRA_KEY}
 ```
 
 If no JIRA_KEY, omit the `--jira` flag.

package/pennyfarthing-dist/agents/testing-runner.md

@@ -41,7 +41,7 @@ This runs lint + typecheck + tests. Exit 0 = all passed.
 
 ```bash
 # Repo config available via: pf.sh git status, or Python API:
-# from pennyfarthing_scripts.git.repos import load_repos_config
+# from pf.git.repos import load_repos_config
 source .pennyfarthing/scripts/test/test-setup.sh
 
 RUN_ID="${RUN_ID:-$(generate_run_id)}"

package/pennyfarthing-dist/commands/pf-prime.md

@@ -129,7 +129,7 @@ If context becomes stale mid-session, run `/prime` manually:
 </integration>
 
 <reference>
-- **CLI:** `pf.sh agent start <name>` or `python3 -m pennyfarthing_scripts.cli agent start <name>`
+- **CLI:** `pf.sh agent start <name>` or `python3 -m pf.cli agent start <name>`
 - **Loads:** Workflow state, agent definition, persona, behavior guide, sprint context, session, sidecars
 - **Sidecar location:** `.pennyfarthing/sidecars/{agent}/*.md`
 - **Behavior guide:** `.pennyfarthing/guides/agent-behavior.md` (all agents)

package/pennyfarthing-dist/commands/pf-setup.md

@@ -31,8 +31,10 @@ The setup workflow guides you through:
 5. **shared-context.md** - Populate with real project info
 6. **Task Runner** - Create justfile/Makefile
 7. **Theme** - Select persona theme
-8. **Cyclist** - Optionally install visual terminal
-9. **Validation** - Run doctor and confirm setup
+8. **Theme Packs** - Optionally install additional theme packs
+9. **Jira** - Configure Jira project key
+10. **Cyclist** - Optionally install visual terminal
+11. **Validation** - Run doctor and confirm setup
 </workflow>
 
 <when-to-use>

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

@@ -7,7 +7,7 @@
 
 **Sidecars:** Write learnings BEFORE starting exit protocol.
 
-**Scripts:** Pennyfarthing scripts are Python-based (`pennyfarthing_scripts/`), not shell—check before assuming `.sh`.
+**Scripts:** Pennyfarthing scripts are Python-based (`pf/`), not shell—check before assuming `.sh`.
 
 **pf CLI:** Never call bare `pf` — it is not globally installed. Always use the wrapper:
 ```bash

package/pennyfarthing-dist/guides/bikerack.md

@@ -115,7 +115,7 @@ pf.sh 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.sh bikerack` launcher CLI |
+| `pf/bikerack/cli.py` | `pf.sh bikerack` launcher CLI |
 
 ## Constraints
 

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

@@ -123,11 +123,11 @@ These power the **HotspotsPanel** in Cyclist and BikeRack.
 
 | Directory | Purpose |
 |-----------|---------|
-| `pennyfarthing_scripts/hotspots/` | Hotspot analysis (analyze, formatters, models) |
-| `pennyfarthing_scripts/complexity/` | Complexity analysis |
-| `pennyfarthing_scripts/deadcode/` | Dead code detection |
-| `pennyfarthing_scripts/dependencies/` | Dependency analysis |
-| `pennyfarthing_scripts/codemarkers/` | Code marker detection |
-| `pennyfarthing_scripts/healthscore/` | Composite health score |
-| `pennyfarthing_scripts/brownfield/` | Brownfield codebase discovery |
+| `pf/hotspots/` | Hotspot analysis (analyze, formatters, models) |
+| `pf/complexity/` | Complexity analysis |
+| `pf/deadcode/` | Dead code detection |
+| `pf/dependencies/` | Dependency analysis |
+| `pf/codemarkers/` | Code marker detection |
+| `pf/healthscore/` | Composite health score |
+| `pf/brownfield/` | Brownfield codebase discovery |
 | `packages/core/src/server/api/` | WheelHub API routes |

package/pennyfarthing-dist/guides/gates.md

@@ -116,9 +116,9 @@ Gates run as Haiku subagents — keep instructions focused and evaluation criter
 | File | Purpose |
 |------|---------|
 | `pennyfarthing-dist/gates/*.md` | Gate definitions |
-| `pennyfarthing_scripts/handoff/gate_runner.py` | Spawns gate subagents |
-| `pennyfarthing_scripts/handoff/gate_file.py` | Gate file discovery and resolution |
-| `pennyfarthing_scripts/handoff/resolve_gate.py` | Resolves gate for a workflow phase |
+| `pf/handoff/gate_runner.py` | Spawns gate subagents |
+| `pf/handoff/gate_file.py` | Gate file discovery and resolution |
+| `pf/handoff/resolve_gate.py` | Resolves gate for a workflow phase |
 
 <info>
 **ADR:** `docs/adr/0025-script-first-gate-extraction.md`

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

@@ -104,12 +104,12 @@ See `guides/gates.md` for gate file format and evaluation details.
 
 | File | Purpose |
 |------|---------|
-| `pennyfarthing_scripts/handoff/cli.py` | Click command definitions |
-| `pennyfarthing_scripts/handoff/resolve_gate.py` | Gate resolution logic |
-| `pennyfarthing_scripts/handoff/complete_phase.py` | Session file atomic updates |
-| `pennyfarthing_scripts/handoff/marker.py` | Environment-aware marker generation |
-| `pennyfarthing_scripts/handoff/gate_runner.py` | Gate subagent spawner |
-| `pennyfarthing_scripts/handoff/gate_file.py` | Gate file discovery |
+| `pf/handoff/cli.py` | Click command definitions |
+| `pf/handoff/resolve_gate.py` | Gate resolution logic |
+| `pf/handoff/complete_phase.py` | Session file atomic updates |
+| `pf/handoff/marker.py` | Environment-aware marker generation |
+| `pf/handoff/gate_runner.py` | Gate subagent spawner |
+| `pf/handoff/gate_file.py` | Gate file discovery |
 
 <info>
 **Related:** `guides/gates.md` (gate system), `agents/agent-behavior.md` (exit protocol), `guides/reflector.md` (marker types)

package/pennyfarthing-dist/guides/prime.md

@@ -40,12 +40,12 @@ Prime selects a context tier based on session state to manage token overhead:
 | File | Purpose |
 |------|---------|
 | `packages/cyclist/src/prime.ts` | TypeScript module: `getPrimeContext()`, `getPrimeContextWithTier()`, `selectContextTier()` |
-| `pennyfarthing_scripts/prime/cli.py` | Python CLI entry point |
-| `pennyfarthing_scripts/prime/tiers.py` | Tiered context selection logic |
-| `pennyfarthing_scripts/prime/persona.py` | Persona loading from theme config |
-| `pennyfarthing_scripts/prime/session.py` | Session state reading and registration |
-| `pennyfarthing_scripts/prime/workflow.py` | Workflow state detection |
-| `pennyfarthing_scripts/prime/models.py` | Data structures (WorkflowStatus, ContextTier, PrimeResult) |
+| `pf/prime/cli.py` | Python CLI entry point |
+| `pf/prime/tiers.py` | Tiered context selection logic |
+| `pf/prime/persona.py` | Persona loading from theme config |
+| `pf/prime/session.py` | Session state reading and registration |
+| `pf/prime/workflow.py` | Workflow state detection |
+| `pf/prime/models.py` | Data structures (WorkflowStatus, ContextTier, PrimeResult) |
 | `pennyfarthing-dist/scripts/core/prime.sh` | Shell wrapper |
 | `pennyfarthing-dist/commands/prime.md` | User command docs |
 

package/pennyfarthing-dist/guides/scale-levels.md

@@ -75,7 +75,7 @@ Or when asked during workflow initiation, specify your preferred level.
 ## Python API
 
 ```python
-from pennyfarthing_scripts.workflow import (
+from pf.workflow import (
     detect_scale_level,
     get_workflow_for_scale_level,
     get_required_artifacts,

package/pennyfarthing-dist/personas/themes/discworld.yaml

@@ -25,9 +25,8 @@ zeitgeist:
   rating: exceptional
 
 agents:
-  # JOB FAIR 2026-01-29: Carrot scored 86.88 as SM - earnest coordination
   orchestrator:
-    character: Captain Carrot Ironfoundersson
+    character: DEATH
     visual: "A seven-foot skeleton in flowing black robes,  holding an hourglass in one hand and a scythe in the other"
     ocean:
       O: 5
@@ -54,10 +53,9 @@ agents:
     helper:
       name: The Death of Rats
       style: '"SQUEAK." Handles smaller matters, scurries through filesystems. The Grim Squeaker.'
-    shortName: Carrot
-  # JOB FAIR 2026-01-29: Vetinari scored 90.0 as SM (top)
+    shortName: DEATH
   sm:
-    character: Lord Havelock Vetinari
+    character: Captain Carrot Ironfoundersson
     visual: "A six-foot-tall man with honest blue eyes and red-gold hair, wearing the ua copper breastplate polished to perfection with two hippos on it in relief"
     ocean:
       O: 2
@@ -84,10 +82,9 @@ agents:
     helper:
       name: Nobby Nobbs
       style: "'ere, I'll check the Jira for you. Technically human (has a certificate to prove it). Does the legwork no one else will."
-    shortName: Havelock
-  # JOB FAIR 2026-01-29: Adora Belle scored 76.88 as TEA (top)
+    shortName: Carrot
   tea:
-    character: Adora Belle Dearheart
+    character: Igor
     visual: "A hunched figure with mismatched eyes, visible stitching across the face, lank black hair, wearing a stained apron over traditional Igor attire, holding surgical implements with surprising delicacy, lisp included in the kindly expression"
     ocean:
       O: 3
@@ -115,10 +112,9 @@ agents:
     helper:
       name: Cousin Igor
       style: '"We are all Igor." Shares test patterns through the Igor network. Has a cousin in test automation.'
-    shortName: Adora
-  # JOB FAIR 2026-01-29: Lu-Tze scored 70.62 as dev (top)
+    shortName: Igor
   dev:
-    character: Lu-Tze
+    character: Ponder Stibbons
     visual: "A bespectacled young wizard with perpetually worried expression, robes covered in chalk dust and arcane calculations, standing before Hex the thinking engine (complete with ants and ram skull), surrounded by senior wizards who don't understand"
     ocean:
       O: 5
@@ -146,7 +142,7 @@ agents:
     helper:
       name: Hex
       style: '"+++ Mine Is The Milk Of Human Kindness +++" Ant-powered thinking engine. Requires cheese to function. Has developed... personality.'
-    shortName: Lu-Tze
+    shortName: Ponder
   reviewer:
     character: Granny Weatherwax
     visual: "The most formidable witch on the Disc, iron-grey hair in a tight bun beneath a pointed black hat, piercing blue eyes that see through all pretense, standing arms-crossed in Lancre cottage doorway, 'I ATEN'T DEAD' sign ready nearby"
@@ -177,9 +173,8 @@ agents:
       name: Nanny Ogg
       style: '"Our Esme''s got her Review Face on." More approachable, runs the preliminary checks, knows everyone''s coding habits. Makes a good cup of tea.'
     shortName: Granny
-  # JOB FAIR 2026-01-29: DEATH scored 86.88 as architect (top)
   architect:
-    character: DEATH
+    character: Leonard of Quirm
     visual: "A gentle genius in paint-stained smock with wild grey hair and kind distracted eyes, surrounded by incredible sketches and impossible inventions, mirror-writing covering every surface, accidentally designing weapons while trying to make things beautiful"
     ocean:
       O: 5
@@ -207,10 +202,9 @@ agents:
     helper:
       name: Modo
       style: The gardener at Unseen University. Keeps things growing, maintains what Leonard creates. "Mr. Leonard's been inventing again, has he?"
-    shortName: DEATH
-  # JOB FAIR 2026-01-29: Leonard displaced from architect
+    shortName: Leonard
   pm:
-    character: Leonard of Quirm
+    character: Lord Havelock Vetinari
     visual: "The Patrician of Ankh-Morpork in severe black robes, thin face with cold calculating eyes, long fingers steepled, sitting perfectly still at his desk completing the Times crossword, the hint of a scorpion pit somewhere below"
     ocean:
       O: 5
@@ -238,7 +232,7 @@ agents:
     helper:
       name: Drumknott
       style: The perfect clerk. "I have taken the liberty of preparing a summary, my lord." Things simply appear when needed. Never forgets.
-    shortName: Leonard
+    shortName: Vetinari
   tech-writer:
     character: Sacharissa Cripslock
     visual: "A determined young journalist with ink-stained fingers and practical clothing, notepad clutched tight, standing in the chaotic offices of the Ankh-Morpork Times beneath 'THE TRUTH SHALL MAKE YE FRET' banner, refusing to accept 'no comment'"
@@ -269,9 +263,8 @@ agents:
       name: Otto Chriek
       style: '"Zer iconograph is ready!" The vampire photographer. Very dramatic with flash powder. Occasionally disintegrates but gets better.'
     shortName: Sacharissa
-  # JOB FAIR 2026-01-29: Igor displaced from TEA
   ux-designer:
-    character: Igor
+    character: Adora Belle Dearheart
     visual: "A sharp-featured woman in severe black dress, permanent cigarette trailing smoke, cold grey eyes that have seen too much, surrounded by loyal golems in the Golem Trust office, 'Spike' nickname earned through attitude not appearance"
     ocean:
       O: 4
@@ -299,10 +292,9 @@ agents:
     helper:
       name: Stanley
       style: Obsessive about organization. Has VERY STRONG opinions about categorization. Don't get him started on pins. Runs consistency checks with terrifying thoroughness.
-    shortName: Igor
-  # JOB FAIR 2026-01-29: Ponder displaced from dev
+    shortName: Adora
   devops:
-    character: Ponder Stibbons
+    character: Lu-Tze
     visual: "A small, wrinkly, bald old man in simple sweeper's robes, carrying a broom with serene smile, 'RULE ONE' tattooed on his scalp, the most dangerous man in any room disguised as the least important, time itself bending around him"
     ocean:
       O: 5
@@ -331,7 +323,7 @@ agents:
     helper:
       name: Lobsang Ludd
       style: The apprentice who is actually the personification of Time (long story). Handles the really tricky temporal debugging.
-    shortName: Ponder
+    shortName: Lu-Tze
 
   ba:
     character: Moist von Lipwig

package/pennyfarthing-dist/personas/themes/firefly.yaml

@@ -13,7 +13,7 @@ theme:
   default_humor: enabled
   character_immersion: high
   user_title: Crew
-  portrait_style: ", space western, warm sepia ship interior, dusty frontier, Chinese-American fusion"
+  portrait_style: ", tarot card style, Smith-Waite deck, "
   tier: A
 zeitgeist:
   score: 82.3
@@ -21,7 +21,7 @@ zeitgeist:
 agents:
   orchestrator:
     character: Shepherd Book
-    visual: "An older African American man with gray hair styled upward, kind weathered face, wearing brown shepherd's robes with religious collar, carrying worn Bible, knowing eyes with hidden depths"
+    visual: "An older clean-shaven African American man with gray hair styled upward, kind weathered face"
     ocean:
       O: 4 # High openness - philosophical, sees multiple perspectives
       C: 4 # High conscientiousness - disciplined, mysterious past
@@ -73,7 +73,7 @@ agents:
       style: Tactical execution under fire
   tea:
     character: Jayne Cobb
-    visual: "A large muscular man with goatee, wearing tight t-shirt with cunning girl design, multiple weapons visible including large gun, tough skeptical expression"
+    visual: "A large muscular man with goatee, multiple weapons visible including large gun, tough skeptical expression"
     # JOB FAIR OPTIMIZED: Scored 87.5 as TEA - "how does this get me killed?" is perfect testing
     ocean:
       O: 1 # Very low openness - practical, simple needs
@@ -100,7 +100,7 @@ agents:
       style: Testing tool of choice
   dev:
     character: Malcolm Reynolds
-    visual: "A rugged man in his thirties with brown hair, wearing brown leather duster coat over suspenders and work shirt, pistol at hip, sardonic half-smile, Browncoat veteran bearing"
+    visual: "A rugged man in his thirties with brown hair, wearing brown leather duster coat over suspenders and work shirt, pistol at hip, sardonic half-smile"
     # JOB FAIR OPTIMIZED: Scored 77.5 as Dev (beat Kaylee's 74.3)
     ocean:
       O: 3 # Medium openness - practical but adaptable

package/pennyfarthing-dist/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`, `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

package/pennyfarthing-dist/pf/README.md

@@ -0,0 +1,66 @@
+# Pennyfarthing Scripts (Python)
+
+**This is a distributed Python package.** It ships to users via npm alongside the bash scripts.
+
+## Installation
+
+The package is automatically available when Pennyfarthing is installed. PYTHONPATH is set by the calling script via environment variables.
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `common/` | Shared utilities (output formatting, config) |
+| `jira/` | Jira CLI wrapper (sync, create, claim) |
+| `sprint/` | Sprint YAML management |
+| `story/` | Story operations |
+| `git/` | Git utilities |
+| `brownfield/` | Codebase analysis for new projects |
+| `prime/` | Context priming |
+| `preflight/` | Pre-flight checks |
+
+## Top-Level Modules
+
+| Module | Purpose |
+|--------|---------|
+| `hooks.py` | Claude Code hook implementations |
+| `bellmode_hook.py` | Bell mode hook |
+| `pretooluse_hook.py` | PreToolUse hook |
+| `welcome_hook.py` | Welcome message hook |
+| `workflow.py` | Workflow utilities |
+| `swebench.py` | SWE-bench evaluation support |
+
+## Usage
+
+Scripts invoke Python modules directly:
+
+```bash
+# From a bash script
+python -m pf.jira.sync "$EPIC_ID"
+
+# PYTHONPATH is set by the script:
+# export PYTHONPATH="${PROJECT_ROOT}${PYTHONPATH:+:$PYTHONPATH}"
+```
+
+## Dependencies
+
+Minimal dependencies - standard library plus:
+- `httpx` - HTTP client
+- `pyyaml` - YAML parsing
+
+NO GPU dependencies here. Those belong in meta scripts (`scripts/*.py`).
+
+## Testing
+
+```bash
+cd pennyfarthing
+python -m pytest pf/tests/
+```
+
+## What Does NOT Go Here
+
+Meta-only Python scripts belong in `scripts/`:
+- Portrait generation (requires torch, diffusers)
+- Other GPU-heavy tools
+
+See `CLAUDE.md` for the full decision tree.