@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/skills/judge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: judge
-description: Evaluate agent responses using standardized rubrics. Invoke with mode and response data.
+description: Evaluate agent responses using standardized rubrics. Use when scoring benchmark results, comparing agent performance, grading code review quality, or running evaluation pipelines.
 ---
 
 # Judge Skill
@@ -35,41 +35,61 @@ Canonical evaluation of agent responses. All judging goes through this skill.
 
 ## Relay Phase Rubrics
 
-### SM Phase
+<details>
+<summary><strong>SM Phase Rubric</strong></summary>
+
 | Dimension | Weight |
 |-----------|--------|
 | Clarity | 30% |
 | Handoff | 40% |
 | Completeness | 30% |
 
-### TEA Phase
+</details>
+
+<details>
+<summary><strong>TEA Phase Rubric</strong></summary>
+
 | Dimension | Weight |
 |-----------|--------|
 | Coverage | 35% |
 | RED State | 35% |
 | Handoff | 30% |
 
-### Dev Phase
+</details>
+
+<details>
+<summary><strong>Dev Phase Rubric</strong></summary>
+
 | Dimension | Weight |
 |-----------|--------|
 | GREEN State | 40% |
 | Code Quality | 30% |
 | Handoff | 30% |
 
-### Reviewer Phase
+</details>
+
+<details>
+<summary><strong>Reviewer Phase Rubric</strong></summary>
+
 | Dimension | Weight |
 |-----------|--------|
 | Detection | 40% |
 | Verdict | 30% |
 | Persona | 30% |
 
-### Chain Coherence
+</details>
+
+<details>
+<summary><strong>Chain Coherence Multipliers</strong></summary>
+
 | Rating | Multiplier |
 |--------|------------|
 | excellent | 1.2x |
 | good | 1.0x |
 | poor | 0.8x |
 
+</details>
+
 ## On Invoke
 
 ### Step 1: Parse Arguments
@@ -96,7 +116,8 @@ Extract:
 
 Based on mode, construct the appropriate prompt:
 
-#### Solo Mode Prompt
+<details>
+<summary><strong>Solo Mode Prompt (Generic Rubric)</strong></summary>
 
 **If NO baseline_issues provided, use generic rubric:**
 
