@pennyfarthing/core 7.5.0 → 7.6.0

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/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)

package/pennyfarthing-dist/guides/SESSION-ARTIFACTS.md

@@ -0,0 +1,193 @@
+# Session Artifacts Naming Convention
+
+This guide defines the standard naming patterns for all files in `.session/`.
+
+## Why This Matters
+
+Consistent naming enables:
+1. **Predictable cleanup** - Scripts can reliably find and remove artifacts
+2. **Easy debugging** - Quickly identify what story/agent created a file
+3. **No accumulation** - Story-specific cleanup catches everything
+
+## File Categories
+
+| Category | Purpose | Lifecycle |
+|----------|---------|-----------|
+| `session` | Active work session file | Archived on story completion |
+| `context` | Technical context (story/epic) | Archived on completion |
+| `test` | Test execution output | Cleaned after 1 day or story completion |
+| `lint` | Lint execution output | Cleaned after 1 day or story completion |
+| `handoff` | Agent-to-agent transition data | Cleaned on story completion |
+
+## Naming Patterns
+
+### Session Files (Canonical)
+
+The primary work session file. One per active story.
+
+```
+{STORY_ID}-session.md
+```
+
+**Examples:**
+- `36-2-session.md`
+- `10-15-session.md`
+
+**Created by:** `sm-setup MODE=setup`
+**Archived by:** `sm-finish PHASE=execute` → `sprint/archive/story-{STORY_ID}-{DATE}.md`
+
+---
+
+### Context Files
+
+Technical context for stories and epics.
+
+```
+context-story-{STORY_ID}.md
+context-epic-{EPIC_NUM}.md
+```
+
+**Examples:**
+- `context-story-36-2.md`
+- `context-epic-10.md`
+
+**Created by:** SM (epic-tech-context task)
+**Archived by:** `sm-finish PHASE=execute` (story), `/start-epic` or `/retro` (epic)
+
+---
+
+### Test Output Files
+
+Test execution logs and reports.
+
+```
+test-{STORY_ID}-{AGENT}-{PHASE}.log
+test-{STORY_ID}-{AGENT}-{PHASE}.md
+```
+
+**Components:**
+- `{STORY_ID}` - e.g., `36-2`
+- `{AGENT}` - `tea`, `dev`, `reviewer`
+- `{PHASE}` - `red`, `green`, `verify`
+
+**Examples:**
+- `test-36-2-tea-red.log`
+- `test-36-2-dev-green.md`
+- `test-36-2-reviewer-verify.log`
+
+**Created by:** `handoff`, `reviewer-preflight`, `testing-runner`
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}` or 1-day retention
+
+---
+
+### Lint Output Files
+
+Lint execution logs.
+
+```
+lint-{STORY_ID}-{REPO}.log
+```
+
+**Examples:**
+- `lint-36-2-api.log`
+- `lint-36-2-ui.log`
+
+**Created by:** `reviewer-preflight`
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}` or 1-day retention
+
+---
+
+### Handoff Files
+
+Agent-to-agent transition data for structured handoffs.
+
+```
+handoff-{STORY_ID}-{FROM_AGENT}.md
+handoff-{STORY_ID}-{FROM_AGENT}.json
+```
+
+**Examples:**
+- `handoff-36-2-tea.md` (TEA → Dev)
+- `handoff-36-2-dev.json` (Dev → Reviewer)
+- `handoff-36-2-reviewer.md` (Reviewer → SM)
+
+**Created by:** Handoff subagents (`tea-handoff`, `dev-handoff`, `reviewer-handoff-*`)
+**Cleaned by:** `session-cleanup.sh --story {STORY_ID}`
+
+---
+
+## System Files
+
+These are managed automatically and should not be manually created.
+
+| File | Purpose | Management |
+|------|---------|------------|
+| `.gitkeep` | Keeps directory in git | Never delete |
+| `session-log.txt` | Session activity log | Rotated to 1000 lines by cleanup |
+| `agents/` | Agent session state (UUIDs) | Cleaned after 1 day |
+
+---
+
+## Cleanup Patterns
+
+The `session-cleanup.sh` script uses these patterns:
+
+### Story-specific cleanup (`--story {ID}`)
+```bash
+test-{STORY_ID}-*.log
+test-{STORY_ID}-*.md
+lint-{STORY_ID}-*.log
+handoff-{STORY_ID}-*.md
+handoff-{STORY_ID}-*.json
+context-story-{STORY_ID}.md
+```
+
+### Time-based cleanup (default: 1 day retention)
+```bash
+test-*.log
+test-*.md
+lint-*.log
+handoff-*.md
+handoff-*.json
+context-story-*.md
+```
+
+### Aggressive cleanup (`--aggressive`)
+```bash
+context-epic-*.md  # Only for completed epics
+```
+
+---
+
+## Migration from Old Patterns
+
+Old patterns that should no longer be used:
+
+| Old Pattern | New Pattern |
+|-------------|-------------|
+| `story-{ID}-context.md` | `context-story-{ID}.md` |
+| `epic-{N}-context.md` | `context-epic-{N}.md` |
+| `test-results-{repo}-{ID}.log` | `test-{ID}-{agent}-{phase}.log` |
+| `tea-{ID}-red-check-results.md` | `test-{ID}-tea-red.md` |
+| `dev-{ID}-red-verify-report.md` | `test-{ID}-dev-red.md` |
+| `{ID}-handoff-summary.md` | `handoff-{ID}-{agent}.md` |
+| `lint-results-{repo}-{ID}.log` | `lint-{ID}-{repo}.log` |
+
+---
+
+## Quick Reference
+
+```
+.session/
+├── .gitkeep                          # Git placeholder
+├── session-log.txt                   # Activity log (auto-rotated)
+├── agents/                           # Agent session state
+│   └── {uuid}.md                     # Per-session state
+├── 36-2-session.md                   # Active story session
+├── context-story-36-2.md             # Story technical context
+├── context-epic-10.md                # Epic technical context
+├── test-36-2-tea-red.log             # TEA test output
+├── test-36-2-dev-green.md            # Dev test report
+├── lint-36-2-api.log                 # Lint output
+└── handoff-36-2-tea.md               # TEA → Dev handoff
+```

