@pennyfarthing/core 6.6.0

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

@@ -0,0 +1,168 @@
+---
+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

@@ -0,0 +1,268 @@
+# 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

@@ -0,0 +1,117 @@
+---
+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
+
+## 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
+
+### 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
+```
+
+### Quick Launch Examples
+
+```bash
+# Web mode for current directory
+cd packages/cyclist && CYCLIST_PROJECT_DIR=$PWD npm start
+
+# Web mode on custom port
+cd packages/cyclist && PORT=3000 CYCLIST_PROJECT_DIR=/path npm start
+
+# Dev mode with hot reload
+cd packages/cyclist && CYCLIST_DEV_WEB=1 CYCLIST_PROJECT_DIR=/path npm run dev: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:web` | Web server with tsx watch |
+| `npm run dev:server` | Server-only with tsx watch |
+| `npm run build` | Compile TypeScript |
+
+## Requirements
+
+- Project must have `.claude/` directory (Pennyfarthing-enabled)
+- For Electron: Cyclist.app must be installed
+- For web: Run from `packages/cyclist/` directory
+
+## Troubleshooting
+
+### Server won't start
+- Ensure you're in the cyclist package directory
+- 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 `.claude/persona-config.yaml`
+
+### "Not a Pennyfarthing project"
+- Ensure project has `.claude/` directory
+- Run `pennyfarthing init` in the project first