@@ -139,6 +160,11 @@ Formula: (correctness × 2.5) + (depth × 2.5) + (quality × 2.5) + (persona ×
 ```
 ```
 
+</details>
+
+<details>
+<summary><strong>Solo Mode Prompt (Checklist Rubric v2 - Precision/Recall)</strong></summary>
+
 **If baseline_issues IS provided, use checklist rubric (v2 - precision/recall):**
 
 ```
@@ -222,10 +248,24 @@ Evaluate the response and output ONLY valid JSON (no markdown, no extra text):
 }
 ```
 
-## Detection Scoring Rules (v2 - Precision/Recall)
+**Detection Scoring Rules (v2 - Precision/Recall):**
+
+- Severity Weights: critical=15, high=10, medium=5, low=2
+- recall = weighted_found / weighted_total
+- precision = true_positives / (true_positives + false_positives)
+- f2_score = 5 × (precision × recall) / (4 × precision + recall)
+- detection.subtotal = (recall × 30) + (precision × 10) + min(novel_valid × 3, 10)
+
+**Other Dimensions:**
+- Quality (25 max): (clear_explanations/10 × 12.5) + (actionable_fixes/10 × 12.5)
+- Persona (25 max): (in_character/10 × 12.5) + (professional_tone/10 × 12.5)
+- weighted_total = detection.subtotal + quality.subtotal + persona.subtotal
+```
+
+</details>
 
-**Severity Weights:**
-- critical: 15, high: 10, medium: 5, low: 2
+<details>
+<summary><strong>Detection Scoring Deep Dive</strong></summary>
 
 **Metric Calculations:**
 ```
@@ -269,12 +309,6 @@ novel_bonus = min(2 × 3, 10) = 6.0
 detection.subtotal = 20.4 + 9.3 + 6.0 = 35.7
 ```
 
-**Other Dimensions:**
-- Quality (25 max): (clear_explanations/10 × 12.5) + (actionable_fixes/10 × 12.5)
-- Persona (25 max): (in_character/10 × 12.5) + (professional_tone/10 × 12.5)
-- weighted_total = detection.subtotal + quality.subtotal + persona.subtotal
-```
-
 **Checklist Scoring Notes:**
 - **Recall dominates** (30/50 pts): Comprehensive coverage is primary goal
 - **Precision matters** (10/50 pts): Penalizes hallucinated issues proportionally
@@ -283,6 +317,11 @@ detection.subtotal = 20.4 + 9.3 + 6.0 = 35.7
 - **Transparent metrics**: All intermediate values visible for debugging
 - Quality/Persona still matter (25% each) - not just about finding issues
 
+</details>
+
+<details>
+<summary><strong>Solo Mode Prompt (Behavior Checklist - SM Scenarios)</strong></summary>
+
 **If baseline_criteria IS provided (SM scenarios), use behavior checklist:**
 
 ```
@@ -346,7 +385,10 @@ Scoring rules:
 - weighted_total = execution.subtotal + quality.subtotal + persona.subtotal
 ```
 
-#### Compare Mode Prompt
+</details>
+
+<details>
+<summary><strong>Compare Mode Prompt</strong></summary>
 
 ```
 You are an impartial judge comparing two AI personas.
@@ -396,11 +438,16 @@ Score both on each dimension (1-10). Output ONLY valid JSON (no markdown, no ext
 ```
 ```
 
-#### Phase Mode Prompts
+</details>
+
+<details>
+<summary><strong>Phase Mode and Coherence Mode Prompts</strong></summary>
+
+**Phase Mode Prompts:**
 
 Use phase-specific rubrics from tables above. Evaluate both teams. Output JSON format.
 
-#### Coherence Mode Prompt
+**Coherence Mode Prompt:**
 
 ```
 Evaluate chain coherence for {theme}.
@@ -421,7 +468,10 @@ Output ONLY valid JSON (no markdown, no extra text):
 ```
 ```
 
-### Step 3: Execute Judge via CLI
+</details>
+
+<details>
+<summary><strong>Step 3: Execute Judge via CLI</strong></summary>
 
 **CRITICAL: Follow this execution pattern for all contexts (main session, skills, subagents).**
 
@@ -459,7 +509,10 @@ JUDGE_OUTPUT_TOKENS=$(jq -r '.usage.output_tokens // 0' .scratch/judge_output.js
 **Key insight:** The shell never parses the JSON when using file redirection.
 The output goes directly to a file, then jq reads it safely.
 
-### Step 4: Extract Scores
+</details>
+
+<details>
+<summary><strong>Step 4: Extract Scores</strong></summary>
 
 ```bash
 # All modes now output JSON - parse with jq
@@ -480,6 +533,8 @@ if [[ -z "$SCORE" ]]; then
 fi
 ```
 
+</details>
+
 ### Step 5: Validate Results
 
 | Check | Requirement |

package/pennyfarthing-dist/skills/just/SKILL.md

@@ -1,160 +1,403 @@
 ---
-name: just-runner
-description: Run just recipes for project tasks. This skill should be used when starting dev servers, running tests, managing databases, checking project health, or writing new justfile recipes.
+name: just
+description: |
+  Run just recipes for project tasks. This skill should be used when starting dev servers,
+  running tests, managing Cyclist, generating portraits, or writing new justfile recipes.
+args: "[recipe] [args...]"
 ---
 
-# Just Command Runner Skill
+# /just - Project Task Runner
 
-## When to Use This Skill
+`just` is a command runner for project tasks. All commands run from the **project root**.
 
-- Starting/stopping development servers
-- Running tests
-- Managing databases (start, stop, reset, seed)
-- Checking service health/status
-- Writing new justfile recipes
+## Commands
 
-## Overview
+### `/just` or `/just --list`
 
-`just` is a command runner (like `make` but simpler). Commands run from the **project root** unless otherwise specified.
+List all available recipes.
 
-**Installation:** `brew install just` or `cargo install just`
+**Run:**
+```bash
+just --list
+```
+
+**Output:** Recipe names with descriptions.
+
+---
+
+### `/just build`
+
+Build all packages in the monorepo.
+
+**Run:**
+```bash
+just build
+```
 
-## Getting Help
+**What it does:** Runs `pnpm run build` to compile TypeScript across all packages.
 
+---
+
+### `/just test`
+
+Run tests for all packages.
+
+**Run:**
 ```bash
-just help      # Show categorized commands with descriptions
-just --list    # List all recipes without descriptions
-just --show <recipe>  # Show recipe definition
+just test
 ```
 
-## Common Recipe Patterns
+**What it does:** Runs `pnpm test` which executes Node.js native test runner across the monorepo.
+
+---
+
+### `/just test-cyclist`
+
+Run tests for the Cyclist package only.
 
-### Development
+**Run:**
 ```bash
-just dev           # Start development environment
-just dev-start     # Start all services
-just dev-stop      # Stop all services
-just dev-status    # Check service status
-just dev-logs      # Tail logs
+just test-cyclist
 ```
 
-### Testing
+**What it does:** Runs `npm test` in `packages/cyclist/`.
+
+---
+
+### `/just test-cyclist-watch`
+
+Run Cyclist tests in watch mode for TDD workflow.
+
+**Run:**
 ```bash
-just test          # Run all tests
-just test-setup    # Setup test infrastructure
-just test-api      # Backend tests only
-just test-ui       # Frontend tests only
+just test-cyclist-watch
 ```
 
-### Database
+**What it does:** Runs Vitest in watch mode, re-running tests on file changes.
+
+---
+
+### `/just install`
+
+Install dependencies for all packages.
+
+**Run:**
 ```bash
-just db-start      # Start database services
-just db-stop       # Stop database services
-just db-reset      # Reset databases (DESTRUCTIVE)
-just db-seed       # Seed with test data
+just install
 ```
 
-## Passing Arguments
+**What it does:** Runs `pnpm install` to install dependencies across the monorepo.
+
+---
+
+## Cyclist Commands
+
+The `cyclist` recipe is the main entry point for Cyclist operations.
+
+### `/just cyclist` (default)
 
-Just recipes accept arguments directly (NO `--` separator needed):
+Launch Cyclist in Electron mode with folder picker.
 
+**Run:**
 ```bash
-# Correct
-just test-api -run TestName ./...
-just build --release
+just cyclist
+```
 
-# WRONG - don't use --
-just test-api -- -run TestName
+**What it does:** Starts Cyclist Electron app, prompting to select a project directory.
+
+---
+
+### `/just cyclist here`
+
+Launch Cyclist for the current directory.
+
+**Run:**
+```bash
+just cyclist here
+```
+
+**What it does:** Starts Cyclist Electron app with `pwd` as the project directory.
+
+---
+
+### `/just cyclist web`
+
+Launch Cyclist in web dev mode with hot reload.
+
+**Run:**
+```bash
+just cyclist web
+```
+
+**What it does:** Starts the web server with Vite for browser-based development.
+
+---
+
+### `/just cyclist server`
+
+Start Cyclist web server only (no browser).
+
+**Run:**
+```bash
+just cyclist server
+```
+
+**What it does:** Starts the backend server for headless or remote access.
+
+---
+
+### `/just cyclist verbose`
+
+Enable debug logging for troubleshooting.
+
+**Run:**
+```bash
+just cyclist verbose
+```
+
+**Combine flags:**
+```bash
+just cyclist here verbose
+just cyclist web verbose
+```
+
+---
+
+### `/just cyclist dir=<path>`
+
+Launch Cyclist for a specific project directory.
+
+**Run:**
+```bash
+just cyclist dir=/path/to/project
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `dir=` | Yes | Absolute path to project directory |
+
+---
+
+### `/just cyclist setup`
+
+First-time setup for Cyclist development.
+
+**Run:**
+```bash
+just cyclist setup
+```
+
+**What it does:**
+1. Cleans stale artifacts (`rm -rf packages/cyclist/dist/`)
+2. Installs dependencies (`pnpm install`)
+3. Rebuilds native modules (`npx electron-rebuild`)
+4. Builds TypeScript (`pnpm run build`)
+
+---
+
+### `/just cyclist doctor`
+
+Diagnose Cyclist setup issues.
+
+**Run:**
+```bash
+just cyclist doctor
+just cyclist doctor --fix
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `--fix` | No | Auto-repair detected issues |
+
+**What it does:** Checks for common setup problems and optionally fixes them.
+
+---
+
+### `/just cyclist build`
+
+Build Cyclist TypeScript only.
+
+**Run:**
+```bash
+just cyclist build
+```
+
+**What it does:** Compiles TypeScript in `packages/cyclist/`. Builds workspace dependencies first if missing.
+
+---
+
+### `/just cyclist clean`
+
+Remove Cyclist build artifacts.
+
+**Run:**
+```bash
+just cyclist clean
+```
+
+**What it does:** Removes `packages/cyclist/dist/` directory.
+
+---
+
+### `/just cyclist rebuild`
+
+Rebuild native modules (node-pty) for Electron.
+
+**Run:**
+```bash
+just cyclist rebuild
+```
+
+**What it does:** Runs `npx electron-rebuild` in `packages/cyclist/`.
+
+**When needed:** After Node.js version changes or native module errors.
+
+---
+
+### `/just cyclist package`
+
+Build Cyclist Electron app for distribution.
+
+**Run:**
+```bash
+just cyclist package
 ```
 
-## Writing Custom Recipes
+**What it does:** Runs `npm run build:electron` to create distributable app.
+
+---
 
-### Basic Recipe
+### `/just cyclist install`
 
-```just
-# Recipe with description (shows in `just --list`)
-hello:
-    echo "Hello, world!"
+Install Cyclist app and CLI.
 
-# Private recipe (doesn't show in list)
-[private]
-_helper:
-    echo "I'm hidden"
+**Run:**
+```bash
+just cyclist install
 ```
 
-### Recipe with Arguments
+**What it does:**
+1. Installs `Cyclist.app` to `/Applications`
+2. Installs `cyclist` CLI to `/usr/local/bin`
+
+---
+
+## Portrait Commands
+
+Generate AI portraits for persona themes.
 
-```just
-# Positional arguments
-greet name:
-    echo "Hello, {{name}}!"
+### `/just portraits <theme>`
 
-# With defaults
-greet name="World":
-    echo "Hello, {{name}}!"
+Generate portraits for a specific theme.
 
-# Variadic arguments
-test *args:
-    go test {{args}}
+**Run:**
+```bash
+just portraits arthurian-mythos
 ```
 
-### Multi-line Scripts
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `theme` | Yes | Theme name (e.g., `arthurian-mythos`, `the-expanse`) |
+
+---
+
+### `/just portraits-all`
+
+Generate portraits for all themes.
 
-```just
-# Use shebang for complex scripts
-build:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    echo "Building..."
-    go build -o bin/app ./cmd/app
-    echo "Done!"
+**Run:**
+```bash
+just portraits-all
 ```
 
-### Variables and Interpolation
+**Warning:** This is time-intensive. Generates portraits for all 102 themes.
+
+---
 
-```just
-# Set variables
-project := "myapp"
-version := `git describe --tags`
+### `/just portraits-preview <theme>`
 
-# Use in recipes
-info:
-    echo "{{project}} version {{version}}"
+Preview portraits for a theme without saving.
 
-# Environment variables
-export DATABASE_URL := "postgres://localhost/dev"
+**Run:**
+```bash
+just portraits-preview arthurian-mythos
 ```
 
-### Dependencies
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `theme` | Yes | Theme name to preview |
+
+---
+
+## Passing Arguments to Recipes
 
-```just
-# Run `setup` before `build`
-build: setup
-    go build ./...
+Just recipes accept arguments directly (no `--` separator needed):
 
-# Multiple dependencies
-deploy: build test
-    ./deploy.sh
+```bash
+# Correct
+just test-cyclist --filter "B-001"
+just cyclist here verbose
+
+# WRONG - don't use --
+just test-cyclist -- --filter "B-001"
 ```
 
-### Conditionals
+---
+
+## Inspecting Recipes
+
+### Show recipe definition
+
+**Run:**
+```bash
+just --show <recipe>
+```
 
-```just
-# Platform-specific
-install:
-    {{ if os() == "macos" }} brew install foo {{ else }} apt install foo {{ endif }}
+**Example:**
+```bash
+just --show cyclist
+# Shows the full recipe implementation
 ```
 
-## Best Practices
+---
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `just` | List available recipes |
+| `just build` | Build all packages |
+| `just test` | Run all tests |
+| `just test-cyclist` | Run Cyclist tests |
+| `just test-cyclist-watch` | Cyclist tests in watch mode |
+| `just install` | Install dependencies |
+| `just cyclist` | Electron + folder picker |
+| `just cyclist here` | Electron + current directory |
+| `just cyclist web` | Web dev mode |
+| `just cyclist server` | Web server only |
+| `just cyclist setup` | First-time setup |
+| `just cyclist doctor` | Diagnose issues |
+| `just cyclist build` | Build TypeScript |
+| `just cyclist clean` | Remove dist/ |
+| `just cyclist rebuild` | Rebuild native modules |
+| `just cyclist package` | Build Electron app |
+| `just cyclist install` | Install app + CLI |
+| `just portraits <theme>` | Generate theme portraits |
+| `just portraits-all` | Generate all portraits |
+| `just portraits-preview <theme>` | Preview portraits |
+
+## Dependencies
 
-1. **Use `echo -e`** for colored output (not plain `echo`)
-2. **Use `#!/usr/bin/env bash`** shebang for multi-line scripts
-3. **Mark internal recipes as `[private]`**
-4. **Use `{{var}}`** for variable interpolation, not `$var`
-5. **Extract complex logic** to scripts in `scripts/` directory
-6. **Add descriptions** to all public recipes
+```bash
+brew install just
+# or
+cargo install just
+```
 
-## Reference Documentation
+## Reference
 
-- **Justfile Syntax:** See `references/justfile-syntax.md`
 - **Official Docs:** https://just.systems/man/en/