@pennyfarthing/core 9.2.0 → 9.4.0

package/README.md

@@ -1,218 +0,0 @@
-# Pennyfarthing
-
-**v9.2.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">
-
-A Claude Code agent orchestration framework built around three pillars: a flexible development platform, scientific personality research, and streamlined integrations.
-
----
-
-## What is Pennyfarthing?
-
-### 1. Development Platform
-
-A multi-agent system with customizable BikeLane workflows for structured software development:
-
-- **19 Coordinated Agents** - SM, TEA, Dev, Reviewer, Architect, PM, and more
-- **24 BikeLane Workflows** - Phased (TDD, BDD, Trivial), Stepped (PRD, Architecture), Procedural (Brainstorming, Retrospective)
-- **48 Slash Commands** - Entry points for agent activation and workflows
-- **24 Skills** - Reusable knowledge domains (testing, code-review, jira, mermaid, etc.)
-- **Automatic Handoffs** - Context-aware agent transitions via subagent delegation
-
-### 2. Personality Research
-
-A scientific study of how strong personalities affect AI agent behavior:
-
-- **OCEAN Profiling** - Big Five personality scores for every character
-- **TRAIL Framework** - Categorizing errors (reasoning, planning, execution) and correlating with personality
-- **Benchmarking System** - `/solo`, `/benchmark-control`, `/benchmark` for statistical evaluation
-- **JobFair** - Discovering which characters excel at roles beyond their native specialization
-
-The 102 persona themes (Discworld, Star Trek, Breaking Bad, etc.) are instruments of inquiry, not decoration. Early findings show character expertise often trumps abstract personality scores.
-
-### 3. Integration & Tooling
-
-Smoothing out development processes:
-
-- **Jira Integration** - Bidirectional sync, epic auto-creation, sprint velocity
-- **Sprint Management** - Story tracking with `current-sprint.yaml`
-- **Cyclist Visual Terminal** - React UI with Dockview panels, agent portraits, tool visualization
-
----
-
-### [**Explore the Research Showcase**](https://animated-meme-3e4494y.pages.github.io/)
-
-102 themes with OCEAN spider charts, benchmark tiers, and 1020 character profiles.
-
----
-
-## Quick Start
-
-```bash
-cd your-project
-
-# Install CLI
-npm install --save-dev @pennyfarthing/core
-
-# Initialize (creates symlinks)
-npx pennyfarthing init
-
-# Verify installation
-npx pennyfarthing doctor
-
-# Start working (in Claude Code)
-/new-work
-```
-
-### Optional: Visual Terminal
-
-```bash
-# Install Cyclist (160 MB, includes portraits)
-npm install --save-dev @pennyfarthing/cyclist
-
-# Launch
-npx pennyfarthing cyclist
-```
-
-## BikeLane Workflows
-
-BikeLane is the umbrella workflow system supporting three types:
-
-| Type | Description | Examples |
-|------|-------------|----------|
-| **Phased** | Agent-driven with automatic handoffs | tdd, bdd, trivial, agent-docs |
-| **Stepped** | Progressive disclosure with user gates | prd, architecture, research, sprint-planning |
-| **Procedural** | Flexible agent-guided processes | brainstorming, code-review, retrospective |
-
-### Example: TDD Workflow (Phased)
-
-```
-/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 |
-
-Use `/workflow list` to see all 24 workflows. Use `/workflow start <name>` to begin any workflow.
-
-## Benchmarking & Personality Research
-
-Pennyfarthing includes a scientific benchmarking system for evaluating how personality affects agent performance:
-
-```bash
-# Run a single agent on a scenario
-/solo theme:agent --scenario cache-invalidation
-
-# Create a control baseline (10 runs)
-/benchmark-control reviewer --scenario order-service
-
-# Compare persona vs control with statistics
-/benchmark breaking-bad reviewer --scenario order-service
-```
-
-**Key Findings:**
-- Cohen's d effect sizes measure performance differences
-- Multivariate OCEAN patterns predict better than individual traits
-- Character expertise often trumps abstract personality scores
-- The "Stoic Analyst" profile (Low O + High C + Low E + Low N) excels at code review
-
-See [Benchmarking Documentation](docs/BENCHMARKING.md) for methodology.
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `pennyfarthing init` | 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 |
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [**User Guide**](docs/USER-GUIDE.md) | Complete documentation |
-| [Getting Started](docs/GETTING-STARTED.md) | Quick start guide |
-| [Workflow Diagrams](docs/WORKFLOW-DIAGRAMS.md) | Visual Mermaid diagrams for all workflows |
-| [BikeLane](docs/BIKELANE.md) | Workflow system architecture |
-| [Agents](docs/AGENTS.md) | Agent reference |
-| [Commands](docs/COMMANDS.md) | Slash command reference |
-| [Benchmarking](docs/BENCHMARKING.md) | Scientific persona evaluation |
-| [Jira Integration](docs/JIRA-INTEGRATION.md) | Jira CLI and sprint sync |
-| [Cyclist](docs/CYCLIST.md) | Visual terminal documentation |
-
-## Available Themes (102)
-
-| Category | Themes |
-|----------|--------|
-| **Sci-Fi TV** | `the-expanse`, `star-trek-tng`, `firefly`, `battlestar-galactica`, `doctor-who` |
-| **Sci-Fi Film** | `star-wars`, `dune`, `blade-runner`, `the-matrix`, `alien` |
-| **Fantasy** | `game-of-thrones`, `lord-of-the-rings`, `discworld`, `sandman`, `arthurian-mythos` |
-| **Drama** | `breaking-bad`, `the-wire`, `succession`, `mad-men`, `fargo` |
-| **Comedy** | `the-office`, `parks-and-rec`, `ted-lasso`, `the-good-place` |
-| **Literary** | `shakespeare`, `jane-austen`, `sherlock-holmes`, `hitchhikers-guide` |
-| **Games** | `mass-effect`, `portal`, `baldurs-gate`, `disco-elysium` |
-
-All themes include OCEAN (Big Five) personality profiles. See [Theme Comparison](docs/THEME-COMPARISON.md) for personality analysis.
-
-Configure in `.pennyfarthing/config.local.yaml`:
-```yaml
-theme: the-expanse
-```
-
-## Directory Structure
-
-After initialization:
-
-```
-your-project/
-├── .claude/
-│   ├── commands/             # → symlinks to @pennyfarthing/core
-│   ├── skills/               # → symlinks to @pennyfarthing/core
-│   └── project/              # Your customizations
-├── .pennyfarthing/
-│   ├── agents/               # → symlink to @pennyfarthing/core
-│   ├── workflows/            # → symlink to @pennyfarthing/core
-│   ├── sidecars/             # Agent learning files
-│   └── config.local.yaml     # Theme selection
-├── sprint/
-│   ├── current-sprint.yaml   # Active sprint
-│   └── archive/              # Completed sessions
-└── .session/
-    └── {story-id}-session.md # Active work session
-```
-
-## What's New in v9.0
-
-- **Dockview Panel System** - Draggable, floatable, splittable panels replacing hand-rolled system (ADR-0019)
-- **React UI** - Full React component architecture for Cyclist
-- **Tool Use Visualization** - Human-readable tool summaries, collapsible results, tool stacking
-- **useMarkdownParser Hook** - React hook for markdown rendering (vanilla JS migration)
-- **Bell Mode** - Queue messages while Claude works (ADR-0016)
-- **Relay Mode** - Automatic agent handoffs (ADR-0017)
-
-### Previous Highlights (v7.6-v8.x)
-
-- **BikeLane Workflow System** - Unified umbrella for Phased, Stepped, and Procedural workflows
-- **BMAD 6.0 Compatibility** - Full import support for BMAD workflows with tri-modal execution
-- **19 Workflows** - Expanded from TDD-only to comprehensive workflow library
-- **Scientific Benchmarking** - TRAIL-OCEAN hypothesis testing framework
-- **JobFair** - Cross-role performance discovery system
-
-See [CHANGELOG.md](CHANGELOG.md) for full details.
-
----
-
-## License
-
-Copyright 2025-2026 1898 & Co. All rights reserved.

package/pennyfarthing-dist/agents/README.md

@@ -1,348 +0,0 @@
-# Pennyfarthing Core Agents
-
-## Overview
-
-This directory contains the **single source of truth** for all Pennyfarthing agent definitions. Agents are coordinated across both `API` and `UI` repositories.
-
-**See:** `../ AGENT-COORDINATION.md` for complete architecture documentation.
-
-## Main Agents
-
-| Agent | Role |
-|-------|------|
-| **SM** | Story coordination, session management |
-| **TEA** | Test writing, TDD guidance |
-| **Dev** | Feature implementation |
-| **Reviewer** | Adversarial code review |
-| **Orchestrator** | Process improvement, meta-ops |
-| **PM** | Planning, prioritization |
-| **Architect** | System design, ADRs |
-| **DevOps** | Infrastructure, deployment |
-| **Tech Writer** | Documentation |
-| **UX Designer** | UI design, accessibility |
-
-### Official Subagents (Haiku-based)
-Lightweight subagents for mechanical tasks. Invoked via `Task tool` with `subagent_type: "general-purpose"` and `model: "haiku"`.
-
-**Invocation pattern:**
-```yaml
-Task tool:
-  subagent_type: "general-purpose"
-  model: "haiku"
-  run_in_background: true   # For independent work; omit for sequential workflows
-  prompt: |
-    Read and follow: .pennyfarthing/agents/{subagent-name}.md
-
-    {PARAMETERS}
-```
-
-**See `agent-behavior.md` → "Interactive Background Task Protocol"** for when to use background vs foreground execution.
-
-- **`workflow-status-check.md`** - Detect workflow state
-- **`sm-setup.md`** - Research OR setup mode (Story 31-11)
-- **`sm-finish.md`** - Preflight OR execute phase (Story 31-11)
-- **`handoff.md`** - Workflow-driven handoff (Stories 31-7, 31-10)
-- **`sm-handoff.md`** - SM→TEA/Dev handoff with Jira/branch verification
-- **`sm-file-summary.md`** - Summarize file changes
-- **`reviewer-preflight.md`** - Gather review data
-- **`testing-runner.md`** - Execute tests, report results
-
-### Removed Files (Stories 31-11, 31-12)
-These files have been deleted and replaced by consolidated versions:
-
-**SM Subagents (Story 31-12):**
-- `sm-work-research.md` → use `sm-setup` with MODE=research
-- `sm-story-setup.md` → use `sm-setup` with MODE=setup
-- `sm-finish-bookkeeping.md` → use `sm-finish` with PHASE=preflight
-- `sm-finish-execution.md` → use `sm-finish` with PHASE=execute
-
-**Handoff Subagents (Story 31-11):**
-- `tea-handoff.md` → use `handoff` with CURRENT_PHASE=red
-- `dev-handoff.md` → use `handoff` with CURRENT_PHASE=green
-- `reviewer-handoff-approve.md` → use `handoff` with VERDICT=approved
-- `reviewer-handoff-reject.md` → use `handoff` with VERDICT=rejected
-
-## Context Loading
-
-Agents load context based on their type:
-
-### Strategic Agents Load:
-- Full sprint status
-- Both API and UI contexts
-- Epic definitions
-- Active work
-
-### Tactical Agents Load:
-- Story section of sprint status
-- Active work
-- Target repo context only (based on story)
-
-**Configuration:** `.claude/project/docs/agent-scopes.yaml`
-
-## Usage
-
-### Activate an Agent
-
-```bash
-# Via workflow
-@/pm
-@/dev
-@/tea
-
-# Or mention in chat
-"Let's activate the PM agent"
-"Activate Dev to implement this story"
-```
-
-### Agent Files
-
-Each agent file contains:
-- **Persona:** Character and expertise
-- **Responsibilities:** What they handle
-- **Context:** Project information
-- **Context Loading:** What files to load on activation
-- **Activation:** How they operate
-- **Workflows:** Common tasks and patterns
-- **Handoffs:** How they coordinate with other agents
-
-## File Structure
-
-```
-.pennyfarthing/agents/
-├── README.md                  # This file
-│
-│ # Main Agents (10)
-├── orchestrator.md            # Master orchestrator
-├── pm.md                      # Product Manager
-├── sm.md                      # Scrum Master
-├── architect.md               # System Architect
-├── devops.md                  # DevOps Engineer
-├── dev.md                     # Developer
-├── tea.md                     # Test Engineer
-├── reviewer.md                # Code Reviewer
-├── tech-writer.md             # Technical Writer
-├── ux-designer.md             # UX Designer
-│
-│ # Official Subagents (8 active)
-├── workflow-status-check.md   # Detect workflow state
-├── sm-setup.md        # Research or setup mode (Story 31-11)
-├── sm-finish.md       # Preflight or execute (Story 31-11)
-├── handoff.md         # Workflow-driven handoff (Stories 31-7, 31-10)
-├── sm-handoff.md              # SM→TEA/Dev handoff with Jira/branch
-├── sm-file-summary.md         # Summarize files
-├── reviewer-preflight.md      # Review prep
-└── testing-runner.md          # Run tests
-```
-
-## Context Budget
-
-Each agent is designed to work within **~500-800 line context budget**:
-
-### Strategic Agent Budget
-- Agent file: ~200-300 lines
-- Sprint status: ~100-150 lines
-- Repo contexts: ~60 lines
-- Epics/docs: ~100 lines
-- Active work: ~50 lines
-- **Total:** ~500-660 lines
-
-### Tactical Agent Budget
-- Agent file: ~250-400 lines
-- Sprint status (story): ~50 lines
-- Active work: ~50 lines
-- Target repo context: ~100 lines
-- **Total:** ~450-600 lines
-
-## Common Handoffs
-
-```
-SM → TEA/Dev:    Story setup complete
-TEA → Dev:       Tests written
-Dev → Reviewer:  Implementation complete
-Reviewer → SM:   Story approved
-Reviewer → Dev:  Changes requested
-```
-
-## Creating New Agents
-
-1. Create `.pennyfarthing/agents/[name].md`
-2. Follow existing agent structure
-3. Update this README
-4. Create command in `.claude/commands/[name].md`
-
-### Agent Template Structure
-
-```markdown
-# [Agent Name] Agent - [Role]
-
-## Persona
-[Character description and expertise]
-
-## Responsibilities
-[What they handle]
-
-## Context
-[Project information]
-
-## Context Loading
-[What files to load on activation]
-
-## Activation
-[How they operate]
-
-## Key Workflows
-[Common tasks]
-
-## Handoffs
-[Coordination with other agents]
-
-## Activation Command
-[@/agent-name]
-
-## Exit
-[How to exit agent mode]
-```
-
-## Benefits
-
-✅ **Single Source of Truth** - All agents in one place
-✅ **Coordinated Planning** - Strategic agents see full scope
-✅ **Focused Implementation** - Tactical agents load only what they need
-✅ **Clear Hierarchy** - Strategic coordinate, tactical execute
-✅ **Scalable** - Easy to add new agents
-
-## Path Standards
-
-**IMPORTANT:** Scripts self-locate via `BASH_SOURCE`. Use direct script invocation.
-
-### Standard Pattern
-```bash
-# ✅ CORRECT - Direct script invocation (scripts self-locate via BASH_SOURCE)
-.pennyfarthing/scripts/core/agent-session.sh start "Agent Name"
-
-# ✅ CORRECT - Relative paths for files (Claude starts in project root)
-.session/{STORY_ID}-session.md
-
-# ✅ CORRECT - Commands use climber pattern to find project root
-d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
-"$d/.pennyfarthing/scripts/core/agent-session.sh" start "sm"
-
-# ❌ WRONG - $CLAUDE_PROJECT_DIR doesn't exist in Claude Bash calls
-$CLAUDE_PROJECT_DIR/.pennyfarthing/scripts/core/agent-session.sh  # BROKEN!
-
-# ❌ WRONG - Don't hardcode absolute paths
-/Users/someone/project/.pennyfarthing/scripts/core/agent-session.sh
-```
-
-### Why Relative Paths?
-- `$CLAUDE_PROJECT_DIR` is available in hooks but NOT in Claude's Bash tool calls
-- Scripts self-locate via `BASH_SOURCE` and `find-root.sh`
-- Claude Code always starts in the project root directory
-- The climber pattern handles subdirectory execution if needed
-
-### Path Context
-| Context | `$CLAUDE_PROJECT_DIR` | Relative Paths |
-|---------|----------------------|----------------|
-| Hooks (settings.json) | ✅ Available | ✅ Works |
-| Claude Bash calls | ❌ Not set | ✅ Works |
-| Inside scripts | ❌ Use `$PROJECT_ROOT` | ✅ Works |
-
-## Background Subagent Execution
-
-Subagents can run in background using Claude Code's `run_in_background` parameter. This allows the user to continue interacting while slow operations complete asynchronously.
-
-**IMPORTANT:** See `agent-behavior.md` → "Interactive Background Task Protocol" for the authoritative guidance.
-
-### The Key Insight
-
-**Background + immediate blocking is an anti-pattern.** If you spawn with `run_in_background: true` then immediately call `TaskOutput` with `block: true`, you've blocked the conversation - the user can't interact.
-
-### When to Use Background Execution
-
-**Good candidates (truly independent work):**
-- Test runs while writing more code
-- Multiple independent file explorations
-- Long-running builds while discussing next steps
-- Parallel searches where you don't need results immediately
-
-**When NOT to use (sequential workflow):**
-- Status checks that determine your next action
-- Handoff operations that must complete before continuing
-- Any operation where you need the result to proceed
-
-### Cyclist Integration
-
-When running in Cyclist, background tasks are automatically tracked:
-- OTEL spans detect `run_in_background: true` Task calls
-- Completion notifications appear in MessageView
-- User can expand to see full output
-
-**This means:** Fire the task, tell the user it's running, and keep working. Cyclist handles the notification when it finishes.
-
-### Tracking Background Tasks in Session Files
-
-Use the background task tracking utilities to manage session file entries:
-
-```bash
-source .pennyfarthing/scripts/lib/background-tasks.sh
-SESSION_FILE=".session/${STORY_ID}-session.md"
-
-# After spawning, record the task:
-bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Background test run"
-
-# After checking TaskOutput, update status:
-bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"  # or "error"
-
-# Clean up finished tasks:
-bg_task_cleanup "$SESSION_FILE"
-```
-
-**Available functions:**
-| Function | Purpose |
-|----------|---------|
-| `bg_task_add` | Record new background task |
-| `bg_task_update` | Update task status (running/completed/error) |
-| `bg_task_cleanup` | Remove completed and errored tasks |
-| `bg_task_list` | Show all running tasks |
-| `bg_task_check` | Return 0 if any tasks running |
-| `bg_task_summary` | Print counts by status |
-
-### Background Execution Constraints
-
-1. **No concurrent state mutation** - Don't have multiple background tasks writing to the same file
-2. **Independent operations only** - Each background task should be self-contained
-3. **Check before proceeding** - If you need the result, wait for it with `block: true`
-4. **Clean up tracking** - Use `bg_task_cleanup` after processing results
-
-### Example: Background Tests While Coding
-
-```bash
-# 1. Spawn testing-runner with run_in_background: true
-# 2. Record: bg_task_add "$SESSION_FILE" "$TASK_ID" "testing-runner" "Tests while coding"
-# 3. Continue writing code
-# 4. Periodically check TaskOutput with block: false
-# 5. When complete: bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"
-# 6. Cleanup: bg_task_cleanup "$SESSION_FILE"
-# 7. If RED: stop and fix
-# 8. If GREEN: continue with confidence
-```
-
-## Quick Reference
-
-```bash
-# View agent scope configuration
-cat .claude/project/docs/agent-scopes.yaml
-
-# List all agents
-ls .pennyfarthing/agents/
-
-# View agent definition
-cat .pennyfarthing/agents/pm.md
-
-# Activate agent
-@/pm
-```
-
----
-
-**Your coordinated Pennyfarthing agent system is ready!**