@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-03-create-stories.md

@@ -0,0 +1,272 @@
+---
+name: 'step-03-create-stories'
+description: 'Generate all epics with their stories following the template structure'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/epics-and-stories'
+
+# File References
+thisStepFile: './step-03-create-stories.md'
+nextStepFile: './step-04-final-validation.md'
+workflowFile: '{workflow_path}/workflow.yaml'
+outputFile: '{planning_artifacts}/epics.md'
+
+# Task References (BMAD features - not yet available in Pennyfarthing)
+# advancedElicitationTask: '{project_root}/.pennyfarthing/workflows/advanced-elicitation/workflow.yaml'
+# partyModeWorkflow: '{project_root}/.pennyfarthing/workflows/party-mode/workflow.yaml'
+
+# Template References
+epicsTemplate: './templates/epics-template.md'
+---
+
+# Step 3: Generate Epics and Stories
+
+## STEP GOAL:
+
+To generate all epics with their stories based on the approved epics_list, following the template structure exactly.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process epics sequentially
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring story creation and acceptance criteria expertise
+- ✅ User brings their implementation priorities and constraints
+
+### Step-Specific Rules:
+
+- 🎯 Generate stories for each epic following the template exactly
+- 🚫 FORBIDDEN to deviate from template structure
+- 💬 Each story must have clear acceptance criteria
+- 🚪 ENSURE each story is completable by a single dev agent
+- 🔗 **CRITICAL: Stories MUST NOT depend on future stories within the same epic**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate stories collaboratively with user input
+- 💾 Append epics and stories to {outputFile} following template
+- 📖 Process epics one at a time in sequence
+- 🚫 FORBIDDEN to skip any epic or rush through stories
+
+## STORY GENERATION PROCESS:
+
+### 1. Load Approved Epic Structure
+
+Load {outputFile} and review:
+
+- Approved epics_list from Step 2
+- FR coverage map
+- All requirements (FRs, NFRs, additional)
+- Template structure at the end of the document
+
+### 2. Explain Story Creation Approach
+
+**STORY CREATION GUIDELINES:**
+
+For each epic, create stories that:
+
+- Follow the exact template structure
+- Are sized for single dev agent completion
+- Have clear user value
+- Include specific acceptance criteria
+- Reference requirements being fulfilled
+
+**🚨 DATABASE/ENTITY CREATION PRINCIPLE:**
+Create tables/entities ONLY when needed by the story:
+
+- ❌ WRONG: Epic 1 Story 1 creates all 50 database tables
+- ✅ RIGHT: Each story creates/alters ONLY the tables it needs
+
+**🔗 STORY DEPENDENCY PRINCIPLE:**
+Stories must be independently completable in sequence:
+
+- ❌ WRONG: Story 1.2 requires Story 1.3 to be completed first
+- ✅ RIGHT: Each story can be completed based only on previous stories
+- ❌ WRONG: "Wait for Story 1.4 to be implemented before this works"
+- ✅ RIGHT: "This story works independently and enables future stories"
+
+**STORY FORMAT (from template):**
+
+```
+### Story {N}.{M}: {story_title}
+
+As a {user_type},
+I want {capability},
+So that {value_benefit}.
+
+**Acceptance Criteria:**
+
+**Given** {precondition}
+**When** {action}
+**Then** {expected_outcome}
+**And** {additional_criteria}
+```
+
+**✅ GOOD STORY EXAMPLES:**
+
+_Epic 1: User Authentication_
+
+- Story 1.1: User Registration with Email
+- Story 1.2: User Login with Password
+- Story 1.3: Password Reset via Email
+
+_Epic 2: Content Creation_
+
+- Story 2.1: Create New Blog Post
+- Story 2.2: Edit Existing Blog Post
+- Story 2.3: Publish Blog Post
+
+**❌ BAD STORY EXAMPLES:**
+
+- Story: "Set up database" (no user value)
+- Story: "Create all models" (too large, no user value)
+- Story: "Build authentication system" (too large)
+- Story: "Login UI (depends on Story 1.3 API endpoint)" (future dependency!)
+- Story: "Edit post (requires Story 1.4 to be implemented first)" (wrong order!)
+
+### 3. Process Epics Sequentially
+
+For each epic in the approved epics_list:
+
+#### A. Epic Overview
+
+Display:
+
+- Epic number and title
+- Epic goal statement
+- FRs covered by this epic
+- Any NFRs or additional requirements relevant
+
+#### B. Story Breakdown
+
+Work with user to break down the epic into stories:
+
+- Identify distinct user capabilities
+- Ensure logical flow within the epic
+- Size stories appropriately
+
+#### C. Generate Each Story
+
+For each story in the epic:
+
+1. **Story Title**: Clear, action-oriented
+2. **User Story**: Complete the As a/I want/So that format
+3. **Acceptance Criteria**: Write specific, testable criteria
+
+**AC Writing Guidelines:**
+
+- Use Given/When/Then format
+- Each AC should be independently testable
+- Include edge cases and error conditions
+- Reference specific requirements when applicable
+
+#### D. Collaborative Review
+
+After writing each story:
+
+- Present the story to user
+- Ask: "Does this story capture the requirement correctly?"
+- "Is the scope appropriate for a single dev session?"
+- "Are the acceptance criteria complete and testable?"
+
+#### E. Append to Document
+
+When story is approved:
+
+- Append it to {outputFile} following template structure
+- Use correct numbering (Epic N, Story M)
+- Maintain proper markdown formatting
+
+### 4. Epic Completion
+
+After all stories for an epic are complete:
+
+- Display epic summary
+- Show count of stories created
+- Verify all FRs for the epic are covered
+- Get user confirmation to proceed to next epic
+
+### 5. Repeat for All Epics
+
+Continue the process for each epic in the approved list, processing them in order (Epic 1, Epic 2, etc.).
+
+### 6. Final Document Completion
+
+After all epics and stories are generated:
+
+- Verify the document follows template structure exactly
+- Ensure all placeholders are replaced
+- Confirm all FRs are covered
+- Check formatting consistency
+
+## TEMPLATE STRUCTURE COMPLIANCE:
+
+The final {outputFile} must follow this structure exactly:
+
+1. **Overview** section with project name
+2. **Requirements Inventory** with all three subsections populated
+3. **FR Coverage Map** showing requirement to epic mapping
+4. **Epic List** with approved epic structure
+5. **Epic sections** for each epic (N = 1, 2, 3...)
+   - Epic title and goal
+   - All stories for that epic (M = 1, 2, 3...)
+     - Story title and user story
+     - Acceptance Criteria using Given/When/Then format
+
+### 7. Present FINAL MENU OPTIONS
+
+After all epics and stories are complete:
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Save content to {outputFile}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-final-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then load and read fully `{nextStepFile}` to execute and begin final validation phase.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics processed in sequence
+- Stories created for each epic
+- Template structure followed exactly
+- All FRs covered by stories
+- Stories appropriately sized
+- Acceptance criteria are specific and testable
+- Document is complete and ready for development
+
+### ❌ SYSTEM FAILURE:
+
+- Deviating from template structure
+- Missing epics or stories
+- Stories too large or unclear
+- Missing acceptance criteria
+- Not following proper formatting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-04-final-validation.md

