# slabgorb/pennyfarthing architecture

> Architecture diagram of the GitHub repository slabgorb/pennyfarthing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/slabgorb/pennyfarthing
- Repository: https://github.com/slabgorb/pennyfarthing

## Overview

1. **Overall shape**
   - Pennyfarthing is a Python-first agent orchestration framework, not a single app. The repo is split between executable Python modules under `pennyfarthing-dist/src/pf` and a large bundle of declarative assets under `pennyfarthing-dist/{agents,commands,skills,gates,workflows,templates,guides}`.
   - The architecture is “engine + content”: Python code interprets workflows, while Markdown/YAML files define behavior, prompts, gates, and personas.

2. **Packaging boundary**
   - `pennyfarthing-dist` is the distributable runtime bundle. It contains the commands, agent definitions, workflow specs, gates, schemas, and helper scripts that get installed into a project’s local `.pennyfarthing/` and `.claude/` directories.
   - `src/pf/_dist` mirrors those bundled assets so the Python runtime can locate them consistently after install.

3. **CLI and bootstrap entry points**
   - The main user entry point is the `pf` CLI, implemented across many `pf/*/cli.py` modules and wired through package metadata in `pyproject.toml`.
   - Root-level `start-session`, `justfile`, and shell scripts in `scripts/` handle startup, bootstrapping, install-time setup, and developer convenience flows.

4. **Core orchestration runtime**
   - The central runtime concerns are agent activation, context assembly, session state, and handoff routing.
   - Key modules here include `prime`, `session`, `workflow`, `handoff`, `subagent`, and `consultation`. These coordinate when an agent starts, what context it receives, when it can hand off, and how background agents are spawned.

5. **Prime context system**
   - `pf.prime` is the context loader/assembler. It combines agent definitions, persona/theme data, workflow state, active session information, and sidecar memory.
   - The README’s tiered injection model is reflected in code under `src/pf/prime/*`, which reduces prompt size depending on whether this is a fresh start, a refresh, or an intra-workflow handoff.

6. **Workflow engine and gate model**
   - BikeLane workflows are the main process abstraction. Declarative workflow definitions live under `pennyfarthing-dist/workflows`, with `workflow.yaml` files, step markdown, and templates.
   - The runtime under `src/pf/workflow`, `src/pf/gate`, and `src/pf/gates` interprets those definitions, evaluates gates, and advances phases. This is how phased workflows like TDD, BDD, release, and git cleanup are enforced.

7. **Persistent project state**
   - The framework writes and reads local project state in `.pennyfarthing/`, `.claude/`, `sprint/`, and `.session/` when installed in a target repo.
   - Session handling is append-oriented and file-based (`src/pf/session`), while sidecars and sprint artifacts preserve learning, story progress, and workflow continuity across sessions.

8. **Integration layer**
   - External service integration is explicit and modular: Jira sync and reconciliation live in `src/pf/jira`, Git/worktree manipulation in `src/pf/git`, repo topology in `src/pf/sprint` and `src/pf/brownfield`, and release/deploy support in `src/pf/release` and `src/pf/package`.
   - These integrations are mostly adapter-style modules, with shell helpers in `pennyfarthing-dist/scripts/{git,jira,workflow,hooks,...}` acting as operational glue.

9. **Frame TUI and observability**
   - Frame is the interactive visibility layer. `src/pf/frame` is a FastAPI/uvicorn server with API routes, WebSocket channels, and OTLP ingestion; it powers real-time panels and telemetry.
   - The `src/pf/tui` package is the Textual-based terminal UI client. It consumes Frame data to render sprint status, diffs, git state, audit logs, debug info, and other live panels.

10. **Analysis, quality, and benchmarking**
   - There is a substantial analysis subsystem: hotspots, dead code, dependencies, codemarkers, complexity, health score, findings aggregation, and reviewer templates all live in dedicated modules.
   - Benchmarking is a separate pipeline under `src/pf/benchmark`, with scenario validation, judge aggregation, variance analysis, and replay support. The checked-in `benchmarks/results` directory stores historical outputs and scoring artifacts.

