pennyfarthing 6.6.0

package/README.md

@@ -0,0 +1,293 @@
+# Pennyfarthing
+
+**v6.5.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, Chernoff faces, 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
+
+# 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/
+│   ├── agents/               # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/agents/
+│   ├── commands/             # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/commands/
+│   ├── skills/               # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/skills/
+│   ├── personas/             # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/personas/
+│   ├── scripts/              # → symlink to node_modules/pennyfarthing/pennyfarthing-dist/scripts/
+│   ├── 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/
+│   └── 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 Chernoff face 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
+
+# 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 v6.4
+
+- **102 Themes** - 11 new themes added since v6.0
+- **20 Skills** - Expanded knowledge domains
+- **43 Commands** - More workflow entry points
+- **Sprint 10** - Customizable workflows and runtime permissions
+
+## What's New in v6.5
+
+- **Simplified Installation** - Two packages for different needs:
+  - `pennyfarthing` - 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

@@ -0,0 +1,58 @@
+{
+  "name": "pennyfarthing",
+  "version": "6.6.0",
+  "description": "Claude Code agent framework with TDD workflow and persona system",
+  "type": "module",
+  "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"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1898andCo/pennyfarthing.git"
+  },
+  "homepage": "https://github.com/1898andCo/pennyfarthing#readme",
+  "bugs": {
+    "url": "https://github.com/1898andCo/pennyfarthing/issues"
+  },
+  "scripts": {
+    "build": "pnpm -r 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": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.12",
+    "open": "^11.0.0",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@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/bin/pennyfarthing.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// Pennyfarthing CLI entry point
+try {
+  await import('../dist/cli/index.js');
+} catch (err) {
+  if (err.code === 'ERR_MODULE_NOT_FOUND') {
+    console.error('Error: Dependencies not installed.\n');
+    console.error('Run: npm install');
+    console.error('Then try again.\n');
+    process.exit(1);
+  }
+  throw err;
+}

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"}