@pennyfarthing/core 9.2.0 → 9.4.0

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

@@ -1,172 +0,0 @@
----
-name: code-review
-description: Code review checklists and patterns for Pennyfarthing. Use when reviewing PRs, self-reviewing code, or checking for common issues before commit.
----
-
-# Code Review Skill
-
-<run>Review code against the checklists below. Focus on authorization, error handling, TypeScript/React patterns, and performance.</run>
-
-<output>Code review comments using [MUST FIX], [SUGGESTION], [QUESTION], [NICE] prefixes</output>
-
-## Overview
-
-This skill provides code review patterns and checklists for the Pennyfarthing 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,277 +0,0 @@
----
-name: context-engineering
-description: Strategies for managing context windows in long-running agent sessions. Use when approaching context limits, designing subagent prompts, optimizing token usage, or implementing just-in-time context loading.
-allowed_tools: [Read, Glob, Grep, Task]
----
-
-# Context Engineering Skill
-
-<run>context-engineering</run>
-<output>strategies for managing context windows in long-running agent sessions</output>
-
-**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,88 +0,0 @@
----
-name: cyclist
-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 - Cyclist Visual Terminal
-
-## Commands
-
-### `/cyclist` or `/cyclist check`
-
-Check if running inside Cyclist visual terminal.
-
-<run>
-.pennyfarthing/scripts/cyclist/is-cyclist.sh
-</run>
-
-<output>
-JSON: `{"cyclist": true}` with exit 0 if in Cyclist, `{"cyclist": false}` with exit 1 if not.
-</output>
-
-<example>
-.pennyfarthing/scripts/cyclist/is-cyclist.sh
-# Returns: {"cyclist": true}
-</example>
-
----
-
-## Environment Variables
-
-Cyclist sets these environment variables when spawning Claude:
-
-| 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 |
-
----
-
-## Starting Cyclist
-
-Use `just cyclist` from the project root (outside of Claude Code):
-
-```bash
-# Electron with folder picker (default)
-just cyclist
-
-# Electron in current directory
-just cyclist here
-
-# Web dev mode (browser + hot reload)
-just cyclist web
-
-# Web server only (production)
-just cyclist server
-```
-
----
-
-## Internal Codenames
-
-| 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 |
-
----
-
-## Quick Reference
-
-| Command | Script |
-|---------|--------|
-| `/cyclist` | `cyclist/is-cyclist.sh` |
-| `/cyclist check` | `cyclist/is-cyclist.sh` |
-
-## Related Skills
-
-| Skill | Purpose |
-|-------|---------|
-| `/theme` | Theme management (list, show, set) |
-| `/just` | Run just recipes including `just cyclist` |