@pennyfarthing/core 7.0.2 → 7.4.1

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

@@ -1,171 +1,88 @@
 ---
 name: cyclist
-description: Launch Cyclist visual terminal for Claude Code. Use this skill when starting Cyclist to monitor agent work, view personas, or debug sessions.
+description: |
+  Cyclist visual terminal detection and status. Use when checking if running inside Cyclist,
+  getting session status, or accessing Cyclist-specific features.
+args: "[check|status]"
 ---
 
-# Cyclist Visual Terminal Skill
+# /cyclist - Cyclist Visual Terminal
 
-## When to Use This Skill
+## Commands
 
-- Starting Cyclist to monitor Claude Code sessions
-- Viewing persona portraits and attributes
-- Debugging agent interactions visually
-- Running Cyclist in web mode for development
+### `/cyclist` or `/cyclist check`
 
-## Overview
+Check if running inside Cyclist visual terminal.
 
-Cyclist is a visual terminal interface for Claude Code that displays:
-- Real-time terminal output with persona styling
-- Agent portraits and OCEAN personality traits
-- Story/session progress tracking
-- Git status and context information
+<run>
+.pennyfarthing/scripts/core/run.sh cyclist/is-cyclist.sh
+</run>
 
-## Quick Start (Recommended)
+<output>
+JSON: `{"cyclist": true}` with exit 0 if in Cyclist, `{"cyclist": false}` with exit 1 if not.
+</output>
 
-Use `just` commands from the project root:
+<example>
+.pennyfarthing/scripts/core/run.sh cyclist/is-cyclist.sh
+# Returns: {"cyclist": true}
+</example>
 
-```bash
-# Start Cyclist Electron (recommended)
-just cyclist-electron
-
-# Start Cyclist web server only (browser-based)
-just cyclist-web
-
-# Start Cyclist for a different project
-just cyclist-electron project_dir=/path/to/project
-```
+---
 
 ## Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CYCLIST_PROJECT_DIR` | Project directory path (required for web mode) | `$PWD` |
-| `PORT` | Server port | `1898` |
-| `CYCLIST_SESSION_ID` | Session tracking ID | auto-generated |
-| `CYCLIST_DEV_WEB` | Enable web dev mode (set to `1`) | unset |
-| `CYCLIST_THEME_PATH` | Custom theme file path | auto-detected |
-
-## CLI Flags (Electron App)
-
-| Flag | Description |
-|------|-------------|
-| `--project-dir=/path` | Specify project directory |
-
-## Launch Commands
-
-### Using Just (Recommended)
+Cyclist sets these environment variables when spawning Claude:
 
-```bash
-# Electron mode (from any pennyfarthing project)
-just cyclist-electron
-
-# Web mode (browser-based)
-just cyclist-web
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `CYCLIST` | `1` | Always set when running in Cyclist |
+| `CYCLIST_SESSION_ID` | UUID | Session tracking identifier |
+| `CYCLIST_PROJECT_DIR` | path | Project directory if specified |
+| `CYCLIST_THEME_PATH` | path | Custom theme file path |
+| `CYCLIST_DEV_WEB` | `1` | Set in web dev mode |
 
-# With explicit project directory
-just cyclist-electron project_dir=/path/to/project
-just cyclist-web project_dir=/path/to/project
-```
+---
 
-### Web Backend (Browser Mode)
+## Starting Cyclist
 
-Run from the **cyclist package directory**:
+Use `just cyclist` from the project root (outside of Claude Code):
 
 ```bash
-# Production mode
-cd packages/cyclist
-CYCLIST_PROJECT_DIR=/path/to/project npm start
+# Electron with folder picker (default)
+just cyclist
 
-# Development mode with hot reload
-cd packages/cyclist
-CYCLIST_PROJECT_DIR=/path/to/project npm run dev:web
-```
-
-Opens at: http://localhost:1898 (or next available port)
-
-### Electron App
-
-```bash
-# Using CLI wrapper (if installed)
-cyclist /path/to/project
+# Electron in current directory
+just cyclist here
 
-# Direct launch via open
-open -a Cyclist --args --project-dir=/path/to/project
+# Web dev mode (browser + hot reload)
+just cyclist web
 
-# Development (from packages/cyclist)
-cd packages/cyclist
-CYCLIST_PROJECT_DIR=/path/to/project npm run dev
+# Web server only (production)
+just cyclist server
 ```
 
-## Port Auto-Discovery
-
-The server automatically finds an available port starting from 1898:
-- Tries ports 1898, 1899, 1900... up to 10 attempts
-- Logs the actual port: `Cyclist running at http://localhost:{port}`
-
-## npm Scripts Reference
-
-From `packages/cyclist/`:
-
-| Script | Description |
-|--------|-------------|
-| `npm start` | Run production server |
-| `npm run dev` | Electron dev mode with file watching |
-| `npm run dev:once` | Build and run Electron once (no watching) |
-| `npm run dev:web` | Web server with tsx watch |
-| `npm run dev:server` | Server-only with tsx watch |
-| `npm run build` | Compile TypeScript |
-
-## Just Commands Reference
-
-| Command | Description |
-|---------|-------------|
-| `just cyclist-electron` | Start Electron dev mode |
-| `just cyclist-web` | Start web server mode |
-| `just cyclist-build` | Build Cyclist TypeScript |
-| `just cyclist-rebuild` | Rebuild native modules (node-pty) |
-| `just cyclist-setup` | Full clean + install + rebuild + build |
-| `just cyclist-build-and-install` | Build and install Cyclist.app |
-| `just test-cyclist` | Run Cyclist tests |
-
-## Requirements
-
-- Project must have `.pennyfarthing/` directory with config (Pennyfarthing-enabled)
-- For Electron: Cyclist.app must be installed, or run from source
-- For web: Run from `packages/cyclist/` directory
-
-## Troubleshooting
-
-### Window not appearing (Electron)
-
-The `package.json` has `"main": "dist/server.js"` for npm module use. The `dev` scripts explicitly run `electron dist/main.js` to use the correct entry point. If you run `electron .` directly, it will run the web server instead of the Electron main process.
-
-**Fix:** Use `just cyclist-electron` or `npm run dev` which run `electron dist/main.js`.
-
-### Server won't start
-
-- Ensure you're in the cyclist package directory (or use `just` commands)
-- Run `npm run build` first if dist/ is stale
-- Check console for port conflict messages
+---
 
