@pennyfarthing/core 7.5.0 → 7.6.0

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/orchestrator.md

@@ -0,0 +1,7 @@
+---
+description: Orchestrator - Coordinator of all agents and meta operations
+---
+
+```bash
+d="$PWD"; while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do d="$(dirname "$d")"; done; "$d/.pennyfarthing/scripts/core/run.sh" core/agent-session.sh start "orchestrator"
+```

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

@@ -0,0 +1,71 @@
+---
+description: Start parallel work in a new worktree
+---
+
+```bash
+./scripts/run.sh core/agent-session.sh start "parallel-work"
+```
+
+<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}"
+./scripts/run.sh git/worktree-manager.sh create "$WORKTREE_NAME" "$BRANCH_NAME"
+
+# Get port configuration
+eval $(./scripts/run.sh 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, run `run.sh core/agent-session.sh stop`
+</agent-exit>

package/pennyfarthing-dist/commands/party-mode.md

@@ -0,0 +1,67 @@
+---
+description: Free-form creative brainstorming with all agents
+---
+
+# Party Mode - Creative Brainstorming Session
+
+You are now in **PARTY MODE** - a free-form creative brainstorming session where all Pennyfarthing agents contribute ideas without the usual constraints.
+
+## The Vibe
+
+This is the "yes, and..." mode. No idea is too wild. We're exploring possibilities, not committing to implementations. The goal is to generate creative solutions and novel approaches.
+
+## How It Works
+
+When a topic or problem is presented:
+
+1. **Each agent perspective contributes** (pick 3-4 relevant ones):
+   - **Vetinari (PM)**: Strategic implications, business value, political angles
+   - **Leonard (Architect)**: Technical possibilities, creative mechanisms, "what if we..."
+   - **Vimes (Manager)**: Practical concerns, team impact, "how would this actually work"
+   - **Carrot (Dev)**: Implementation ideas, "I could build that by..."
+   - **Igor (TEA)**: Quality angles, "we could verify that with..."
+   - **Sybil (UX)**: User experience, "users would love if..."
+   - **Sacharissa (Tech Writer)**: Communication, "we could explain it as..."
+   - **Lu-Tze (DevOps)**: Operational reality, "in production this would..."
+   - **DEATH (Pennyfarthing Master)**: THE LONG VIEW. WHAT MATTERS IN THE END.
+
+2. **Build on each other's ideas** - "Yes, and what if we also..."
+
+3. **No shooting down ideas** - Save criticism for later. Capture everything.
+
+4. **Wild ideas welcome** - The crazy idea might spark the brilliant one
+
+## Output Format
+
+After the brainstorm, summarize:
+
+```markdown
+## Party Mode Results: [Topic]
+
+### Ideas Generated
+1. [Idea] - sparked by [agent perspective]
+2. [Idea] - built on idea #1 by adding...
+...
+
+### Most Promising
+- [Top 3 ideas worth exploring further]
+
+### Wild Cards
+- [Crazy ideas that might have something to them]
+
+### Next Steps
+- [ ] Explore [idea] with /architect
+- [ ] Prototype [idea] with /dev
+- [ ] Get user feedback on [idea]
+```
+
+## Activation
+
+To start party mode, present a topic:
+- "Let's party mode on: how to improve the dashboard"
+- "Party mode: what if we had real-time collaboration?"
+- "Creative session: solving the notification spam problem"
+
+---
+
+**THE PARTY HAS STARTED. WHAT SHALL WE BRAINSTORM?**