slabgorb/pennyfarthing

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.