@pennyfarthing/core 7.0.2 → 7.4.1

package/pennyfarthing-dist/workflows/retrospective/workflow.yaml

@@ -0,0 +1,50 @@
+# BMAD Retrospective Workflow - Imported for BMAD Compatibility
+#
+# This is a reference workflow imported from BMAD for compatibility with
+# BMAD-based projects. It provides structured retrospective ceremonies with
+# epic review and next epic preparation.
+#
+# Key features:
+# - Single-agent execution (Scrum Master facilitation)
+# - Party mode protocol with named agent roles
+# - Two-part format: Epic Review + Next Epic Preparation
+# - Deep story analysis and lesson extraction
+# - Previous retrospective integration for continuity
+#
+# For Pennyfarthing projects, the /retro skill provides a simpler
+# retrospective experience without the full BMAD ceremony format.
+#
+# Source: BMAD-METHOD/src/modules/bmm/workflows/4-implementation/retrospective/
+# Migrated: 2026-01-22
+
+workflow:
+  name: retrospective
+  description: |
+    BMAD reference workflow: Run after epic completion to review overall success,
+    extract lessons learned, and explore if new information emerged that might
+    impact the next epic. This is imported for BMAD compatibility.
+  version: "1.0.0"
+  type: procedural
+  author: BMad
+
+  # Primary agent for this workflow
+  agent: sm
+
+  # Instructions and validation files
+  instructions: ./instructions.md
+  checklist: ./checklist.md
+
+  # Variables available in instruction files
+  variables:
+    project_root: .
+    config_source: "./_bmad/bmm/config.yaml"
+    planning_artifacts: ./artifacts/planning
+    implementation_artifacts: ./artifacts
+    sprint_status_file: ./artifacts/sprint-status.yaml
+    story_directory: ./artifacts/stories
+    retrospectives_folder: ./artifacts
+
+  # Triggers - when to suggest this workflow
+  triggers:
+    types: [bmad-retro, bmad-retrospective, epic-completion]
+    tags: [bmad, reference, procedural, retrospective]

package/pennyfarthing-dist/workflows/sprint-planning/checklist.md

@@ -0,0 +1,33 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation
+
+### Complete Coverage Check
+
+- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml:
+
+```
+Epic Files Contains:                Sprint Status Contains:
+✓ Epic 1                            ✓ epic-1: [status]
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth: [status]
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt: [status]
+  ✓ Story 1.3: Plant Naming           ✓ 1-3-plant-naming: [status]
+                                      ✓ epic-1-retrospective: [status]
+✓ Epic 2                            ✓ epic-2: [status]
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model: [status]
+  ✓ Story 2.2: Chat Interface         ✓ 2-2-chat-interface: [status]
+                                      ✓ epic-2-retrospective: [status]
+```
+
+### Final Check
+
+- [ ] Total count of epics matches
+- [ ] Total count of stories matches
+- [ ] All items are in the expected order (epic, stories, retrospective)

package/pennyfarthing-dist/workflows/sprint-planning/sprint-status-template.yaml

@@ -0,0 +1,55 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the expected format
+# The actual file will be generated with all epics/stories from your epic files
+
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - ready-for-dev: Story file created, ready for development
+#   - in-progress: Developer actively working on implementation
+#   - review: Implementation complete, ready for review
+#   - done: Story completed
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - done: Retrospective has been completed
+#
+# WORKFLOW NOTES:
+# ===============
+# - Mark epic as 'in-progress' when starting work on its first story
+# - SM typically creates next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
+
+# EXAMPLE STRUCTURE (your actual epics/stories will replace these):
+
+generated: 05-06-2-2025 21:30
+project: My Awesome Project
+project_key: jira-1234
+tracking_system: file-system
+story_location: "{story_location}"
+
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: done
+  1-2-account-management: ready-for-dev
+  1-3-plant-data-model: backlog
+  1-4-add-plant-manual: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-personality-system: backlog
+  2-2-chat-interface: backlog
+  2-3-llm-integration: backlog
+  epic-2-retrospective: optional

