@pennyfarthing/core 11.3.3 → 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/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/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.