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/guides/HOOKS.md DELETED Viewed

@@ -1,230 +0,0 @@
-# Hooks Configuration Guide
-Pennyfarthing uses Claude Code hooks to integrate with session lifecycle events and protect files from accidental modification.
-## Overview
-Hooks are shell scripts that Claude Code runs at specific events:
-| Hook Type | When It Runs | Purpose |
-|-----------|--------------|---------|
-| `SessionStart` | When Claude Code session begins | Initialize environment, set variables |
-| `PreToolUse` | Before a tool call executes | Validate/block operations |
-| `PostToolUse` | After a tool call completes | Log, cleanup, notifications |
-## Pennyfarthing Default Hooks
-### SessionStart: session-start.sh
-**Location:** `.claude/pennyfarthing/scripts/hooks/session-start.sh`
-Initializes the Pennyfarthing environment:
-- Creates `.session/` directory structure
-- Clears stale agent state from previous sessions
-- Sets `PROJECT_ROOT` and `SESSION_ID` environment variables
-### SessionStart: setup-env.sh
-**Location:** `.claude/project/hooks/setup-env.sh`
-Project-specific environment setup. Edit this file to:
-- Set custom environment variables
-- Configure project-specific paths
-- Initialize project dependencies
-### PreToolUse: pre-edit-check.sh
-**Location:** `.claude/pennyfarthing/scripts/hooks/pre-edit-check.sh`
-Protects sensitive files from accidental edits:
-- Blocks: `.env`, `.pem`, `.key`, credentials, secrets
-- Blocks: `.git/`, `node_modules/`, `vendor/`
-- Blocks: `.claude/pennyfarthing/*` (managed files)
-## Configuration Schema
-Hooks are configured in `.claude/settings.local.json`:
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/session-start.sh"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/pennyfarthing/scripts/hooks/pre-edit-check.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-### Hook Entry Structure
-```json
-{
-  "matcher": "ToolNameRegex",  // Optional: regex to filter by tool name
-  "hooks": [
-    {
-      "type": "command",
-      "command": "path/to/script.sh"
-    }
-  ]
-}
-```
-### Matcher Format
-The `matcher` field is a regex string that matches tool names:
-- `"Edit|Write"` - Match Edit or Write tools
-- `"Bash"` - Match Bash tool only
-- Omit matcher to run on all tool uses
-## Hook Script Contract
-### Input
-Hooks receive JSON via stdin:
-```json
-{
-  "session_id": "abc123",
-  "source": "vscode",
-  "tool_name": "Edit",
-  "tool_input": {
-    "file_path": "/path/to/file.ts",
-    "old_string": "...",
-    "new_string": "..."
-  }
-}
-```
-### Output
-| Exit Code | Meaning |
-|-----------|---------|
-| `0` | Allow (continue execution) |
-| `2` | Block (stderr shown to Claude as error) |
-### Environment Variables
-Available in hooks:
-- `CLAUDE_PROJECT_DIR` - Project root directory
-- `CLAUDE_ENV_FILE` - Path to write persistent env vars
-## Adding Custom Hooks
-### 1. Create Hook Script
-```bash
-#!/usr/bin/env zsh
-# .claude/project/hooks/my-custom-hook.sh
-set -euo pipefail
-input=$(cat)
-# Your logic here
-exit 0  # Allow, or exit 2 to block
-```
-### 2. Make Executable
-```bash
-chmod +x .claude/project/hooks/my-custom-hook.sh
-```
-### 3. Configure in settings.local.json
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/project/hooks/my-custom-hook.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-## Examples
-### Block Specific File Patterns
-```bash
-#!/usr/bin/env zsh
-# Block edits to migration files
-input=$(cat)
-file_path=$(echo "$input" | jq -r '.tool_input.file_path // ""')
-if [[ "$file_path" == *"/migrations/"* ]]; then
-    echo "BLOCKED: Migration files are immutable" >&2
-    exit 2
-fi
-exit 0
-```
-### Log All Bash Commands
-```bash
-#!/usr/bin/env zsh
-# Log bash commands for audit
-input=$(cat)
-command=$(echo "$input" | jq -r '.tool_input.command // ""')
-echo "$(date -Iseconds) | $command" >> "$CLAUDE_PROJECT_DIR/.session/bash-log.txt"
-exit 0
-```
-### Environment Setup
-```bash
-#!/usr/bin/env zsh
-# .claude/project/hooks/setup-env.sh
-# Set project-specific environment
-if [ -n "${CLAUDE_ENV_FILE:-}" ]; then
-    cat >> "$CLAUDE_ENV_FILE" << EOF
-export API_URL="http://localhost:3000"
-export DATABASE_URL="postgres://localhost/myapp"
-EOF
-fi
-exit 0
-```
-## Debugging Hooks
-If a hook fails or behaves unexpectedly:
-1. **Check permissions:** `chmod +x your-hook.sh`
-2. **Test manually:** `echo '{}' | ./your-hook.sh`
-3. **Check stderr:** Hook errors appear in Claude Code output
-4. **Validate JSON:** Use `jq` to parse input correctly
-## File Locations
-| Type | Location | Editable |
-|------|----------|----------|
-| Managed hooks | `.claude/pennyfarthing/scripts/hooks/` | No (use pennyfarthing repo) |
-| Project hooks | `.claude/project/hooks/` | Yes |
-| Settings | `.claude/settings.local.json` | Yes |

