@pennyfarthing/core 7.5.0 → 7.6.0

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 1898 & Co.
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of this Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+the copyright holder.
+
+Unauthorized copying, modification, distribution, or use of this Software, via
+any medium, is strictly prohibited.
+
+For licensing inquiries, contact: 1898 & Co.

package/README.md

@@ -0,0 +1,301 @@
+# Pennyfarthing
+
+**v7.0.0** | *The outer loop goes once, the inner loop goes many times.*
+
+<img src="pennyfarthing.png" alt="Pennyfarthing Logo" width="75" style="float:left; margin:10px" margin="10px">
+
+A Claude Code agent orchestration framework with TDD workflow and themed personas. Install via npm, configure once, and let coordinated agents guide your development.
+
+---
+
+### [**Browse 102 Themes in the Interactive Showcase**](https://animated-meme-3e4494y.pages.github.io/)
+
+Explore all themes with OCEAN spider charts and 1020 character profiles.
+
+---
+
+## Features
+
+- **24 Agents** - Strategic (PM, Architect) and tactical (SM, TEA, Dev, Reviewer) agents with official Haiku-based subagents for mechanical tasks
+- **Automatic Handoffs** - Context-aware agent transitions via official subagent format
+- **102 Persona Themes** - Star Trek, Breaking Bad, Dune, The Office, Game of Thrones, Arthurian Mythos, and more with OCEAN personality profiles
+- **20 Skills** - Reusable knowledge domains (testing, code-review, judge, jira, etc.)
+- **43 Slash Commands** - Entry points for agent activation, benchmarking, and workflows
+- **Scientific Benchmarking** - Evaluate personas against standardized scenarios with statistical analysis
+- **CLI Tool** - `pennyfarthing init`, `update`, `doctor`, `uninstall`, `theme`
+
+## Quick Start
+
+```bash
+cd your-project
+
+# Install CLI (1.1 MB)
+npm install --save-dev @pennyfarthing/core
+
+# Initialize (creates symlinks, no file copying)
+npx pennyfarthing init
+
+# Verify installation
+npx pennyfarthing doctor
+
+# Start working (in Claude Code)
+/new-work
+```
+
+### Optional: Visual Terminal
+
+For the Cyclist visual terminal with agent portraits and rich UI:
+
+```bash
+# Install optional visual terminal (160 MB, includes portraits)
+npm install --save-dev @pennyfarthing/cyclist
+
+# Launch Cyclist
+npx pennyfarthing cyclist
+```
+
+## The TDD Flow
+
+```
+/new-work → SM → TEA → Dev → Reviewer → SM (finish)
+             │     │     │       │
+          setup  tests  impl   review
+```
+
+| Agent | Role | Phase |
+|-------|------|-------|
+| **SM** | Scrum Master | Story selection, session setup, completion |
+| **TEA** | Test Engineer | Write failing tests (RED) |
+| **Dev** | Developer | Make tests pass (GREEN) |
+| **Reviewer** | Code Reviewer | Quality validation, approve/reject |
+
+Handoffs are automatic when context usage is below 70%. Above that threshold, agents recommend starting a fresh session.
+
+## Cyclist - Visual Terminal
+
+Cyclist is the visual companion to Pennyfarthing - a rich UI that wraps Claude Code with real-time agent personas, session stats, and workflow visualization.
+
+```bash
+# Install (optional, 160 MB with portraits)
+npm install --save-dev @pennyfarthing/cyclist
+
+# Launch
+npx pennyfarthing cyclist
+```
+
+### Features
+
+- **Real-time Persona Display** - Character portraits and OCEAN personality profiles update as agents change
+- **Session Statistics** - Token usage (input/output), context percentage, model info
+- **Story Progress** - Visual TDD workflow tracker (SM → TEA → Dev → Reviewer)
+- **Task Visualizer** - Live todo list from Claude's TodoWrite tool
+- **Rich Text Editor** - TipTap-based prompt editor with formatting
+- **Tab Panel** - Diff viewer, file browser, workspace tools
+
+### Architecture
+
+Cyclist uses Electron with an Express server for the UI:
+
+| Component | Purpose |
+|-----------|---------|
+| `main.ts` | Electron main process, IPC handlers, PTY spawn |
+| `preload.ts` | Secure IPC bridge via contextBridge |
+| `pennyfarthing.ts` | Theme loading, persona detection |
+| `claude-service.ts` | Claude Code CLI wrapper |
+| `otlp-receiver.ts` | OpenTelemetry metrics receiver |
+
+See [Cyclist Documentation](docs/CYCLIST.md) for full details.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `pennyfarthing init [name]` | Initialize in a project |
+| `pennyfarthing update` | Update to latest version |
+| `pennyfarthing doctor` | Check installation health |
+| `pennyfarthing doctor --fix` | Auto-fix common issues |
+| `pennyfarthing uninstall` | Remove for clean reinstall |
+| `pennyfarthing theme list` | Show available themes |
+| `pennyfarthing theme set <name>` | Change active theme |
+| `pennyfarthing theme show [name]` | Display theme details |
+| `pennyfarthing theme create <name>` | Create custom theme |
+| `pennyfarthing version` | Show version info |
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [**User Guide**](docs/USER-GUIDE.md) | Complete documentation |
+| [Getting Started](docs/GETTING-STARTED.md) | Quick start guide |
+| [TDD Flow Diagrams](docs/TDD-FLOW-DIAGRAMS.md) | Visual sequence diagrams and flowcharts |
+| [Architecture](docs/ARCHITECTURE.md) | System design and principles |
+| [Agents](docs/AGENTS.md) | Agent reference |
+| [Commands](docs/COMMANDS.md) | Slash command reference |
+| [Skills](docs/SKILLS.md) | Knowledge domain reference |
+| [Workflows](docs/WORKFLOWS.md) | TDD and workflow guides |
+| [Personas](docs/PERSONAS.md) | Theme customization |
+| [Theme Comparison](docs/THEME-COMPARISON.md) | Personality analysis & Big Five (OCEAN) profiles |
+| [Configuration](docs/CONFIGURATION.md) | Configuration reference |
+| [Permissions](docs/PERMISSIONS.md) | Claude Code permissions setup |
+| [Benchmarking](docs/BENCHMARKING.md) | Scientific persona evaluation |
+| [Cyclist](docs/CYCLIST.md) | Cyclist sidebar integration |
+
+## Directory Structure
+
+After initialization:
+
+```
+your-project/
+├── .claude/
+│   ├── commands/             # → symlinks to @pennyfarthing/core commands
+│   ├── skills/               # → symlinks to @pennyfarthing/core skills
+│   ├── project/              # YOUR customizations
+│   │   ├── agents/*-sidecar/ # Agent memory/learnings
+│   │   ├── docs/             # shared-context.md
+│   │   └── hooks/            # setup-env.sh
+│   ├── manifest.json         # Installation manifest
+│   └── settings.local.json   # Claude Code settings
+├── .pennyfarthing/
+│   ├── agents/               # → symlink to @pennyfarthing/core agents
+│   ├── guides/               # → symlink to @pennyfarthing/core guides
+│   ├── personas/             # → symlink to @pennyfarthing/core personas
+│   ├── scripts/              # → symlink to @pennyfarthing/core scripts
+│   ├── sidecars/             # Agent learning files
+│   └── config.local.yaml     # Theme selection (gitignored)
+├── sprint/
+│   ├── current-sprint.yaml   # Active sprint
+│   ├── archive/              # Completed sessions
+│   └── context/              # Story summaries
+└── .session/
+    └── {story-id}-session.md # Active work session
+```
+
+## Available Themes (102 total)
+
+| Category | Themes |
+|----------|--------|
+| **Sci-Fi TV** | `the-expanse`, `star-trek-tng`, `star-trek-tos`, `firefly`, `battlestar-galactica`, `doctor-who` |
+| **Sci-Fi Film** | `star-wars`, `dune`, `blade-runner`, `the-matrix`, `alien` |
+| **Fantasy** | `game-of-thrones`, `lord-of-the-rings`, `the-witcher`, `sandman`, `his-dark-materials`, `arthurian-mythos` |
+| **Mythology** | `greek-mythology`, `lovecraft-mythos`, `norse-mythology` |
+| **Drama** | `breaking-bad`, `the-wire`, `succession`, `mad-men`, `deadwood`, `fargo` |
+| **Comedy** | `the-office`, `parks-and-rec`, `ted-lasso`, `the-good-place`, `arrested-development` |
+| **Literary** | `discworld`, `shakespeare`, `jane-austen`, `sherlock-holmes`, `hitchhikers-guide` |
+| **Games** | `mass-effect`, `portal`, `baldurs-gate`, `disco-elysium` |
+| **Classic** | `princess-bride`, `a-team`, `mash`, `west-wing` |
+| **Minimal** | `control`, `minimalist` |
+
+All 102 themes include OCEAN (Big Five) personality profiles and spider chart visualizations.
+
+See [Theme Comparison Guide](docs/THEME-COMPARISON.md) for personality analysis, OCEAN profiles, and help choosing between themes.
+
+Create custom themes with `/theme-maker`.
+
+Configure in `.pennyfarthing/config.local.yaml`:
+```yaml
+theme: star-trek-tos
+```
+
+## Customization
+
+### Output Styles
+
+Pennyfarthing ships with output styles for Claude Code's `/output-style` command:
+
+| Style | Description |
+|-------|-------------|
+| `verbose` | Detailed explanations, educational |
+| `terse` | Minimal output, just the essentials |
+| `teaching` | Explains reasoning, suggests alternatives |
+
+Usage: `/output-style verbose` (in Claude Code)
+
+### Preferences
+
+User preferences are configured in `.claude/pennyfarthing/preferences.yaml`:
+
+```yaml
+# Enable persona character voice in agent output
+character_voice: true
+
+# Show reasoning and decision explanations
+explain_decisions: true
+
+# Auto-commit on story completion
+auto_commit: false
+```
+
+Override locally with `.claude/pennyfarthing/preferences.local.yaml` (gitignored).
+
+## Updating
+
+```bash
+# Update CLI
+npm update @pennyfarthing/core
+
+# Update visual terminal (if installed)
+npm update @pennyfarthing/cyclist
+
+# Verify after update
+npx pennyfarthing doctor
+```
+
+## Uninstalling
+
+```bash
+# Remove managed files (preserves your project customizations)
+pennyfarthing uninstall
+
+# Remove everything except archived work
+pennyfarthing uninstall --all
+```
+
+Archived sprint data (`sprint/archive/`, `sprint/context/`) is always preserved.
+
+## What's New in v7.0
+
+- **BREAKING: Package Renamed** - `pennyfarthing` → `@pennyfarthing/core`
+- **BREAKING: Directory Restructure** - Content moved from `.claude/` to `.pennyfarthing/`
+- **Cyclist Split** - Visual terminal is now optional `@pennyfarthing/cyclist` (160MB → 1.1MB core)
+- **Customizable Workflow Engine** - YAML-based workflow definitions with story routing
+- **BMAD Interoperability** - Parse and export BMAD format stories and epics
+- **Runtime Permission Management** - Approval gates, spot grants, `/permissions` skill
+- **Enhanced OTEL** - Tool enrichment for Bash, Read, Edit, Write, Grep/Glob spans
+- **Agent Modernization** - All agents updated with status tags and shared behavior
+
+See [CHANGELOG.md](CHANGELOG.md) for full migration guide.
+
+## What's New in v6.5
+
+- **Simplified Installation** - Two packages for different needs:
+  - `@pennyfarthing/core` - CLI only (1.1 MB)
+  - `@pennyfarthing/cyclist` - Optional visual terminal with portraits (160 MB)
+- **Portrait Optimization** - Cyclist bundles only 128px and 256px portraits (saves 450MB)
+- **Agent Modernization** - All agents updated with status tags and consolidated shared behavior
+- **OTEL Tool Enrichment** - Bash, Write, Read, Edit, Grep/Glob spans enriched with operation context
+
+## What's New in v6.0
+
+- **Monorepo Architecture** - Restructured as pnpm workspace for development
+- **Cyclist Visual Terminal** - Full GUI support with persona sidebar
+  - Portrait resolver works across all install scenarios
+  - Real-time agent display with OCEAN-slugged filenames
+- **New Themes** - Arthurian Mythos, Greek Mythology, Lovecraft Mythos
+  - 30 new characters with full OCEAN profiles
+  - Woodcut-style portraits for all characters
+
+## What's New in v5.x
+
+- **Job Fair Benchmarking** - Data-driven role optimization with `/job-fair` command
+- **Context Circuit Breaker** - Hard stop at 85% context with `/continue-session` recovery
+- **Choreography Patterns** - 4 comprehensive guides (TDD flow, helper delegation, fan-out/fan-in, approval gates)
+- **Scientific Benchmarking** - `/solo`, `/benchmark`, `/judge` commands for persona evaluation
+- **Showcase Website** - Interactive theme browser at [showcase site](https://animated-meme-3e4494y.pages.github.io/)
+
+---
+
+*For full changelog, see [CHANGELOG.md](CHANGELOG.md)*
+
+## License
+
+Copyright 2025 1898 & Co. All rights reserved.

package/package.json

@@ -1,46 +1,42 @@
 {
   "name": "@pennyfarthing/core",
-  "version": "7.5.0",
+  "version": "7.6.0",
   "description": "Claude Code agent framework with TDD workflow and persona system",
   "type": "module",
-  "keywords": [
-    "claude",
-    "claude-code",
-    "agents",
-    "ai",
-    "tdd",
-    "workflow",
-    "anthropic"
+  "bin": {
+    "pennyfarthing": "./packages/core/bin/pennyfarthing.js"
+  },
+  "files": [
+    "packages/core/bin/",
+    "packages/core/dist/",
+    "pennyfarthing-dist/agents/",
+    "pennyfarthing-dist/commands/",
+    "pennyfarthing-dist/guides/",
+    "pennyfarthing-dist/output-styles/",
+    "pennyfarthing-dist/personas/themes/",
+    "pennyfarthing-dist/scripts/",
+    "pennyfarthing-dist/skills/",
+    "pennyfarthing-dist/templates/",
+    "pennyfarthing-dist/workflows/",
+    "README.md"
   ],
-  "license": "UNLICENSED",
-  "author": "1898andCo",
   "repository": {
     "type": "git",
-    "url": "https://github.com/1898andCo/pennyfarthing.git",
-    "directory": "packages/core"
+    "url": "https://github.com/1898andCo/pennyfarthing.git"
   },
   "homepage": "https://github.com/1898andCo/pennyfarthing#readme",
   "bugs": {
     "url": "https://github.com/1898andCo/pennyfarthing/issues"
   },
-  "bin": {
-    "pennyfarthing": "./bin/pennyfarthing.js"
-  },
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist/",
-    "bin/"
-  ],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "node --test dist/**/*.test.js",
-    "lint": "eslint src/",
-    "clean": "rm -rf dist/"
+    "build": "pnpm --filter @pennyfarthing/shared build && pnpm --filter @pennyfarthing/core build && pnpm --filter @pennyfarthing/cyclist build && ./scripts/utils/generate-skill-docs.sh",
+    "docs": "./scripts/utils/generate-skill-docs.sh",
+    "dev": "pnpm -r --parallel dev",
+    "test": "pnpm -r test",
+    "lint": "eslint 'packages/*/src/**/*.ts' --max-warnings 0",
+    "clean": "pnpm -r clean"
   },
   "dependencies": {
-    "@pennyfarthing/shared": "workspace:*",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "fs-extra": "^11.2.0",
@@ -49,15 +45,14 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
-    "@types/inquirer": "^9.0.7",
-    "@types/node": "^20.10.0",
-    "typescript": "^5.3.3"
-  },
-  "publishConfig": {
-    "access": "public"
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "globals": "^17.0.0",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.53.0"
   },
   "engines": {
     "node": ">=18.0.0"
-  }
+  },
+  "packageManager": "pnpm@9.0.0"
 }