package/pennyfarthing-dist/guides/XML-TAGS.md

@@ -0,0 +1,156 @@
+# XML Tag Taxonomy
+
+Pennyfarthing uses XML-style tags to structure agent definitions and skill documentation. These tags help LLMs identify and prioritize different types of content.
+
+## Priority Tags
+
+Tags that affect LLM behavior and attention.
+
+### `<critical>`
+
+**Purpose:** Non-negotiable rules that MUST be followed. LLMs should treat these as hard constraints.
+
+**Usage:** Gates, invariants, protocol requirements, things that break the system if ignored.
+
+```markdown
+<critical>
+**Never edit sprint YAML directly.** Use scripts.
+</critical>
+```
+
+**Examples:**
+- "Subagent output is NOT visible to Cyclist"
+- "NEVER mark acceptance criteria as complete" (for subagents)
+- "Write assessment BEFORE spawning handoff subagent"
+
+### `<gate>`
+
+**Purpose:** Prerequisites that MUST be verified before proceeding. Checklist-style validation.
+
+**Usage:** Entry/exit conditions for workflows, handoff requirements, quality gates.
+
+```markdown
+<gate>
+## Handoff Checklist
+1. Session file exists
+2. Acceptance criteria defined
+3. Feature branches created
+</gate>
+```
+
+**Difference from `<critical>`:** Gates are procedural checkpoints; critical items are invariant rules.
+
+### `<info>`
+
+**Purpose:** Contextual information that helps but doesn't constrain. Reference material.
+
+**Usage:** Background context, defaults, file locations, tips.
+
+```markdown
+<info>
+**Workflow:** SM → TEA → Dev → Reviewer → SM
+**Skills:** `/sprint`, `/jira`, `/testing`
+</info>
+```
+
+## Identity Tags
+
+Tags that define agent personality and role.
+
+### `<persona>`
+
+**Purpose:** Character personality from the active theme. Loaded at agent activation.
+
+**Usage:** Top of agent files, sets tone and style.
+
+```markdown
+<persona>
+Auto-loaded by `agent-session.sh start` from theme config.
+**Fallback if not loaded:** Supportive, methodical, detail-oriented
+</persona>
+```
+
+### `<role>`
+
+**Purpose:** Agent's position in the workflow and primary responsibility.
+
+**Usage:** Brief statement of what the agent does and when it's invoked.
+
+```markdown
+<role>
+Test specification, RED phase execution, handoff to Dev
+</role>
+```
+
+## Structure Tags
+
+Tags that organize agent content.
+
+### `<helpers>`
+
+**Purpose:** Describes Haiku subagents and their invocation pattern.
+
+**Usage:** Lists subagents, their purposes, and how to spawn them.
+
+### `<responsibilities>`
+
+**Purpose:** Bullet list of what this agent does vs delegates.
+
+### `<skills>`
+
+**Purpose:** Slash commands this agent commonly uses.
+
+### `<context>`
+
+**Purpose:** Guide files and sidecars to reference.
+
+### `<reasoning-mode>`
+
+**Purpose:** Verbose/quiet toggle for showing thought process.
+
+### `<on-activation>`
+
+**Purpose:** Startup checklist - what to do when agent is invoked.
+
+### `<exit>`
+
+**Purpose:** How to leave agent mode and cleanup.
+
+## Usage Guidelines
+
+1. **`<critical>` sparingly** - If everything is critical, nothing is. Reserve for true invariants.
+
+2. **`<gate>` for checkpoints** - Use when there's a clear pass/fail condition.
+
+3. **`<info>` generously** - Helpful context improves agent performance.
+
+4. **Order matters:**
+   ```
+   <persona>      # Who am I?
+   <role>         # What do I do?
+   <helpers>      # Who helps me?
+   <critical>     # What must I never violate?
+   <gate>         # What must I check?
+   <info>         # What's helpful to know?
+   ```
+
+5. **Close your tags** - Always use `</tag>` even though markdown parsers are lenient.
+
+## Tag Locations
+
+| Tag | Typical Location |
+|-----|------------------|
+| `<critical>` | Agent files, skill files, workflow instructions |
+| `<gate>` | Subagent files (handoff, finish, setup) |
+| `<info>` | Agent files, guide files |
+| `<persona>` | Agent files (top) |
+| `<role>` | Agent files (after persona) |
+
+## Adding New Tags
+
+Before adding a new tag type:
+
+1. Check if existing tags cover the use case
+2. Document the tag's purpose and priority level
+3. Update this file
+4. Be consistent across all files using the tag