package/pennyfarthing-dist/workflows/sprint-planning/steps/step-01-parse-epic-files.md

@@ -0,0 +1,54 @@
+---
+name: 'step-01-parse-epic-files'
+description: 'Parse epic files and extract all work items for sprint status tracking'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/sprint-planning'
+
+# File References
+thisStepFile: './step-01-parse-epic-files.md'
+nextStepFile: './step-02-build-sprint-status.md'
+---
+
+# Step 1: Parse Epic Files and Extract All Work Items
+
+## Goal
+
+Parse epic files and extract all work items for sprint status tracking.
+
+## Actions
+
+1. Look for all files matching `{epics_pattern}` in `{epics_location}`
+   - Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files
+
+2. For each epic file found, extract:
+   - Epic numbers from headers like `## Epic 1:` or `## Epic 2:`
+   - Story IDs and titles from patterns like `### Story 1.1: User Authentication`
+   - Convert story format from `Epic.Story: Title` to kebab-case key: `epic-story-title`
+
+## Story ID Conversion Rules
+
+- Original: `### Story 1.1: User Authentication`
+- Replace period with dash: `1-1`
+- Convert title to kebab-case: `user-authentication`
+- Final key: `1-1-user-authentication`
+
+## Output
+
+Build complete inventory of all epics and stories from all epic files.
+
+## Document Discovery
+
+**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
+
+**Epic Discovery Process:**
+
+1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
+2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
+   - Process all epics and their stories from the combined content
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.

package/pennyfarthing-dist/workflows/sprint-planning/steps/step-02-build-sprint-status.md

@@ -0,0 +1,44 @@
+---
+name: 'step-02-build-sprint-status'
+description: 'Build sprint status structure from parsed epic and story data'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/sprint-planning'
+
+# File References
+thisStepFile: './step-02-build-sprint-status.md'
+nextStepFile: './step-03-status-detection.md'
+---
+
+# Step 2: Build Sprint Status Structure
+
+## Goal
+
+Build sprint status structure from parsed epic and story data.
+
+## Actions
+
+For each epic found, create entries in this order:
+
+1. **Epic entry** - Key: `epic-{num}`, Default status: `backlog`
+2. **Story entries** - Key: `{epic}-{story}-{title}`, Default status: `backlog`
+3. **Retrospective entry** - Key: `epic-{num}-retrospective`, Default status: `optional`
+
+## Example Structure
+
+```yaml
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: backlog
+  1-2-account-management: backlog
+  epic-1-retrospective: optional
+```
+
+## Ordering
+
+Ensure items are grouped by epic:
+- Epic N entry
+- All stories for Epic N
+- Retrospective for Epic N
+- Epic N+1 entry
+- etc.

package/pennyfarthing-dist/workflows/sprint-planning/steps/step-03-status-detection.md