@@ -0,0 +1,153 @@
+---
+name: 'step-04-final-validation'
+description: 'Validate complete coverage of all requirements and ensure implementation readiness'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/epics-and-stories'
+
+# File References
+thisStepFile: './step-04-final-validation.md'
+nextStepFile: './step-05-import-to-future.md'
+workflowFile: '{workflow_path}/workflow.yaml'
+outputFile: '{planning_artifacts}/epics.md'
+
+# Task References (BMAD features - not yet available in Pennyfarthing)
+# advancedElicitationTask: '{project_root}/.pennyfarthing/workflows/advanced-elicitation/workflow.yaml'
+# partyModeWorkflow: '{project_root}/.pennyfarthing/workflows/party-mode/workflow.yaml'
+
+# Template References
+epicsTemplate: './templates/epics-template.md'
+---
+
+# Step 4: Final Validation
+
+## STEP GOAL:
+
+To validate complete coverage of all requirements and ensure stories are ready for development.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process validation sequentially without skipping
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring validation expertise and quality assurance
+- ✅ User brings their implementation priorities and final review
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on validating complete requirements coverage
+- 🚫 FORBIDDEN to skip any validation checks
+- 💬 Validate FR coverage, story completeness, and dependencies
+- 🚪 ENSURE all stories are ready for development
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Validate every requirement has story coverage
+- 💾 Check story dependencies and flow
+- 📖 Verify architecture compliance
+- 🚫 FORBIDDEN to approve incomplete coverage
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete epic and story breakdown from previous steps
+- Focus: Final validation of requirements coverage and story readiness
+- Limits: Validation only, no new content creation
+- Dependencies: Completed story generation from Step 3
+
+## VALIDATION PROCESS:
+
+### 1. FR Coverage Validation
+
+Review the complete epic and story breakdown to ensure EVERY FR is covered:
+
+**CRITICAL CHECK:**
+
+- Go through each FR from the Requirements Inventory
+- Verify it appears in at least one story
+- Check that acceptance criteria fully address the FR
+- No FRs should be left uncovered
+
+### 2. Architecture Implementation Validation
+
+**Check for Starter Template Setup:**
+
+- Does Architecture document specify a starter template?
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- This includes cloning, installing dependencies, initial configuration
+
+**Database/Entity Creation Validation:**
+
+- Are database tables/entities created ONLY when needed by stories?
+- ❌ WRONG: Epic 1 creates all tables upfront
+- ✅ RIGHT: Tables created as part of the first story that needs them
+- Each story should create/modify ONLY what it needs
+
+### 3. Story Quality Validation
+
+**Each story must:**
+
+- Be completable by a single dev agent
+- Have clear acceptance criteria
+- Reference specific FRs it implements
+- Include necessary technical details
+- **Not have forward dependencies** (can only depend on PREVIOUS stories)
+- Be implementable without waiting for future stories
+
+### 4. Epic Structure Validation
+
+**Check that:**
+
+- Epics deliver user value, not technical milestones
+- Dependencies flow naturally
+- Foundation stories only setup what's needed
+- No big upfront technical work
+
+### 5. Dependency Validation (CRITICAL)
+
+**Epic Independence Check:**
+
+- Does each epic deliver COMPLETE functionality for its domain?
+- Can Epic 2 function without Epic 3 being implemented?
+- Can Epic 3 function standalone using Epic 1 & 2 outputs?
+- ❌ WRONG: Epic 2 requires Epic 3 features to work
+- ✅ RIGHT: Each epic is independently valuable
+
+**Within-Epic Story Dependency Check:**
+For each epic, review stories in order:
+
+- Can Story N.1 be completed without Stories N.2, N.3, etc.?
+- Can Story N.2 be completed using only Story N.1 output?
+- Can Story N.3 be completed using only Stories N.1 & N.2 outputs?
+- ❌ WRONG: "This story depends on a future story"
+- ❌ WRONG: Story references features not yet implemented
+- ✅ RIGHT: Each story builds only on previous stories
+
+### 6. Complete and Save
+
+If all validations pass:
+
+- Update any remaining placeholders in the document
+- Ensure proper formatting
+- Save the final epics.md
+
+**Present Menu:**
+**All validations complete!** [C] Continue to import to future.yaml
+
+#### Menu Handling Logic:
+
+- IF C: Save final document, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then redisplay menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and validations are complete, will you then load, read entire file, then execute {nextStepFile} to import epics to future.yaml.