11. **Assets, schemas, and governance**
   - The framework is heavily schema-driven: personas, themes, workflows, gates, skills, and session/context formats all have dedicated YAML/Markdown schemas in `pennyfarthing-dist` and `src/pf/schemas`.
   - This makes the repo diagrammatic: Python code is the control plane, while the content files are the policy/data plane.

12. **Testing and release discipline**
   - The repo has layered validation: Python unit tests in `src/pf/tests`, broader Python integration tests in `tests/python`, shell/integration tests, and end-to-end scenarios under `tests/e2e`.
   - Release and upgrade flows are explicit modules and scripts, which suggests the project treats packaging integrity, install safety, and backward compatibility as first-class architectural concerns.

Main entry points: [`pennyfarthing-dist/src/pf/prime`](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/prime) (Prime), [`pennyfarthing-dist/scripts`](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/scripts) (Scripts), [`pennyfarthing-dist/src/pf/cli.py`](https://github.com/slabgorb/pennyfarthing/blob/develop/pennyfarthing-dist/src/pf/cli.py) (pf CLI), [`pennyfarthing-dist/src/pf/workflow`](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/workflow) (Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_node_cli["pf CLI<br/>entrypoint<br/>[cli.py]"]
  node_node_init["Bootstrap<br/>setup"]
  node_node_prime["Prime<br/>context loader"]
  node_node_session[("Session<br/>state store")]
  node_node_workflow["Workflow<br/>engine"]
  node_node_handoff["Handoff<br/>routing"]
  node_node_subagent["Subagents<br/>spawn"]
  node_node_peloton["Peloton<br/>orchestration"]
end

subgraph group_group_content["Content bundle"]
  node_node_agents["Agents<br/>persona pack"]
  node_node_commands["Commands<br/>command pack"]
  node_node_skills["Skills<br/>skill pack"]
  node_node_workflows_content["Workflows<br/>workflow specs"]
  node_node_gates["Gates<br/>policy pack"]
  node_node_personas["Personas<br/>theme system"]
  node_node_scripts["Scripts<br/>shell glue"]
  node_node_schemas["Schemas<br/>contracts"]
end

subgraph group_group_observability["Observability"]
  node_node_frame["Frame<br/>server"]
  node_node_tui["TUI<br/>client"]
end

subgraph group_group_integrations["Integrations"]
  node_node_git["Git<br/>repo adapter"]
  node_node_jira["Jira<br/>integration"]
  node_node_release["Release<br/>packaging"]
end

subgraph group_group_quality["Quality"]
  node_node_benchmark["Benchmark<br/>pipeline"]
  node_node_analysis["Analysis<br/>inspection"]
  node_node_validate["Validate<br/>policy checker"]
end

node_node_cli -->|"prime"| node_node_prime
node_node_cli -->|"workflow"| node_node_workflow
node_node_cli -->|"handoff"| node_node_handoff
node_node_cli -->|"bootstrap"| node_node_init
node_node_cli -->|"release"| node_node_release
node_node_prime -->|"reads state"| node_node_session
node_node_prime -->|"reads workflow"| node_node_workflow
node_node_prime -->|"loads persona"| node_node_personas
node_node_prime -->|"validates"| node_node_schemas
node_node_workflow -->|"interprets"| node_node_workflows_content
node_node_workflow -->|"evaluates"| node_node_gates
node_node_handoff -->|"updates state"| node_node_session
node_node_handoff -->|"resolves"| node_node_gates
node_node_subagent -->|"context"| node_node_prime
node_node_subagent -->|"before/after"| node_node_gates
node_node_peloton -->|"publishes"| node_node_frame
node_node_frame -->|"serves"| node_node_tui
node_node_tui -->|"reads state"| node_node_session
node_node_tui -->|"subscribes"| node_node_frame
node_node_git -->|"hooks"| node_node_scripts
node_node_jira -->|"glue"| node_node_scripts
node_node_release -->|"release ops"| node_node_scripts
node_node_benchmark -->|"checks"| node_node_validate
node_node_analysis -->|"reports"| node_node_validate
node_node_validate -->|"contracts"| node_node_schemas
node_node_scripts -->|"imports"| node_node_workflows_content
node_node_scripts -->|"installs"| node_node_agents
node_node_scripts -->|"installs"| node_node_personas

click node_node_cli "https://github.com/slabgorb/pennyfarthing/blob/develop/pennyfarthing-dist/src/pf/cli.py"
click node_node_init "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/init"
click node_node_prime "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/prime"
click node_node_session "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/session"
click node_node_workflow "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/workflow"
click node_node_handoff "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/handoff"
click node_node_subagent "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/subagent"
click node_node_peloton "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/peloton"
click node_node_frame "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/frame"
click node_node_tui "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/tui"
click node_node_agents "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/agents"
click node_node_commands "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/commands"
click node_node_skills "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/skills"
click node_node_workflows_content "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/workflows"
click node_node_gates "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/gates"
click node_node_personas "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/personas"
click node_node_scripts "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/scripts"
click node_node_schemas "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/schemas"
click node_node_git "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/git"
click node_node_jira "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/jira"
click node_node_release "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/release"
click node_node_benchmark "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/benchmark"
click node_node_analysis "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf"
click node_node_validate "https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/validate"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_init,node_node_prime,node_node_session,node_node_workflow,node_node_handoff,node_node_subagent,node_node_peloton toneBlue
class node_node_agents,node_node_commands,node_node_skills,node_node_workflows_content,node_node_gates,node_node_personas,node_node_scripts,node_node_schemas toneAmber
class node_node_frame,node_node_tui toneMint
class node_node_git,node_node_jira,node_node_release toneRose
class node_node_benchmark,node_node_analysis,node_node_validate toneIndigo
```

## Components

### Runtime

Python control plane and execution flow

- [pf CLI](https://github.com/slabgorb/pennyfarthing/blob/develop/pennyfarthing-dist/src/pf/cli.py): entrypoint · Main command surface and subcommand dispatch · `pennyfarthing-dist/src/pf/cli.py`
- [Bootstrap](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/init): setup · Install-time/project bootstrap and local scaffolding · `pennyfarthing-dist/src/pf/init`
- [Prime](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/prime): context loader · Builds agent context from session, persona, workflow, and memory · `pennyfarthing-dist/src/pf/prime`
- [Session](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/session): state store · Append-only project/session state and path handling · `pennyfarthing-dist/src/pf/session`
- [Workflow](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/workflow): engine · Interprets workflow state, step gates, and lifecycle progression · `pennyfarthing-dist/src/pf/workflow`
- [Handoff](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/handoff): routing · Completes phases, resolves gates, and routes between agents · `pennyfarthing-dist/src/pf/handoff`
- [Subagents](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/subagent): spawn · Loads, prompts, spawns, and chains background agents · `pennyfarthing-dist/src/pf/subagent`
- [Peloton](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/peloton): orchestration · Multi-pane workflow driver and live result aggregation · `pennyfarthing-dist/src/pf/peloton`

### Content bundle

Declarative assets interpreted by the runtime

- [Agents](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/agents): persona pack · Declarative agent personas and role variants · `pennyfarthing-dist/agents`
- [Commands](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/commands): command pack · User-facing command definitions and CLI prompts · `pennyfarthing-dist/commands`
- [Skills](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/skills): skill pack · Reusable capability docs and usage guides · `pennyfarthing-dist/skills`
- [Workflows](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/workflows): workflow specs · Declarative workflow definitions, steps, templates, and rules · `pennyfarthing-dist/workflows`
- [Gates](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/gates): policy pack · Declarative gate checks and workflow constraints · `pennyfarthing-dist/gates`
- [Personas](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/personas): theme system · Theme, portrait, and persona calibration assets · `pennyfarthing-dist/personas`
- [Scripts](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/scripts): shell glue · Operational shell helpers for install, hooks, workflow, git, and jira · `pennyfarthing-dist/scripts`
- [Schemas](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/schemas): contracts · Shared markdown/YAML schemas for context, session, gate, and workflow data · `pennyfarthing-dist/schemas`

### Observability

Live UI and telemetry surfaces

- [Frame](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/frame): server · FastAPI/uvicorn visibility server with routes, websockets, and OTLP · `pennyfarthing-dist/src/pf/frame`
- [TUI](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/tui): client · Textual terminal client for live sprint, git, and debug panels · `pennyfarthing-dist/src/pf/tui`

### Integrations

Adapters for external systems and repo operations

- [Git](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/git): repo adapter · Worktree, snapshot, status, and hook installation helpers · `pennyfarthing-dist/src/pf/git`
- [Jira](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/jira): integration · Bidirectional Jira create, sync, claim, and reconcile flows · `pennyfarthing-dist/src/pf/jira`
- [Release](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/release): packaging · Versioning, contents verification, and release/deprecation flows · `pennyfarthing-dist/src/pf/release`

### Quality

Analysis, benchmark, validation, and release tooling

- [Benchmark](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/benchmark): pipeline · Scenario validation, judging, aggregation, replay, and variance analysis · `pennyfarthing-dist/src/pf/benchmark`
- [Analysis](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf): inspection · Hotspots, complexity, dependencies, dead code, codemarkers, and health scoring · `pennyfarthing-dist/src/pf`
- [Validate](https://github.com/slabgorb/pennyfarthing/tree/develop/pennyfarthing-dist/src/pf/validate): policy checker · Cross-cutting repository validation adapters and CLI · `pennyfarthing-dist/src/pf/validate`

## Connections

- pf CLI → Prime: prime · Builds execution context before agent activity
- pf CLI → Workflow: workflow · Dispatches workflow commands and phase control
- pf CLI → Handoff: handoff · Runs handoff and phase-completion operations
- pf CLI → Bootstrap: bootstrap · Sets up a new project installation
- pf CLI → Release: release · Exposes packaging and release commands
- Prime → Session: reads state · Consumes session and sidecar state
- Prime → Workflow: reads workflow · Injects workflow phase and step context
- Prime → Personas: loads persona · Selects theme/persona data for activation
- Prime → Schemas: validates · Uses structured contracts for generated context
- Workflow → Workflows: interprets · Executes declarative workflow definitions
- Workflow → Gates: evaluates · Checks gate policy at step boundaries
- Handoff → Session: updates state · Writes phase transitions and session artifacts
- Handoff → Gates: resolves · Evaluates and resolves gate files
- Subagents → Prime: context · Creates per-subagent prompt/context bundles
- Subagents → Gates: before/after · Enforces gate checks around subagent execution
- Peloton → Frame: publishes · Streams live orchestration state to Frame
- Frame → TUI: serves · Provides data and events consumed by the terminal UI
- TUI → Session: reads state · Displays local session and sprint artifacts
- TUI → Frame: subscribes · Consumes live panels, telemetry, and websocket updates
- Git → Scripts: hooks · Backs shell helpers for git/worktree operations
- Jira → Scripts: glue · Uses shell helpers for Jira synchronization flows
- Release → Scripts: release ops · Orchestrates release-time shell operations
- Benchmark → Validate: checks · Validates scenarios, scoring, and replay artifacts
- Analysis → Validate: reports · Feeds findings into validation and scoring workflows
- Validate → Schemas: contracts · Checks repository artifacts against shared schemas
- Scripts → Workflows: imports · Bootstraps workflow assets into target repos
- Scripts → Agents: installs · Installs or syncs agent definitions
- Scripts → Personas: installs · Installs or syncs persona and portrait assets