@pennyfarthing/core 9.2.0 → 9.3.0

package/pennyfarthing-dist/guides/prompt-patterns.md

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

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

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