package/pennyfarthing-dist/guides/PROMPT-PATTERNS.md DELETED Viewed

@@ -1,338 +0,0 @@
-# Prompt Patterns Guide
-This document describes the prompt engineering patterns used in Pennyfarthing, based on [Anthropic's official documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview).
----
-## Why XML Tags?
-From [Anthropic's documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/use-xml-tags):
-> When your prompts involve multiple components like context, instructions, and examples, XML tags can be a game-changer. They help Claude parse your prompts more accurately, leading to higher-quality outputs.
-**Benefits:**
-- **Clarity:** Clearly separate different parts of your prompt
-- **Accuracy:** Reduce errors caused by Claude misinterpreting parts of your prompt
-- **Flexibility:** Easily find, add, remove, or modify parts without rewriting everything
-- **Parseability:** Makes it easier to extract specific parts of Claude's response
-**Key insight from Anthropic:**
-> There are no canonical "best" XML tags that Claude has been trained with in particular, although we recommend that your tag names make sense with the information they surround.
----
-## Anthropic's Best Practices
-### 1. Be Consistent
-Use the same tag names throughout your prompts, and refer to those tag names when talking about the content:
-```
-Using the contract in <contract> tags, analyze the liability clauses.
-```
-### 2. Nest Tags for Hierarchy
-```xml
-<outer>
-  <inner>
-    Content here
-  </inner>
-</outer>
-```
-### 3. Combine with Other Techniques
-Combine XML tags with:
-- **Multishot prompting:** `<examples>`
-- **Chain of thought:** `<thinking>`, `<answer>`
-- **Role prompting:** System message for role, XML for structure
----
-## Pennyfarthing Tag Conventions
-### Agent Lifecycle Tags
-| Tag | Purpose | When Applied |
-|-----|---------|--------------|
-| `<agent-activation>` | Step-by-step activation sequence | On agent start |
-| `<agent-exit>` | Cleanup steps when leaving | On "exit" or switch |
-| `<persona-loading>` | Instructions for loading character | Before activation |
-### Guidance Tags
-| Tag | Purpose | Used By |
-|-----|---------|---------|
-| `<blessed-path-guidance>` | Explains the primary workflow | Tactical agents |
-| `<support-agent-guidance>` | Clarifies this is a support agent | PM, Architect, etc. |
-### Attribute Patterns
-Use attributes to signal importance or provide metadata:
-```xml
-<agent-activation CRITICAL="TRUE">
-  These steps MUST be followed exactly.
-</agent-activation>
-<persona-loading agent="dev">
-  Load the dev agent's persona.
-</persona-loading>
-```
----
-## Tag Reference
-### `<agent-activation CRITICAL="TRUE">`
-The core activation sequence for every agent. The `CRITICAL="TRUE"` attribute signals this must be followed exactly.
-**Structure:**
-```xml
-<agent-activation CRITICAL="TRUE">
-1. LOAD shared behavior from .pennyfarthing/guides/shared-agent-behavior.md
-2. LOAD the FULL agent file from .pennyfarthing/agents/{agent}.md
-3. READ its entire contents
-4. LOAD SIDECAR MEMORY:
-   ```bash
-   SIDECAR="$CLAUDE_PROJECT_DIR/.claude/project/agents/{agent}-sidecar"
-   [ -d "$SIDECAR" ] && cat "$SIDECAR"/*.md 2>/dev/null | head -150
-   ```
-5. Execute ALL activation steps exactly as written
-6. Apply the loaded persona throughout the session
-7. Stay in character until exit
-</agent-activation>
-```
-### `<agent-exit>`
-Cleanup steps when the agent exits or switches.
-**Structure:**
-```xml
-<agent-exit>
-When the user says "exit", "switch agent", or ends the session:
-1. CAPTURE LEARNINGS: Ask yourself - any patterns, gotchas, or decisions to save?
-   If yes, append to `.claude/project/agents/{agent}-sidecar/{patterns|gotchas|decisions}.md`
-2. Run: [session stop command]
-3. Confirm session closed.
-</agent-exit>
-```
-### `<persona-loading agent="X">`
-Instructions for loading the agent's character from the theme system.
-**Structure:**
-```xml
-<persona-loading agent="dev">
-Load this agent's persona before activation:
-1. Read `.pennyfarthing/config.local.yaml`
-2. Get `theme` value (default: "discworld")
-3. Read `.pennyfarthing/personas/themes/{theme}.yaml`
-4. Extract `agents.{agent}` section (character, style, helper, etc.)
-5. Apply `attributes` from config (verbosity, formality, humor, emoji_use)
-</persona-loading>
-```
-### `<blessed-path-guidance>`
-Explains the primary "happy path" workflow for tactical agents.
-**Purpose:** Guides users to use `/new-work` rather than invoking agents directly.
-**Structure:**
-```xml
-<blessed-path-guidance>
-## The Blessed Path
-**For story-based development work:**
-| Command | When to Use |
-|---------|-------------|
-| `/new-work` | Start a NEW story from the backlog |
-**The TDD Flow:** `/new-work` -> SM -> TEA -> Dev -> Reviewer -> SM (finish)
-**Other commands exist** but are not part of the main dev loop.
-</blessed-path-guidance>
-```
-### `<support-agent-guidance>`
-Clarifies that an agent is outside the core TDD loop.
-**Structure:**
-```xml
-<support-agent-guidance>
-## About This Agent
-This agent supports the development process but is **not part of the core TDD loop**.
-**The Core TDD Loop:** `/new-work` -> SM -> TEA -> Dev -> Reviewer -> SM
-**When to use {Agent}:**
-- {Use case 1}
-- {Use case 2}
-**To start story-based development work,** use `/new-work` instead.
-</support-agent-guidance>
-```
----
-## Role Prompting
-From [Anthropic's documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/system-prompts):
-> When using Claude, you can dramatically improve its performance by using the `system` parameter to give it a role. This technique, known as role prompting, is the most powerful way to use system prompts with Claude.
-**Benefits:**
-- **Enhanced accuracy:** In complex scenarios, role prompting significantly boosts performance
-- **Tailored tone:** Adjusts Claude's communication style
-- **Improved focus:** Keeps Claude within task-specific requirements
-### Pennyfarthing's Approach
-We use the **persona system** for role prompting:
-1. **Theme files** define characters (e.g., Discworld theme)
-2. **Persona-loading** instructions tell Claude to adopt the character
-3. **Agent files** provide the role's expertise and workflows
-This separates:
-- **Who you are** (persona) from
-- **What you do** (agent instructions) from
-- **How you do it** (shared behavior)
----
-## Common Patterns
-### Conditional Behavior Blocks
-Use tags to define behavior for specific situations:
-```xml
-<when-tests-fail>
-If tests are failing:
-1. Read the error output
-2. Identify the root cause
-3. Fix the issue
-4. Re-run tests
-</when-tests-fail>
-```
-### Instruction Blocks
-Use tags to group related instructions:
-```xml
-<instructions>
-1. First, do X
-2. Then, do Y
-3. Finally, do Z
-</instructions>
-```
-### Context Blocks
-Use tags to separate context from instructions:
-```xml
-<context>
-This project uses Go for the backend and React for the frontend.
-The API follows REST conventions.
-</context>
-<task>
-Implement a new endpoint for user authentication.
-</task>
-```
-### Example Blocks
-Use tags to provide examples:
-```xml
-<example>
-Input: "hello world"
-Output: "HELLO WORLD"
-</example>
-```
----
-## Chain of Thought
-For complex reasoning, use thinking tags:
-```xml
-<thinking>
-Let me work through this step by step...
-1. First, I need to understand the problem
-2. Then, identify possible solutions
-3. Finally, choose the best approach
-</thinking>
-<answer>
-The best solution is X because...
-</answer>
-```
-Pennyfarthing uses this in the **Reasoning Mode** (verbose mode) for tactical agents.
----
-## Anti-Patterns
-### Don't: Use Tags for Everything
-Tags are for **structure**, not emphasis. Use markdown for emphasis:
-```markdown
-**IMPORTANT:** This is critical.  <!-- Good -->
-```
-```xml
-<important>This is critical.</important>  <!-- Overkill -->
-```
-### Don't: Invent Unparseable Tags
-If you need to extract content programmatically, use consistent, simple tags:
-```xml
-<output>Result here</output>  <!-- Easy to parse -->
-```
-```xml
-<the-final-output-of-the-analysis>Result</the-final-output-of-the-analysis>  <!-- Hard to parse -->
-```
-### Don't: Mix Instruction Styles
-Be consistent. Don't mix XML tags with other delimiters:
-```xml
-<!-- Good: Consistent -->
-<instructions>Do X</instructions>
-<context>Background info</context>
-<!-- Bad: Mixed styles -->
-<instructions>Do X</instructions>
----CONTEXT---
-Background info
-```
----
-## Further Reading
-- [Anthropic: Use XML tags](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/use-xml-tags)
-- [Anthropic: Prompt engineering overview](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)
-- [Anthropic: System prompts and roles](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/system-prompts)
-- [GitHub: Anthropic prompt engineering tutorial](https://github.com/anthropics/prompt-eng-interactive-tutorial)
-- [Google Sheets: Interactive prompting tutorial](https://docs.google.com/spreadsheets/d/19jzLgRruG9kjUQNKtCg1ZjdD6l6weA6qRXG5zLIAhC8)