@@ -0,0 +1,64 @@
+---
+name: 'step-03-status-detection'
+description: 'Apply intelligent status detection based on file existence and existing status'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/sprint-planning'
+
+# File References
+thisStepFile: './step-03-status-detection.md'
+nextStepFile: './step-04-generate-status-file.md'
+---
+
+# Step 3: Apply Intelligent Status Detection
+
+## Goal
+
+Apply intelligent status detection based on file existence and existing status.
+
+## Actions
+
+For each story, detect current status by checking files:
+
+### Story File Detection
+
+- Check: `{story_location}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
+- If exists → upgrade status to at least `ready-for-dev`
+
+### Preservation Rule
+
+- If existing `{status_file}` exists and has more advanced status, preserve it
+- Never downgrade status (e.g., don't change `done` to `ready-for-dev`)
+
+## Status Flow Reference
+
+### Epic Status
+
+```
+backlog → in-progress → done
+```
+
+- **backlog**: Epic not yet started
+- **in-progress**: Epic actively being worked on (stories being created/implemented)
+- **done**: All stories in epic completed
+
+### Story Status
+
+```
+backlog → ready-for-dev → in-progress → review → done
+```
+
+- **backlog**: Story only exists in epic file
+- **ready-for-dev**: Story file created (e.g., `stories/1-3-plant-naming.md`)
+- **in-progress**: Developer actively working
+- **review**: Ready for code review
+- **done**: Completed
+
+### Retrospective Status
+
+```
+optional ↔ done
+```
+
+- **optional**: Ready to be conducted but not required
+- **done**: Finished

package/pennyfarthing-dist/workflows/sprint-planning/steps/step-04-generate-status-file.md

@@ -0,0 +1,73 @@
+---
+name: 'step-04-generate-status-file'
+description: 'Generate the sprint status YAML file with all epics, stories, and retrospectives'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/sprint-planning'
+
+# File References
+thisStepFile: './step-04-generate-status-file.md'
+nextStepFile: './step-05-validate-and-report.md'
+---
+
+# Step 4: Generate Sprint Status File
+
+## Goal
+
+Generate the sprint status YAML file with all epics, stories, and retrospectives.
+
+## Actions
+
+Create or update `{status_file}` with the following structure:
+
+## File Structure
+
+```yaml
+# generated: {date}
+# project: {project_name}
+# tracking_system: file-system
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
+#
+# Epic Status Transitions:
+#   - backlog → in-progress: Automatically when first story is created
+#   - in-progress → done: Manually when all stories reach 'done' status
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - ready-for-dev: Story file created in stories folder
+#   - in-progress: Developer actively working on implementation
+#   - review: Ready for code review
+#   - done: Story completed
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - done: Retrospective has been completed
+#
+# WORKFLOW NOTES:
+# ===============
+# - Epic transitions to 'in-progress' automatically when first story is created
+# - Stories can be worked in parallel if team capacity allows
+# - SM typically creates next story after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then runs code-review
+
+generated: {date}
+project: {project_name}
+tracking_system: file-system
+story_location: {story_location}
+
+development_status:
+  # All epics, stories, and retrospectives in order
+```
+
+## Critical Notes
+
+- **CRITICAL**: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing
+- Ensure all items are ordered: epic, its stories, its retrospective, next epic...
+- Write the complete sprint status YAML to `{status_file}`

package/pennyfarthing-dist/workflows/sprint-planning/steps/step-05-validate-and-report.md

@@ -0,0 +1,56 @@
+---
+name: 'step-05-validate-and-report'
+description: 'Validate the generated sprint status file and report results'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/sprint-planning'
+
+# File References
+thisStepFile: './step-05-validate-and-report.md'
+nextStepFile: null
+---
+
+# Step 5: Validate and Report
+
+## Goal
+
+Validate the generated sprint status file and report results.
+
+## Validation Checks
+
+Perform the following validation checks:
+
+- [ ] Every epic in epic files appears in `{status_file}`
+- [ ] Every story in epic files appears in `{status_file}`
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in `{status_file}` that don't exist in epic files
+- [ ] All status values are legal (match state machine definitions)
+- [ ] File is valid YAML syntax
+
+## Count Totals
+
+Calculate and report:
+
+- Total epics: `{epic_count}`
+- Total stories: `{story_count}`
+- Epics in-progress: `{in_progress_count}`
+- Stories done: `{done_count}`
+
+## Completion Summary
+
+Display to user:
+
+**Sprint Status Generated Successfully**
+
+- **File Location:** `{status_file}`
+- **Total Epics:** `{epic_count}`
+- **Total Stories:** `{story_count}`
+- **Epics In Progress:** `{epics_in_progress_count}`
+- **Stories Completed:** `{done_count}`
+
+## Next Steps
+
+1. Review the generated `{status_file}`
+2. Use this file to track development progress
+3. Agents will update statuses as they work
+4. Re-run this workflow to refresh auto-detected statuses

package/pennyfarthing-dist/workflows/sprint-planning/workflow.yaml

@@ -0,0 +1,34 @@
+# sprint-planning Workflow - Migrated from BMAD format
+# Manual migration (source used workflow.yaml + instructions.md format)
+
+workflow:
+  name: sprint-planning
+  description: Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle.
+  version: "1.0.0"
+  type: stepped
+
+  # Step configuration
+  steps:
+    path: ./steps/
+    pattern: step-*.md
+
+  # Variables available in step files
+  variables:
+    project_root: .
+    planning_artifacts: ./artifacts
+    implementation_artifacts: ./artifacts
+    epics_location: ./artifacts
+    epics_pattern: "epic*.md"
+    status_file: artifacts/sprint-status.yaml
+    output_file: artifacts/sprint-status.yaml
+
+  # Agent assignment - SM handles sprint planning
+  agent: sm
+
+  # Triggers - when to suggest this workflow
+  triggers:
+    types: [sprint-planning, sprint-status]
+    tags: [sprint-planning, implementation, stepped]
+
+  # Standalone workflow (not part of TDD cycle)
+  standalone: true

package/pennyfarthing-dist/workflows/trivial.yaml

@@ -14,7 +14,7 @@ workflow:
       agent: sm
       output: [session_file, branches]
 
-    - name: implement
+    - name: impl
       agent: dev
       input: [session_file]
       output: [implementation]

package/pennyfarthing-dist/workflows/ux-design/steps/step-01-init.md

@@ -0,0 +1,135 @@
+# Step 1: UX Design Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## YOUR TASK:
+
+Initialize the UX design workflow by detecting continuation state and setting up the design specification document.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{planning_artifacts}/*ux-design-specification*.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery. Documents can be in the following locations:
+- {planning_artifacts}/**
+- {output_folder}/**
+- {product_knowledge}/**
+- docs/**
+
+Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
+
+Try to discover the following:
+- Product Brief (`*brief*.md`)
+- Research Documents (`*prd*.md`)
+- Project Documentation (generally multiple documents might be found for this in the `{product_knowledge}` or `docs` folder.)
+- Project Context (`**/project-context.md`)
+
+<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+
+**Loading Rules:**
+
+- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
+- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
+- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
+- index.md is a guide to what's relevant whenever available
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Create Initial Document
+
+Copy the template from `{installed_path}/ux-design-template.md` to `{planning_artifacts}/ux-design-specification.md`
+Initialize frontmatter in the template.
+
+#### C. Complete Initialization and Report
+
+Complete setup and report to user:
+
+**Document Setup:**
+
+- Created: `{planning_artifacts}/ux-design-specification.md` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+Report what was found:
+"Welcome {{user_name}}! I've set up your UX design workspace for {{project_name}}.
+
+**Documents Found:**
+
+- PRD: {number of PRD files loaded or "None found"}
+- Product brief: {number of brief files loaded or "None found"}
+- Other context: {number of other files loaded or "None found"}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Do you have any other documents you'd like me to include, or shall we continue to the next step?
+
+[C] Continue to UX discovery"
+
+## NEXT STEP:
+
+After user selects [C] to continue, ensure the file `{planning_artifacts}/ux-design-specification.md` has been created and saved, and then load `./step-02-discovery.md` to begin the UX discovery phase.
+
+Remember: Do NOT proceed to step-02 until output file has been updated and user explicitly selects [C] to continue!
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and handed off to step-01b correctly
+✅ Fresh workflow initialized with template and frontmatter
+✅ Input documents discovered and loaded using sharded-first logic
+✅ All discovered files tracked in frontmatter `inputDocuments`
+✅ User confirmed document setup and can proceed
+
+## FAILURE MODES:
+
+❌ Proceeding with fresh initialization when existing workflow exists
+❌ Not updating frontmatter with discovered input documents
+❌ Creating document without proper template
+❌ Not checking sharded folders first before whole files
+❌ Not reporting what documents were found to user
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols