@pennyfarthing/core 7.5.0 → 7.6.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/tdd.yaml

@@ -0,0 +1,50 @@
+# TDD Workflow - Test-Driven Development
+# Default workflow for feature development in Pennyfarthing
+#
+# Flow: SM → TEA → Dev → Reviewer → SM
+# Scale routing: 1-2 pts use 'trivial' workflow instead
+
+workflow:
+  name: tdd
+  description: Test-driven development with code review
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches, story_context]
+
+    - name: red
+      agent: tea
+      input: [session_file, story_context]
+      output: [failing_tests]
+      gate:
+        type: tests_fail
+        condition: All acceptance criteria have test coverage
+
+    - name: green
+      agent: dev
+      input: [failing_tests, story_context]
+      output: [implementation, passing_tests]
+      gate:
+        type: tests_pass
+        condition: All tests passing, no skipped tests
+
+    - name: review
+      agent: reviewer
+      input: [implementation, passing_tests]
+      output: [approval]
+      gate:
+        type: approval
+        condition: Code review approved, no blocking issues
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session, story_summary]
+
+  triggers:
+    types: [feature, enhancement]
+    points:
+      min: 3
+    default: true

package/pennyfarthing-dist/workflows/trivial.yaml

@@ -0,0 +1,40 @@
+# Trivial Workflow - Quick Fixes
+# For small changes that don't need full TDD ceremony
+#
+# Flow: SM → Dev → Reviewer → SM (skips TEA)
+# Use for: chores, fixes, 1-2 point stories
+
+workflow:
+  name: trivial
+  description: Quick fixes without full TDD ceremony
+  version: "1.0.0"
+
+  phases:
+    - name: setup
+      agent: sm
+      output: [session_file, branches]
+
+    - name: impl
+      agent: dev
+      input: [session_file]
+      output: [implementation]
+      gate:
+        type: tests_pass
+        condition: Existing tests still pass
+
+    - name: review
+      agent: reviewer
+      input: [implementation]
+      output: [approval]
+      gate:
+        type: approval
+
+    - name: finish
+      agent: sm
+      input: [approval]
+      output: [archived_session]
+
+  triggers:
+    types: [chore, fix, refactor]
+    points:
+      max: 2