@pennyfarthing/core 7.9.3 → 8.0.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/scale-levels.md

@@ -0,0 +1,114 @@
+# Scale Levels Guide
+
+Pennyfarthing uses scale levels (0-4) to route work to appropriate workflows. Scale levels are aligned with BMAD 6.0 methodology.
+
+## Scale Level Definitions
+
+| Level | Scope | Story Count | Workflow | Required Artifacts |
+|-------|-------|-------------|----------|-------------------|
+| **0** | fix, bug, typo, small change, patch | 1 | `trivial` | None |
+| **1** | simple, basic, small feature, add | 1-10 | `quick-spec` | tech-spec |
+| **2** | dashboard, several features, admin panel | 5-15 | `prd` | PRD |
+| **3** | platform, integration, complex, system | 12-40 | `prd` | PRD + architecture |
+| **4** | enterprise, multi-tenant, multiple products | 40+ | `prd` | Full BMAD process |
+
+## Automatic Detection
+
+When you describe work to Pennyfarthing, the scale level is detected from keywords:
+
+### Level 0 Keywords
+- fix, bug, typo, patch, hotfix, small change
+
+### Level 1 Keywords
+- simple, basic, small, add, minor
+
+### Level 2 Keywords
+- dashboard, admin panel, several, multiple features
+
+### Level 3 Keywords
+- platform, integration, complex, system
+
+### Level 4 Keywords
+- enterprise, multi-tenant, multiple products
+
+**Priority:** Higher levels take precedence. "Enterprise dashboard" → Level 4.
+
+## Workflow Routing
+
+| Level | Workflow | Description |
+|-------|----------|-------------|
+| 0 | `trivial` | Direct fix, no planning artifacts |
+| 1 | `quick-spec` | Conversational spec, produces tech-spec |
+| 2-4 | `prd` | Full PRD workflow with gates |
+
+## Required Artifacts
+
+### Level 0: None
+Just fix it. No planning documents required.
+
+### Level 1: Tech-Spec
+Quick conversational spec producing implementation-ready technical specification.
+
+### Level 2: PRD
+Product Requirements Document. Architecture is optional.
+
+### Level 3: PRD + Architecture
+Both PRD and architecture documents required. System-level changes need design review.
+
+### Level 4: Full BMAD
+Complete BMAD process:
+- PRD
+- Architecture
+- Epics and Stories breakdown
+- Implementation Readiness checklist
+
+## User Override
+
+You can always override the detected level:
+
+```bash
+# Explicitly set scale level
+/workflow start prd --scale 3
+```
+
+Or when asked during workflow initiation, specify your preferred level.
+
+## Python API
+
+```python
+from pennyfarthing_scripts.workflow import (
+    detect_scale_level,
+    get_workflow_for_scale_level,
+    get_required_artifacts,
+    get_scale_level_info,
+)
+
+# Detect from description
+level = detect_scale_level("build an enterprise platform")  # Returns 4
+
+# Get recommended workflow
+workflow = get_workflow_for_scale_level(level)  # Returns "prd"
+
+# Get required artifacts
+artifacts = get_required_artifacts(level)  # Returns ["prd", "architecture", "epics-and-stories"]
+
+# Get full metadata
+info = get_scale_level_info(level)
+# Returns: {"level": 4, "scope": "...", "stories_min": 40, ...}
+```
+
+## Examples
+
+| Description | Detected Level | Workflow |
+|-------------|----------------|----------|
+| "Fix the login bug" | 0 | trivial |
+| "Add a logout button" | 1 | quick-spec |
+| "Build an admin dashboard" | 2 | prd |
+| "New platform for data processing" | 3 | prd |
+| "Enterprise multi-tenant SaaS" | 4 | prd |
+
+## Related
+
+- [Workflow Skill](/workflow) - Workflow management commands
+- [PRD Workflow](../workflows/prd/) - Full PRD stepped workflow
+- [Quick-Spec Workflow](../workflows/quick-spec/) - Lightweight spec workflow

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
+```