root
/
Midtrans-Middleware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Midtrans-Middleware/.bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions-generate-stori...

13 KiB
Raw Blame History

Unified Epic and Story Generation

⚠️ CHECKPOINT PROTOCOL: After EVERY tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.

This generates epic + stories for ALL quick-flow projects Always generates: epics.md + story files (1-5 stories based on {{story_count}}) Runs AFTER tech-spec.md completion Story format MUST match create-story template for compatibility with story-context and dev-story workflows

Read the completed tech-spec.md file from {default_output_file} Load bmm-workflow-status.yaml from {workflow-status} (if exists) Get story_count from workflow variables (1-5) Ensure {sprint_artifacts} directory exists

Extract from tech-spec structure:

From "The Change" section:

  • Problem statement and solution overview
  • Scope (in/out)

From "Implementation Details" section:

  • Source tree changes
  • Technical approach
  • Integration points

From "Implementation Guide" section:

  • Implementation steps
  • Testing strategy
  • Acceptance criteria
  • Time estimates

From "Development Context" section:

  • Framework dependencies with versions
  • Existing code references
  • Internal dependencies

From "Developer Resources" section:

  • File paths
  • Key code locations
  • Testing locations

Use this rich context to generate comprehensive, implementation-ready epic and stories.

Create epic based on the overall feature/change from tech-spec

Derive epic slug from the feature name:

  • Use 2-3 words max
  • Kebab-case format
  • User-focused, not implementation-focused

Examples:

  • "OAuth Integration" → "oauth-integration"
  • "Fix Login Bug" → "login-fix"
  • "User Profile Page" → "user-profile"

Store as {{epic_slug}} - this will be used for all story filenames

Adapt epic detail to story count:

For single story (story_count == 1):

  • Epic is minimal - just enough structure
  • Goal: Brief statement of what's being accomplished
  • Scope: High-level boundary
  • Success criteria: Core outcomes

For multiple stories (story_count > 1):

  • Epic is detailed - full breakdown
  • Goal: Comprehensive purpose and value statement
  • Scope: Clear boundaries with in/out examples
  • Success criteria: Measurable, testable outcomes
  • Story map: Visual representation of epic → stories
  • Implementation sequence: Logical ordering with dependencies

Initialize {epics_file} using {epics_template}

Populate epic metadata from tech-spec context:

Epic Title: User-facing outcome (not implementation detail)

  • Good: "OAuth Integration", "Login Bug Fix", "Icon Reliability"
  • Bad: "Update recommendedLibraries.ts", "Refactor auth service"

Epic Goal: Why this matters to users/business

Epic Scope: Clear boundaries from tech-spec scope section

Epic Success Criteria: Measurable outcomes from tech-spec acceptance criteria

Dependencies: From tech-spec integration points and dependencies

project_name date epic_title epic_slug epic_goal epic_scope epic_success_criteria epic_dependencies

Analyze tech-spec implementation steps and create story breakdown

For story_count == 1:

  • Create single comprehensive story covering all implementation
  • Title: Focused on the deliverable outcome
  • Tasks: Map directly to tech-spec implementation steps
  • Estimated points: Typically 1-5 points

For story_count > 1:

  • Break implementation into logical story boundaries
  • Each story must be:
    • Independently valuable (delivers working functionality)
    • Testable (has clear acceptance criteria)
    • Sequentially ordered (no forward dependencies)
    • Right-sized (prefer 2-4 stories over many tiny ones)

Story Sequencing Rules (CRITICAL):

  1. Foundation → Build → Test → Polish
  2. Database → API → UI
  3. Backend → Frontend
  4. Core → Enhancement
  5. NO story can depend on a later story!

Validate sequence: Each story N should only depend on stories 1...N-1