-### No portraits showing
+## Internal Codenames
 
-- Verify `pennyfarthing-dist/personas/portraits/` exists
-- Check theme in `.pennyfarthing/config.local.yaml`
+| Codename | Component | Description |
+|----------|-----------|-------------|
+| **WheelHub** | Server | Central coordination (API, WebSocket, OTLP) |
+| **TirePump** | Context clearing | Clear session, reset stats, reload agent |
+| **JobFair** | Character benchmarking | Discover which characters excel at each role |
 
-### "Not a Pennyfarthing project"
+---
 
-- Ensure project has `.pennyfarthing/` directory with `config.local.yaml` or agent symlinks
-- Or has `.claude/` directory with persona-config.yaml (legacy)
-- Run `pennyfarthing init` in the project first
-- Or set `CYCLIST_PROJECT_DIR` to point to a valid project
+## Quick Reference
 
-### Native module issues (node-pty)
+| Command | Script |
+|---------|--------|
+| `/cyclist` | `cyclist/is-cyclist.sh` |
+| `/cyclist check` | `cyclist/is-cyclist.sh` |
 
-```bash
-# Rebuild native modules for current Electron version
-just cyclist-rebuild
+## Related Skills
 
-# Or full setup from scratch
-just cyclist-setup
-```
+| Skill | Purpose |
+|-------|---------|
+| `/theme` | Theme management (list, show, set) |
+| `/just` | Run just recipes including `just cyclist` |

package/pennyfarthing-dist/skills/dev-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dev-patterns
 description: Common development patterns, fixes, and gotchas. Use when implementing features, debugging issues, or avoiding known pitfalls.
+allowed_tools: [Read, Glob, Grep, Task]
 ---
 
 # Dev Patterns Skill
@@ -105,7 +106,8 @@ Use appropriate status codes consistently:
 | `409 Conflict` | Resource state conflict (duplicate) |
 | `500 Internal Server Error` | Server-side error (always log it!) |
 
-## Test Patterns
+<details>
+<summary><strong>Test Patterns</strong></summary>
 
 ### Test Isolation
 
@@ -156,6 +158,8 @@ func TestValidate(t *testing.T) {
 }
 ```
 
+</details>
+
 ## Common Gotchas
 
 1. **Working directory** - Always use `$CLAUDE_PROJECT_DIR` for absolute paths
@@ -243,7 +247,8 @@ Glob: **/*.tsx
 Glob: **/*.{ts,tsx}
 ```
 
-### Compound Subagents
+<details>
+<summary><strong>Compound Subagents</strong></summary>
 
 Design subagents to do multiple related steps in one spawn:
 
@@ -311,6 +316,8 @@ Task tool:
 - When the first step might fail often (better to fail fast)
 - When prompts are already long (context limits)
 
+</details>
+
 ### Turn Budget Guidelines
 
 | Story Size | Target Turns |
@@ -329,7 +336,8 @@ Task tool:
 6. Spawn independent subagents in parallel
 7. Run tests in background while continuing work
 
-### Background Subagent Execution
+<details>
+<summary><strong>Background Subagent Execution</strong></summary>
 
 Run slow operations in background to continue working:
 
@@ -365,7 +373,10 @@ TaskOutput tool:
 - Before commit (need to verify GREEN)
 - During handoff (need synchronous verification)
 
-### Background Task Tracking
+</details>
+
+<details>
+<summary><strong>Background Task Tracking</strong></summary>
 
 Use the background task tracking utilities to manage session file entries:
 
@@ -401,7 +412,10 @@ bg_task_cleanup "$SESSION_FILE"
 5. Update: `bg_task_update "$SESSION_FILE" "$TASK_ID" "completed"`
 6. Cleanup: `bg_task_cleanup "$SESSION_FILE"`
 
-### Example: Background Tests While Implementing
+</details>
+
+<details>
+<summary><strong>Example: Background Tests While Implementing</strong></summary>
 
 ```
 Turn 1: Spawn testing-runner in background, continue editing
@@ -413,6 +427,8 @@ Turn 5: Check TaskOutput (complete, GREEN), proceed to commit
 
 This pattern saves turns by overlapping test execution with implementation work.
 
+</details>
+
 ## Project Customization
 
 Projects should create their own dev-patterns skill in `.claude/project/skills/dev-patterns/` with:

package/pennyfarthing-dist/skills/finalize-run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finalize-run
-description: Validate and save run results. Single exit point for all benchmark runs.
+description: Validate and save benchmark run results. Use when completing a benchmark run, validating results before storage, or ensuring all runs pass through the single guardrail exit point.
 ---
 
 # Finalize Run Skill