package/packages/core/dist/bmad/context-reader.d.ts

@@ -0,0 +1,71 @@
+/**
+ * BMAD Project Context Reader - Story 32-4
+ *
+ * Parses BMAD project-context.md files and extracts technology stack,
+ * implementation rules, and AI agent guidance for Pennyfarthing integration.
+ */
+export interface TechnologyStack {
+    frontend?: {
+        framework?: string;
+        language?: string;
+        stateManagement?: string;
+        styling?: string;
+        buildTool?: string;
+    };
+    backend?: {
+        language?: string;
+        framework?: string;
+        database?: string;
+        cache?: string;
+        apiStyle?: string;
+    };
+    infrastructure?: {
+        cloudProvider?: string;
+        containerRuntime?: string;
+        orchestration?: string;
+        ciCd?: string;
+    };
+}
+export interface ImplementationRule {
+    number: number;
+    title: string;
+    description: string;
+}
+export interface AiAgentGuidance {
+    do?: string[];
+    dont?: string[];
+    contextLoading?: string;
+}
+export interface ExternalDependency {
+    name: string;
+    purpose: string;
+    documentation: string;
+}
+export interface BmadProjectContext {
+    overview: string;
+    technologyStack: TechnologyStack;
+    implementationRules: ImplementationRule[];
+    projectStructure?: string;
+    codingStandards?: string;
+    aiAgentGuidance?: AiAgentGuidance;
+    externalDependencies?: ExternalDependency[];
+    environmentSetup?: string;
+}
+export interface ContextParseError {
+    section: string;
+    message: string;
+    line?: number;
+}
+export interface ContextParseResult {
+    success: boolean;
+    context?: BmadProjectContext;
+    errors?: ContextParseError[];
+}
+/**
+ * Parse a BMAD project-context.md file and extract structured context.
+ *
+ * @param content - Raw markdown content of project-context.md
+ * @returns ContextParseResult with success status and either context or errors
+ */
+export declare function parseBmadContext(content: string): ContextParseResult;
+//# sourceMappingURL=context-reader.d.ts.map

package/packages/core/dist/bmad/context-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-reader.d.ts","sourceRoot":"","sources":["../../src/bmad/context-reader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,cAAc,CAAC,EAAE;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,eAAe,CAAC;IACjC,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,oBAAoB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAkUD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAmGpE"}