pig-farm-controller/bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md

Level 1 - Epic and Stories Generation

This generates epic and user stories for Level 1 projects after tech-spec completion This is a lightweight story breakdown - not a full PRD Level 1 = coherent feature, 1-10 stories (prefer 2-3), 1 epic This workflow runs AFTER tech-spec.md has been completed Story format MUST match create-story template for compatibility with story-context and dev-story workflows

Read the completed tech-spec.md file from {output_folder}/tech-spec.md Load bmm-workflow-status.md from {output_folder}/bmm-workflow-status.md Extract dev_story_location from config (where stories are stored) Identify all implementation tasks from the "Implementation Guide" section Identify the overall feature goal from "Technical Approach" section Extract time estimates for each implementation phase Identify any dependencies between implementation tasks

Create 1 epic that represents the entire feature Epic title should be user-facing value statement Epic goal should describe why this matters to users

**Epic Best Practices:** - Title format: User-focused outcome (not implementation detail) - Good: "JS Library Icon Reliability" - Bad: "Update recommendedLibraries.ts file" - Scope: Clearly define what's included/excluded - Success criteria: Measurable outcomes that define "done" **Epic:** JS Library Icon Reliability

Goal: Eliminate external dependencies for JS library icons to ensure consistent, reliable display and improve application performance.

Scope: Migrate all 14 recommended JS library icons from third-party CDN URLs (GitHub, jsDelivr) to internal static asset hosting.

Success Criteria:

• All library icons load from internal paths
• Zero external requests for library icons
• Icons load 50-200ms faster than baseline
• No broken icons in production

Derive epic slug from epic title (kebab-case, 2-3 words max)

• "JS Library Icon Reliability" → "icon-reliability"
• "OAuth Integration" → "oauth-integration"
• "Admin Dashboard" → "admin-dashboard"

Initialize epics.md summary document using epics_template

epic_title epic_slug epic_goal epic_scope epic_success_criteria epic_dependencies

Level 1 should have 2-3 stories maximum - prefer longer stories over more stories

Analyze tech spec implementation tasks and time estimates Group related tasks into logical story boundaries

**Story Count Decision Matrix:**

2 Stories (preferred for most Level 1):

• Use when: Feature has clear build/verify split
• Example: Story 1 = Build feature, Story 2 = Test and deploy
• Typical points: 3-5 points per story

3 Stories (only if necessary):

• Use when: Feature has distinct setup, build, verify phases
• Example: Story 1 = Setup, Story 2 = Core implementation, Story 3 = Integration and testing
• Typical points: 2-3 points per story

Never exceed 3 stories for Level 1:

• If more needed, consider if project should be Level 2
• Better to have longer stories (5 points) than more stories (5x 1-point stories)

Determine story_count = 2 or 3 based on tech spec complexity

For each story (2-3 total), generate separate story file Story filename format: "story-{epic_slug}-{n}.md" where n = 1, 2, or 3

**Story Generation Guidelines:** - Each story = multiple implementation tasks from tech spec - Story title format: User-focused deliverable (not implementation steps) - Include technical acceptance criteria from tech spec tasks - Link back to tech spec sections for implementation details

Story Point Estimation:

• 1 point = < 1 day (2-4 hours)
• 2 points = 1-2 days
• 3 points = 2-3 days
• 5 points = 3-5 days

Level 1 Typical Totals:

• Total story points: 5-10 points
• 2 stories: 3-5 points each
• 3 stories: 2-3 points each
• If total > 15 points, consider if this should be Level 2

Story Structure (MUST match create-story format):

• Status: Draft
• Story: As a [role], I want [capability], so that [benefit]
• Acceptance Criteria: Numbered list from tech spec
• Tasks / Subtasks: Checkboxes mapped to tech spec tasks (AC: #n references)
• Dev Notes: Technical summary, project structure notes, references
• Dev Agent Record: Empty sections for context workflow to populate

Set story_path_{n} = "{dev_story_location}/story-{epic_slug}-{n}.md" Create story file from user_story_template with the following content: - story_title: User-focused deliverable title - role: User role (e.g., developer, user, admin) - capability: What they want to do - benefit: Why it matters - acceptance_criteria: Specific, measurable criteria from tech spec - tasks_subtasks: Implementation tasks with AC references - technical_summary: High-level approach, key decisions - files_to_modify: List of files that will change - test_locations: Where tests will be added - story_points: Estimated effort (1/2/3/5) - time_estimate: Days/hours estimate - architecture_references: Links to tech-spec.md sections

Generate exactly {story_count} story files (2 or 3 based on Step 3 decision)

Generate visual story map showing epic → stories hierarchy Calculate total story points across all stories Estimate timeline based on total points (1-2 points per day typical) Define implementation sequence considering dependencies

## Story Map

Epic: Icon Reliability
├── Story 1: Build Icon Infrastructure (3 points)
└── Story 2: Test and Deploy Icons (2 points)

Total Story Points: 5 Estimated Timeline: 1 sprint (1 week)

Implementation Sequence

1. Story 1 → Build icon infrastructure (setup, download, configure)
2. Story 2 → Test and deploy (depends on Story 1)

story_summaries story_map total_points estimated_timeline implementation_sequence

mode: update action: complete_workflow workflow_name: tech-spec populate_stories_from: {epics_output_file} ✅ Status updated! Loaded {{total_stories}} stories from epics. Next: {{next_workflow}} ({{next_agent}} agent) ⚠️ Status update failed: {{error}}

Confirm all stories map to tech spec implementation tasks Verify total story points align with tech spec time estimates Verify stories are properly sequenced with dependencies noted Confirm all stories have measurable acceptance criteria

Level 1 Planning Complete!

Epic: {{epic_title}} Total Stories: {{story_count}} Total Story Points: {{total_points}} Estimated Timeline: {{estimated_timeline}}

Generated Artifacts:

• tech-spec.md → Technical source of truth
• epics.md → Epic and story summary
• story-{epic_slug}-1.md → First story (ready for implementation)
• story-{epic_slug}-2.md → Second story {{#if story_3}}
• story-{epic_slug}-3.md → Third story {{/if}}

Story Location: {dev_story_location}/

Next Steps - Iterative Implementation:

1. Start with Story 1: a. Load SM agent: {project-root}/bmad/bmm/agents/sm.md b. Run story-context workflow (select story-{epic_slug}-1.md) c. Load DEV agent: {project-root}/bmad/bmm/agents/dev.md d. Run dev-story workflow to implement story 1

2. After Story 1 Complete:

• Repeat process for story-{epic_slug}-2.md
• Story context will auto-reference completed story 1

3. After Story 2 Complete: {{#if story_3}}

• Repeat process for story-{epic_slug}-3.md {{/if}}
• Level 1 feature complete!

Progress Tracking:

• All decisions logged in: bmm-workflow-status.md
• Next action clearly identified

Ready to proceed? Choose your path:

1. Generate context for story 1 (recommended - run story-context)
2. Go directly to dev-story for story 1 (faster)
3. Exit for now

Select option (1-3):