npm - @pennyfarthing/core - Versions diffs - 7.0.2 → 7.4.0 - Mend

@pennyfarthing/core 7.0.2 → 7.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (692) hide show

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

@@ -1,236 +0,0 @@
-# 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 DELETED Viewed

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