@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/templates/LEADERBOARD.schema.yaml

@@ -0,0 +1,187 @@
+# Leaderboard Schema Specification
+# Version: 1.0.0
+# Generated leaderboards must conform to this structure
+
+schema_version: 1
+
+# Header section - metadata about the benchmark
+header:
+  scenario_name:
+    type: string
+    example: "race-condition-cache"
+    description: "Scenario identifier from scenarios/ directory"
+
+  scenario_title:
+    type: string
+    example: "Race Condition Cache"
+    description: "Human-readable scenario name (title case)"
+
+  difficulty:
+    type: enum
+    values: [easy, medium, hard, extreme]
+    description: "Scenario difficulty level"
+
+  role:
+    type: string
+    example: "dev"
+    description: "Agent role (dev, reviewer, tea, sm, architect)"
+
+  role_title:
+    type: string
+    example: "Developer"
+    description: "Human-readable role name"
+
+  baseline:
+    mean:
+      type: number
+      precision: 2
+      description: "Control agent mean score"
+    std_dev:
+      type: number
+      precision: 2
+      description: "Control agent standard deviation"
+    n:
+      type: integer
+      description: "Number of control runs"
+
+  version:
+    type: string
+    example: "5.0.1"
+    description: "Pennyfarthing version used"
+
+  generated_timestamp:
+    type: string
+    format: "ISO8601"
+    example: "2026-01-03T03:45:00Z"
+    description: "When leaderboard was generated"
+
+# Rankings table columns
+rankings:
+  columns:
+    - name: Rank
+      type: integer
+      description: "Position by mean score (ties share rank)"
+
+    - name: Theme
+      type: string
+      description: "Theme identifier"
+
+    - name: Character
+      type: string
+      description: "Persona character name for this role. Cross-role entries show '(as {role})' suffix."
+
+    - name: Mean
+      type: number
+      precision: 2
+      description: "Mean score across all runs"
+
+    - name: Std Dev
+      type: number
+      precision: 2
+      description: "Standard deviation of scores"
+
+    - name: n
+      type: integer
+      description: "Number of runs"
+
+    - name: Delta
+      type: number
+      precision: 2
+      signed: true
+      description: "Difference from baseline mean (+ or -)"
+
+    - name: "Cohen's d"
+      type: number
+      precision: 2
+      signed: true
+      description: "Effect size using pooled standard deviation"
+
+  # Cross-role metadata (optional, present when cross_role=true in summary.yaml)
+  cross_role_fields:
+    - name: Cross-Role
+      type: boolean
+      optional: true
+      description: "True if character is performing outside their native role"
+
+    - name: Source Role
+      type: string
+      optional: true
+      description: "Character's native role (e.g., 'sm' for Prospero)"
+
+    - name: Effective Role
+      type: string
+      optional: true
+      description: "Role being performed (matches the leaderboard's role)"
+
+  special_rows:
+    control_row:
+      position: "After last positive delta, before first negative"
+      format: "| --- | **CONTROL** | **Baseline** | **{mean}** | **{std}** | **{n}** | **0.00** | **0.00** |"
+      description: "Bold separator row showing baseline"
+
+  sorting:
+    primary: mean
+    order: descending
+    tie_handling: "Same rank, listed alphabetically by theme"
+
+# Cohen's d calculation
+cohens_d:
+  formula: "d = (M1 - M2) / sqrt(((n1-1)*s1² + (n2-1)*s2²) / (n1+n2-2))"
+  interpretation:
+    negligible: "< 0.20"
+    small: "0.20"
+    medium: "0.50"
+    large: "0.80"
+    very_large: "> 1.20"
+  notes:
+    - "Positive d = outperforms baseline"
+    - "Negative d = underperforms baseline"
+    - "Uses pooled standard deviation for unequal sample sizes"
+
+# Summary statistics section
+summary:
+  total_themes:
+    type: integer
+    description: "Count of all themed agents benchmarked"
+
+  themes_above:
+    type: integer
+    description: "Count with mean > baseline mean"
+
+  themes_near:
+    type: integer
+    description: "Count within 1 point of baseline"
+
+  total_runs:
+    type: integer
+    description: "Sum of all n values"
+
+# Top/Bottom performer tables
+highlights:
+  top_performers:
+    count: 5
+    criteria: "Highest Cohen's d (most positive)"
+    columns: [Theme, Character, Mean, Delta, "Cohen's d"]
+
+  bottom_performers:
+    count: 5
+    criteria: "Lowest Cohen's d (most negative)"
+    columns: [Theme, Character, Mean, Delta, "Cohen's d"]
+
+# Data sources
+data_sources:
+  baseline: "internal/results/baselines/{scenario}/{role}/summary.yaml"
+  themes: "internal/results/benchmarks/{scenario}/{theme}-{role}/summary.yaml"
+  cross_role: "internal/results/benchmarks/{scenario}/{theme}-{character}-as-{role}/summary.yaml"
+  ocean_analysis: "./OCEAN-ANALYSIS.md"
+
+# Generation requirements
+requirements:
+  minimum_n: 4
+  recommended_n: 5
+  baseline_n: 10
+  character_required: true
+  notes:
+    - "All themes should have consistent n for valid comparison"
+    - "Character names must be populated from theme YAML"
+    - "Model and token data tracked per-run, not in leaderboard header"

