@pennyfarthing/core 7.0.2 → 7.4.0

package/pennyfarthing-dist/skills/code-review/SKILL.md

@@ -1,168 +0,0 @@
----
-name: code-review
-description: Code review checklists and patterns for Conductor. Use when reviewing PRs, self-reviewing code, or checking for common issues before commit.
----
-
-# Code Review Skill - Conductor Project
-
-## Overview
-
-This skill provides code review patterns and checklists for the Conductor project. Use this when reviewing PRs or self-reviewing before commit.
-
-## Review Checklists
-
-### API Handler Review
-
-- [ ] **Authorization check present** - Uses `utils.GetClientIDsForQuery()` for admin bypass
-- [ ] **Input validation** - Request body and params validated
-- [ ] **Error handling** - Appropriate status codes, no internal leaks
-- [ ] **Response format** - Consistent with other endpoints
-- [ ] **Tests** - Cover happy path + edge cases + error cases
-
-### UI Component Review
-
-- [ ] **Props typed correctly** - Interface defined, no `any`
-- [ ] **Loading states** - Shows spinner/skeleton while fetching
-- [ ] **Error states** - Graceful error display with retry option
-- [ ] **Empty states** - Meaningful message when no data
-- [ ] **Accessibility** - Proper ARIA labels, keyboard navigation
-- [ ] **No hardcoded strings** - Ready for i18n
-
-### Database Changes
-
-- [ ] **Migration reversible** - Can roll back cleanly
-- [ ] **Indexes present** - For common query patterns
-- [ ] **FK constraints** - Appropriate relationships defined
-- [ ] **NULL semantics** - Comments explain NULL meaning
-- [ ] **Default values** - Sensible defaults for new columns
-
-### TypeScript/React
-
-- [ ] **Type imports use `import type`** - Required for build
-- [ ] **No unused imports** - Remove or use
-- [ ] **No `any` types** - Use proper types
-- [ ] **useCallback/useMemo** - For expensive operations in deps
-- [ ] **Error boundaries** - Around risky components
-
-## Common Review Issues
-
-### Authorization
-
-```go
-// BAD - blocks admins with empty ClientIDs
-if len(clientIDs) == 0 {
-    return http.StatusForbidden
-}
-
-// GOOD - use centralized utility
-clientIDs, err := utils.GetClientIDsForQuery(user, h.db)
-```
-
-### Error Messages
-
-```go
-// BAD - leaks internals
-http.Error(w, err.Error(), 500)
-
-// GOOD - generic message, log details
-log.Error("database error", "error", err, "user_id", user.ID)
-http.Error(w, "Internal server error", 500)
-```
-
-### TypeScript Imports
-
-```typescript
-// BAD - causes build errors
-import { SomeType } from './types';
-
-// GOOD
-import type { SomeType } from './types';
-```
-
-### React Query
-
-```typescript
-// BAD - query runs even when not ready
-const { data } = useQuery({
-  queryKey: ['items', clientId],
-  queryFn: () => fetchItems(clientId),
-});
-
-// GOOD - only runs when clientId is set
-const { data } = useQuery({
-  queryKey: ['items', clientId],
-  queryFn: () => fetchItems(clientId),
-  enabled: !!clientId,
-});
-```
-
-## Approval Criteria
-
-### Must Have for Approval
-
-1. **Tests pass** - All CI checks green
-2. **No security issues** - Auth, input validation, no SQL injection
-3. **No breaking changes** - Or migration path provided
-4. **Code follows patterns** - Consistent with existing codebase
-
-### Nice to Have
-
-1. Documentation updated
-2. Performance considered
-3. Error messages helpful
-4. Edge cases handled
-
-## Security Checklist
-
-- [ ] **No SQL injection** - Use parameterized queries
-- [ ] **No XSS** - Sanitize user input in UI
-- [ ] **Auth on all endpoints** - Middleware applied
-- [ ] **Client isolation** - Multi-tenant data filtered
-- [ ] **No secrets in code** - Use env vars or KMS
-- [ ] **SSRF protection** - URL validation for external calls
-
-## Performance Checklist
-
-- [ ] **N+1 queries** - Use preloading/joins
-- [ ] **Pagination** - For list endpoints
-- [ ] **Indexes** - For filtered/sorted columns
-- [ ] **Memoization** - For expensive React renders
-- [ ] **Bundle size** - No unnecessary imports
-
-## Review Comments Format
-
-### Requesting Changes
-
-```
-**[MUST FIX]** This leaks internal error details to the client.
-Suggest: Use a generic message and log the details server-side.
-```
-
-### Suggestions
-
-```
-**[SUGGESTION]** Consider using `useMemo` here since this calculation
-runs on every render.
-```
-
-### Questions
-
-```
-**[QUESTION]** What happens if `clientId` is undefined? Should we
-add an early return or enabled flag?
-```
-
-### Praise
-
-```
-**[NICE]** Good use of the centralized auth utility here!
-```
-
-## Recent Learnings
-
-| Date | Issue | Resolution |
-|------|-------|------------|
-| Dec 2024 | Admin 403 errors | Use `GetClientIDsForQuery()` |
-| Dec 2024 | Type import errors | Use `import type` |
-| Dec 2024 | Role-based filtering | Check analyst vs manager vs admin |
-| Dec 2024 | Error boundaries | Wrap risky components |

