@pennyfarthing/core 10.0.0 → 10.0.2

package/pennyfarthing-dist/commands/health-check.md

@@ -0,0 +1,143 @@
+---
+description: Check Pennyfarthing installation health and apply updates
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
+python3 -m pennyfarthing_scripts.cli agent start "devops"
+```
+
+<agent-activation>
+1. Load DevOps agent for infrastructure work
+2. Run health check via CLI
+</agent-activation>
+
+<purpose>
+Examine current Pennyfarthing installation, detect drift from expected state, and guide user through fixes/updates.
+</purpose>
+
+<when-to-use>
+- After updating Pennyfarthing (`pennyfarthing update`)
+- When something seems broken
+- Periodic health verification
+- Before starting new sprint
+</when-to-use>
+
+<health-checks>
+
+## Health Check
+
+Use the pennyfarthing CLI:
+
+```bash
+# Full health check
+pennyfarthing doctor
+
+# Or via npx
+npx pennyfarthing doctor
+
+# Auto-fix issues
+pennyfarthing doctor --fix
+```
+
+The CLI checks:
+- manifest.json exists and is valid
+- All managed files present in .claude/pennyfarthing/
+- Symlinks point to correct targets
+- User directories exist (.claude/project/)
+- Settings paths are correct
+- Hook scripts are executable
+
+## Check for Updates
+
+```bash
+# Check if update available
+pennyfarthing update --check
+
+# Apply update
+pennyfarthing update
+```
+
+</health-checks>
+
+<output-format>
+
+```markdown
+# Pennyfarthing Health Check
+
+## Installation: npm v2.2.x
+## Status: [HEALTHY | NEEDS_UPDATE | NEEDS_FIX]
+
+### Checks
+| Check | Status | Detail |
+|-------|--------|--------|
+| Installation | OK | npm v2.2.0 |
+| Core Files | OK | All present |
+| Symlinks | OK | All valid |
+| User Files | OK | 10 sidecars |
+| Directories | OK | sprint/, .session/ |
+| Hooks | WARN | Not executable |
+
+### Recommended Actions
+1. [Action with command to run]
+2. [Action with command to run]
+```
+
+</output-format>
+
+<auto-fixes>
+
+```bash
+pennyfarthing doctor --fix
+```
+
+The CLI can auto-fix:
+- Broken symlinks
+- Missing directories
+- Outdated settings format
+- Non-executable hooks
+
+**Always ask before applying fixes.**
+
+</auto-fixes>
+
+<drift-detection>
+
+## Agent Behavior Drift Detection
+
+Check if agents are following expected behavioral patterns:
+
+```bash
+# Run drift detection
+.pennyfarthing/scripts/health/drift-detection.sh
+
+# Verbose mode (see individual files)
+.pennyfarthing/scripts/health/drift-detection.sh --verbose
+```
+
+The script analyzes archived session files for:
+
+| Agent | Checks For |
+|-------|------------|
+| **Reviewer** | Substantive comments (not just approvals) |
+| **Dev** | Test evidence when declaring GREEN |
+| **SM** | Structured handoff sections with target agent |
+| **TEA** | Test file references before Dev handoff |
+
+**Healthy rates:** Under 10% drift is considered normal.
+
+**When drift is high:**
+- Review agent behavior files for clarity
+- Add explicit gates/checklists
+- Consider making critical behaviors automatic via scripts
+
+</drift-detection>
+
+<reference>
+- **CLI:** `pennyfarthing doctor`, `pennyfarthing update`
+- **Manifest:** `.claude/manifest.json` (tracks version and file hashes)
+- **Source:** `.claude/pennyfarthing/` (managed files)
+- **Symlinks:** `.pennyfarthing/agents/`, `.claude/commands/`, etc.
+- **Drift Detection:** `.pennyfarthing/scripts/health/drift-detection.sh`
+</reference>

package/pennyfarthing-dist/commands/help.md

@@ -0,0 +1,264 @@
+---
+description: Context-aware help for Pennyfarthing commands, agents, and workflows
+---
+
+<purpose>
+Get help with Pennyfarthing commands, agents, themes, and workflows.
+Provides quick-start guidance for new users and context-aware suggestions based on current work state.
+</purpose>
+
+<when-to-use>
+- New to Pennyfarthing and need orientation
+- Looking for a specific command or agent
+- Want to understand the TDD workflow
+- Need to check available themes
+- Forgot what command to use next
+</when-to-use>
+
+<quick-start>
+
+## New to Pennyfarthing?
+
+Start here:
+
+1. **`/work`** - Smart entry point (resumes existing work or starts new)
+2. **`/new-work`** - Start a fresh work session from backlog
+3. **`/health-check`** - Verify your installation is working
+
+### First Time Setup
+
+If Pennyfarthing isn't installed yet:
+```bash
+npx pennyfarthing init
+```
+
+</quick-start>
+
+<workflow>
+
+## TDD Workflow
+
+Pennyfarthing uses Test-Driven Development with four core agents:
+
+```
+SM → TEA → Dev → Reviewer → SM (finish)
+```
+
+| Phase | Agent | Command | Role |
+|-------|-------|---------|------|
+| Setup | SM (Scrum Master) | `/sm` | Story selection, context creation |
+| RED | TEA (Test Engineer) | `/tea` | Write failing tests |
+| GREEN | Dev (Developer) | `/dev` | Implement to pass tests |
+| Review | Reviewer | `/reviewer` | Code review, quality enforcement |
+| Finish | SM | `/sm` | Merge PR, archive session |
+
+### Workflow Commands
+
+| Command | Description |
+|---------|-------------|
+| `/new-work` | Start a new work session with Pennyfarthing |
+| `/work` | Resume work or start new - smart entry point |
+| `/sm` | Scrum Master - Story coordination and sprint management |
+| `/tea` | Test Engineer/Architect - Test strategy and TDD |
+| `/dev` | Developer - Feature implementation and coding |
+| `/reviewer` | Code Reviewer - Critical code review and quality enforcement |
+| `/check` | Run quality gates (lint, type check, tests) before handoff |
+
+</workflow>
+
+<agents>
+
+## All Agents (24)
+
+### TDD Workflow Agents
+
+| Agent | Command | Role |
+|-------|---------|------|
+| SM | `/sm` | Scrum Master - Story coordination, sprint management, workflow entry/exit |
+| TEA | `/tea` | Test Engineer - Test strategy, TDD design, RED phase |
+| Dev | `/dev` | Developer - Implementation, feature shipping, GREEN phase |
+| Reviewer | `/reviewer` | Code Reviewer - Quality enforcement, adversarial review |
+
+### Specialist Agents
+
+| Agent | Command | Role |
+|-------|---------|------|
+| Architect | `/architect` | System Architect - Technical design and architecture |
+| PM | `/pm` | Product Manager - Strategic planning and prioritization |
+| DevOps | `/devops` | DevOps Engineer - Infrastructure and deployment automation |
+| Tech-Writer | `/tech-writer` | Technical Writer - Documentation creation and maintenance |
+| UX-Designer | `/ux-designer` | UX Designer - User experience design and UI patterns |
+| Orchestrator | `/orchestrator` | Orchestrator - Coordinator of all agents and meta operations |
+
+</agents>
+
+<commands>
+
+## All Commands (43)
+
+### TDD Workflow (7)
+| Command | Description |
+|---------|-------------|
+| `/new-work` | Start a new work session with Pennyfarthing |
+| `/work` | Resume work or start new - smart entry point |
+| `/sm` | Scrum Master - Story coordination and sprint management |
+| `/tea` | Test Engineer/Architect - Test strategy and TDD |
+| `/dev` | Developer - Feature implementation and coding |
+| `/reviewer` | Code Reviewer - Critical code review and quality enforcement |
+| `/check` | Run quality gates (lint, type check, tests) before handoff |
+
+### Specialist Agents (6)
+| Command | Description |
+|---------|-------------|
+| `/architect` | System Architect - Technical design and architecture |
+| `/pm` | Product Manager - Strategic planning and prioritization |
+| `/devops` | DevOps Engineer - Infrastructure and deployment automation |
+| `/tech-writer` | Technical Writer - Documentation creation and maintenance |
+| `/ux-designer` | UX Designer - User experience design and UI patterns |
+| `/orchestrator` | Orchestrator - Coordinator of all agents and meta operations |
+
+### Sprint & Planning (5)
+| Command | Description |
+|---------|-------------|
+| `/sprint-planning` | Facilitate sprint planning session |
+| `/start-epic` | Start an epic - move to current sprint and generate tech context |
+| `/retro` | Facilitate a sprint retrospective |
+| `/sync-work-with-sprint` | Sync Pennyfarthing work session with unified sprint status |
+| `/sync-epic-to-jira` | Sync Pennyfarthing epic to Jira MSSCI project |
+
+### Context & Loading (2)
+| Command | Description |
+|---------|-------------|
+| `/prime` | Load essential project context at agent activation |
+| `/health-check` | Check Pennyfarthing installation health and apply updates |
+
+### Theme Management (5)
+| Command | Description |
+|---------|-------------|
+| `/list-themes` | List all available persona themes |
+| `/show-theme` | Show details of a theme including all agent personas |
+| `/set-theme` | Set the active persona theme |
+| `/create-theme` | Create a new custom persona theme |
+| `/theme-maker` | Interactive wizard for creating custom persona themes |
+
+### Creative & Brainstorm (4)
+| Command | Description |
+|---------|-------------|
+| `/party-mode` | Free-form creative brainstorming with all agents |
+| `/brainstorm` | Structured problem-solving brainstorm session |
+| `/job-fair` | Discover which characters in a theme excel at each role |
+| `/solo` | Run a single agent on a scenario with absolute rubric scoring |
+
+### Benchmarking (2)
+| Command | Description |
+|---------|-------------|
+| `/benchmark` | Compare an agent's performance against a stored baseline |
+| `/benchmark-control` | Create control baseline for a scenario |
+
+### Git & Repository (4)
+| Command | Description |
+|---------|-------------|
+| `/repo-status` | Check git status of all project repos |
+| `/git-cleanup` | Clean up git repos by organizing changes into commits/branches |
+| `/create-branches-from-story` | Create feature branches in both repos from a story |
+| `/release` | Merge develop to main and push (optional version bump) |
+
+### Utility (4)
+| Command | Description |
+|---------|-------------|
+| `/continue-session` | Resume work from a saved checkpoint after context circuit breaker |
+| `/parallel-work` | Start parallel work in a new worktree |
+| `/update-domain-docs` | Update CLAUDE-*.md domain documentation files |
+| `/help` | This help command |
+
+</commands>
+
+<themes>
+
+## Themes
+
+Pennyfarthing agents adopt personas from themed character sets. There are **102 themes** available.
+
+### Popular Themes
+
+| Theme | Description |
+|-------|-------------|
+| `rome` | Characters from HBO's Rome series |
+| `star-trek-tos` | Original Star Trek series characters |
+| `star-trek-tng` | Star Trek: The Next Generation characters |
+| `discworld` | Terry Pratchett's Discworld characters |
+| `shakespeare` | Shakespearean characters |
+| `jane-austen` | Jane Austen novel characters |
+| `breaking-bad` | Breaking Bad characters |
+| `battlestar-galactica` | Battlestar Galactica characters |
+
+Run `/list-themes` to see all 102 available themes.
+
+### Theme Commands
+
+| Command | Description |
+|---------|-------------|
+| `/list-themes` | See all available themes |
+| `/show-theme` | View current theme with character mappings |
+| `/set-theme <name>` | Change to a different theme |
+| `/create-theme` | Create a custom theme |
+| `/theme-maker` | Interactive theme creation wizard |
+
+### Current Theme
+
+Check your current theme:
+```bash
+cat .pennyfarthing/config.local.yaml
+```
+
+</themes>
+
+<context-aware>
+
+## Context-Aware Help
+
+Based on your current state, here's what you might need:
+
+### No Active Session
+- Use `/work` or `/new-work` to begin
+- Check `/health-check` if first time
+
+### In Dev Phase
+- Run `/check` before handoff
+- Then `/reviewer` for code review
+
+### In Review Phase
+- Reviewer will approve or reject
+- Then `/sm` to finish the story
+
+### Between Stories
+- `/work` to pick up next story
+- `/sprint-planning` for planning session
+
+</context-aware>
+
+<reference>
+
+## Documentation
+
+- **Project Setup:** `CLAUDE.md`
+- **Sprint Status:** `sprint/current-sprint.yaml`
+- **Active Session:** `.session/*-session.md`
+- **Agent Definitions:** `pennyfarthing-dist/agents/*.md`
+- **Command Definitions:** `pennyfarthing-dist/commands/*.md`
+- **Theme Files:** `pennyfarthing-dist/personas/themes/*.yaml`
+- **Guides:** `.pennyfarthing/guides/*.md`
+
+## Getting More Help
+
+For detailed help on a specific command, read its definition file:
+```bash
+cat pennyfarthing-dist/commands/<command-name>.md
+```
+
+For agent documentation:
+```bash
+cat pennyfarthing-dist/agents/<agent-name>.md
+```
+
+</reference>

package/pennyfarthing-dist/commands/job-fair.md

@@ -0,0 +1,102 @@
+---
+description: Discover which characters in a theme excel at each role
+argument-hint: <theme> [--runs N] [--roles <list>]
+---
+
+# Job Fair
+
+Run every character in a theme against benchmarks to find hidden talents.
+
+## Usage
+
+```
+/job-fair <theme>
+/job-fair <theme> --runs 2
+/job-fair <theme> --roles dev,reviewer
+```
+
+## On Invoke
+
+**Arguments:** $ARGUMENTS
+
+### Step 1: Parse and Validate
+
+```bash
+# Theme is first positional arg (strip any --flags)
+THEME=$(echo "$ARGUMENTS" | awk '{print $1}' | sed 's/^--theme[= ]//')
+
+# Check theme exists
+ls pennyfarthing-dist/personas/themes/${THEME}.yaml
+```
+
+If not found, list available themes and stop.
+
+Extract `--runs N` (default: 4) and `--roles x,y` (default: all with baselines).
+
+### Step 2: Load Characters
+
+Read `pennyfarthing-dist/personas/themes/${THEME}.yaml` and list agents:
+
+| Role | Character |
+|------|-----------|
+| sm | {agents.sm.character} |
+| dev | {agents.dev.character} |
+| ... | ... |
+
+### Step 3: Find Baselines
+
+Pick ONE scenario per role from `internal/results/baselines/`:
+
+```bash
+# For each role, find first available baseline
+for role in dev reviewer tea sm architect; do
+  baseline=$(ls -d internal/results/baselines/*/${role} 2>/dev/null | head -1)
+  if [ -n "$baseline" ]; then
+    scenario=$(basename $(dirname "$baseline"))
+    summary="$baseline/summary.yaml"
+    # Read statistics.mean and statistics.n from summary.yaml
+  fi
+done
+```
+
+Show table:
+
+| Role | Scenario | Baseline | n |
+|------|----------|----------|---|
+| dev | race-condition-cache | 76.8 | 10 |
+
+### Step 4: Confirm
+
+Show: `{characters} × {roles} × {runs} = {total} runs`
+
+Ask user to confirm or cancel.
+
+### Step 5: Execute
+
+For each role, for each character:
+
+```bash
+# Native role
+scripts/solo-runner.sh "${THEME}:${role}" "${scenario}" ${runs}
+
+# Cross-role (character playing different role)
+scripts/solo-runner.sh "${THEME}:${native_role}" "${scenario}" ${runs} --as ${target_role}
+```
+
+Show progress as each completes.
+
+### Step 6: Report Results
+
+Show champions per role and full matrix:
+
+| Character | dev | reviewer | tea | sm | Avg |
+|-----------|-----|----------|-----|-----|-----|
+| ... | ... | ... | ... | ... | ... |
+
+Save to `internal/results/job-fair/${THEME}-${timestamp}/summary.yaml`
+
+## Reference
+
+- Theme files: `pennyfarthing-dist/personas/themes/*.yaml`
+- Baselines: `internal/results/baselines/{scenario}/{role}/summary.yaml`
+- Solo runner: `scripts/solo-runner.sh`

package/pennyfarthing-dist/commands/list-themes.md

@@ -0,0 +1,21 @@
+---
+description: List all available persona themes
+---
+
+# List Themes
+
+Show all available persona themes with the current theme highlighted.
+
+## Instructions
+
+Run the list-themes script and display the output directly to the user:
+
+```bash
+$CLAUDE_PROJECT_DIR/pennyfarthing-dist/scripts/list-themes.sh
+```
+
+**IMPORTANT:** Copy the script output into your response text so the user sees it in the console. Bash tool output may be collapsed in the UI.
+
+The output shows:
+- Current theme marked with `*`
+- Tier in brackets: `[S]` elite, `[A]` excellent, `[B]` strong, `[C]` good, `[D]` below average, `[U]` unbenchmarked

package/pennyfarthing-dist/commands/new-work.md

@@ -0,0 +1,23 @@
+---
+description: Start the next available story from the sprint backlog
+---
+
+# New Work
+
+<purpose>
+Shortcut to start the highest priority available story. Alias for `/sprint work next`.
+</purpose>
+
+<on-invoke>
+Invoke the sprint work command with "next" to auto-select the highest priority story:
+
+```
+/sprint work next
+```
+</on-invoke>
+
+<related>
+- `/sprint work` - Interactive story selection
+- `/sprint backlog` - View available stories
+- `/work` - Resume existing work or start new
+</related>

package/pennyfarthing-dist/commands/orchestrator.md

@@ -0,0 +1,9 @@
+---
+description: Orchestrator - Coordinator of all agents and meta operations
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
+python3 -m pennyfarthing_scripts.cli agent start "orchestrator"
+```

package/pennyfarthing-dist/commands/parallel-work.md

@@ -0,0 +1,73 @@
+---
+description: Start parallel work in a new worktree
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.pennyfarthing" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done
+export PYTHONPATH="$(dirname "$(dirname "$(cd "$d/.pennyfarthing/scripts" && pwd -P)")"):${PYTHONPATH:-}"
+python3 -m pennyfarthing_scripts.cli agent start "sm"
+```
+
+<parallel-work-flow>
+## Parallel Work Setup
+
+Start a new story in a worktree while keeping main checkout intact.
+
+### Step 1: Create Worktree
+
+```bash
+# Get story info from user
+read -p "Story ID (e.g., 5-3a): " STORY_ID
+read -p "Branch name (e.g., feat/5-3a-feature): " BRANCH_NAME
+
+# Create worktree
+WORKTREE_NAME="wt-${STORY_ID}"
+.pennyfarthing/scripts/git/worktree-manager.sh create "$WORKTREE_NAME" "$BRANCH_NAME"
+
+# Get port configuration
+eval $(.pennyfarthing/scripts/git/worktree-manager.sh ports "$WORKTREE_NAME")
+```
+
+### Step 2: Create Session File
+
+Create `.session/${STORY_ID}-session.md` with:
+
+```markdown
+# Story ${STORY_ID}: [Title]
+
+## Worktree Context
+worktree: ${WORKTREE_NAME}
+path: ${WORKTREE_PATH}
+api_port: ${API_PORT}
+ui_port: ${UI_PORT}
+
+## Story Info
+- **Epic:** [from sprint]
+- **Points:** [from sprint]
+- **Repos:** Both
+
+## Phase
+sm
+
+## Status
+setup
+
+## Acceptance Criteria
+- [ ] AC1
+- [ ] AC2
+```
+
+### Step 3: Hand to SM
+
+Invoke SM to complete story setup in the worktree context.
+</parallel-work-flow>
+
+<agent-activation>
+1. Load persona from theme config → `agents.sm`
+2. Load and follow `.pennyfarthing/agents/sm.md`
+3. SM will detect worktree session and work in that context
+</agent-activation>
+
+<agent-exit>
+On exit: Capture learnings to sidecar.
+</agent-exit>