@pennyfarthing/core 6.6.0

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

@@ -0,0 +1,236 @@
+# Agentic Patterns Skill
+
+**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

@@ -0,0 +1,367 @@
+---
+name: changelog-management
+description: Maintain changelogs following Keep a Changelog format. Parse git commits with conventional commits conventions and auto-generate release notes.
+---
+
+# 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