package/pennyfarthing-dist/templates/LEADERBOARD.template.md

@@ -0,0 +1,59 @@
+# {SCENARIO_TITLE} - {ROLE_TITLE} Leaderboard
+
+**Scenario:** `{scenario_name}` ({difficulty} difficulty)
+**Role:** {role_title} (`{role}`)
+**Baseline:** Control agent, mean {baseline_mean}, std_dev {baseline_std}, n={baseline_n}
+**Pennyfarthing Version:** {version}
+**Generated:** {generated_timestamp}
+
+**Analysis:** [OCEAN Personality Correlation Analysis](./OCEAN-ANALYSIS.md)
+
+---
+
+## Cohen's d Interpretation
+
+| Effect Size | Cohen's d |
+|-------------|-----------|
+| Negligible | |d| < 0.20 |
+| Small | |d| = 0.20 |
+| Medium | |d| = 0.50 |
+| Large | |d| = 0.80 |
+| Very Large | |d| > 1.20 |
+
+---
+
+## Rankings
+
+| Rank | Theme | Character | Mean | Std Dev | n | Delta | Cohen's d |
+|------|-------|-----------|------|---------|---|-------|-----------|
+{RANKINGS_ROWS}
+
+---
+
+## Summary Statistics
+
+- **Total Themes:** {total_themes}
+- **Themes Beating Baseline:** {themes_above}
+- **Themes At/Near Baseline (within 1 point):** {themes_near}
+- **Total Benchmark Runs:** {total_runs}
+
+## Top Performers (Above Baseline)
+
+| Theme | Character | Mean | Delta | Cohen's d |
+|-------|-----------|------|-------|-----------|
+{TOP_PERFORMERS_ROWS}
+
+## Bottom Performers
+
+| Theme | Character | Mean | Delta | Cohen's d |
+|-------|-----------|------|-------|-----------|
+{BOTTOM_PERFORMERS_ROWS}
+
+---
+
+## Notes
+
+- Cohen's d uses pooled standard deviation: `d = (M1 - M2) / sqrt(((n1-1)*s1² + (n2-1)*s2²) / (n1+n2-2))`
+- Positive d indicates theme outperforms baseline; negative indicates underperformance
+- Model and token usage tracked per-run in individual result files
+- {scenario_description}

package/pennyfarthing-dist/templates/agent-scopes.yaml.template

