@pennyfarthing/core 9.2.0 → 9.3.0

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

@@ -1,246 +0,0 @@
----
-name: agentic-patterns
-description: Core reasoning patterns for building effective LLM agents. Use when designing agent behavior, debugging agent failures, improving agent reliability, or understanding ReAct/Plan-and-Execute patterns.
-allowed_tools: [Read, Glob, Grep, Task]
----
-
-# Agentic Patterns Skill
-
-<run>When designing agent behavior, debugging agent failures, improving agent reliability.</run>
-
-<output>Core reasoning patterns for building effective LLM agents. Includes ReAct, Plan-and-Execute, Self-Reflection, confidence calibration, error recovery, multi-agent coordination, and context management strategies.</output>
-
-**Purpose:** Core reasoning patterns for building effective LLM agents.
-
-**Use when:** Designing agent behavior, debugging agent failures, improving agent reliability.
-
----
-
-## Core Reasoning Patterns
-
-### 1. ReAct (Reasoning and Acting)
-
-The foundational agentic loop. Combines chain-of-thought with tool use.
-
-```
-THOUGHT: What am I trying to accomplish? What do I know?
-ACTION: Execute tool/command based on reasoning
-OBSERVATION: What was the result? Did it match expectations?
-THOUGHT: Based on observation, what next?
-... repeat until goal achieved
-```
-
-**Why it works:** Grounds LLM outputs in real observations. Reduces hallucinations.
-
-**When to use:** Most tasks. This is the default pattern.
-
-**Example:**
-```
-THOUGHT: I need to find where authentication is handled
-ACTION: grep -r "authenticate" --include="*.go"
-OBSERVATION: Found 3 files: auth.go, middleware.go, handlers.go
-THOUGHT: middleware.go likely has the auth middleware, let me read it
-```
-
-### 2. Plan-and-Execute
-
-Decompose complex goals into sub-tasks before acting.
-
-```
-1. PLAN: Break goal into discrete steps
-2. EXECUTE: Work through each step
-3. VERIFY: Check each step succeeded before moving on
-4. ADJUST: Replan if something fails
-```
-
-**Why it works:** Prevents getting lost in complex tasks. Makes progress visible.
-
-**When to use:** Multi-step tasks, unfamiliar codebases, architectural changes.
-
-**Example:**
-```
-PLAN for "Add user authentication":
-1. Check existing auth patterns in codebase
-2. Design auth middleware
-3. Implement token validation
-4. Add protected routes
-5. Write tests
-6. Update documentation
-
-Now executing step 1...
-```
-
-### 3. Self-Reflection
-
-Evaluate own outputs before presenting them.
-
-```
-1. GENERATE: Produce initial output
-2. CRITIQUE: What could be wrong? What did I assume?
-3. REFINE: Improve based on critique
-4. PRESENT: Only after reflection
-```
-
-**Why it works:** Catches errors before they propagate. Improves quality.
-
-**When to use:** Code generation, architectural decisions, any output that matters.
-
-**Example:**
-```
-GENERATED: Function to validate email
-CRITIQUE: Did I handle edge cases? Empty string? Unicode?
-REFINE: Add null check, use proper regex, handle IDN domains
-PRESENT: Here's the validated function...
-```
-
----
-
-## Confidence and Uncertainty
-
-### Confidence Levels
-
-| Level | Indicators | Action |
-|-------|-----------|--------|
-| HIGH (proceed) | Matches known patterns, clear requirements, similar past success | Act autonomously |
-| MEDIUM (verify) | Some unknowns, first time for this pattern, could break things | Ask before risky actions |
-| LOW (ask) | Architectural change, security-sensitive, deleting files | Always ask user |
-
-### Expressing Uncertainty
-
-When uncertain, SAY SO:
-
-```
-GOOD: "I'm not sure if this is the right approach. Here's my reasoning..."
-GOOD: "I found two possible solutions. Let me explain the tradeoffs..."
-BAD: [silently picks one approach without mentioning alternatives]
-BAD: [confidently states something without verifying]
-```
-
-### Confidence Calibration
-
-Before acting, ask yourself:
-1. Have I seen this pattern before? (in skills, sidecars, or this session)
-2. What could go wrong?
-3. Is this reversible?
-4. Would a senior engineer want to review this?
-
----
-
-## Error Recovery
-
-### The Retry Pattern
-
-```
-1. ATTEMPT: Try the action
-2. OBSERVE: Did it succeed?
-3. DIAGNOSE: If failed, why?
-4. ADJUST: Modify approach based on diagnosis
-5. RETRY: Max 2 retries with different approaches
-6. ESCALATE: If still failing, ask user
-```
-
-### Graceful Degradation
-
-When stuck:
-1. **Never silently fail.** Always report what happened.
-2. **Provide context.** What were you trying to do? What went wrong?
-3. **Suggest alternatives.** "I couldn't do X, but I could try Y instead..."
-4. **Ask for help.** "I'm blocked on Z. Can you help?"
-
-### Common Failure Modes
-
-| Failure | Recovery |
-|---------|----------|
-| Tool returned error | Read error message, adjust inputs, retry |
-| Unexpected output | Verify assumptions, try different approach |
-| Stuck in loop | Stop, reflect, try fundamentally different approach |
-| Context exhaustion | Summarize progress, ask user for direction |
-
----
-
-## Multi-Agent Coordination
-
-### Handoff Patterns
-
-When handing off to another agent:
-
-1. **Write before you speak.** Update session file BEFORE saying "ready for X"
-2. **Summarize, don't dump.** Pass key findings, not full context
-3. **State expectations.** What should the next agent do?
-4. **Verify handoff.** Confirm the update was written
-
-### State Synchronization
-
-**Session file is source of truth.** Always:
-- Read session file on activation
-- Write your assessment before handoff
-- Verify what you wrote is actually in the file
-
-### Conflict Resolution
-
-If agents disagree (e.g., Reviewer rejects Dev's code):
-1. Reviewer documents specific issues
-2. Dev addresses each issue
-3. Reviewer re-reviews
-4. Repeat until resolved or escalate to user
-
----
-
-## Context Management
-
-### Just-in-Time Loading
-
-**Don't:** Load all potentially relevant files upfront
-**Do:** Store paths/identifiers, load only when needed
-
-```
-WRONG: Read all 50 test files to understand testing patterns
-RIGHT: Read testing skill, then load specific test when implementing
-```
-
-### Context Efficiency
-
-- Keep tool results focused (don't read entire files if you need one function)
-- Summarize findings rather than quoting everything
-- Reference file:line instead of copying code
-
-### When Context Gets Full
-
-1. Summarize progress so far
-2. Identify what's still needed
-3. Ask user if you should continue with fresh context
-4. Or hand off to subagent with focused task
-
----
-
-## Reasoning Mode (Toggleable)
-
-**Default:** Quiet mode - follow patterns internally, show only key decisions
-
-**Verbose mode:** User says "verbose mode" to enable explicit reasoning
-
-When verbose, show:
-```
-THOUGHT: [articulate intent]
-ACTION: [describe tool/command]
-OBSERVATION: [verify result]
-REFLECT: [adjust if needed]
-```
-
-When quiet, only show:
-- Key decisions
-- Results
-- Questions/blockers
-
----
-
-## Key Sources
-
-- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
-- [Anthropic: Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
-- [LangChain: ReAct Pattern](https://blog.langchain.com/react-agent/)
-- [LangChain: Reflection Agents](https://blog.langchain.com/reflection-agents/)
-
----
-
-**Remember:** The goal is not to follow patterns rigidly, but to THINK before acting, VERIFY results, and ASK when uncertain.

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

@@ -1,385 +0,0 @@
----
-name: changelog
-description: Maintain changelogs following Keep a Changelog format. Use when creating release notes, parsing conventional commits for changelog entries, auto-generating changelog sections from git history, or preparing CHANGELOG.md for releases.
----
-
-<run>
-Commands for changelog maintenance:
-- Parse conventional commits for changelog entries
-- Auto-generate changelog sections from git history
-- Version bump decisions using semantic versioning
-- Create release notes and CHANGELOG.md updates
-</run>
-
-<output>
-Changelog entries in Keep a Changelog format:
-- Added (new features from `feat:` commits)
-- Changed (changes from `perf:` commits, breaking changes)
-- Deprecated (features marked for removal)
-- Removed (removed features)
-- Fixed (bug fixes from `fix:` commits)
-- Security (vulnerability fixes)
-</output>
-
-# Changelog Management Skill
-
-## When to Use This Skill
-
-- Creating release notes
-- Parsing conventional commits for changelog entries
-- Auto-generating changelog sections from git history
-- Managing semantic versioning changes
-- Preparing CHANGELOG.md for releases
-- Documenting breaking changes, features, and fixes
-
-## Overview
-
-This skill guides changelog management using the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format combined with [Conventional Commits](https://www.conventionalcommits.org/). This approach ensures consistency, enables automation, and provides clear communication about changes.
-
-**Project Reference:** Pennyfarthing uses Keep a Changelog format in `/CHANGELOG.md` with semantic versioning.
-
-## Keep a Changelog Format Reference
-
-The standard structure is:
-
-```markdown
-# Changelog
-
-All notable changes to [Project] are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/),
-and this project adheres to [Semantic Versioning](https://semver.org/).
-
-## [Unreleased]
-
-*No unreleased changes*
-
----
-
-## [1.0.0] - 2024-01-15
-
-### Added
-- New user-facing features
-
-### Changed
-- Changes in existing functionality
-
-### Deprecated
-- Features marked for removal
-
-### Removed
-- Removed features
-
-### Fixed
-- Bug fixes
-
-### Security
-- Security vulnerability fixes
-
----
-
-## [0.9.0] - 2024-01-10
-...
-```
-
-### Guidelines
-
-1. **One version per section** - Each release gets its own `## [version] - date` heading
-2. **Semantic versioning** - Follow MAJOR.MINOR.PATCH (e.g., 1.5.3)
-3. **ISO 8601 dates** - Format as YYYY-MM-DD
-4. **Categorized entries** - Group changes by type (Added, Changed, Fixed, etc.)
-5. **Unreleased section** - Always maintain an `[Unreleased]` section at the top for staging changes
-6. **End-user focus** - Write for developers using your project, not your own team
-
-### Section Hierarchy
-
-- **Added** - New features
-- **Changed** - Changes to existing functionality
-- **Deprecated** - Features soon to be removed (provide migration path)
-- **Removed** - Removed features (finalize deprecations)
-- **Fixed** - Bug fixes
-- **Security** - Vulnerability fixes with patches
-
-## Conventional Commits Parsing
-
-[Conventional Commits](https://www.conventionalcommits.org/) structure commits to enable automatic changelog generation:
-
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-### Types and Changelog Mapping
-
-| Commit Type | Changelog Section | Example |
-|-------------|-------------------|---------|
-| `feat:` | Added | `feat: add user authentication` |
-| `fix:` | Fixed | `fix: handle null pointer in parser` |
-| `perf:` | Changed | `perf: optimize database queries` |
-| `docs:` | (skip) | `docs: update README` |
-| `style:` | (skip) | `style: format code` |
-| `refactor:` | (skip) | `refactor: simplify module` |
-| `test:` | (skip) | `test: add unit tests` |
-| `chore:` | (skip) | `chore: update dependencies` |
-| `ci:` | (skip) | `ci: update GitHub Actions` |
-
-### Breaking Changes
-
-Mark breaking changes with `!` or `BREAKING CHANGE:` footer:
-
-```bash
-# Using ! suffix
-feat!: redesign authentication API
-
-# Using footer
-feat: change password hashing algorithm
-
-BREAKING CHANGE: passwords now require bcrypt hashing
-```
-
-These go into the **Changed** or **Removed** section, not Added.
-
-## Auto-Generation from Git Commits
-
-### Step 1: Get Commits Since Last Tag
-
-```bash
-# Find the last tag
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-
-# Get commits since that tag
-if [ -z "$LAST_TAG" ]; then
-  git log --format="%H %s" | head -50
-else
-  git log "${LAST_TAG}..HEAD" --format="%H %s"
-fi
-```
-
-### Step 2: Parse Conventional Commits
-
-```bash
-# Extract type and description from commits
-git log "${LAST_TAG}..HEAD" --format="%s" | while read line; do
-  TYPE=$(echo "$line" | cut -d: -f1)
-  DESC=$(echo "$line" | cut -d: -f2- | sed 's/^ //')
-  echo "$TYPE: $DESC"
-done
-```
-
-### Step 3: Group by Category
-
-```bash
-# Group features
-git log "${LAST_TAG}..HEAD" --format="%s" | grep "^feat" | sed 's/^feat: /- /'
-
-# Group fixes
-git log "${LAST_TAG}..HEAD" --format="%s" | grep "^fix" | sed 's/^fix: /- /'
-
-# Group breaking changes
-git log "${LAST_TAG}..HEAD" --format="%B" | grep -A1 "BREAKING CHANGE:" | tail -n +2
-```
-
-## Complete Auto-Generation Script
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-RANGE="${LAST_TAG:+${LAST_TAG}..HEAD}"
-
-echo "## [Unreleased]"
-echo ""
-
-# Added (feat commits)
-FEATURES=$(git log ${RANGE:---all} --format="%s" | grep "^feat:" || echo "")
-if [ -n "$FEATURES" ]; then
-  echo "### Added"
-  echo "$FEATURES" | sed 's/^feat: /- /'
-  echo ""
-fi
-
-# Fixed (fix commits)
-FIXES=$(git log ${RANGE:---all} --format="%s" | grep "^fix:" || echo "")
-if [ -n "$FIXES" ]; then
-  echo "### Fixed"
-  echo "$FIXES" | sed 's/^fix: /- /'
-  echo ""
-fi
-
-# Breaking changes
-BREAKING=$(git log ${RANGE:---all} --format="%B" | grep -A1 "BREAKING CHANGE:" | grep "^-" || echo "")
-if [ -n "$BREAKING" ]; then
-  echo "### Changed"
-  echo "**Breaking Changes:**"
-  echo "$BREAKING"
-  echo ""
-fi
-```
-
-## Version Bump Patterns
-
-### Semantic Versioning
-
-```
-MAJOR.MINOR.PATCH
-
-- MAJOR: Incompatible API changes (breaking changes)
-- MINOR: Backward-compatible functionality additions
-- PATCH: Backward-compatible bug fixes
-```
-
-### Decision Tree
-
-```
-Breaking change detected?
-├─ Yes → MAJOR.0.0  (or X+1.0.0 from X.0.0)
-└─ No
-   └─ feat: commits present?
-      ├─ Yes → X.Y+1.0  (minor version bump)
-      └─ No  → X.Y.Z+1  (patch version bump)
-```
-
-### Examples
-
-```bash
-# Current version: 1.5.0
-
-# Patch release (bug fixes only)
-1.5.1  # fix: memory leak in parser
-
-# Minor release (new features, backward-compatible)
-1.6.0  # feat: add config validation, feat: support ENV vars
-
-# Major release (breaking changes)
-2.0.0  # feat!: redesign CLI API, BREAKING CHANGE: remove old flags
-```
-
-## Release Workflow Example
-
-### 1. During Development
-
-Maintain `[Unreleased]` section in CHANGELOG.md:
-
-```markdown
-## [Unreleased]
-
-### Added
-- New dark mode theme
-- User preference persistence
-
-### Fixed
-- Memory leak in event handler
-- Incorrect timezone calculations
-```
-
-### 2. Prepare Release
-
-```bash
-# Determine new version (inspect commits)
-LAST_VERSION="1.5.0"
-COMMITS=$(git log v${LAST_VERSION}..HEAD --format="%s")
-echo "$COMMITS" | grep -q "^feat:" && NEW_VERSION="1.6.0" || NEW_VERSION="1.5.1"
-
-echo "Releasing version $NEW_VERSION"
-```
-
-### 3. Create Release Section
-
-```bash
-# Generate section from commits
-NEW_DATE=$(date +%Y-%m-%d)
-
-# Update CHANGELOG.md
-sed -i '' "s/## \[Unreleased\]/## [Unreleased]\n\n*No unreleased changes*\n\n---\n\n## [$NEW_VERSION] - $NEW_DATE/" CHANGELOG.md
-```
-
-### 4. Commit and Tag
-
-```bash
-git add CHANGELOG.md VERSION
-git commit -m "chore: bump to version $NEW_VERSION"
-git tag -a "v$NEW_VERSION" -m "Release $NEW_VERSION"
-git push origin main --tags
-```
-
-## Integration with /release Command
-
-The `/release` command in Pennyfarthing can use this skill for:
-
-1. **Auto-detecting new commits** - Run conventional commit analysis since last tag
-2. **Generating changelog sections** - Create properly formatted entries
-3. **Version bumping** - Semantic versioning based on commit types
-4. **Tagging** - Create annotated tags for releases
-
-Reference in `/release` command:
-
-```markdown
-See the [Changelog Skill](/changelog) for patterns on:
-- Maintaining CHANGELOG.md
-- Parsing conventional commits
-- Auto-generating release notes
-- Version bump decisions
-```
-
-## Best Practices
-
-1. **Commit message quality** - Enforce conventional commits in CI/CD
-2. **Review before release** - Manual changelog review catches automation gaps
-3. **One changelog file** - Single CHANGELOG.md in project root
-4. **Link to releases** - Provide direct links to tags/release pages
-5. **Backfill old changes** - If starting Keep a Changelog mid-project, document recent versions
-6. **Human-friendly descriptions** - Conventional commits are machine-parseable; enhance for humans
-7. **Changelog in PR reviews** - Ensure PR descriptions clarify what should be in changelog
-
-## Tools and Automation
-
-### Conventional Commits Linting
-
-```bash
-# Install commitlint
-npm install --save-dev @commitlint/config-conventional @commitlint/cli
-
-# Configure .commitlintrc.js
-echo "module.exports = {extends: ['@commitlint/config-conventional']}" > .commitlintrc.js
-
-# Test a message
-echo "feat: add new feature" | commitlint
-```
-
-### Automatic Changelog Generation
-
-Tools that auto-generate from commits:
-
-- **conventional-changelog** - Node.js package
-- **changie** - Go-based with template support
-- **git-cliff** - Rust-based with flexible templates
-
-Example with conventional-changelog:
-
-```bash
-npm install --save-dev conventional-changelog-cli
-npx conventional-changelog -p angular -i CHANGELOG.md -s
-```
-
-### CI/CD Integration
-
-```yaml
-# GitHub Actions example
-- name: Generate Changelog
-  run: |
-    npx conventional-changelog -p angular -i CHANGELOG.md -s
-    git add CHANGELOG.md
-    git commit -m "docs: update CHANGELOG" || echo "No changes"
-```
-
-## Reference Documentation
-
-- **Keep a Changelog:** https://keepachangelog.com/
-- **Conventional Commits:** https://www.conventionalcommits.org/
-- **Semantic Versioning:** https://semver.org/
-- **conventional-changelog:** https://github.com/conventional-changelog/conventional-changelog
-- **Pennyfarthing Release:** `/release` command