For each story position (1 to {{story_count}}):

  1. Determine story scope from tech-spec tasks

    • Group related implementation steps
    • Ensure story leaves system in working state

  2. Create story title

    • User-focused deliverable
    • Active, clear language
    • Good: "OAuth Backend Integration", "OAuth UI Components"
    • Bad: "Write some OAuth code", "Update files"

  3. Extract acceptance criteria

    • From tech-spec testing strategy and acceptance criteria
    • Must be numbered (AC #1, AC #2, etc.)
    • Must be specific and testable
    • Use Given/When/Then format when applicable

  4. Map tasks to implementation steps

    • Break down tech-spec implementation steps for this story
    • Create checkbox list
    • Reference AC numbers: (AC: #1), (AC: #2)

  5. Estimate story points

    • 1 point = < 1 day (2-4 hours)
    • 2 points = 1-2 days
    • 3 points = 2-3 days
    • 5 points = 3-5 days
    • Total across all stories should align with tech-spec estimates
Set story_filename = "story-{{epic_slug}}-{{n}}.md" Set story_path = "{sprint_artifacts}/{{story_filename}}"

Create story file using {user_story_template}

Populate story with:

Story Header:

  • N.M format (where N is always 1 for quick-flow, M is story number)
  • Title: User-focused deliverable
  • Status: Draft

User Story:

  • As a [role] (developer, user, admin, system, etc.)
  • I want [capability/change]
  • So that [benefit/value]

Acceptance Criteria:

  • Numbered list (AC #1, AC #2, ...)
  • Specific, measurable, testable
  • Derived from tech-spec testing strategy and acceptance criteria
  • Cover all success conditions for this story

Tasks/Subtasks:

  • Checkbox list mapped to tech-spec implementation steps
  • Each task references AC numbers: (AC: #1)
  • Include explicit testing tasks

Technical Summary:

  • High-level approach for this story
  • Key technical decisions
  • Files/modules involved

Project Structure Notes:

  • files_to_modify: From tech-spec "Developer Resources → File Paths"
  • test_locations: From tech-spec "Developer Resources → Testing Locations"
  • story_points: Estimated effort
  • dependencies: Prerequisites (other stories, systems, data)

Key Code References:

  • From tech-spec "Development Context → Relevant Existing Code"
  • From tech-spec "Developer Resources → Key Code Locations"
  • Specific file:line references when available

Context References:

  • Link to tech-spec.md (primary context document)
  • Note: Tech-spec contains brownfield analysis, framework versions, patterns, etc.

Dev Agent Record:

  • Empty sections (populated during dev-story execution)
  • Agent Model Used
  • Debug Log References
  • Completion Notes
  • Files Modified
  • Test Results

Review Notes:

  • Empty section (populated during code review)

story_number story_title user_role capability benefit acceptance_criteria tasks_subtasks technical_summary files_to_modify test_locations story_points time_estimate dependencies existing_code_references

Create visual story map showing epic → stories hierarchy

Include:

  • Epic title at top
  • Stories listed with point estimates
  • Dependencies noted
  • Sequence validation confirmation

Example:

Epic: OAuth Integration (8 points)
├── Story 1.1: OAuth Backend (3 points)
│   Dependencies: None
│
├── Story 1.2: OAuth UI Components (3 points)
│   Dependencies: Story 1.1
│
└── Story 1.3: OAuth Testing & Polish (2 points)
    Dependencies: Stories 1.1, 1.2

Calculate totals:

  • Total story points across all stories
  • Estimated timeline (typically 1-2 points per day)

Append to {epics_file}:

  • Story summaries
  • Story map visual
  • Implementation sequence
  • Total points and timeline

story_map story_summaries total_points estimated_timeline implementation_sequence

Always run validation - NOT optional!

Validate all stories against quality standards:

Story Sequence Validation (CRITICAL):

  • For each story N, verify it doesn't depend on story N+1 or later
  • Check: Can stories be implemented in order 1→2→3→...?
  • If sequence invalid: Identify problem, propose reordering, ask user to confirm

Acceptance Criteria Quality:

  • All AC are numbered (AC #1, AC #2, ...)
  • Each AC is specific and testable (no "works well", "is good", "performs fast")
  • AC use Given/When/Then or equivalent structure
  • All success conditions are covered

Story Completeness:

  • All stories map to tech-spec implementation steps
  • Story points align with tech-spec time estimates
  • Dependencies are clearly documented
  • Each story has testable AC
  • Files and locations reference tech-spec developer resources

Template Compliance:

  • All required sections present
  • Dev Agent Record sections exist (even if empty)
  • Context references link to tech-spec.md
  • Story numbering follows N.M format
⚠️ **Story Validation Issues:**

{{issues_list}}

Recommended Fixes: {{fixes}}

Shall I fix these automatically? (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!**

Quality Scores:

  • Sequence: ✅ Valid (no forward dependencies)
  • AC Quality: ✅ All specific and testable
  • Completeness: ✅ All tech spec tasks covered
  • Template Compliance: ✅ All sections present

Stories are implementation-ready!

Update bmm-workflow-status.yaml (if exists):

  • Mark tech-spec as complete
  • Initialize story sequence tracking
  • Set first story as TODO
  • Track epic slug and story count

✅ Epic and Stories Generated!

Epic: {{epic_title}} ({{epic_slug}}) Total Stories: {{story_count}} {{#if story_count > 1}}Total Points: {{total_points}} Estimated Timeline: {{estimated_timeline}}{{/if}}

Files Created:

  • {epics_file} - Epic structure{{#if story_count == 1}} (minimal){{/if}}
  • {sprint_artifacts}/story-{{epic_slug}}-1.md{{#if story_count > 1}}
  • {sprint_artifacts}/story-{{epic_slug}}-2.md{{/if}}{{#if story_count > 2}}
  • Through story-{{epic_slug}}-{{story_count}}.md{{/if}}

What's Next: All stories reference tech-spec.md as primary context. You can proceed directly to development with the DEV agent!

Story files are ready for:

  • Direct implementation (dev-story workflow)
  • Optional context generation (story-context workflow for complex cases)
  • Sprint planning organization (sprint-planning workflow for multi-story coordination)