root
/
LMS-BGN
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
LMS-BGN/.bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-level1-stories.md

16 KiB
Raw Blame History

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.yaml from {output_folder}/bmm-workflow-status.yaml (if exists) Extract dev_ephemeral_location from config (where stories are stored)

Extract from the ENHANCED tech-spec structure:

  • Overall feature goal from "The Change → Problem Statement" and "Proposed Solution"
  • Implementation tasks from "Implementation Guide → Implementation Steps"
  • Time estimates from "Implementation Guide → Implementation Steps"
  • Dependencies from "Implementation Details → Integration Points" and "Development Context → Dependencies"
  • Source tree from "Implementation Details → Source Tree Changes"
  • Framework dependencies from "Development Context → Framework/Libraries"
  • Existing code references from "Development Context → Relevant Existing Code"
  • File paths from "Developer Resources → File Paths Reference"
  • Key code locations from "Developer Resources → Key Code Locations"
  • Testing locations from "Developer Resources → Testing Locations"
  • Acceptance criteria from "Implementation Guide → Acceptance Criteria"

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

Also capture project_level for the epic template

project_level 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

CRITICAL: Acceptance Criteria Must Be:

  1. Numbered - AC #1, AC #2, AC #3, etc.
  2. Specific - No vague statements like "works well" or "is fast"
  3. Testable - Can be verified objectively
  4. Complete - Covers all success conditions
  5. Independent - Each AC tests one thing
  6. Format: Use Given/When/Then when applicable

Good AC Examples: ✅ AC #1: Given a valid email address, when user submits the form, then the account is created and user receives a confirmation email within 30 seconds ✅ AC #2: Given an invalid email format, when user submits, then form displays "Invalid email format" error message ✅ AC #3: All unit tests in UserService.test.ts pass with 100% coverage

Bad AC Examples: ❌ "User can create account" (too vague) ❌ "System performs well" (not measurable) ❌ "Works correctly" (not specific)

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 (tech-spec provides context)

NEW: Comprehensive Context Fields

Since tech-spec is context-rich, populate ALL template fields:

  • dependencies: Extract from tech-spec "Development Context → Dependencies" and "Integration Points"
  • existing_code_references: Extract from "Development Context → Relevant Existing Code" and "Developer Resources → Key Code Locations"
Set story_path_{n} = "{dev_ephemeral_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 (from tech-spec "Developer Resources → File Paths Reference") - test_locations: Where tests will be added (from tech-spec "Developer Resources → Testing Locations") - story_points: Estimated effort (1/2/3/5) - time_estimate: Days/hours estimate - dependencies: Internal/external dependencies (from tech-spec "Development Context" and "Integration Points") - existing_code_references: Code to reference (from tech-spec "Development Context → Relevant Existing Code" and "Key Code Locations") - architecture_references: Links to tech-spec.md sections

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

Stories MUST be ordered so earlier stories don't depend on later ones Each story must have CLEAR, TESTABLE acceptance criteria

Analyze dependencies between stories:

Dependency Rules:

  1. Infrastructure/setup → Feature implementation → Testing/polish
  2. Database changes → API changes → UI changes
  3. Backend services → Frontend components
  4. Core functionality → Enhancement features
  5. No story can depend on a later story!

Validate Story Sequence: For each story N, check:

  • Does it require anything from Story N+1, N+2, etc.? ❌ INVALID
  • Does it only use things from Story 1...N-1? ✅ VALID
  • Can it be implemented independently or using only prior stories? ✅ VALID

If invalid dependencies found, REORDER stories!

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

## Story Map 
Epic: Icon Reliability
├── Story 1: Build Icon Infrastructure (3 points)
│   Dependencies: None (foundational work)
│
└── Story 2: Test and Deploy Icons (2 points)
    Dependencies: Story 1 (requires infrastructure)

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

Implementation Sequence

  1. Story 1 → Build icon infrastructure (setup, download, configure)

    • Dependencies: None
    • Deliverable: Icon files downloaded, organized, accessible

  2. Story 2 → Test and deploy (depends on Story 1)

    • Dependencies: Story 1 must be complete
    • Deliverable: Icons verified, tested, deployed to production

Dependency Validation: ✅ Valid sequence - no forward dependencies

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}}

Auto-run validation - NOT optional!

Running automatic story validation...

Validate Story Sequence (CRITICAL):

For each story, check:

  1. Does Story N depend on Story N+1 or later? ❌ FAIL - Reorder required!
  2. Are dependencies clearly documented? ✅ PASS
  3. Can stories be implemented in order 1→2→3? ✅ PASS

If sequence validation FAILS:

  • Identify the problem dependencies
  • Propose new ordering
  • Ask user to confirm reordering

Validate Acceptance Criteria Quality:

For each story's AC, check:

  1. Is it numbered (AC #1, AC #2, etc.)? ✅ Required
  2. Is it specific and testable? ✅ Required
  3. Does it use Given/When/Then or equivalent? ✅ Recommended
  4. Are all success conditions covered? ✅ Required

Count vague AC (contains "works", "good", "fast", "well"):

  • 0 vague AC: ✅ EXCELLENT
  • 1-2 vague AC: ⚠️ WARNING - Should improve
  • 3+ vague AC: ❌ FAIL - Must improve

Validate Story Completeness:

  1. Do all stories map to tech spec tasks? ✅ Required
  2. Do story points align with tech spec estimates? ✅ Recommended
  3. Are dependencies clearly noted? ✅ Required
  4. Does each story have testable AC? ✅ Required

Generate validation report

❌ **Story Validation Failed:**

{{issues_found}}

Recommended Fixes: {{recommended_fixes}}

Shall I fix these issues? (yes/no)

Apply fixes? (yes/no)

Apply fixes (reorder stories, rewrite vague AC, add missing details) Re-validate ✅ Validation passed after fixes! ✅ **Story Validation Passed!**

Sequence: ✅ Valid (no forward dependencies) AC Quality: ✅ All specific and testable Completeness: ✅ All tech spec tasks covered Dependencies: ✅ Clearly documented

Stories are implementation-ready!

Confirm all validation passed Verify total story points align with tech spec time estimates Confirm epic and stories are complete

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_ephemeral_location}/

Next Steps - Iterative Implementation:

🎯 RECOMMENDED - Direct to Development (Level 1):

Since the tech-spec is now CONTEXT-RICH with:

  • ✅ Brownfield codebase analysis (if applicable)
  • ✅ Framework and library details with exact versions
  • ✅ Existing patterns and code references
  • ✅ Complete file paths and integration points
  • ✅ Dependencies clearly mapped

You can skip story-context for most Level 1 stories!

1. Start with Story 1: a. Load DEV agent: {project-root}/.bmad/bmm/agents/dev.md b. Run dev-story workflow (select story-{epic_slug}-1.md) c. Tech-spec provides all context needed d. Implement story 1

2. After Story 1 Complete:

  • Repeat for story-{epic_slug}-2.md
  • Reference completed story 1 in your work

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

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

Option B - Generate Additional Context (optional):

Only needed for extremely complex multi-story dependencies:

  1. Load SM agent: {project-root}/.bmad/bmm/agents/sm.md
  2. Run story-context workflow for complex stories
  3. Then load DEV agent and run dev-story

Progress Tracking:

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

Ready to proceed? Choose your path:

  1. Go directly to dev-story for story 1 (RECOMMENDED - tech-spec has all context)
  2. Generate additional story context first (for complex dependencies)
  3. Exit for now

Select option (1-3):