@@ -0,0 +1,276 @@
+# Pennyfarthing Agent Scope Configuration
+# Defines permissions and context for each agent type
+#
+# Three-Tier Permission Model:
+# 1. Strategic Agents (Opus) - Full project scope, broad permissions
+# 2. Tactical Agents (Opus)  - Story-scoped, focused permissions
+# 3. Helper Subagents (Haiku) - Minimal scope, specific task permissions
+
+# =============================================================================
+# STRATEGIC AGENTS - Full project scope, planning & coordination
+# =============================================================================
+# These agents see the whole project and can make cross-cutting decisions.
+# They handle: sprint planning, architecture, story coordination, DevOps
+
+strategic_agents:
+
+  orchestrator:
+    description: "Master orchestrator - coordinates all agents"
+    scope: full
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Bash
+      - Edit(.claude/**)
+      - Edit(sprint/**)
+      - Edit(.session/**)
+      - Write(.claude/**)
+      - Write(sprint/**)
+      - Write(.session/**)
+      - Skill(*)           # Can invoke any agent
+      - Task(*)            # Can spawn any subagent
+    context_files:
+      - sprint/current-sprint.yaml
+      - .claude/project/docs/shared-context.md
+      - .session/*-session.md
+
+  pm:
+    description: "Product Manager - strategic planning & prioritization"
+    scope: full
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Edit(sprint/**)
+      - Edit(.session/**)
+      - Write(sprint/**)
+      - Skill(sm)
+      - Skill(architect)
+    context_files:
+      - sprint/current-sprint.yaml
+      - .claude/project/docs/shared-context.md
+      - .session/*-session.md
+
+  sm:
+    description: "Scrum Master - story coordination & workflow"
+    scope: full
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Bash
+      - Edit(sprint/**)
+      - Edit(.session/**)
+      - Write(sprint/**)
+      - Write(.session/**)
+      - Skill(tea)
+      - Skill(dev)
+      - Skill(reviewer)
+      - Task(workflow-status-check)
+      - Task(sm-*)
+    context_files:
+      - sprint/current-sprint.yaml
+      - .claude/project/docs/shared-context.md
+      - .session/*-session.md
+
+  architect:
+    description: "System Architect - technical design & patterns"
+    scope: full
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Edit(.claude/project/**)
+      - Write(.claude/project/**)
+    context_files:
+      - .claude/project/docs/shared-context.md
+      - .session/*-session.md
+
+  devops:
+    description: "DevOps Engineer - infrastructure & deployment"
+    scope: infrastructure
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Bash
+      - Edit(.github/**)
+      - Edit(docker*)
+      - Edit(**/Dockerfile)
+      - Write(.github/**)
+    context_files:
+      - sprint/current-sprint.yaml
+      - .claude/project/docs/shared-context.md
+      - .session/*-session.md
+
+# =============================================================================
+# TACTICAL AGENTS - Story-scoped, focused on current work
+# =============================================================================
+# These agents focus on the active story and implement specific changes.
+# They handle: coding, testing, reviewing, documentation
+
+tactical_agents:
+
+  dev:
+    description: "Developer - implements features & fixes"
+    scope: story
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Bash
+      - Edit(src/**)
+      - Edit(tests/**)
+      - Edit(.session/**)
+      - Write(src/**)
+      - Write(tests/**)
+      - Task(testing-runner)
+      - Task(dev-handoff)
+    context_files:
+      - .session/*-session.md
+      - .claude/project/docs/shared-context.md
+
+  tea:
+    description: "Test Engineer - writes tests & test strategy"
+    scope: story
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Bash
+      - Edit(tests/**)
+      - Edit(.session/**)
+      - Write(tests/**)
+      - Task(testing-runner)
+      - Task(tea-handoff)
+    context_files:
+      - .session/*-session.md
+      - .claude/project/docs/shared-context.md
+
+  reviewer:
+    description: "Code Reviewer - adversarial review & quality"
+    scope: story
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Bash                  # For git diff, tests
+      - Edit(.session/**)     # Write assessment
+      - Task(reviewer-preflight)
+      - Task(reviewer-handoff-*)
+    context_files:
+      - .session/*-session.md
+      - .claude/project/docs/shared-context.md
+
+  tech-writer:
+    description: "Technical Writer - documentation & guides"
+    scope: story
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Edit(**/*.md)
+      - Edit(.claude/project/docs/**)
+      - Write(**/*.md)
+    context_files:
+      - .session/*-session.md
+      - .claude/project/docs/shared-context.md
+
+  ux-designer:
+    description: "UX Designer - user experience & UI patterns"
+    scope: story
+    permissions:
+      - Read
+      - Grep
+      - Glob
+      - Edit(src/components/**)
+      - Edit(src/styles/**)
+      - Edit(**/*.css)
+      - Edit(**/*.scss)
+    context_files:
+      - .session/*-session.md
+      - .claude/project/docs/shared-context.md
+
+# =============================================================================
+# HELPER SUBAGENTS - Minimal scope, specific task execution
+# =============================================================================
+# These are Haiku-powered subagents that handle mechanical tasks.
+# They have restricted permissions and short context windows.
+
+helper_subagents:
+
+  testing-runner:
+    description: "Runs tests and reports results"
+    scope: task
+    model: haiku
+    permissions:
+      - Read
+      - Bash               # Run test commands only
+      - Grep               # Search test output
+
+  workflow-status-check:
+    description: "Scans session files and git status"
+    scope: task
+    model: haiku
+    permissions:
+      - Read
+      - Glob
+      - Grep
+      - Bash               # Git commands only
+
+  sm-story-setup:
+    description: "Creates branches and session files"
+    scope: task
+    model: haiku
+    permissions:
+      - Read
+      - Bash               # Git commands
+      - Edit(.session/**)
+      - Edit(sprint/**)
+      - Write(.session/**)
+
+  reviewer-preflight:
+    description: "Gathers test/lint results before review"
+    scope: task
+    model: haiku
+    permissions:
+      - Read
+      - Bash
+      - Grep
+      - Glob
+
+  dev-handoff:
+    description: "Updates session for Dev → Reviewer transition"
+    scope: task
+    model: haiku
+    permissions:
+      - Read
+      - Bash               # Git status
+      - Edit(.session/**)
+      - Grep
+
+# =============================================================================
+# PERMISSION SCOPE REFERENCE
+# =============================================================================
+# Permission patterns follow Claude Code conventions:
+#
+# Tool Permissions:
+#   Read          - Read any file
+#   Grep          - Search file contents
+#   Glob          - Find files by pattern
+#   Bash          - Execute shell commands
+#   Edit(path)    - Edit files matching path pattern
+#   Write(path)   - Create files matching path pattern
+#   Skill(name)   - Invoke named skill/agent
+#   Task(type)    - Spawn subagent of type
+#
+# Path Patterns:
+#   **            - Recursive wildcard
+#   *             - Single level wildcard
+#   src/**        - All files under src/
+#   **/*.md       - All markdown files
+#
+# Wildcards in permissions:
+#   Skill(*)      - Any skill
+#   Task(sm-*)    - Any sm-prefixed subagent

package/pennyfarthing-dist/templates/pennyfarthing-settings.yaml.template

@@ -0,0 +1,61 @@
+# Pennyfarthing Project Settings
+# Consolidated configuration for repos, services, and testing
+
+# ============================================================================
+# Repository Definitions
+# ============================================================================
+repos:
+  ${PROJECT_NAME}:
+    path: .
+    type: monorepo
+    language: typescript
+    test_command: npm test
+    build_command: npm run build
+    lint_command: npm run lint
+
+# Multi-repo example (uncomment and modify):
+# repos:
+#   api:
+#     path: api
+#     type: api
+#     language: go
+#     test_command: go test ./...
+#   ui:
+#     path: ui
+#     type: ui
+#     language: typescript
+#     test_command: npm test
+
+# ============================================================================
+# Services Configuration
+# ============================================================================
+# Define dev server ports for worktree management
+# Each service gets offset ports in worktrees (base + worktree_index * port_offset)
+
+services:
+  port_offset: 100
+  definitions:
+    - name: App
+      base_port: 3000
+      env_var: APP_PORT
+
+# Example for Go API + React UI:
+# services:
+#   port_offset: 100
+#   definitions:
+#     - name: API
+#       base_port: 8080
+#       env_var: API_PORT
+#     - name: UI
+#       base_port: 5173
+#       env_var: UI_PORT
+
+# ============================================================================
+# Testing Configuration (optional)
+# ============================================================================
+# testing:
+#   log_dir: ".session"
+#   skip_patterns_by_language:
+#     typescript:
+#       patterns: ['it\.skip', 'describe\.skip']
+#       file_pattern: "*.test.*"

package/pennyfarthing-dist/templates/persona-config.yaml.template

@@ -0,0 +1,22 @@
+# Persona Configuration
+# Controls agent personalities in Pennyfarthing
+#
+# Available themes: discworld, star-trek-tos, literary-classics, minimalist
+# See .pennyfarthing/personas/themes/ for full list
+
+# Base theme
+theme: discworld
+
+# Personality attributes (modify agent behavior independent of theme)
+attributes:
+  verbosity: medium      # low | medium | high
+  formality: casual      # formal | casual | playful
+  humor: enabled         # enabled | disabled | subtle
+  emoji_use: minimal     # none | minimal | frequent
+
+# Per-agent overrides (optional)
+overrides: {}
+  # Example: Use a different character for reviewer
+  # reviewer:
+  #   theme: star-trek-tos
+  #   character: spock

package/pennyfarthing-dist/templates/preferences.yaml.template

@@ -0,0 +1,15 @@
+# Pennyfarthing User Preferences
+# Copy to .claude/pennyfarthing/preferences.yaml to customize
+# Override with .local.yaml for personal preferences (gitignored)
+
+# Enable persona character voice in agent output
+# When false, agents respond in a neutral, professional tone
+character_voice: true
+
+# Show reasoning and decision explanations
+# When true, agents explain their thought process
+explain_decisions: true
+
+# Auto-commit on story completion
+# When true, SM auto-commits after finishing a story
+auto_commit: false

package/pennyfarthing-dist/templates/settings.local.json.template

@@ -0,0 +1,90 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Grep",
+      "Glob",
+      "Bash",
+      "Bash(claude:*)",
+      "Bash(date:*)",
+      "Bash(mkdir:*)",
+      "Edit(.claude/**)",
+      "Edit(.pennyfarthing/**)",
+      "Edit(sprint/**)",
+      "Edit(.session/**)",
+      "Edit(results/**)",
+      "Write(.claude/**)",
+      "Write(.pennyfarthing/**)",
+      "Write(sprint/**)",
+      "Write(.session/**)",
+      "Write(results/**)",
+      "Skill(sm)",
+      "Skill(tea)",
+      "Skill(dev)",
+      "Skill(reviewer)",
+      "Skill(solo)",
+      "Skill(benchmark)",
+      "Skill(benchmark-control)",
+      "Skill(judge)",
+      "Skill(finalize-run)"
+    ]
+  },
+  "context_budget": {
+    "warning_threshold": 70,
+    "critical_threshold": 85,
+    "max_tokens": 200000
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/hooks/session-start.sh"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/project/hooks/setup-env.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/hooks/pre-edit-check.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|Bash|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/hooks/context-warning.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|Bash|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/hooks/context-circuit-breaker.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "\"$CLAUDE_PROJECT_DIR\"/.pennyfarthing/scripts/misc/statusline.sh"
+  }
+}