package/pennyfarthing-dist/skills/context-engineering/SKILL.md

@@ -1,268 +0,0 @@
-# Context Engineering Skill
-
-**Purpose:** Strategies for managing context windows efficiently in long-running agent sessions.
-
-**Use when:** Working on complex tasks, approaching context limits, designing subagent prompts.
-
-**Source:** [Anthropic: Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
-
----
-
-## Core Principle
-
-> Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.
-
-Don't pre-load everything. Store lightweight identifiers (paths, URLs, queries) and load just-in-time.
-
----
-
-## Just-in-Time Context Loading
-
-### The Pattern
-
-```
-WRONG: Read all 50 test files upfront to understand patterns
-RIGHT: Store test file paths, read specific ones when implementing
-
-WRONG: Load entire codebase structure at session start
-RIGHT: Load CLAUDE.md + current task context, explore as needed
-```
-
-### Implementation
-
-1. **Store references, not content:**
-   ```
-   - Test patterns: See .claude/skills/testing/SKILL.md
-   - API handlers: internal/handlers/ (or use repos.yaml for multi-repo)
-   - UI components: src/components/
-   ```
-
-2. **Load on demand:**
-   ```
-   "I need to implement a handler. Let me read one existing handler first..."
-   [reads one file, not all handlers]
-   ```
-
-3. **Summarize, don't quote:**
-   ```
-   GOOD: "The auth middleware checks JWT tokens in the Authorization header"
-   BAD: [pastes entire middleware.go into context]
-   ```
-
----
-
-## Context Editing
-
-### Clearing Stale Results
-
-Tool results become stale over time. In long sessions:
-
-1. **Identify stale context:** Results from early in session no longer relevant
-2. **Summarize findings:** "Earlier I found X, Y, Z"
-3. **Clear mental model:** Focus on current task state
-
-### When to Reset
-
-Consider resetting context when:
-- You've been working for 20+ tool calls
-- Earlier findings are no longer relevant
-- You're going in circles
-- The task has shifted significantly
-
-### Reset Pattern
-
-```
-"Let me summarize progress:
-- Completed: A, B, C
-- Current state: D
-- Remaining: E, F
-
-Starting fresh from current state..."
-```
-
----
-
-## Subagent Patterns
-
-### The Golden Rule
-
-> Subagents return SUMMARIES, not full context.
-
-### Spawning Subagents
-
-When to spawn:
-- Task requires sifting through large amounts of data
-- Parallel exploration needed
-- Isolated context window beneficial
-
-How to spawn:
-```
-Task tool:
-  subagent_type: "Explore" or "general-purpose"
-  model: "haiku"  # For mechanical tasks
-  prompt: "Find X, summarize what you find. Don't paste entire files."
-```
-
-### Receiving Subagent Results
-
-What you get back:
-- Summary of findings
-- Key file paths (not file contents)
-- Specific answers to questions asked
-
-What you DON'T get:
-- Full tool call history
-- All files the subagent read
-- Raw grep/glob results
-
----
-
-## Memory Tools
-
-### Cross-Session State
-
-For long-running work, use external files:
-
-1. **Session file:** `.session/{STORY_ID}-session.md`
-   - Current story context
-   - Progress notes
-   - Handoff state
-
-2. **Progress log:** Project-specific tracking
-   - What was done
-   - What remains
-   - Blockers encountered
-
-3. **Sidecar files:** `.pennyfarthing/agents/{agent}-sidecar/`
-   - Patterns learned
-   - Common fixes
-   - Accumulated knowledge
-
-### Writing to Memory
-
-When you learn something reusable:
-```
-"This pattern worked well. Let me add it to the sidecar..."
-[Edit sidecar file with new pattern]
-```
-
-When completing work:
-```
-"Session complete. Updating session file with final state..."
-[Update .session/{STORY_ID}-session.md]
-```
-
----
-
-## CLAUDE.md Best Practices
-
-### Keep It Minimal
-
-CLAUDE.md should contain ONLY:
-- Project conventions (naming, structure)
-- Key commands (test, build, deploy)
-- Directory layout
-- Architecture notes
-- Core app features
-
-### What NOT to Include
-
-- Full API documentation
-- Complete code examples
-- Every edge case
-- Historical decisions
-
-### Reference, Don't Duplicate
-
-```
-GOOD:
-  "Test patterns: See .claude/skills/testing/SKILL.md"
-
-BAD:
-  "Here's how to test:
-   [300 lines of testing documentation]"
-```
-
----
-
-## Context Budget
-
-### Typical Limits
-
-| Content Type | Target Lines |
-|-------------|--------------|
-| Agent file | 200-400 |
-| Session file | 50-100 |
-| Skill file | 100-200 |
-| Repo context | 30-50 |
-| **Total per activation** | **500-800** |
-
-### Staying Under Budget
-
-1. **Load incrementally:** Start minimal, add as needed
-2. **Summarize findings:** Don't keep raw results
-3. **Use subagents:** Offload data-heavy exploration
-4. **Reference, don't embed:** Point to files instead of pasting
-
----
-
-## Signs You're Using Context Poorly
-
-| Symptom | Problem | Solution |
-|---------|---------|----------|
-| Reading same file multiple times | Not retaining key info | Summarize on first read |
-| Pasting entire files in responses | Over-sharing | Quote only relevant sections |
-| Long tool result chains | Not filtering | Request focused results |
-| Subagent returns everything | Bad prompt | Ask for summary, not raw data |
-| "I forgot what we were doing" | Context overflow | Reset with progress summary |
-
----
-
-## Templates
-
-### Subagent Exploration Prompt
-
-```
-Explore the codebase to find [SPECIFIC THING].
-
-Return:
-1. File paths where you found it (not file contents)
-2. Brief description of what each file does
-3. The most relevant 5-10 lines (not entire file)
-
-Do NOT paste entire files or long grep results.
-```
-
-### Progress Summary Template
-
-```
-## Progress Summary
-
-**Completed:**
-- [x] Task A - [brief result]
-- [x] Task B - [brief result]
-
-**Current State:**
-- Working on: [current task]
-- Blockers: [any blockers]
-
-**Remaining:**
-- [ ] Task C
-- [ ] Task D
-
-**Key Findings:**
-- [Important thing 1]
-- [Important thing 2]
-```
-
----
-
-## Key Insight
-
-Context is precious. Every token you waste on stale information is a token you can't use for solving the actual problem.
-
-**Ask yourself:**
-- Do I need to load this file, or just know it exists?
-- Can I summarize this finding instead of quoting it?
-- Would a subagent handle this better?
-- Is this context still relevant?

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

@@ -1,171 +0,0 @@
----
-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.
----
-
-# Cyclist Visual Terminal Skill
-
-## When to Use This Skill
-
-- Starting Cyclist to monitor Claude Code sessions
-- Viewing persona portraits and attributes
-- Debugging agent interactions visually
-- Running Cyclist in web mode for development
-
-## Overview
-
-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
-
-## Quick Start (Recommended)
-
-Use `just` commands from the project root:
-
-```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)
-
-```bash
-# Electron mode (from any pennyfarthing project)
-just cyclist-electron
-
-# Web mode (browser-based)
-just cyclist-web
-
-# With explicit project directory
-just cyclist-electron project_dir=/path/to/project
-just cyclist-web project_dir=/path/to/project
-```
-
-### Web Backend (Browser Mode)
-
-Run from the **cyclist package directory**:
-
-```bash
-# Production mode
-cd packages/cyclist
-CYCLIST_PROJECT_DIR=/path/to/project npm start
-
-# 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
-
-# Direct launch via open
-open -a Cyclist --args --project-dir=/path/to/project
-
-# Development (from packages/cyclist)
-cd packages/cyclist
-CYCLIST_PROJECT_DIR=/path/to/project npm run dev
-```
-
-## 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
-
-- Verify `pennyfarthing-dist/personas/portraits/` exists
-- Check theme in `.pennyfarthing/config.local.yaml`
-
-### "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
-
-### Native module issues (node-pty)
-
-```bash
-# Rebuild native modules for current Electron version
-just cyclist-rebuild
-
-# Or full setup from scratch
-just cyclist-setup
-```