package/pennyfarthing-dist/workflows/epics-and-stories/steps/step-05-import-to-future.md

@@ -0,0 +1,122 @@
+---
+name: 'step-05-import-to-future'
+description: 'Import validated epics and stories into sprint/future.yaml backlog'
+
+# Path Definitions
+workflow_path: '{project_root}/.pennyfarthing/workflows/epics-and-stories'
+
+# File References
+thisStepFile: './step-05-import-to-future.md'
+workflowFile: '{workflow_path}/workflow.yaml'
+outputFile: '{planning_artifacts}/epics.md'
+futureYaml: '{project_root}/sprint/future.yaml'
+
+# Script References
+importScript: '{project_root}/.pennyfarthing/scripts/sprint/import-epic-to-future.sh'
+---
+
+# Step 5: Import to Future Backlog
+
+## STEP GOAL:
+
+To import the validated epics and stories into `sprint/future.yaml` so they appear in the backlog and can be promoted to sprints.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER skip this step - epics must be in future.yaml to be scheduled
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, confirming import with user
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on importing to future.yaml
+- 💬 Ask user for initiative name if not obvious from document
+- 🚫 FORBIDDEN to modify the validated epics document
+- ✅ Show dry-run output before applying
+
+## IMPORT PROCESS:
+
+### 1. Determine Initiative Name
+
+Look at the epics document title and ask user:
+
+> "What should this initiative be called in future.yaml?"
+>
+> Suggested: `{extracted_title}`
+
+Wait for user confirmation or alternative name.
+
+### 2. Preview Import (Dry Run)
+
+Run the import script with `--dry-run` to show what will be added:
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/import-epic-to-future.sh {outputFile} "{initiative_name}" --dry-run
+```
+
+Display the preview output to the user showing:
+- Next epic number that will be assigned
+- Initiative structure
+- All stories with IDs
+
+### 3. Confirm and Apply
+
+Ask user: "Does this look correct? [Y] Yes, import to future.yaml / [N] No, make changes"
+
+**If Y:**
+Run the import without `--dry-run`:
+
+```bash
+.pennyfarthing/scripts/core/run.sh sprint/import-epic-to-future.sh {outputFile} "{initiative_name}"
+```
+
+**If N:**
+Ask what changes are needed and help user adjust before re-running.
+
+### 4. Verify Import
+
+After successful import, verify by showing:
+
+```bash
+grep -A3 "{initiative_name}" sprint/future.yaml
+```
+
+Confirm:
+- Epic appears in future.yaml
+- Epic number is correct
+- Stories have proper IDs
+
+### 5. Complete Workflow
+
+Display completion message:
+
+```
+## Workflow Complete!
+
+**Epic imported:** epic-{N}
+**Initiative:** {initiative_name}
+**Stories:** {count} stories ready for sprint planning
+**Location:** sprint/future.yaml
+
+Next steps:
+- Use `/sprint` to view the backlog
+- Use `promote-epic.sh` to move to a sprint when ready
+```
+
+## SUCCESS CRITERIA:
+
+- ✅ Initiative appears in future.yaml
+- ✅ Epic has correct sequential number
+- ✅ All stories have proper IDs (epic-story format)
+- ✅ User confirms import is correct
+
+## FAILURE MODES:
+
+- ❌ Import script not found - check .pennyfarthing symlinks
+- ❌ future.yaml not found - ensure sprint/ directory exists
+- ❌ Duplicate epic number - script should handle this automatically
+
+**Master Rule:** The workflow is not complete until epics are in future.yaml and accessible via sprint commands.

package/pennyfarthing-dist/workflows/epics-and-stories/templates/epics-template.md

@@ -0,0 +1,57 @@
+---
+stepsCompleted: []
+inputDocuments: []
+---
+
+# {{project_name}} - Epic Breakdown
+
+## Overview
+
+This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
+
+## Requirements Inventory
+
+### Functional Requirements
+
+{{fr_list}}
+
+### NonFunctional Requirements
+
+{{nfr_list}}
+
+### Additional Requirements
+
+{{additional_requirements}}
+
+### FR Coverage Map
+
+{{requirements_coverage_map}}
+
+## Epic List
+
+{{epics_list}}
+
+<!-- Repeat for each epic in epics_list (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+{{epic_goal_N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+<!-- for each AC on this story -->
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+**And** {{additional_criteria}}
+
+<!-- End story repeat -->

package/pennyfarthing-dist/workflows/epics-and-stories/workflow.yaml

@@ -0,0 +1,28 @@
+# create-epics-and-stories Workflow - Migrated from BMAD format
+# Generated by migrate-bmad-workflow.mjs
+# Updated: Added step-05 for automatic import to future.yaml
+
+workflow:
+  name: create-epics-and-stories
+  description: Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value. This workflow requires completed PRD + Architecture documents (UX recommended if UI exists) and breaks down requirements into implementation-ready epics and user stories that incorporate all available technical and design context. Creates detailed, actionable stories with complete acceptance criteria for development teams. Automatically imports validated epics to sprint/future.yaml backlog.
+  version: "1.1.0"
+  type: stepped
+
+  # Step configuration
+  steps:
+    path: ./steps/
+    pattern: step-*.md
+
+  # Variables available in step files
+  variables:
+    project_root: .
+    planning_artifacts: ./artifacts
+    output_file: artifacts/create-epics-and-stories.md
+
+  # Agent assignment (customize as needed)
+  agent: architect
+
+  # Triggers - when to suggest this workflow
+  triggers:
+    types: [create-epics-and-stories]
+    tags: [create-epics-and-stories, stepped]