@pennyfarthing/core 6.6.0

package/pennyfarthing-dist/guides/HOOKS.md

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

@@ -0,0 +1,338 @@
+# 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)