diff --git a/src/bmm/workflows/4-implementation/batch-super-dev/instructions.md b/src/bmm/workflows/4-implementation/batch-super-dev/instructions.md
deleted file mode 100644
index c7fd4498..00000000
--- a/src/bmm/workflows/4-implementation/batch-super-dev/instructions.md
+++ /dev/null
@@ -1,1270 +0,0 @@
-# Batch Super-Dev - Interactive Story Selector
-## AKA: "Mend the Gap" π
-
-**Primary Use Case:** Gap analysis and reconciliation workflow
-
-This workflow helps you "mind the gap" between story requirements and codebase reality, then "mend the gap" by building only what's truly missing.
-
-### What This Workflow Does
-
-1. **Scans codebase** to verify what's actually implemented vs what stories claim
-2. **Finds the gap** between story requirements and reality
-3. **Mends the gap** by building ONLY what's truly missing (no duplicate work)
-4. **Updates tracking** to reflect actual completion status (check boxes, sprint-status)
-
-### Common Use Cases
-
-**Reconciliation Mode (Most Common):**
-- Work was done but not properly tracked
-- Stories say "build X" but X is 60-80% already done
-- Need second set of eyes to find real gaps
-- Update story checkboxes to match reality
-
-**Greenfield Mode:**
-- Story says "build X", nothing exists
-- Build 100% from scratch with full quality gates
-
-**Brownfield Mode:**
-- Story says "modify X", X exists
-- Refactor carefully, add only new requirements
-
-### Execution Modes
-
-**Sequential (Recommended for Gap Analysis):**
-- Process stories ONE-BY-ONE in THIS SESSION
-- After each story: verify existing code β build only gaps β check boxes β move to next
-- Easier to monitor, can intervene if issues found
-- Best for reconciliation work
-
-**Parallel (For Greenfield Batch Implementation):**
-- Spawn autonomous Task agents to process stories concurrently
-- Faster completion but harder to monitor
-- Best when stories are independent and greenfield
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml
-
-βοΈ HOSPITAL-GRADE CODE STANDARDS βοΈ
-This code may be used in healthcare settings where LIVES ARE AT STAKE.
-Every line of code must meet hospital-grade reliability standards.
-QUALITY >> SPEED. Take 5 hours to do it right, not 1 hour to do it poorly.
-
-
-
-
- Read {sprint_status} file
- Parse metadata: project, project_key, tracking_system
- Parse development_status map
-
- Filter stories with status = "ready-for-dev" OR "backlog"
- Exclude entries that are epics (keys starting with "epic-") or retrospectives (keys ending with "-retrospective")
- Group by status: ready_for_dev_stories, backlog_stories
-
-
- Further filter stories to only include those starting with "{filter_by_epic}-"
- If filter_by_epic = "3", only include stories like "3-1-...", "3-2-...", etc.
-
-
- Sort filtered stories by epic number, then story number (e.g., 1-1, 1-2, 2-1, 3-1)
- Store as: ready_for_dev_stories (list of story keys)
-
-
-
- Exit workflow
-
-
- Combine both lists: available_stories = ready_for_dev_stories + backlog_stories
-
-
-
- Read comment field for each story from sprint-status.yaml (text after # on the same line)
-
- For each story, verify story file exists using COMPREHENSIVE naming pattern detection:
-
-
- Parse story_key (e.g., "20-9-megamenu-navigation" or "20-9") to extract:
- - epic_num: first number (e.g., "20")
- - story_num: second number (e.g., "9")
- - optional_suffix: everything after second number (e.g., "-megamenu-navigation" or empty)
- Input: "20-9-megamenu-navigation" β epic=20, story=9, suffix="-megamenu-navigation"
- Input: "20-11" β epic=20, story=11, suffix=""
-
-
-
- Use Glob tool to search for files matching these patterns (in priority order):
-
- story-{epic_num}.{story_num}.md
- story-20.9.md (DOT notation, no suffix)
-
- story-{epic_num}.{story_num}*.md
- story-20.9-megamenu-navigation.md (DOT notation WITH suffix - use Glob wildcard)
-
- {epic_num}-{story_num}.md
- 20-9.md (HYPHEN notation, no "story-" prefix)
-
- {epic_num}-{story_num}*.md
- 20-9-megamenu-navigation.md (HYPHEN notation WITH suffix)
-
- story-{story_key}.md
- story-20-9-megamenu-navigation.md (literal story_key with "story-" prefix)
-
- {story_key}.md
- 20-9-megamenu-navigation.md (literal story_key)
-
- Stop at first match and store file_path
- If NO match found after all 6 patterns β file_status = β MISSING
- If match found β file_status = β
EXISTS
-
-
- Mark stories as: β
(file exists), β (file missing), π (already implemented but not marked done)
-
-
-
-
-
-
-
- For each story in available_stories (ready_for_dev + backlog):
-
-
- Check if story file exists (already done in Step 2)
-
-
-
-
- Mark story as needs_story_creation = true
- Mark story.creation_workflow = "/create-story" (lightweight, no gap analysis)
- Mark story as validated (will create in next step)
-
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "Story file missing (status ready-for-dev but no file)"
-
-
-
-
- Read story file: {{file_path}}
- Parse sections and validate BMAD format
-
- Check for all 12 required sections:
- 1. Business Context
- 2. Current State
- 3. Acceptance Criteria
- 4. Tasks and Subtasks
- 5. Technical Requirements
- 6. Architecture Compliance
- 7. Testing Requirements
- 8. Dev Agent Guardrails
- 9. Definition of Done
- 10. References
- 11. Dev Agent Record
- 12. Change Log
-
-
- Count sections present: sections_found
- Check Current State content length (word count)
- Check Acceptance Criteria item count: ac_count
- Count unchecked tasks ([ ]) in Tasks/Subtasks: task_count
- Look for gap analysis markers (β
/β) in Current State
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "INVALID - Only {{task_count}} tasks (need β₯3)"
-
-
-
-
-
-
- Regenerate story with codebase scan? (yes/no):
-
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "Story regeneration requires manual workflow (agents cannot invoke /create-story)"
- Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis"
-
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "User declined regeneration"
-
-
-
-
-
- Mark story as validated
-
-
-
-
-
- Mark story as validated (already done)
-
-
-
- Remove skipped stories from ready_for_dev_stories
- Update count of available stories
-
-
-
-
-
-
-
- Exit workflow
-
-
-
-
-
-
-
-
- For each validated story:
-
-
- Read story file: {{file_path}}
-
- Count unchecked tasks ([ ]) at top level only in Tasks/Subtasks section β task_count
- (See workflow.yaml complexity.task_counting.method = "top_level_only")
-
-
-
-
- Set {{story_key}}.complexity = {level: "INVALID", score: 0, task_count: {{task_count}}, reason: "Insufficient tasks ({{task_count}}/3 minimum)"}
- Continue to next story
-
-
- Extract file paths mentioned in tasks β file_count
- Scan story title and task descriptions for risk keywords using rules from workflow.yaml:
- - Case insensitive matching (require_word_boundaries: true)
- - Include keyword variants (e.g., "authentication" matches "auth")
- - Scan: story_title, task_descriptions, subtask_descriptions
-
-
- Calculate complexity score:
- - Base score = task_count
- - Add 5 for each HIGH risk keyword match (auth, security, payment, migration, database, schema, encryption)
- - Add 2 for each MEDIUM risk keyword match (api, integration, external, third-party, cache)
- - Add 0 for LOW risk keywords (ui, style, config, docs, test)
- - Count each keyword only once (no duplicates)
-
-
- Assign complexity level using mutually exclusive decision tree (priority order):
-
- 1. Check COMPLEX first (highest priority):
- IF (task_count β₯ 16 OR complexity_score β₯ 20 OR has ANY HIGH risk keyword)
- THEN level = COMPLEX
-
- 2. Else check MICRO (lowest complexity):
- ELSE IF (task_count β€ 3 AND complexity_score β€ 5 AND file_count β€ 5)
- THEN level = MICRO
-
- 3. Else default to STANDARD:
- ELSE level = STANDARD
-
- This ensures no overlaps:
- - Story with HIGH keyword β COMPLEX (never MICRO or STANDARD)
- - Story with 4-15 tasks or >5 files β STANDARD (not MICRO or COMPLEX)
- - Story with β€3 tasks, β€5 files, no HIGH keywords β MICRO
-
-
- Store complexity_level for story: {{story_key}}.complexity = {level, score, task_count, risk_keywords}
-
-
- Group stories by complexity level
-
- Filter out INVALID stories (those with level="INVALID"):
- For each INVALID story, add to skipped_stories with reason from complexity object
- Remove INVALID stories from complexity_groups and ready_for_dev_stories
-
-
-
-
-
-
-
-
-
- Exit workflow
-
-
-
-
-
-**Select stories to process:**
-
-Enter story numbers to process (examples):
- - Single: `1`
- - Multiple: `1,3,5`
- - Range: `1-5` (processes 1,2,3,4,5)
- - Mixed: `1,3-5,8` (processes 1,3,4,5,8)
- - All: `all` (processes all {{count}} stories)
-
-Or:
- - `cancel` - Exit without processing
-
-**Your selection:**
-
-
- Parse user input
-
-
-
- Exit workflow
-
-
-
- Set selected_stories = all ready_for_dev_stories
-
-
-
- Parse selection (handle commas, ranges)
- Input "1,3-5,8" β indexes [1,3,4,5,8] β map to story keys
- Map selected indexes to story keys from ready_for_dev_stories
- Store as: selected_stories
-
-
-
-
- Truncate selected_stories to first max_stories entries
-
-
- Display confirmation
-
-
-
-
-
-
- For each selected story:
-
-
- Read story file: {{story_file_path}}
-
-
-
-
- Mark story as needs_creation
- Continue to next story
-
-
-
-
- Add to validation_failures list
- Continue to next story
-
-
-
-
- Validate story completeness:
- - Count sections (need 12)
- - Check Current State word count (need β₯100)
- - Check gap analysis markers (β
/β)
- - Count Acceptance Criteria (need β₯3)
- - Count unchecked tasks (need β₯3)
-
-
-
-
- Add to validation_failures: "{{story_key}}: Only {{task_count}} tasks"
-
-
-
-
- Add to validation_warnings: "{{story_key}}: Needs regeneration"
-
-
-
-
- Add to validated_stories list
-
-
-
-
-
-
-
- Remove failed stories and continue? (yes/no):
-
-
- Remove validation_failures from selected_stories
-
-
-
-
-
- Exit workflow
-
-
-
-
-
-
- Continue with these stories anyway? (yes/no):
-
-
-
- Exit workflow
-
-
-
-
-
-
-
-
-
- Jump to Step 3
-
-
-
-
- Create these {{needs_creation.length}} story files now? (yes/no):
-
-
-
- Remove needs_creation stories from selected_stories
-
-
-
- Exit workflow
-
-
-
- For each story in needs_creation:
-
-
-
-
- Invoke workflow: /bmad_bmm_create-story
- Parameters:
- - story_key: {{story_key}}
- - epic_num: {{epic_num}}
- - mode: batch (auto-approve, minimal prompts)
-
-
-
-
- Mark story.needs_story_creation = false
-
-
-
-
- Add to failed_creations list
- Remove from selected_stories
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-**Choose execution mode:**
-
-[I] INTERACTIVE CHECKPOINT MODE
- - After each story completes, pause for your review
- - You approve before proceeding to next story
- - Allows course correction if issues detected
- - Best for: When you want to monitor progress
-
-[A] FULLY AUTONOMOUS MODE
- - Process all selected stories without pausing
- - No human interaction until completion
- - Best for: When stories are well-defined and you trust the process
-
-Which mode? [I/A]:
-
-
- Read user input
-
-
- Set execution_mode = "interactive_checkpoint"
-
-
-
-
- Set execution_mode = "fully_autonomous"
-
- Activate hospital_grade_mode = true
- Set quality_multiplier = 1.5
-
-
-
-**How should these stories be processed?**
-
-Options:
-- **sequential**: Run stories one-by-one in this session (slower, easier to monitor)
-- **parallel**: Spawn Task agents to process stories concurrently (faster, autonomous)
-
-Enter: sequential or parallel
-
-
- Capture response as: execution_mode
-
-
- Set parallel_count = 1
- Set use_task_agents = false
-
-
-
-
- Set use_task_agents = true
-
-
-**How many agents should run in parallel?**
-
-Options:
-- **2**: Conservative (low resource usage, easier debugging)
-- **4**: Moderate (balanced performance, recommended)
-- **8**: Aggressive (higher throughput)
-- **10**: Maximum (10 agent limit for safety)
-- **all**: Use all stories (max 10 agents)
-
-Enter number (2-10) or 'all':
-
-
- Capture response as: parallel_count
- If parallel_count == 'all': set parallel_count = min(count of selected_stories, 10)
- If parallel_count > 10: set parallel_count = 10 (safety limit)
-
-
-
-
-
-
-
-
- Confirm execution plan? (yes/no):
-
-
-
- Exit workflow
-
-
-
-
- Initialize counters: completed=0, failed=0, failed_stories=[], reconciliation_warnings=[], reconciliation_warnings_count=0
- Set start_time = current timestamp
-
-
- Jump to Step 4-Parallel (Task Agent execution)
-
-
-
- Continue to Step 4-Sequential (In-session execution)
-
-
-
-
-
-
- For each story in selected_stories:
-
-
-
-
- Invoke workflow: /bmad:bmm:workflows:super-dev-pipeline
- Parameters: mode=batch, story_key={{story_key}}, complexity_level={{story_key}}.complexity.level
-
-
-
-
- ORCHESTRATOR: You must execute reconciliation directly using Bash/Read/Edit tools.
- Do NOT delegate this to an agent. YOU do it.
-
-
- 1. Use Bash: `git log -3 --oneline | grep "{{story_key}}"` to find commit
- 2. Use Bash: `git diff HEAD~1 --name-only` to get files changed
- 3. Use Read: `docs/sprint-artifacts/{{story_key}}.md` to see tasks
- 4. Use Edit: Check off tasks (change `- [ ]` to `- [x]`) for completed work
- 5. Use Edit: Fill Dev Agent Record with files/date/summary
- 6. Use Bash: Verify with `grep -c "^- \[x\]"` (must be > 0)
- 7. Use Edit: Update sprint-status.yaml to "done" or "review"
-
-
-
-
- Increment completed counter
-
-
- PAUSE FOR USER REVIEW
-
-
- Read user input
-
-
-
-
-
-
-
- Display story file, test results, review findings
-
- Read user input
-
-
-
-
-
- Jump to Step 5 (Summary)
-
-
-
-
-
- Jump to Step 5 (Summary)
-
-
-
-
-
-
-
-
-
-
- Increment completed counter (implementation was successful)
- Add to reconciliation_warnings: {story_key: {{story_key}}, warning_message: "Reconciliation failed - manual verification needed"}
- Increment reconciliation_warnings_count
-
-
-
-
-
- Increment failed counter
- Add story_key to failed_stories list
-
-
-
- Jump to Step 5 (Summary)
-
-
-
-
-
-
-
-
-
- Wait {{pause_between_stories}} seconds
-
-
-
- After all stories processed, jump to Step 5 (Summary)
-
-
-
-
-
- Initialize worker pool state:
-
- - story_queue = selected_stories (all stories to process)
- - active_workers = {} (map of worker_id β {story_key, task_id, started_at})
- - completed_stories = []
- - failed_stories = []
- - next_story_index = 0
- - max_workers = {{parallel_count}}
-
-
-
-
-
- Spawn first {{max_workers}} agents (or fewer if less stories):
-
- While next_story_index < min(max_workers, story_queue.length):
-
-
- story_key = story_queue[next_story_index]
- worker_id = next_story_index + 1
-
- Spawn Task agent:
- - subagent_type: "general-purpose"
- - description: "Implement story {{story_key}}"
- - prompt: "Execute super-dev-pipeline workflow for story {{story_key}}.
-
- CRITICAL INSTRUCTIONS:
- 1. Load workflow.xml: _bmad/core/tasks/workflow.xml
- 2. Load workflow config: _bmad/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml
- 3. Execute in BATCH mode with story_key={{story_key}} and complexity_level={{story_key}}.complexity.level
- 4. Follow all 7 pipeline steps (init, pre-gap, implement, post-validate, code-review, complete, summary)
- 5. Commit changes when complete
- 6. Report final status (done/failed) with file list
-
- Story file will be auto-resolved from multiple naming conventions."
- - run_in_background: true (non-blocking - critical for semaphore pattern)
-
- Store in active_workers[worker_id]:
- story_key: {{story_key}}
- task_id: {{returned_task_id}}
- started_at: {{timestamp}}
- status: "running"
-
-
- Increment next_story_index
-
-
-
- After spawning initial workers:
-
-
-
-
- SEMAPHORE PATTERN: Keep {{max_workers}} agents running continuously
-
- While active_workers.size > 0 OR next_story_index < story_queue.length:
-
- Poll for completed workers (check task outputs non-blocking):
-
- For each worker_id in active_workers:
-
- Check if worker task completed using TaskOutput(task_id, block=false)
-
-
- Continue to next worker (don't wait)
-
-
-
- Get worker details: story_key = active_workers[worker_id].story_key
-
-
-
- ORCHESTRATOR: You must execute reconciliation directly using Bash/Read/Edit tools.
-
-
- 1. Use Bash: `git log -3 --oneline | grep "{{story_key}}"` to find commit
- 2. Use Bash: `git diff HEAD~1 --name-only` to get files changed
- 3. Use Read: `docs/sprint-artifacts/{{story_key}}.md` to see tasks
- 4. Use Edit: Check off tasks (change `- [ ]` to `- [x]`) for completed work
- 5. Use Edit: Fill Dev Agent Record with files/date/summary
- 6. Use Bash: Verify with `grep -c "^- \[x\]"` (must be > 0)
- 7. Use Edit: Update sprint-status.yaml to "done" or "review"
-
-
-
-
- Add to completed_stories
-
-
-
-
- Add to completed_stories (implementation successful)
- Add to reconciliation_warnings: {story_key: {{story_key}}, warning_message: "Reconciliation failed - manual verification needed"}
-
-
- Remove worker_id from active_workers (free the slot)
-
- IMMEDIATELY refill slot if stories remain:
-
- story_key = story_queue[next_story_index]
-
-
-
- Spawn new Task agent for this worker_id (same parameters as init)
- Update active_workers[worker_id] with new task_id and story_key
- Increment next_story_index
-
-
-
-
- Get worker details: story_key = active_workers[worker_id].story_key
-
-
-
- Add to failed_stories
- Remove worker_id from active_workers (free the slot)
-
-
-
- Kill all active workers
- Clear story_queue
- Break worker pool loop
-
-
-
- story_key = story_queue[next_story_index]
-
-
-
- Spawn new Task agent for this worker_id
- Update active_workers[worker_id] with new task_id and story_key
- Increment next_story_index
-
-
-
- Display live progress every 30 seconds:
-
-
- Sleep 5 seconds before next poll (prevents tight loop)
-
-
-
- After worker pool drains (all stories processed), jump to Step 5 (Summary)
-
-
-
- Calculate end_time and total_duration
- Calculate success_rate = (completed / total_count) * 100
-
-
-
- Save batch log to {batch_log}
- Log contents: start_time, end_time, total_duration, selected_stories, completed_stories, failed_stories, success_rate
-
-
-
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md
deleted file mode 100644
index 08f41fa6..00000000
--- a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# Create Story With Gap Analysis
-
-**Custom Workflow by Jonah Schulte**
-**Created:** December 24, 2025
-**Purpose:** Generate stories with SYSTEMATIC codebase gap analysis (not inference-based)
-
----
-
-## Problem This Solves
-
-**Standard `/create-story` workflow:**
-- β Reads previous stories and git commits (passive)
-- β Infers what probably exists (guessing)
-- β Gap analysis quality varies by agent thoroughness
-- β Checkboxes may not reflect reality
-
-**This custom workflow:**
-- β
Actively scans codebase with Glob/Read tools
-- β
Verifies file existence (not inference)
-- β
Reads key files to check implementation depth (mocked vs real)
-- β
Generates TRUTHFUL gap analysis
-- β
Checkboxes are FACTS verified by file system
-
----
-
-## Usage
-
-```bash
-/create-story-with-gap-analysis
-
-# Or via Skill tool:
-Skill: "create-story-with-gap-analysis"
-Args: "1.9" (epic.story number)
-```
-
-**Workflow will:**
-1. Load existing story + epic context
-2. **SCAN codebase systematically** (Glob for files, Read to verify implementation)
-3. Generate gap analysis with verified β
/β/β οΈ status
-4. Update story file with truthful checkboxes
-5. Save to _bmad-output/implementation-artifacts/
-
----
-
-## What It Scans
-
-**For each story, the workflow:**
-
-1. **Identifies target directories** (from story title/requirements)
- - Example: "admin-user-service" β apps/backend/admin-user-service/
-
-2. **Globs for all files**
- - `{target}/src/**/*.ts` - Find all TypeScript files
- - `{target}/src/**/*.spec.ts` - Find all tests
-
-3. **Checks specific required files**
- - Based on ACs, check if files exist
- - Example: `src/auth/controllers/bridgeid-auth.controller.ts` β β MISSING
-
-4. **Reads key files to verify depth**
- - Check if mocked: Search for "MOCK" string
- - Check if incomplete: Search for "TODO"
- - Verify real implementation exists
-
-5. **Checks package.json**
- - Verify required dependencies are installed
- - Identify missing packages
-
-6. **Counts tests**
- - How many test files exist
- - Coverage for each component
-
----
-
-## Output Format
-
-**Generates story with:**
-
-1. β
Standard BMAD 5 sections (Story, AC, Tasks, Dev Notes, Dev Agent Record)
-2. β
Enhanced Dev Notes with verified gap analysis subsections:
- - Gap Analysis: Current State vs Requirements
- - Library/Framework Requirements (from package.json)
- - File Structure Requirements (from Glob results)
- - Testing Requirements (from test file count)
- - Architecture Compliance
- - Previous Story Intelligence
-
-3. β
Truthful checkboxes based on verified file existence
-
----
-
-## Difference from Standard /create-story
-
-| Feature | /create-story | /create-story-with-gap-analysis |
-|---------|---------------|--------------------------------|
-| Reads previous story | β
| β
|
-| Reads git commits | β
| β
|
-| Loads epic context | β
| β
|
-| **Scans codebase with Glob** | β | β
SYSTEMATIC |
-| **Verifies files exist** | β | β
VERIFIED |
-| **Reads files to check depth** | β | β
MOCKED vs REAL |
-| **Checks package.json** | β | β
DEPENDENCIES |
-| **Counts test coverage** | β | β
COVERAGE |
-| Gap analysis quality | Variable (agent-dependent) | Systematic (tool-verified) |
-| Checkbox accuracy | Inference-based | File-existence-based |
-
----
-
-## When to Use
-
-**This workflow (planning-time gap analysis):**
-- Use when regenerating/auditing stories
-- Use when you want verified checkboxes upfront
-- Best for stories that will be implemented immediately
-- Manual verification at planning time
-
-**Standard /create-story + /dev-story (dev-time gap analysis):**
-- Recommended for most workflows
-- Stories start as DRAFT, validated when dev begins
-- Prevents staleness in batch planning
-- Automatic verification at development time
-
-**Use standard /create-story when:**
-- Greenfield project (nothing exists yet)
-- Backlog stories (won't be implemented for months)
-- Epic planning phase (just sketching ideas)
-
-**Tip:** Both approaches are complementary. You can use this workflow to regenerate stories, then use `/dev-story` which will re-validate at dev-time.
-
----
-
-## Examples
-
-**Regenerating Story 1.9:**
-```bash
-/create-story-with-gap-analysis
-
-Choice: 1.9
-
-# Workflow will:
-# 1. Load existing 1-9-admin-user-service-bridgeid-rbac.md
-# 2. Identify target: apps/backend/admin-user-service/
-# 3. Glob: apps/backend/admin-user-service/src/**/*.ts (finds 47 files)
-# 4. Check: src/auth/controllers/bridgeid-auth.controller.ts β β MISSING
-# 5. Read: src/bridgeid/services/bridgeid-client.service.ts β β οΈ MOCKED
-# 6. Read: package.json β axios β NOT INSTALLED
-# 7. Generate gap analysis with verified status
-# 8. Write story with truthful checkboxes
-```
-
-**Result:** Story with verified gap analysis showing:
-- β
7 components IMPLEMENTED (verified file existence)
-- β 6 components MISSING (verified file not found)
-- β οΈ 1 component PARTIAL (file exists but contains "MOCK")
-
----
-
-## Installation
-
-This workflow is auto-discovered when BMAD is installed.
-
-**To use:**
-```bash
-/bmad:bmm:workflows:create-story-with-gap-analysis
-```
-
----
-
-**Last Updated:** December 27, 2025
-**Status:** Integrated into BMAD-METHOD
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md
deleted file mode 100644
index 6212924b..00000000
--- a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Step 1: Initialize and Extract Story Requirements
-
-## Goal
-Load epic context and identify what needs to be scanned in the codebase.
-
-## Execution
-
-### 1. Determine Story to Create
-
-**Ask user:**
-```
-Which story should I regenerate with gap analysis?
-
-Options:
-1. Provide story number (e.g., "1.9" or "1-9")
-2. Provide story filename (e.g., "story-1.9.md" or legacy "1-9-admin-user-service-bridgeid-rbac.md")
-
-Your choice:
-```
-
-**Parse input:**
-- Extract epic_num (e.g., "1")
-- Extract story_num (e.g., "9")
-- Locate story file: `{story_dir}/story-{epic_num}.{story_num}.md` (fallback: `{story_dir}/{epic_num}-{story_num}-*.md`)
-
-### 2. Load Existing Story Content
-
-```bash
-Read: {story_dir}/story-{epic_num}.{story_num}.md
-# If not found, fallback:
-Read: {story_dir}/{epic_num}-{story_num}-*.md
-```
-
-**Extract from existing story:**
-- Story title
-- User story text (As a... I want... So that...)
-- Acceptance criteria (the requirements, not checkboxes)
-- Any existing Dev Notes or technical context
-
-**Store for later use.**
-
-### 3. Load Epic Context
-
-```bash
-Read: {planning_artifacts}/epics.md
-```
-
-**Extract from epic:**
-- Epic business objectives
-- This story's original requirements
-- Technical constraints
-- Dependencies on other stories
-
-### 4. Determine Target Directories
-
-**From story title and requirements, identify:**
-- Which service/app this story targets
-- Which directories to scan
-
-**Examples:**
-- "admin-user-service" β `apps/backend/admin-user-service/`
-- "Widget Batch 1" β `packages/widgets/`
-- "POE Integration" β `apps/frontend/web/`
-
-**Store target directories for Step 2 codebase scan.**
-
-### 5. Ready for Codebase Scan
-
-**Output:**
-```
-β
Story Context Loaded
-
-Story: {epic_num}.{story_num} - {title}
-Target directories identified:
- - {directory_1}
- - {directory_2}
-
-Ready to scan codebase for gap analysis.
-
-[C] Continue to Codebase Scan
-```
-
-**WAIT for user to select Continue.**
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md
deleted file mode 100644
index 69f4022f..00000000
--- a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# Step 2: Systematic Codebase Gap Analysis
-
-## Goal
-VERIFY what code actually exists vs what's missing using Glob and Read tools.
-
-## CRITICAL
-This step uses ACTUAL file system tools to generate TRUTHFUL gap analysis.
-No guessing. No inference. VERIFY with tools.
-
-## Execution
-
-### 1. Scan Target Directories
-
-**For each target directory identified in Step 1:**
-
-```bash
-# List all TypeScript files
-Glob: {target_dir}/src/**/*.ts
-Glob: {target_dir}/src/**/*.tsx
-
-# Store file list
-```
-
-**Output:**
-```
-π Codebase Scan Results for {target_dir}
-
-Found {count} TypeScript files:
- - {file1}
- - {file2}
- ...
-```
-
-### 2. Check for Specific Required Components
-
-**Based on story Acceptance Criteria, check if required files exist:**
-
-**Example for Auth Story:**
-```bash
-# Check for OAuth endpoints
-Glob: {target_dir}/src/auth/controllers/*bridgeid*.ts
-Result: β MISSING (0 files found)
-
-# Check for BridgeID client
-Glob: {target_dir}/src/bridgeid/**/*.ts
-Result: β
EXISTS (found: bridgeid-client.service.ts, bridgeid-sync.service.ts)
-
-# Check for permission guards
-Glob: {target_dir}/src/auth/guards/permissions*.ts
-Result: β MISSING (0 files found)
-
-# Check for decorators
-Glob: {target_dir}/src/auth/decorators/*permission*.ts
-Result: β MISSING (0 files found)
-```
-
-### 3. Verify Implementation Depth
-
-**For files that exist, read them to check if MOCKED or REAL:**
-
-```bash
-# Read key implementation file
-Read: {target_dir}/src/bridgeid/services/bridgeid-client.service.ts
-
-# Search for indicators:
-- Contains "MOCK" or "mock" β β οΈ MOCKED (needs real implementation)
-- Contains "TODO" β β οΈ INCOMPLETE
-- Contains real HTTP client (axios) β β
IMPLEMENTED
-```
-
-### 4. Check Dependencies
-
-```bash
-# Read package.json
-Read: {target_dir}/package.json
-
-# Verify required dependencies exist:
-Required: axios
-Found in package.json? β β NO (needs to be added)
-
-Required: @aws-sdk/client-secrets-manager
-Found in package.json? β β NO (needs to be added)
-```
-
-### 5. Check Test Coverage
-
-```bash
-# Find test files
-Glob: {target_dir}/src/**/*.spec.ts
-Glob: {target_dir}/test/**/*.test.ts
-
-# Count tests
-Found {test_count} test files
-
-# Check for specific test coverage
-Glob: {target_dir}/src/**/*bridgeid*.spec.ts
-Result: β
EXISTS (found 3 test files)
-```
-
-### 6. Generate Truthful Gap Analysis
-
-**Create structured gap analysis:**
-
-```markdown
-## Gap Analysis: Current State vs Requirements
-
-**β
IMPLEMENTED (Verified by Codebase Scan):**
-
-1. **BridgeID Client Infrastructure** - MOCKED (needs real HTTP)
- - File: src/bridgeid/services/bridgeid-client.service.ts β
EXISTS
- - Implementation: Mock user data with circuit breaker
- - Status: β οΈ PARTIAL - Ready for real HTTP client
- - Tests: 15 tests passing β
-
-2. **User Synchronization Service**
- - File: src/bridgeid/services/bridgeid-sync.service.ts β
EXISTS
- - Implementation: Bulk sync BridgeID β admin_users
- - Status: β
COMPLETE
- - Tests: 6 tests passing β
-
-3. **Role Mapping Logic**
- - File: src/bridgeid/constants/role-mapping.constants.ts β
EXISTS
- - Implementation: 7-tier role mapping with priority selection
- - Status: β
COMPLETE
- - Tests: 10 tests passing β
-
-**β MISSING (Required for AC Completion):**
-
-1. **BridgeID OAuth Endpoints**
- - File: src/auth/controllers/bridgeid-auth.controller.ts β NOT FOUND
- - Need: POST /api/auth/bridgeid/login endpoint
- - Need: GET /api/auth/bridgeid/callback endpoint
- - Status: β NOT IMPLEMENTED
-
-2. **Permission Guards**
- - File: src/auth/guards/permissions.guard.ts β NOT FOUND
- - File: src/auth/decorators/require-permissions.decorator.ts β NOT FOUND
- - Status: β NOT IMPLEMENTED
-
-3. **Real OAuth HTTP Client**
- - Package: axios β NOT in package.json
- - Package: @aws-sdk/client-secrets-manager β NOT in package.json
- - Status: β DEPENDENCIES NOT ADDED
-```
-
-### 7. Update Acceptance Criteria Checkboxes
-
-**Based on verified gap analysis, mark checkboxes:**
-
-```markdown
-### AC1: BridgeID OAuth Integration
-- [ ] OAuth login endpoint (VERIFIED MISSING - file not found)
-- [ ] OAuth callback endpoint (VERIFIED MISSING - file not found)
-- [ ] Client configuration (VERIFIED PARTIAL - exists but mocked)
-
-### AC3: RBAC Permission System
-- [x] Role mapping defined (VERIFIED COMPLETE - file exists, tests pass)
-- [ ] Permission guard (VERIFIED MISSING - file not found)
-- [ ] Permission decorator (VERIFIED MISSING - file not found)
-```
-
-**Checkboxes are now FACTS, not guesses.**
-
-### 8. Present Gap Analysis
-
-**Output:**
-```
-β
Codebase Scan Complete
-
-Scanned: apps/backend/admin-user-service/
-Files found: 47 TypeScript files
-Tests found: 31 test files
-
-Gap Analysis Generated:
- β
7 components IMPLEMENTED (verified)
- β 6 components MISSING (verified)
- β οΈ 1 component PARTIAL (needs completion)
-
-Story checkboxes updated based on verified file existence.
-
-[C] Continue to Story Generation
-```
-
-**WAIT for user to continue.**
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md
deleted file mode 100644
index 34281465..00000000
--- a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md
+++ /dev/null
@@ -1,181 +0,0 @@
-# Step 3: Generate Story with Verified Gap Analysis
-
-## Goal
-Generate complete 7-section story file using verified gap analysis from Step 2.
-
-## Execution
-
-### 1. Load Template
-
-```bash
-Read: {installed_path}/template.md
-```
-
-### 2. Fill Template Variables
-
-**Basic Story Info:**
-- `{{epic_num}}` - from Step 1
-- `{{story_num}}` - from Step 1
-- `{{story_title}}` - from existing story or epic
-- `{{priority}}` - from epic (P0, P1, P2)
-- `{{effort}}` - from epic or estimate
-
-**Story Section:**
-- `{{role}}` - from existing story
-- `{{action}}` - from existing story
-- `{{benefit}}` - from existing story
-
-**Business Context:**
-- `{{business_value}}` - from epic context
-- `{{scale_requirements}}` - from epic/architecture
-- `{{compliance_requirements}}` - from epic/architecture
-- `{{urgency}}` - from epic priority
-
-**Acceptance Criteria:**
-- `{{acceptance_criteria}}` - from epic + existing story
-- Update checkboxes based on Step 2 gap analysis:
- - [x] = Component verified EXISTS
- - [ ] = Component verified MISSING
- - [~] = Component verified PARTIAL (optional notation)
-
-**Tasks / Subtasks:**
-- `{{tasks_subtasks}}` - from epic + existing story
-- Add "β
DONE", "β οΈ PARTIAL", "β TODO" markers based on gap analysis
-
-**Gap Analysis Section:**
-- `{{implemented_components}}` - from Step 2 codebase scan (verified β
)
-- `{{missing_components}}` - from Step 2 codebase scan (verified β)
-- `{{partial_components}}` - from Step 2 codebase scan (verified β οΈ)
-
-**Architecture Compliance:**
-- `{{architecture_patterns}}` - from architecture doc + playbooks
-- Multi-tenant isolation requirements
-- Caching strategies
-- Error handling patterns
-- Performance requirements
-
-**Library/Framework Requirements:**
-- `{{current_dependencies}}` - from Step 2 package.json scan
-- `{{required_dependencies}}` - missing deps identified in Step 2
-
-**File Structure:**
-- `{{existing_files}}` - from Step 2 Glob results (verified β
)
-- `{{required_files}}` - from gap analysis (verified β)
-
-**Testing Requirements:**
-- `{{test_count}}` - from Step 2 test file count
-- `{{required_tests}}` - based on missing components
-- `{{coverage_target}}` - from architecture or default 90%
-
-**Dev Agent Guardrails:**
-- `{{guardrails}}` - from playbooks + previous story lessons
-- What NOT to do
-- Common mistakes to avoid
-
-**Previous Story Intelligence:**
-- `{{previous_story_learnings}}` - from Step 1 previous story Dev Agent Record
-
-**Project Structure Notes:**
-- `{{structure_alignment}}` - from architecture compliance
-
-**References:**
-- `{{references}}` - Links to epic, architecture, playbooks, related stories
-
-**Definition of Done:**
-- Standard DoD checklist with story-specific coverage target
-
-### 3. Generate Complete Story
-
-**Write filled template:**
-```bash
-Write: {story_dir}/story-{{epic_num}}.{{story_num}}.md
-[Complete 7-section story with verified gap analysis]
-```
-
-### 4. Validate Generated Story
-
-```bash
-# Check section count
-grep "^## " {story_dir}/story-{{epic_num}}.{{story_num}}.md | wc -l
-# Should output: 7
-
-# Check for gap analysis
-grep -q "Gap Analysis.*Current State" {story_dir}/story-{{epic_num}}.{{story_num}}.md
-# Should find it
-
-# Run custom validation
-./scripts/validate-bmad-format.sh {story_dir}/story-{{epic_num}}.{{story_num}}.md
-# Update script to expect 7 sections + gap analysis subsection
-```
-
-### 5. Update Sprint Status
-
-```bash
-Read: {sprint_status}
-
-# Find story entry
-# Update status to "ready-for-dev" if was "backlog"
-# Preserve all comments and structure
-
-Write: {sprint_status}
-```
-
-### 6. Report Completion
-
-**Output:**
-```
-β
Story {{epic_num}}.{{story_num}} Regenerated with Gap Analysis
-
-File: {story_dir}/story-{{epic_num}}.{{story_num}}.md
-Sections: 7/7 β
-Gap Analysis: VERIFIED with codebase scan
-
-Summary:
- β
{{implemented_count}} components IMPLEMENTED (verified by file scan)
- β {{missing_count}} components MISSING (verified file not found)
- β οΈ {{partial_count}} components PARTIAL (file exists but mocked/incomplete)
-
-Checkboxes in ACs and Tasks reflect VERIFIED status (not guesses).
-
-Next Steps:
-1. Review story file for accuracy
-2. Use /dev-story to implement missing components
-3. Story provides complete context for flawless implementation
-
-Story is ready for development. π
-```
-
-### 7. Cleanup
-
-**Ask user:**
-```
-Story regeneration complete!
-
-Would you like to:
-[N] Regenerate next story ({{next_story_num}})
-[Q] Quit workflow
-[R] Review generated story first
-
-Your choice:
-```
-
-**If N selected:** Loop back to Step 1 with next story number
-**If Q selected:** End workflow
-**If R selected:** Display story file, then show menu again
-
----
-
-## Success Criteria
-
-**Story generation succeeds when:**
-1. β
7 top-level ## sections present
-2. β
Gap Analysis subsection exists with β
/β/β οΈ verified status
-3. β
Checkboxes match codebase reality (spot-checked)
-4. β
Dev Notes has all mandatory subsections
-5. β
Definition of Done checklist included
-6. β
File saved to correct location
-7. β
Sprint status updated
-
----
-
-**WORKFLOW COMPLETE - Ready to execute.**
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md
deleted file mode 100644
index c0b7c87d..00000000
--- a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Story {{epic_num}}.{{story_num}}: {{story_title}}
-
-**Status:** ready-for-dev
-**Epic:** {{epic_num}}
-**Priority:** {{priority}}
-**Estimated Effort:** {{effort}}
-
----
-
-## Story
-
-As a **{{role}}**,
-I want to **{{action}}**,
-So that **{{benefit}}**.
-
----
-
-## Business Context
-
-### Why This Matters
-
-{{business_value}}
-
-### Production Reality
-
-{{scale_requirements}}
-{{compliance_requirements}}
-{{urgency}}
-
----
-
-## Acceptance Criteria
-
-{{acceptance_criteria}}
-
----
-
-## Tasks / Subtasks
-
-{{tasks_subtasks}}
-
----
-
-## Dev Notes
-
-### Gap Analysis: Current State vs Requirements
-
-**β
IMPLEMENTED (Verified by Codebase Scan):**
-
-{{implemented_components}}
-
-**β MISSING (Required for AC Completion):**
-
-{{missing_components}}
-
-**β οΈ PARTIAL (Needs Enhancement):**
-
-{{partial_components}}
-
-### Architecture Compliance
-
-{{architecture_patterns}}
-
-### Library/Framework Requirements
-
-**Current Dependencies:**
-```json
-{{current_dependencies}}
-```
-
-**Required Additions:**
-```json
-{{required_dependencies}}
-```
-
-### File Structure Requirements
-
-**Completed Files:**
-```
-{{existing_files}}
-```
-
-**Required New Files:**
-```
-{{required_files}}
-```
-
-### Testing Requirements
-
-**Current Test Coverage:** {{test_count}} tests passing
-
-**Required Additional Tests:**
-{{required_tests}}
-
-**Target:** {{coverage_target}}
-
-### Dev Agent Guardrails
-
-{{guardrails}}
-
-### Previous Story Intelligence
-
-{{previous_story_learnings}}
-
-### Project Structure Notes
-
-{{structure_alignment}}
-
-### References
-
-{{references}}
-
----
-
-## Definition of Done
-
-### Code Quality (BLOCKING)
-- [ ] Type check passes: `pnpm type-check` (zero errors)
-- [ ] Zero `any` types in new code
-- [ ] Lint passes: `pnpm lint` (zero errors in new code)
-- [ ] Build succeeds: `pnpm build`
-
-### Testing (BLOCKING)
-- [ ] Unit tests: {{coverage_target}} coverage
-- [ ] Integration tests: Key workflows validated
-- [ ] All tests pass: New + existing (zero regressions)
-
-### Security (BLOCKING)
-- [ ] Dependency scan: `pnpm audit` (zero high/critical)
-- [ ] No hardcoded secrets
-- [ ] Input validation on all endpoints
-- [ ] Auth checks on protected endpoints
-- [ ] Audit logging on mutations
-
-### Architecture Compliance (BLOCKING)
-- [ ] Multi-tenant isolation: dealerId in all queries
-- [ ] Cache namespacing: Cache keys include siteId
-- [ ] Performance: External APIs cached, no N+1 queries
-- [ ] Error handling: No silent failures
-- [ ] Follows patterns from playbooks
-
-### Deployment Validation (BLOCKING)
-- [ ] Service starts: `pnpm dev` runs successfully
-- [ ] Health check: `/health` returns 200
-- [ ] Smoke test: Primary functionality verified
-
-### Documentation (BLOCKING)
-- [ ] API docs: Swagger decorators on endpoints
-- [ ] Inline comments: Complex logic explained
-- [ ] Story file: Dev Agent Record complete
-
----
-
-## Dev Agent Record
-
-### Agent Model Used
-
-(To be filled by dev agent)
-
-### Implementation Summary
-
-(To be filled by dev agent)
-
-### File List
-
-(To be filled by dev agent)
-
-### Test Results
-
-(To be filled by dev agent)
-
-### Completion Notes
-
-(To be filled by dev agent)
-
----
-
-**Generated by:** /create-story-with-gap-analysis
-**Date:** {{date}}
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md
new file mode 100644
index 00000000..b40462b5
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md
@@ -0,0 +1,286 @@
+# Create Story with Gap Analysis v3.0 - Verified Story Generation
+
+
+Regenerate story with VERIFIED codebase gap analysis.
+Uses Glob/Read tools to determine what actually exists vs what's missing.
+Checkboxes reflect reality, not guesses.
+
+
+
+**Truth from Codebase, Not Assumptions**
+
+1. Scan codebase for actual implementations
+2. Verify files exist, check for stubs/TODOs
+3. Check test coverage
+4. Generate story with checkboxes matching reality
+5. No guessingβevery checkbox has evidence
+
+
+
+name: create-story-with-gap-analysis
+version: 3.0.0
+
+verification_status:
+ verified: "[x]" # File exists, real implementation, tests exist
+ partial: "[~]" # File exists but stub/TODO or no tests
+ missing: "[ ]" # File does not exist
+
+defaults:
+ update_sprint_status: true
+ create_report: false
+
+
+
+@patterns/verification.md
+@patterns/hospital-grade.md
+
+
+
+
+
+**Identify story and load context**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STORY REGENERATION WITH GAP ANALYSIS
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**Ask user for story:**
+```
+Which story should I regenerate with gap analysis?
+
+Provide:
+- Story number (e.g., "1.9" or "1-9")
+- OR story filename
+
+Your choice:
+```
+
+**Parse input:**
+- Extract epic_num, story_num
+- Locate story file
+
+**Load existing story:**
+```bash
+Read: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md
+```
+
+Extract:
+- Story title
+- User story (As a... I want... So that...)
+- Acceptance criteria
+- Tasks
+- Dev Notes
+
+**Load epic context:**
+```bash
+Read: {{planning_artifacts}}/epics.md
+```
+
+Extract:
+- Epic business objectives
+- Technical constraints
+- Dependencies
+
+**Determine target directories:**
+From story title/requirements, identify which directories to scan.
+
+```
+β
Story Context Loaded
+
+Story: {{epic_num}}.{{story_num}} - {{title}}
+Target directories:
+{{#each directories}}
+ - {{this}}
+{{/each}}
+
+[C] Continue to Codebase Scan
+```
+
+
+
+**VERIFY what code actually exists**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π CODEBASE SCAN
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**For each target directory:**
+
+1. **List all source files:**
+ ```bash
+ Glob: {{target_dir}}/src/**/*.ts
+ Glob: {{target_dir}}/src/**/*.tsx
+ ```
+
+2. **Check for specific required components:**
+ Based on story ACs, check if required files exist:
+ ```bash
+ Glob: {{target_dir}}/src/auth/controllers/*oauth*.ts
+ # Result: β
EXISTS or β MISSING
+ ```
+
+3. **Verify implementation depth:**
+ For files that exist, check quality:
+ ```bash
+ Read: {{file}}
+
+ # Check for stubs
+ Grep: "MOCK|TODO|FIXME|Not implemented" {{file}}
+ # If found: β οΈ STUB
+ ```
+
+4. **Check dependencies:**
+ ```bash
+ Read: {{target_dir}}/package.json
+
+ # Required: axios - Found? β
/β
+ # Required: @aws-sdk/client-secrets-manager - Found? β
/β
+ ```
+
+5. **Check test coverage:**
+ ```bash
+ Glob: {{target_dir}}/src/**/*.spec.ts
+ Glob: {{target_dir}}/test/**/*.test.ts
+ ```
+
+
+
+**Create verified gap analysis**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GAP ANALYSIS RESULTS
+βββββββββββββββββββββββββββββββββββββββββββ
+
+β
IMPLEMENTED (Verified):
+{{#each implemented}}
+{{@index}}. **{{name}}**
+ - File: {{file}} β
EXISTS
+ - Status: {{status}}
+ - Tests: {{test_count}} tests
+{{/each}}
+
+β MISSING (Verified):
+{{#each missing}}
+{{@index}}. **{{name}}**
+ - Expected: {{expected_file}} β NOT FOUND
+ - Needed for: {{requirement}}
+{{/each}}
+
+β οΈ PARTIAL (Stub/Incomplete):
+{{#each partial}}
+{{@index}}. **{{name}}**
+ - File: {{file}} β
EXISTS
+ - Issue: {{issue}}
+{{/each}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+**Generate story with verified checkboxes**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GENERATING STORY
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Use story template with:
+- `[x]` for VERIFIED items (evidence: file exists, not stub, has tests)
+- `[~]` for PARTIAL items (evidence: file exists but stub/no tests)
+- `[ ]` for MISSING items (evidence: file not found)
+
+**Write story file:**
+```bash
+Write: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md
+```
+
+**Validate generated story:**
+```bash
+# Check 7 sections exist
+grep "^## " {{story_file}} | wc -l
+# Should be 7
+
+# Check gap analysis section exists
+grep "Gap Analysis" {{story_file}}
+```
+
+
+
+**Update sprint-status.yaml**
+
+```bash
+Read: {{sprint_status}}
+
+# Update story status to "ready-for-dev" if was "backlog"
+# Preserve comments and structure
+
+Write: {{sprint_status}}
+```
+
+
+
+**Report completion**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
STORY REGENERATED WITH GAP ANALYSIS
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{epic_num}}.{{story_num}} - {{title}}
+File: {{story_file}}
+Sections: 7/7 β
+
+Gap Analysis Summary:
+- β
{{implemented_count}} components VERIFIED complete
+- β {{missing_count}} components VERIFIED missing
+- β οΈ {{partial_count}} components PARTIAL (stub/no tests)
+
+Checkboxes reflect VERIFIED codebase state.
+
+Next Steps:
+1. Review story for accuracy
+2. Use /dev-story to implement missing components
+3. Story provides complete context for implementation
+
+[N] Regenerate next story
+[Q] Quit
+[R] Review generated story
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**If [N]:** Loop back to initialize with next story.
+**If [R]:** Display story content, then show menu.
+
+
+
+
+
+```bash
+# Regenerate specific story
+/create-story-with-gap-analysis
+> Which story? 1.9
+
+# With explicit story file
+/create-story-with-gap-analysis story_file=docs/sprint-artifacts/story-1.9.md
+```
+
+
+
+**Story not found:** HALT with clear error.
+**Target directory not found:** Warn, scan available directories.
+**Glob/Read fails:** Log warning, count as MISSING.
+**Write fails:** Report error, display generated content.
+
+
+
+- [ ] Codebase scanned for all story requirements
+- [ ] Gap analysis generated with evidence
+- [ ] Story written with verified checkboxes
+- [ ] 7 sections present
+- [ ] Sprint status updated (if enabled)
+
diff --git a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
index 19217943..d6297e95 100644
--- a/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
+++ b/src/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
@@ -14,10 +14,9 @@ story_dir: "{implementation_artifacts}"
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story-with-gap-analysis"
-template: "{installed_path}/template.md"
-instructions: "{installed_path}/step-01-initialize.md"
+instructions: "{installed_path}/workflow.md"
-# Variables and inputs
+# Variables
variables:
sprint_status: "{implementation_artifacts}/sprint-status.yaml"
epics_file: "{planning_artifacts}/epics.md"
@@ -28,12 +27,6 @@ project_context: "**/project-context.md"
default_output_file: "{story_dir}/{{story_key}}.md"
-# Workflow steps (processed in order)
-steps:
- - step-01-initialize.md
- - step-02-codebase-scan.md
- - step-03-generate-story.md
-
standalone: true
web_bundle: false
diff --git a/src/bmm/workflows/4-implementation/detect-ghost-features/instructions.md b/src/bmm/workflows/4-implementation/detect-ghost-features/instructions.md
deleted file mode 100644
index dc113271..00000000
--- a/src/bmm/workflows/4-implementation/detect-ghost-features/instructions.md
+++ /dev/null
@@ -1,625 +0,0 @@
-# Detect Ghost Features - Reverse Gap Analysis (Who You Gonna Call?)
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-
-
-
-
- Determine scan scope based on parameters:
-
-
- Read {sprint_status}
- Filter stories starting with "{{epic_number}}-"
- Store as: stories_in_scope
-
-
-
-
- Read {sprint_status}
- Get ALL story keys (exclude epics and retrospectives)
- Store as: stories_in_scope
-
-
-
-
- Set stories_in_scope = ALL stories found in {sprint_artifacts}
-
-
-
- For each story in stories_in_scope:
- Read story file
- Extract documented artifacts:
- - File List (all paths mentioned)
- - Tasks (all file/component/service names mentioned)
- - ACs (all features/functionality mentioned)
- Store in: documented_artifacts[story_key] = {files, components, services, apis, features}
-
-
-
-
-
-
-
-
-
- Use Glob to find component files:
- - **/*.component.{tsx,jsx,ts,js,vue} (Angular/Vue pattern)
- - **/components/**/*.{tsx,jsx} (React pattern)
- - **/src/**/*{Component,View,Screen,Page}.{tsx,jsx} (Named pattern)
-
- For each found component file:
- Extract component name from filename or export
- Check file size (ignore <50 lines as trivial)
- Read file to determine if it's a significant feature
-
- Store as: codebase_components = [{name, path, size, purpose}]
-
-
-
-
-
-
-
- Use Glob to find API files:
- - **/api/**/*.{ts,js} (Next.js/Express pattern)
- - **/*.controller.{ts,js} (NestJS pattern)
- - **/routes/**/*.{ts,js} (Generic routes)
-
- Use Grep to find endpoint definitions:
- - @Get|@Post|@Put|@Delete decorators (NestJS)
- - export async function GET|POST|PUT|DELETE (Next.js App Router)
- - router.get|post|put|delete (Express)
- - app.route (Flask/FastAPI if Python)
-
- For each endpoint found:
- Extract: HTTP method, path, handler name
- Read file to understand functionality
-
- Store as: codebase_apis = [{method, path, handler, file}]
-
-
-
-
-
-
-
- Use Glob to find schema files:
- - **/prisma/schema.prisma (Prisma)
- - **/*.entity.{ts,js} (TypeORM)
- - **/models/**/*.{ts,js} (Mongoose/Sequelize)
- - **/*-table.ts (Custom)
-
- Use Grep to find table definitions:
- - model (Prisma)
- - @Entity (TypeORM)
- - createTable (Migrations)
-
- For each table found:
- Extract: table name, columns, relationships
-
- Store as: codebase_tables = [{name, file, columns}]
-
-
-
-
-
-
-
- Use Glob to find service files:
- - **/*.service.{ts,js}
- - **/services/**/*.{ts,js}
- - **/*Service.{ts,js}
-
- For each service found:
- Extract: service name, key methods, dependencies
- Ignore trivial services (<100 lines)
-
- Store as: codebase_services = [{name, file, methods}]
-
-
-
-
-
-
-
-
-
- Initialize: orphaned_features = []
-
-
- For each component in codebase_components:
-
- Search all stories for mentions of:
- - Component name in File Lists
- - Component name in Task descriptions
- - Component file path in File Lists
- - Feature described by component in ACs
-
-
- Add to orphaned_features:
-
- type: "component"
- name: {{component.name}}
- path: {{component.path}}
- size: {{component.size}} lines
- purpose: {{inferred_purpose_from_code}}
- severity: "HIGH" # Significant orphan
-
-
-
-
-
-
-
-
-
-
- For each API in codebase_apis:
-
- Search all stories for mentions of:
- - Endpoint path (e.g., "/api/users")
- - HTTP method + resource (e.g., "POST users")
- - Handler file in File Lists
- - API functionality in ACs (e.g., "Users can create account")
-
-
- Add to orphaned_features:
-
- type: "api"
- method: {{api.method}}
- path: {{api.path}}
- handler: {{api.handler}}
- file: {{api.file}}
- severity: "CRITICAL" # APIs are critical functionality
-
-
-
-
-
-
- For each table in codebase_tables:
-
- Search all stories for mentions of:
- - Table name
- - Migration file in File Lists
- - Data model in Tasks
-
-
- Add to orphaned_features:
-
- type: "database"
- name: {{table.name}}
- file: {{table.file}}
- columns: {{table.columns.length}}
- severity: "HIGH" # Database changes are significant
-
-
-
-
-
-
- For each service in codebase_services:
-
- Search all stories for mentions of:
- - Service name or class name
- - Service file in File Lists
- - Service functionality in Tasks/ACs
-
-
- Add to orphaned_features:
-
- type: "service"
- name: {{service.name}}
- file: {{service.file}}
- methods: {{service.methods.length}}
- severity: "MEDIUM" # Services are business logic
-
-
-
-
-
-
-
-
-
- Group orphans by type and severity:
-
- - critical_orphans (APIs, auth, payment)
- - high_orphans (Components, DB tables, services)
- - medium_orphans (Utilities, helpers)
- - low_orphans (Config files, constants)
-
-
- Estimate complexity for each orphan:
- Based on file size, dependencies, test coverage
-
- Suggest epic assignment based on functionality:
- - Auth components β Epic focusing on authentication
- - UI components β Epic focusing on frontend
- - API endpoints β Epic for that resource type
-
-
-
-
-
-
-
- Jump to Step 7 (Generate Report)
-
-
-
-
- Jump to Step 7
-
-
-
-
- For each orphaned feature (prioritized by severity):
-
-
- Analyze orphan to understand functionality:
- - Read implementation code
- - Identify dependencies and related files
- - Determine what it does (infer from code)
- - Find tests (if any) to understand use cases
-
- Generate story draft:
-
-Story Title: "Document existing {{name}} {{type}}"
-
-Story Description:
-This is a BACKFILL STORY documenting existing functionality found in the codebase
-that was not tracked in any story (likely vibe-coded or manually added).
-
-Business Context:
-{{inferred_business_purpose_from_code}}
-
-Current State:
-β
**Implementation EXISTS:** {{file}}
-- {{description_of_what_it_does}}
-- {{key_features_or_methods}}
-{{#if has_tests}}β
Tests exist: {{test_files}}{{else}}β No tests found{{/if}}
-
-Acceptance Criteria:
-{{#each inferred_acs_from_code}}
-- [ ] {{this}}
-{{/each}}
-
-Tasks:
-- [x] {{name}} implementation (ALREADY EXISTS - {{file}})
-{{#if missing_tests}}- [ ] Add tests for {{name}}{{/if}}
-{{#if missing_docs}}- [ ] Add documentation for {{name}}{{/if}}
-- [ ] Verify functionality works as expected
-- [ ] Add to relevant epic or create new epic for backfills
-
-Definition of Done:
-- [x] Implementation exists and works
-{{#if has_tests}}- [x] Tests exist{{else}}- [ ] Tests added{{/if}}
-- [ ] Documented in story (this story)
-- [ ] Assigned to appropriate epic
-
-Story Type: BACKFILL (documenting existing code)
-
-
-
-
-
-
-
- Create backfill story automatically
-
-
-
-
-
-Create backfill story for {{name}}?
-
-**Type:** {{type}}
-**File:** {{file}}
-**Suggested Epic:** {{suggested_epic}}
-**Complexity:** {{complexity_estimate}}
-
-[Y] Yes - Create this backfill story
-[A] Auto - Create this and all remaining backfill stories
-[E] Edit - Let me adjust the story draft first
-[S] Skip - Don't create story for this orphan
-[H] Halt - Stop backfill story creation
-
-Your choice:
-
-
-
- Create backfill story file: {sprint_artifacts}/backfill-{{type}}-{{name}}.md
- Add to backfill_stories_created list
-
-
-
-
- Set auto_create = true
- Create this story and auto-create remaining
-
-
-
- Provide your adjusted story content or instructions for modifications:
- Apply user's edits to story draft
- Create modified backfill story
-
-
-
- Add to skipped_backfills list
-
-
-
-
- Exit backfill story creation loop
- Jump to Step 6
-
-
-
-
-
- Load {sprint_status} file
-
- For each created backfill story:
- Add entry: {{backfill_story_key}}: backlog # BACKFILL - documents existing {{name}}
-
- Save sprint-status.yaml
-
-
-
-
-
-
-
-
-
- Group backfill stories by suggested epic:
-
- For each suggested_epic:
-
-
-
-
- How should backfill stories be organized?
-
-
- Create epic-backfill.md in epics directory
- Update sprint-status.yaml with epic-backfill entry
- Assign all backfill stories to epic-backfill
-
-
-
- For each backfill story:
- Assign to suggested_epic in sprint-status.yaml
- Update story_key to match epic (e.g., 2-11-backfill-userprofile)
-
-
-
- Leave stories in backlog
-
-
-
-
-
-
- Write report to: {sprint_artifacts}/ghost-features-report-{{timestamp}}.md
-
- Report structure:
-
-# Ghost Features Report (Reverse Gap Analysis)
-
-**Generated:** {{timestamp}}
-**Scope:** {{scan_scope}} {{#if epic_number}}(Epic {{epic_number}}){{/if}}
-
-## Executive Summary
-
-**Codebase Artifacts Scanned:** {{total_artifacts_scanned}}
-**Stories Cross-Referenced:** {{stories_in_scope.length}}
-**Orphaned Features Found:** {{orphaned_features.length}}
-**Documentation Coverage:** {{documented_pct}}%
-**Backfill Stories Created:** {{backfill_stories_created.length}}
-
-## Orphaned Features Detail
-
-### CRITICAL Orphans ({{critical_orphans.length}})
-[Full list with files, purposes, risks]
-
-### HIGH Priority Orphans ({{high_orphans.length}})
-[Full list]
-
-### MEDIUM Priority Orphans ({{medium_orphans.length}})
-[Full list]
-
-## Backfill Stories Created
-
-{{#each backfill_stories_created}}
-- {{story_key}}: {{story_file}}
-{{/each}}
-
-## Recommendations
-
-[Epic assignment suggestions, next steps]
-
-## Appendix: Scan Methodology
-
-[How detection worked, patterns used, confidence levels]
-
-
-
-
-
-
-
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/gap-analysis/instructions.xml b/src/bmm/workflows/4-implementation/gap-analysis/instructions.xml
deleted file mode 100644
index 4af6db50..00000000
--- a/src/bmm/workflows/4-implementation/gap-analysis/instructions.xml
+++ /dev/null
@@ -1,367 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language}
-
-
-
- Use {{story_file}} directly
- Read COMPLETE story file
- Extract story_key from filename or metadata
-
-
-
-
-
-
- Enter story file path, story key (e.g., "1-2-auth"), or status to scan (e.g., "done", "review", "in-progress"):
-
-
- Use provided file path as {{story_file}}
- Read COMPLETE story file
- Extract story_key from filename
-
-
-
-
- Search {story_dir} for file matching pattern {{story_key}}.md
- Set {{story_file}} to found file path
- Read COMPLETE story file
-
-
-
-
-
-
-
- Load the FULL file: {{sprint_status}}
- Parse development_status section
- Find all stories where status equals {{user_input}}
-
-
-
- HALT
-
-
-
-
- Which story would you like to validate? [Enter story key or 'all']:
-
-
- Set {{batch_mode}} = true
- Store list of all story keys to validate
- Set {{story_file}} to first story in list
- Read COMPLETE story file
-
-
-
-
- Set {{story_file}} to selected story path
- Read COMPLETE story file
-
-
-
-
-
- Set {{story_file}} to found story path
- Read COMPLETE story file
-
-
-
-
-
-
- HALT
-
-
-
-
-
-
-
- π CODEBASE REALITY CHECK - Validate tasks against actual code!
-
-
-
-
- Parse story sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status
- Extract all tasks and subtasks from story file
- Identify technical areas mentioned in tasks (files, classes, functions, services, components)
-
-
- Determine scan targets from task descriptions:
- - For "Create X" tasks: Check if X already exists
- - For "Implement Y" tasks: Search for Y functionality
- - For "Add Z" tasks: Verify Z is missing
- - For test tasks: Check for existing test files
-
- Use Glob to find relevant files matching patterns from tasks (e.g., **/*.ts, **/*.tsx, **/*.test.ts)
- Use Grep to search for specific classes, functions, or components mentioned in tasks
- Use Read to verify implementation details and functionality in key discovered files
-
-
- Document scan results:
-
- **CODEBASE REALITY:**
- β
What Exists:
- - List verified files, classes, functions, services found
- - Note implementation completeness (partial vs full)
- - Identify code that tasks claim to create but already exists
-
-
- β What's Missing:
- - List features mentioned in tasks but NOT found in codebase
- - Identify claimed implementations that don't exist
- - Note tasks marked complete but code missing
-
-
-
- For each task in the story, determine:
- - ACCURATE: Task matches reality (code exists if task is checked, missing if unchecked)
- - FALSE POSITIVE: Task checked [x] but code doesn't exist (BS detection!)
- - FALSE NEGATIVE: Task unchecked [ ] but code already exists
- - NEEDS UPDATE: Task description doesn't match current implementation
-
- Generate validation report with:
- - Tasks that are accurate
- - Tasks that are false positives (marked done but not implemented) β οΈ
- - Tasks that are false negatives (not marked but already exist)
- - Recommended task updates
-
-
-
- π SHOW TRUTH - Compare story claims vs codebase reality
-
-
-
-
-
-
-
-
-
-
-
- **What would you like to do?**
-
- Options:
- [U] Update - Apply proposed changes to story file
- [A] Audit Report - Save findings to report file without updating story
- [N] No Changes - Just show me the findings
- [R] Review Details - Show me more details about specific findings
- [C] Continue to Next - Move to next story (batch mode only)
- [Q] Quit - Exit gap analysis
-
-
-
-
- Update story file with proposed changes:
- - Uncheck false positive tasks
- - Check false negative tasks
- - Update task descriptions as needed
- - Add or update "Gap Analysis" section with findings
- - Add Change Log entry: "Gap analysis performed - tasks validated against codebase ({{date}})"
-
-
- Story has false positives. Update status to 'in-progress'? [Y/n]:
-
- Update story Status to 'in-progress'
-
- Update sprint-status.yaml status for this story to 'in-progress'
-
-
-
-
-
-
-
- Continue to next story? [Y/n]:
-
- Load next story from batch list
- Analyze next story
-
-
-
- HALT - Gap analysis complete
-
-
-
-
- Generate audit report file: {{story_dir}}/gap-analysis-report-{{story_key}}-{{date}}.md
- Include full findings, accuracy scores, recommendations
-
-
-
- Continue to next story? [Y/n]:
-
- Load next story from batch list
- Analyze next story
-
-
-
- HALT - Gap analysis complete
-
-
-
-
-
- HALT - Gap analysis complete
-
-
-
-
- Which findings would you like more details about? (specify task numbers, file names, or areas):
- Provide detailed analysis of requested areas using Read tool for deeper code inspection
- After review, re-present the decision options
- Continue based on user's subsequent choice
-
-
-
-
- Load next story from batch list
- Analyze next story
-
-
-
-
- HALT
-
-
-
-
-
- HALT
-
-
-
-
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/gap-analysis/workflow.md b/src/bmm/workflows/4-implementation/gap-analysis/workflow.md
new file mode 100644
index 00000000..c672b0be
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/gap-analysis/workflow.md
@@ -0,0 +1,246 @@
+# Gap Analysis v3.0 - Verify Story Tasks Against Codebase
+
+
+Validate story checkbox claims against actual codebase reality.
+Find false positives (checked but not done) and false negatives (done but unchecked).
+Interactive workflow with options to update, audit, or review.
+
+
+
+**Evidence-Based Verification**
+
+Checkboxes lie. Code doesn't.
+- Search codebase for implementation evidence
+- Check for stubs, TODOs, empty functions
+- Verify tests exist for claimed features
+- Report accuracy of story completion claims
+
+
+
+name: gap-analysis
+version: 3.0.0
+
+defaults:
+ auto_update: false
+ create_audit_report: true
+ strict_mode: false # If true, stubs count as incomplete
+
+output:
+ update_story: "Modify checkbox state to match reality"
+ audit_report: "Generate detailed gap analysis document"
+ no_changes: "Display results only"
+
+
+
+@patterns/verification.md
+@patterns/hospital-grade.md
+
+
+
+
+
+**Load and parse story file**
+
+```bash
+STORY_FILE="{{story_file}}"
+[ -f "$STORY_FILE" ] || { echo "β story_file required"; exit 1; }
+```
+
+Use Read tool on story file. Extract:
+- All `- [ ]` and `- [x]` items
+- File references from Dev Agent Record
+- Task descriptions with expected artifacts
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GAP ANALYSIS: {{story_key}}
+βββββββββββββββββββββββββββββββββββββββββββ
+Tasks: {{total_tasks}}
+Currently checked: {{checked_count}}
+```
+
+
+
+**Verify each task against codebase**
+
+For each task item:
+
+1. **Extract artifacts** - File names, component names, function names
+2. **Search codebase:**
+ ```bash
+ # Check file exists
+ Glob: {{expected_file}}
+
+ # Check function/component exists
+ Grep: "{{function_or_component_name}}"
+ ```
+
+3. **If file exists, check quality:**
+ ```bash
+ # Check for stubs
+ Grep: "TODO|FIXME|Not implemented|throw new Error" {{file}}
+
+ # Check for tests
+ Glob: {{file_base}}.test.* OR {{file_base}}.spec.*
+ ```
+
+4. **Determine status:**
+ - **VERIFIED:** File exists, not a stub, tests exist
+ - **PARTIAL:** File exists but stub/TODO or no tests
+ - **MISSING:** File does not exist
+
+
+
+**Compare claimed vs actual**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GAP ANALYSIS RESULTS
+βββββββββββββββββββββββββββββββββββββββββββ
+Tasks analyzed: {{total}}
+
+By Status:
+- β
Verified Complete: {{verified}} ({{verified_pct}}%)
+- β οΈ Partial: {{partial}} ({{partial_pct}}%)
+- β Missing: {{missing}} ({{missing_pct}}%)
+
+Accuracy Analysis:
+- Checked & Verified: {{correct_checked}}
+- Checked but MISSING: {{false_positives}} β FALSE POSITIVES
+- Unchecked but DONE: {{false_negatives}} β FALSE NEGATIVES
+
+Checkbox Accuracy: {{accuracy}}%
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**If false positives found:**
+```
+β οΈ FALSE POSITIVES DETECTED
+The following tasks are marked done but code is missing:
+
+{{#each false_positives}}
+- [ ] {{task}} β Expected: {{expected_file}} β β NOT FOUND
+{{/each}}
+```
+
+
+
+**Ask user how to proceed**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π OPTIONS
+βββββββββββββββββββββββββββββββββββββββββββ
+[U] Update - Fix checkboxes to match reality
+[A] Audit Report - Generate detailed report file
+[N] No Changes - Display only (already done)
+[R] Review Details - Show full evidence for each task
+
+Your choice:
+```
+
+
+
+**Update story file checkboxes**
+
+For false positives:
+- Change `[x]` to `[ ]` for tasks with missing code
+
+For false negatives:
+- Change `[ ]` to `[x]` for tasks with verified code
+
+Use Edit tool to make changes.
+
+```
+β
Story checkboxes updated
+- {{fp_count}} false positives unchecked
+- {{fn_count}} false negatives checked
+- New completion: {{new_pct}}%
+```
+
+
+
+**Generate audit report**
+
+Write to: `{{story_dir}}/gap-analysis-{{story_key}}-{{timestamp}}.md`
+
+Include:
+- Executive summary
+- Detailed task-by-task evidence
+- False positive/negative lists
+- Recommendations
+
+```
+β
Audit report generated: {{report_path}}
+```
+
+
+
+**Show detailed evidence**
+
+For each task:
+```
+Task: {{task_text}}
+Checkbox: {{checked_state}}
+Evidence:
+ - File: {{file}} - {{exists ? "β
EXISTS" : "β MISSING"}}
+ {{#if exists}}
+ - Stub check: {{is_stub ? "β οΈ STUB DETECTED" : "β
Real implementation"}}
+ - Tests: {{has_tests ? "β
Tests exist" : "β No tests"}}
+ {{/if}}
+Verdict: {{status}}
+```
+
+After review, return to options menu.
+
+
+
+**Display completion**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
GAP ANALYSIS COMPLETE
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{story_key}}
+Verified Completion: {{verified_pct}}%
+Checkbox Accuracy: {{accuracy}}%
+
+{{#if updated}}
+β
Checkboxes updated to match reality
+{{/if}}
+
+{{#if report_generated}}
+π Report: {{report_path}}
+{{/if}}
+
+{{#if false_positives > 0}}
+β οΈ {{false_positives}} tasks need implementation work
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+
+
+```bash
+# Quick gap analysis of single story
+/gap-analysis story_file=docs/sprint-artifacts/2-5-auth.md
+
+# With auto-update enabled
+/gap-analysis story_file=docs/sprint-artifacts/2-5-auth.md auto_update=true
+```
+
+
+
+**Story file not found:** HALT with clear error.
+**Search fails:** Log warning, count as MISSING.
+**Edit fails:** Report error, suggest manual update.
+
+
+
+- [ ] All tasks verified against codebase
+- [ ] False positives/negatives identified
+- [ ] Accuracy metrics calculated
+- [ ] User choice executed (update/audit/review)
+
diff --git a/src/bmm/workflows/4-implementation/gap-analysis/workflow.yaml b/src/bmm/workflows/4-implementation/gap-analysis/workflow.yaml
index 88417f98..07eea0a2 100644
--- a/src/bmm/workflows/4-implementation/gap-analysis/workflow.yaml
+++ b/src/bmm/workflows/4-implementation/gap-analysis/workflow.yaml
@@ -11,7 +11,7 @@ story_dir: "{implementation_artifacts}"
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/gap-analysis"
-instructions: "{installed_path}/instructions.xml"
+instructions: "{installed_path}/workflow.md"
# Variables
story_file: "" # User provides story file path or auto-discover
diff --git a/src/bmm/workflows/4-implementation/migrate-to-github/instructions.md b/src/bmm/workflows/4-implementation/migrate-to-github/instructions.md
deleted file mode 100644
index d3ccab25..00000000
--- a/src/bmm/workflows/4-implementation/migrate-to-github/instructions.md
+++ /dev/null
@@ -1,957 +0,0 @@
-# Migrate to GitHub - Production-Grade Story Migration
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-RELIABILITY FIRST: This workflow prioritizes data integrity over speed
-
-
-
-
- MUST verify all prerequisites before ANY migration operations
-
-
-
-
- Test GitHub MCP connection:
- Call: mcp__github__get_me()
-
-
-
- HALT
-
-
- Extract current user info:
- - username: {{user.login}}
- - user_id: {{user.id}}
-
-
-
-
-
- Verify github_owner and github_repo parameters provided
-
-
-
- HALT
-
-
- Test repository access:
- Call: mcp__github__list_issues({
- owner: {{github_owner}},
- repo: {{github_repo}},
- per_page: 1
- })
-
-
-
- HALT
-
-
-
-
-
-
- Check sprint-status.yaml exists:
- test -f {{sprint_status}}
-
-
-
- HALT
-
-
- Read and parse sprint-status.yaml
- Count total stories to migrate
-
-
-
- Verify story files exist:
- For each story, try multiple naming patterns to find file
-
- Report:
-
-
-
-
-β οΈ {{stories_without_files}} stories have no files
-
-Options:
-[C] Continue (only migrate stories with files)
-[S] Skip these stories (add to skip list)
-[H] Halt (fix missing files first)
-
-Choice:
-
-
-
- HALT
-
-
-
-
-
- Check if state file exists: {{state_file}}
-
-
- Read migration state
- Extract: stories_migrated, issues_created, last_completed, timestamp
-
-
-
- How to proceed?
-
-
- Set resume_mode = true
- Load list of already-migrated stories
- Filter them out from migration queue
-
-
-
-
-
- Confirm fresh start (will check for duplicates)? (yes/no):
-
- HALT
-
-
-
-
- Display migration state details
- Then re-prompt for choice
-
-
-
- Delete state file
- Set resume_mode = false
-
-
-
-
-
-
-
-
-
-
- Skip to Step 2 (Execute mode)
-
-
-
-
- For each story in sprint-status.yaml:
-
- For each story_key:
-
-
- Search GitHub: mcp__github__search_issues({
- query: "repo:{{github_owner}}/{{github_repo}} label:story:{{story_key}}"
- })
-
-
- would_update = {{update_existing}}
-
-
-
-
- would_create = true
- Read local story file
- Parse: title, ACs, tasks, epic, status
-
-
-
-
-
- Count actions:
-
-
- Exit workflow (dry-run complete)
-
-
-
-
- Skip to Step 3 (Verify mode)
-
-
-
-
-
-β οΈ FINAL CONFIRMATION
-
-You are about to create ~{{would_create_count}} GitHub Issues.
-
-This operation:
-- WILL create issues in {{github_owner}}/{{github_repo}}
-- WILL modify your GitHub repository
-- CAN be rolled back (we'll create rollback manifest)
-- CANNOT be undone automatically after issues are created
-
-Have you:
-- [ ] Run dry-run mode to preview?
-- [ ] Verified repository is correct?
-- [ ] Backed up sprint-status.yaml?
-- [ ] Confirmed you want to proceed?
-
-Type "I understand and want to proceed" to continue:
-
-
-
-
- HALT
-
-
- Initialize migration state:
-
-migration_state = {
- started_at: {{timestamp}},
- mode: "execute",
- github_owner: {{github_owner}},
- github_repo: {{github_repo}},
- total_stories: {{total_stories}},
- stories_migrated: [],
- issues_created: [],
- issues_updated: [],
- issues_failed: [],
- rollback_manifest: [],
- last_completed: null
-}
-
-
- Save initial state to {{state_file}}
-
- Initialize rollback manifest (for safety):
- rollback_manifest = {
- created_at: {{timestamp}},
- github_owner: {{github_owner}},
- github_repo: {{github_repo}},
- created_issues: [] # Will track issue numbers for rollback
- }
-
- For each story in sprint-status.yaml:
-
-
-
-
- Read local story file
-
-
-
- Add to migration_state.issues_failed with reason: "File not found"
- Continue to next story
-
-
- Parse story file:
- - Extract all 12 sections
- - Parse Acceptance Criteria (convert to checkboxes)
- - Parse Tasks (convert to checkboxes)
- - Extract metadata: epic_number, complexity
-
- Check if issue already exists (idempotent check):
- Call: mcp__github__search_issues({
- query: "repo:{{github_owner}}/{{github_repo}} label:story:{{story_key}}"
- })
-
-
-
- Add to migration_state.stories_migrated (already done)
- Continue to next story
-
-
-
-
-
- ATOMIC UPDATE with retry:
-
-attempt = 0
-max_attempts = {{max_retries}} + 1
-
-WHILE attempt < max_attempts:
- TRY:
- # Update issue
- result = mcp__github__issue_write({
- method: "update",
- owner: {{github_owner}},
- repo: {{github_repo}},
- issue_number: {{existing_issue.number}},
- title: "Story {{story_key}}: {{parsed_title}}",
- body: {{convertStoryToIssueBody(parsed)}},
- labels: {{generateLabels(story_key, status, parsed)}}
- })
-
- # Verify update succeeded (read back)
- sleep 1 second # GitHub eventual consistency
-
- verification = mcp__github__issue_read({
- method: "get",
- owner: {{github_owner}},
- repo: {{github_repo}},
- issue_number: {{existing_issue.number}}
- })
-
- # Check verification
- IF verification.title != expected_title:
- THROW "Write verification failed"
-
- # Success!
- output: " β
UPDATED and VERIFIED - Issue #{{existing_issue.number}}"
- BREAK
-
- CATCH error:
- attempt++
- IF attempt < max_attempts:
- sleep {{retry_backoff_ms[attempt]}}
- output: " β οΈ Retry {{attempt}}/{{max_retries}} after error: {{error}}"
- ELSE:
- output: " β FAILED after {{max_retries}} retries: {{error}}"
- add to migration_state.issues_failed
-
- IF halt_on_critical_error:
- HALT
- ELSE:
- CONTINUE to next story
-
-
- Add to migration_state.issues_updated
-
-
-
-
-
- Generate issue body from story file:
-
-issue_body = """
-**Story File:** [{{story_key}}.md]({{file_path_in_repo}})
-**Epic:** {{epic_number}}
-**Complexity:** {{complexity}} ({{task_count}} tasks)
-
-## Business Context
-{{parsed.businessContext}}
-
-## Acceptance Criteria
-{{#each parsed.acceptanceCriteria}}
-- [ ] AC{{@index + 1}}: {{this}}
-{{/each}}
-
-## Tasks
-{{#each parsed.tasks}}
-- [ ] {{this}}
-{{/each}}
-
-## Technical Requirements
-{{parsed.technicalRequirements}}
-
-## Definition of Done
-{{#each parsed.definitionOfDone}}
-- [ ] {{this}}
-{{/each}}
-
----
-_Migrated from BMAD local files_
-_Sync timestamp: {{timestamp}}_
-_Local file: `{{story_file_path}}`_
-"""
-
-
- Generate labels:
-
-labels = [
- "type:story",
- "story:{{story_key}}",
- "status:{{current_status}}",
- "epic:{{epic_number}}",
- "complexity:{{complexity}}"
-]
-
-{{#if has_high_risk_keywords}}
-labels.push("risk:high")
-{{/if}}
-
-
- ATOMIC CREATE with retry and verification:
-
-attempt = 0
-
-WHILE attempt < max_attempts:
- TRY:
- # Create issue
- created_issue = mcp__github__issue_write({
- method: "create",
- owner: {{github_owner}},
- repo: {{github_repo}},
- title: "Story {{story_key}}: {{parsed_title}}",
- body: {{issue_body}},
- labels: {{labels}}
- })
-
- issue_number = created_issue.number
-
- # CRITICAL: Verify creation succeeded (read back)
- sleep 2 seconds # GitHub eventual consistency
-
- verification = mcp__github__issue_read({
- method: "get",
- owner: {{github_owner}},
- repo: {{github_repo}},
- issue_number: {{issue_number}}
- })
-
- # Verify all fields
- IF verification.title != expected_title:
- THROW "Title mismatch after create"
-
- IF NOT verification.labels.includes("story:{{story_key}}"):
- THROW "Story label missing after create"
-
- # Success - record for rollback capability
- output: " β
CREATED and VERIFIED - Issue #{{issue_number}}"
-
- rollback_manifest.created_issues.push({
- story_key: {{story_key}},
- issue_number: {{issue_number}},
- created_at: {{timestamp}}
- })
-
- migration_state.issues_created.push({
- story_key: {{story_key}},
- issue_number: {{issue_number}}
- })
-
- BREAK
-
- CATCH error:
- attempt++
-
- # Check if issue was created despite error (orphaned issue)
- check_result = mcp__github__search_issues({
- query: "repo:{{github_owner}}/{{github_repo}} label:story:{{story_key}}"
- })
-
- IF check_result.length > 0:
- # Issue was created, verification failed - treat as success
- output: " β
CREATED (verification had transient error)"
- BREAK
-
- IF attempt < max_attempts:
- sleep {{retry_backoff_ms[attempt]}}
- output: " β οΈ Retry {{attempt}}/{{max_retries}}"
- ELSE:
- output: " β FAILED after {{max_retries}} retries: {{error}}"
-
- migration_state.issues_failed.push({
- story_key: {{story_key}},
- error: {{error}},
- attempts: {{attempt}}
- })
-
- IF halt_on_critical_error:
- output: "HALTING - Critical error during migration"
- save migration_state
- HALT
- ELSE:
- output: "Continuing despite failure (continue_on_failure=true)"
- CONTINUE to next story
-
-
-
- Update migration state:
- migration_state.stories_migrated.push({{story_key}})
- migration_state.last_completed = {{story_key}}
-
-
- Save migration state to {{state_file}}
- Save rollback manifest to {{output_folder}}/migration-rollback-{{timestamp}}.yaml
-
-
-
-
-
-
-
-
-
- Continue to Step 3 (Verify)
-
-
-
-
- Skip to Step 4
-
-
-
-
-Migration complete. Run verification to double-check accuracy? (yes/no):
-
-
-
- Skip to Step 5 (Report)
-
-
-
-
-
- Load migration state from {{state_file}}
-
- For each migrated story in migration_state.stories_migrated:
-
- Fetch issue from GitHub:
- Search: label:story:{{story_key}}
-
-
-
- Add to verification_failures
-
-
-
- Verify fields match expected:
- - Title contains story_key β
- - Label "story:{{story_key}}" exists β
- - Status label matches sprint-status.yaml β
- - AC count matches local file β
-
-
-
-
-
-
-
-
-
- Add to verification_warnings
-
-
-
-
-
-
-
-
- Skip to Step 5 (Report)
-
-
-
-
- Load rollback manifest from {{output_folder}}/migration-rollback-*.yaml
-
-
-
- HALT
-
-
-
-
-
-Type "DELETE ALL ISSUES" to proceed with rollback:
-
-
-
-
- HALT
-
-
- For each issue in manifest.created_issues:
-
- Delete issue (GitHub API doesn't support delete, so close + lock):
-
-# GitHub doesn't allow issue deletion via API
-# Best we can do: close, lock, and add label "migrated:rolled-back"
-
-mcp__github__issue_write({
- method: "update",
- issue_number: {{issue_number}},
- state: "closed",
- labels: ["migrated:rolled-back", "do-not-use"],
- state_reason: "not_planned"
-})
-
-# Add comment explaining
-mcp__github__add_issue_comment({
- issue_number: {{issue_number}},
- body: "Issue closed - migration was rolled back. Do not use."
-})
-
-
-
-
-
-
-
-
- Calculate final statistics:
-
-final_stats = {
- total_stories: {{total_stories}},
- migrated_successfully: {{issues_created.length + issues_updated.length}},
- failed: {{issues_failed.length}},
- success_rate: ({{migrated_successfully}} / {{total_stories}}) * 100,
- duration: {{end_time - start_time}},
- avg_time_per_story: {{duration / total_stories}}
-}
-
-
-
- Write comprehensive report to {{report_path}}
-
- Report structure:
-
-# GitHub Migration Report
-
-**Date:** {{timestamp}}
-**Repository:** {{github_owner}}/{{github_repo}}
-**Mode:** {{mode}}
-
-## Executive Summary
-
-- **Total Stories:** {{total_stories}}
-- **β
Migrated:** {{migrated_successfully}} ({{success_rate}}%)
-- **β Failed:** {{failed}}
-- **Duration:** {{duration}}
-- **Avg per story:** {{avg_time_per_story}}
-
-## Created Issues
-
-{{#each issues_created}}
-- Story {{story_key}} β Issue #{{issue_number}}
- URL:
-{{/each}}
-
-## Updated Issues
-
-{{#each issues_updated}}
-- Story {{story_key}} β Issue #{{issue_number}} (updated)
-{{/each}}
-
-## Failed Migrations
-
-{{#if issues_failed.length > 0}}
-{{#each issues_failed}}
-- Story {{story_key}}: {{error}}
- Attempts: {{attempts}}
-{{/each}}
-
-**Recovery Steps:**
-1. Fix underlying issues (check error messages)
-2. Re-run migration (will skip already-migrated stories)
-{{else}}
-None - all stories migrated successfully!
-{{/if}}
-
-## Rollback Information
-
-**Rollback Manifest:** {{rollback_manifest_path}}
-
-To rollback this migration:
-```bash
-/migrate-to-github mode=rollback
-```
-
-## Next Steps
-
-1. **Verify migration:** /migrate-to-github mode=verify
-2. **Test story checkout:** /checkout-story story_key=2-5-auth
-3. **Enable GitHub sync:** Update workflow.yaml with github_sync_enabled=true
-4. **Product Owner setup:** Share GitHub Issues URL with PO team
-
-## Migration Details
-
-**API Calls Made:** ~{{total_api_calls}}
-**Rate Limit Used:** {{api_calls_used}}/5000
-**Errors Encountered:** {{error_count}}
-**Retries Performed:** {{retry_count}}
-
----
-_Generated by BMAD migrate-to-github workflow_
-
-
-
-
-
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/multi-agent-review/instructions.md b/src/bmm/workflows/4-implementation/multi-agent-review/instructions.md
deleted file mode 100644
index bb51d72c..00000000
--- a/src/bmm/workflows/4-implementation/multi-agent-review/instructions.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# Multi-Agent Code Review
-
-**Purpose:** Perform unbiased code review using multiple specialized AI agents in FRESH CONTEXT, with agent count based on story complexity.
-
-## Overview
-
-**Key Principle: FRESH CONTEXT**
-- Review happens in NEW session (not the agent that wrote the code)
-- Prevents bias from implementation decisions
-- Provides truly independent perspective
-
-**Variable Agent Count by Complexity:**
-- **MICRO** (2 agents): Security + Code Quality - Quick sanity check
-- **STANDARD** (4 agents): + Architecture + Testing - Balanced review
-- **COMPLEX** (6 agents): + Performance + Domain Expert - Comprehensive analysis
-
-**Available Specialized Agents:**
-- **Security Agent**: Identifies vulnerabilities and security risks
-- **Code Quality Agent**: Reviews style, maintainability, and best practices
-- **Architecture Agent**: Reviews system design, patterns, and structure
-- **Testing Agent**: Evaluates test coverage and quality
-- **Performance Agent**: Analyzes efficiency and optimization opportunities
-- **Domain Expert**: Validates business logic and domain constraints
-
-## Workflow
-
-### Step 1: Determine Agent Count
-
-Based on {complexity_level}:
-
-```
-If complexity_level == "micro":
- agent_count = 2
- agents = ["security", "code_quality"]
- Display: π MICRO Review (2 agents: Security + Code Quality)
-
-Else if complexity_level == "standard":
- agent_count = 4
- agents = ["security", "code_quality", "architecture", "testing"]
- Display: π STANDARD Review (4 agents: Multi-perspective)
-
-Else if complexity_level == "complex":
- agent_count = 6
- agents = ["security", "code_quality", "architecture", "testing", "performance", "domain_expert"]
- Display: π¬ COMPLEX Review (6 agents: Comprehensive analysis)
-```
-
-### Step 2: Load Story Context
-
-```bash
-# Read story file
-story_file="{story_file}"
-test -f "$story_file" || (echo "β Story file not found: $story_file" && exit 1)
-```
-
-Read the story file to understand:
-- What was supposed to be implemented
-- Acceptance criteria
-- Tasks and subtasks
-- File list
-
-### Step 3: Invoke Multi-Agent Review Skill (Fresh Context + Smart Agent Selection)
-
-**CRITICAL:** This review MUST happen in a FRESH CONTEXT (new session, different agent).
-
-**Smart Agent Selection:**
-- Skill analyzes changed files and selects MOST RELEVANT agents
-- Touching payments code? β Add financial-security agent
-- Touching auth code? β Add auth-security agent
-- Touching file uploads? β Add file-security agent
-- Touching performance-critical code? β Add performance agent
-- Agent count determined by complexity, but agents chosen by code analysis
-
-```xml
-
- {story_id}
- {base_branch}
- {agent_count}
- smart
- true
-
-```
-
-The skill will:
-1. Create fresh context (unbiased review session)
-2. Analyze changed files in the story
-3. Detect code categories (auth, payments, file handling, etc.)
-4. Select {agent_count} MOST RELEVANT specialized agents
-5. Run parallel reviews from selected agents
-6. Each agent reviews from their expertise perspective
-7. Aggregate findings with severity ratings
-8. Return comprehensive review report
-
-### Step 3: Save Review Report
-
-```bash
-# The skill returns a review report
-# Save it to: {review_report}
-```
-
-Display summary:
-```
-π€ MULTI-AGENT CODE REVIEW COMPLETE
-
-Agents Used: {agent_count}
-- Architecture Agent
-- Security Agent
-- Performance Agent
-- Testing Agent
-- Code Quality Agent
-
-Findings:
-- π΄ CRITICAL: {critical_count}
-- π HIGH: {high_count}
-- π‘ MEDIUM: {medium_count}
-- π΅ LOW: {low_count}
-- βΉοΈ INFO: {info_count}
-
-Report saved to: {review_report}
-```
-
-### Step 4: Present Findings
-
-For each finding, display:
-```
-[{severity}] {title}
-Agent: {agent_name}
-Location: {file}:{line}
-
-{description}
-
-Recommendation:
-{recommendation}
-
----
-```
-
-### Step 5: Next Steps
-
-Suggest actions based on findings:
-```
-π RECOMMENDED NEXT STEPS:
-
-If CRITICAL findings exist:
- β οΈ MUST FIX before proceeding
- - Address all critical security/correctness issues
- - Re-run review after fixes
-
-If only HIGH/MEDIUM findings:
- β
Story may proceed
- - Consider addressing high-priority items
- - Create follow-up tasks for medium items
- - Document LOW items as tech debt
-
-If only LOW/INFO findings:
- β
Code quality looks good
- - Optional: Address style/optimization suggestions
- - Proceed to completion
-```
-
-## Integration with Super-Dev-Pipeline
-
-This workflow is designed to be called from super-dev-pipeline step 7 (code review) when the story complexity is COMPLEX or when user explicitly requests multi-agent review.
-
-**When to Use:**
-- Complex stories (β₯16 tasks or high-risk keywords)
-- Stories involving security-sensitive code
-- Stories with significant architectural changes
-- When single-agent review has been inconclusive
-- User explicitly requests comprehensive review
-
-**When NOT to Use:**
-- Micro stories (β€3 tasks)
-- Standard stories with simple changes
-- Stories that passed adversarial review cleanly
-
-## Output Files
-
-- `{review_report}`: Full review findings in markdown
-- Integrated into story completion summary
-- Referenced in audit trail
-
-## Error Handling
-
-If multi-agent-review skill fails:
-- Fall back to adversarial code review
-- Log the failure reason
-- Continue pipeline with warning
diff --git a/src/bmm/workflows/4-implementation/push-all/instructions.xml b/src/bmm/workflows/4-implementation/push-all/instructions.xml
deleted file mode 100644
index 9e5b715d..00000000
--- a/src/bmm/workflows/4-implementation/push-all/instructions.xml
+++ /dev/null
@@ -1,549 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language}
- π PUSH-ALL - Stage, commit, and push changes with comprehensive safety validation
-
-
- β‘ PARALLEL AGENT MODE: When {{target_files}} is provided:
- - ONLY stage and commit the specified files
- - Do NOT use `git add .` or `git add -A`
- - Use `git add [specific files]` instead
- - This prevents committing work from other parallel agents
-
- π ALL FILES MODE: When {{target_files}} is empty:
- - Stage ALL changes with `git add .`
- - Original behavior for single-agent execution
-
-
-
-
-
-
- Run git commands in parallel:
- - git status - Show modified/added/deleted/untracked files
- - git diff --stat - Show change statistics
- - git log -1 --oneline - Show recent commit for message style
- - git branch --show-current - Confirm current branch
-
- Parse git status output to identify:
- - Modified files
- - Added files
- - Deleted files
- - Untracked files
- - Total insertion/deletion counts
-
-
-
-
- HALT - No work to do
-
-
-
-
- π SAFETY CHECKS - Validate changes before committing
-
- Scan all changed files for dangerous patterns:
-
- **Secret Detection:**
- Check for files matching secret patterns:
- - .env*, *.key, *.pem, credentials.json, secrets.yaml
- - id_rsa, *.p12, *.pfx, *.cer
- - Any file containing: _API_KEY=, _SECRET=, _TOKEN= with real values (not placeholders)
-
-
- Validate API keys are placeholders only:
- β
Acceptable placeholders:
- - API_KEY=your-api-key-here
- - SECRET=placeholder
- - TOKEN=xxx
- - API_KEY=${{YOUR_KEY}}
- - SECRET_KEY=<your-key>
-
-
- β BLOCK real keys:
- - OPENAI_API_KEY=sk-proj-xxxxx (real OpenAI key)
- - AWS_SECRET_KEY=AKIA... (real AWS key)
- - STRIPE_API_KEY=sk_live_... (real Stripe key)
- - Any key with recognizable provider prefix + actual value
-
-
- **File Size Check:**
- Check for files >10MB without Git LFS configuration
-
- **Build Artifacts:**
- Check for unwanted directories/files that should be gitignored:
- - node_modules/, dist/, build/, .next/, __pycache__/, *.pyc, .venv/
- - .DS_Store, Thumbs.db, *.swp, *.tmp, *.log (in root)
- - *.class, target/, bin/ (Java)
- - vendor/ (unless dependency managed)
-
-
- **Git State:**
- Verify:
- - .gitignore exists and properly configured
- - No unresolved merge conflicts
- - Git repository initialized
-
-
-
-
-
- HALT - Cannot proceed with secrets
-
-
-
-
-
- Proceed with large files anyway? [y/n]:
-
-
-
- HALT
-
-
-
-
-
-
- Commit build artifacts anyway? [y/n]:
-
-
-
- HALT
-
-
-
-
-
-
- Push directly to {{branch_name}}? [y/n]:
-
-
-
- HALT
-
-
-
-
-
-
-
-
-
- **Proceed with commit and push?**
-
- Options:
- [yes] - Proceed with commit and push
- [no] - Cancel (leave changes unstaged)
- [review] - Show detailed diff first
-
-
-
- Execute: git diff --stat
- Execute: git diff | head -100 (show first 100 lines of changes)
-
- After reviewing, proceed with commit and push? [yes/no]:
-
-
-
-
- HALT - User cancelled
-
-
-
-
-
-
-
- Execute: git add {{target_files}}
- Execute: git status
-
-
-
-
-
- Execute: git add .
- Execute: git status
-
-
-
-
-
- π COMMIT MESSAGE - Generate conventional commit format
-
- Analyze changes to determine commit type:
- - feat: New features (new files with functionality)
- - fix: Bug fixes (fixing broken functionality)
- - docs: Documentation only (*.md, comments)
- - style: Formatting, missing semicolons (no code change)
- - refactor: Code restructuring (no feature/fix)
- - test: Adding/updating tests
- - chore: Tooling, configs, dependencies
- - perf: Performance improvements
-
- Determine scope (optional):
- - Component/feature name if changes focused on one area
- - Omit if changes span multiple areas
-
-
- Generate message summary (max 72 chars):
- - Use imperative mood: "add feature" not "added feature"
- - Lowercase except proper nouns
- - No period at end
-
-
- Generate message body (if changes >5 files):
- - List key changes as bullet points
- - Max 3-5 bullets
- - Keep concise
-
-
- Reference recent commits for style consistency
-
-
-
- **Use this commit message?**
-
- Options:
- [yes] - Use generated message
- [edit] - Let me write custom message
- [cancel] - Cancel push-all (leave staged)
-
-
-
- Enter your commit message (use conventional commit format if possible):
- Store user input as {{commit_message}}
-
-
-
-
-
- HALT
-
-
-
- Use {{generated_commit_message}} as {{commit_message}}
-
-
-
-
- Execute git commit with heredoc for multi-line message safety:
- git commit -m "$(cat <<'EOF'
-{{commit_message}}
-EOF
-)"
-
-
-
-
- HALT - Fix errors before proceeding
-
-
- Parse commit output for hash
-
-
-
-
-
-
- Execute: git push
-
-
-
-
-
- Execute: git pull --rebase
-
-
-
- HALT - Resolve conflicts manually
-
-
- Execute: git push
-
-
-
-
-
- Execute: git push -u origin {{current_branch}}
-
-
-
-
- HALT - Use PR workflow for protected branches
-
-
-
-
- HALT - Fix authentication
-
-
-
-
- HALT - Manual push required
-
-
-
-
-
-
- Execute: git log -1 --oneline --decorate
-
-
-
-
-
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/push-all/workflow.md b/src/bmm/workflows/4-implementation/push-all/workflow.md
new file mode 100644
index 00000000..44637b79
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/push-all/workflow.md
@@ -0,0 +1,366 @@
+# Push All v3.0 - Safe Git Staging, Commit, and Push
+
+
+Safely stage, commit, and push changes with comprehensive validation.
+Detects secrets, large files, build artifacts. Handles push failures gracefully.
+Supports targeted mode for specific files (parallel agent coordination).
+
+
+
+**Safe by Default, No Surprises**
+
+- Validate BEFORE committing (secrets, size, artifacts)
+- Show exactly what will be committed
+- Handle push failures with recovery options
+- Never force push without explicit confirmation
+
+
+
+name: push-all
+version: 3.0.0
+
+modes:
+ full: "Stage all changes (default)"
+ targeted: "Only stage specified files"
+
+defaults:
+ max_file_size_kb: 500
+ check_secrets: true
+ check_build_artifacts: true
+ auto_push: false
+ allow_force_push: false
+
+secret_patterns:
+ - "AKIA[0-9A-Z]{16}" # AWS Access Key
+ - "sk-[a-zA-Z0-9]{48}" # OpenAI Key
+ - "ghp_[a-zA-Z0-9]{36}" # GitHub Personal Token
+ - "xox[baprs]-[a-zA-Z0-9-]+" # Slack Token
+ - "-----BEGIN.*PRIVATE KEY" # Private Keys
+ - "password\\s*=\\s*['\"][^'\"]{8,}" # Hardcoded passwords
+
+build_artifacts:
+ - "node_modules/"
+ - "dist/"
+ - "build/"
+ - ".next/"
+ - "*.min.js"
+ - "*.bundle.js"
+
+
+
+@patterns/hospital-grade.md
+
+
+
+
+
+**Verify git repository state**
+
+```bash
+# Check we're in a git repo
+git rev-parse --is-inside-work-tree || { echo "β Not a git repository"; exit 1; }
+
+# Get current branch
+git branch --show-current
+
+# Check for uncommitted changes
+git status --porcelain
+```
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π¦ PUSH-ALL: {{mode}} mode
+βββββββββββββββββββββββββββββββββββββββββββ
+Branch: {{branch}}
+Mode: {{mode}}
+{{#if targeted}}Files: {{file_list}}{{/if}}
+```
+
+**If no changes:**
+```
+β
Working directory clean - nothing to commit
+```
+Exit successfully.
+
+
+
+**Identify files to be staged**
+
+**Full mode:**
+```bash
+git status --porcelain | awk '{print $2}'
+```
+
+**Targeted mode:**
+Only include files specified in `target_files` parameter.
+
+**Categorize changes:**
+- New files (A)
+- Modified files (M)
+- Deleted files (D)
+- Renamed files (R)
+
+
+
+**Scan for secrets in staged content**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π SECRET SCAN
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+For each file to be staged:
+```bash
+# Check for secret patterns
+Grep: "{{pattern}}" {{file}}
+```
+
+**If secrets found:**
+```
+β POTENTIAL SECRETS DETECTED
+
+{{#each secrets}}
+File: {{file}}
+Line {{line}}: {{preview}} (pattern: {{pattern_name}})
+{{/each}}
+
+β οΈ BLOCKING COMMIT
+Remove secrets before proceeding.
+
+Options:
+[I] Ignore (I know what I'm doing)
+[E] Exclude these files
+[H] Halt
+```
+
+**If [I] selected:** Require explicit confirmation text.
+
+
+
+**Check for oversized files**
+
+```bash
+# Find files larger than max_file_size_kb
+find . -type f -size +{{max_file_size}}k -not -path "./.git/*"
+```
+
+**If large files found:**
+```
+β οΈ LARGE FILES DETECTED
+
+{{#each large_files}}
+- {{file}} ({{size_kb}}KB)
+{{/each}}
+
+Options:
+[I] Include anyway
+[E] Exclude large files
+[H] Halt
+```
+
+
+
+**Check for build artifacts**
+
+```bash
+# Check if any staged files match artifact patterns
+git status --porcelain | grep -E "{{artifact_pattern}}"
+```
+
+**If artifacts found:**
+```
+β οΈ BUILD ARTIFACTS DETECTED
+
+{{#each artifacts}}
+- {{file}}
+{{/each}}
+
+These should typically be in .gitignore.
+
+Options:
+[E] Exclude artifacts (recommended)
+[I] Include anyway
+[H] Halt
+```
+
+
+
+**Show what will be committed**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π COMMIT PREVIEW
+βββββββββββββββββββββββββββββββββββββββββββ
+Files to commit: {{count}}
+
+Added ({{added_count}}):
+{{#each added}}
+ + {{file}}
+{{/each}}
+
+Modified ({{modified_count}}):
+{{#each modified}}
+ M {{file}}
+{{/each}}
+
+Deleted ({{deleted_count}}):
+{{#each deleted}}
+ - {{file}}
+{{/each}}
+
+{{#if excluded}}
+Excluded: {{excluded_count}} files
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+**Generate or request commit message**
+
+**If commit_message provided:** Use it.
+
+**Otherwise, generate from changes:**
+```
+Analyzing changes to generate commit message...
+
+Changes detected:
+- {{summary_of_changes}}
+
+Suggested message:
+"{{generated_message}}"
+
+[Y] Use this message
+[E] Edit message
+[C] Custom message
+```
+
+If user selects [C] or [E], prompt for message.
+
+
+
+**Stage and commit changes**
+
+```bash
+# Stage files (targeted or full)
+{{#if targeted}}
+git add {{#each target_files}}{{this}} {{/each}}
+{{else}}
+git add -A
+{{/if}}
+
+# Commit with message
+git commit -m "{{commit_message}}"
+```
+
+**Verify commit:**
+```bash
+# Check commit was created
+git log -1 --oneline
+```
+
+```
+β
Commit created: {{commit_hash}}
+```
+
+
+
+**Push to remote with error handling**
+
+```bash
+git push origin {{branch}}
+```
+
+**If push fails:**
+
+**Case: Behind remote**
+```
+β οΈ Push rejected - branch is behind remote
+
+Options:
+[P] Pull and retry (git pull --rebase)
+[F] Force push (DESTRUCTIVE - overwrites remote)
+[H] Halt (commit preserved locally)
+```
+
+**Case: No upstream**
+```
+β οΈ No upstream branch
+
+Setting upstream and pushing:
+git push -u origin {{branch}}
+```
+
+**Case: Auth failure**
+```
+β Authentication failed
+
+Check:
+1. SSH key configured?
+2. Token valid?
+3. Repository access?
+```
+
+**Case: Protected branch**
+```
+β Cannot push to protected branch
+
+Use pull request workflow instead:
+gh pr create --title "{{commit_message}}"
+```
+
+
+
+**Display completion status**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
PUSH-ALL COMPLETE
+βββββββββββββββββββββββββββββββββββββββββββ
+Branch: {{branch}}
+Commit: {{commit_hash}}
+Files: {{file_count}}
+{{#if pushed}}
+Remote: β
Pushed to origin/{{branch}}
+{{else}}
+Remote: βΈοΈ Not pushed (commit preserved locally)
+{{/if}}
+
+{{#if excluded_count > 0}}
+Excluded: {{excluded_count}} files (secrets/artifacts/size)
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+
+
+```bash
+# Stage all, commit, and push
+/push-all commit_message="feat: add user authentication" auto_push=true
+
+# Targeted mode - only specific files
+/push-all mode=targeted target_files="src/auth.ts,src/auth.test.ts" commit_message="fix: auth bug"
+
+# Dry run - see what would be committed
+/push-all auto_push=false
+```
+
+
+
+**Secrets detected:** BLOCK commit, require explicit override.
+**Large files:** Warn, allow exclude or include.
+**Build artifacts:** Warn, recommend exclude.
+**Push rejected:** Offer pull/rebase, force push (with confirmation), or halt.
+**Auth failure:** Report, suggest troubleshooting.
+
+
+
+- [ ] Changes validated (secrets, size, artifacts)
+- [ ] Files staged correctly
+- [ ] Commit created with message
+- [ ] Push successful (if requested)
+- [ ] No unintended files included
+
diff --git a/src/bmm/workflows/4-implementation/push-all/workflow.yaml b/src/bmm/workflows/4-implementation/push-all/workflow.yaml
index 1eedfe30..5875d911 100644
--- a/src/bmm/workflows/4-implementation/push-all/workflow.yaml
+++ b/src/bmm/workflows/4-implementation/push-all/workflow.yaml
@@ -9,7 +9,7 @@ communication_language: "{config_source}:communication_language"
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/push-all"
-instructions: "{installed_path}/instructions.xml"
+instructions: "{installed_path}/workflow.md"
# Target files to commit (for parallel agent execution)
# When empty/not provided: commits ALL changes (original behavior)
diff --git a/src/bmm/workflows/4-implementation/recover-sprint-status/instructions.md b/src/bmm/workflows/4-implementation/recover-sprint-status/instructions.md
deleted file mode 100644
index 7ec69cd7..00000000
--- a/src/bmm/workflows/4-implementation/recover-sprint-status/instructions.md
+++ /dev/null
@@ -1,306 +0,0 @@
-# Sprint Status Recovery - Instructions
-
-**Workflow:** recover-sprint-status
-**Purpose:** Fix sprint-status.yaml when tracking has drifted for days/weeks
-
----
-
-## What This Workflow Does
-
-Analyzes multiple sources to rebuild accurate sprint-status.yaml:
-
-1. **Story File Quality** - Validates size (>=10KB), task lists, checkboxes
-2. **Explicit Status: Fields** - Reads story Status: when present
-3. **Git Commits** - Searches last 30 days for story references
-4. **Autonomous Reports** - Checks .epic-*-completion-report.md files
-5. **Task Completion Rate** - Analyzes checkbox completion in story files
-
-**Infers Status Based On:**
-- Explicit Status: field (highest priority)
-- Git commits referencing story (strong signal)
-- Autonomous completion reports (very high confidence)
-- Task checkbox completion rate (90%+ = done)
-- File quality (poor quality prevents "done" marking)
-
----
-
-## Step 1: Run Recovery Analysis
-
-```bash
-Execute: {recovery_script} --dry-run
-```
-
-**This will:**
-- Analyze all story files (quality, tasks, status)
-- Search git commits for completion evidence
-- Check autonomous completion reports
-- Infer status from all evidence
-- Report recommendations with confidence levels
-
-**No changes** made in dry-run mode - just analysis.
-
----
-
-## Step 2: Review Recommendations
-
-**Check the output for:**
-
-### High Confidence Updates (Safe)
-- Stories with explicit Status: fields
-- Stories in autonomous completion reports
-- Stories with 3+ git commits + 90%+ tasks complete
-
-### Medium Confidence Updates (Verify)
-- Stories with 1-2 git commits
-- Stories with 50-90% tasks complete
-- Stories with file size >=10KB
-
-### Low Confidence Updates (Question)
-- Stories with no Status: field, no commits
-- Stories with file size <10KB
-- Stories with <5 tasks total
-
----
-
-## Step 3: Choose Recovery Mode
-
-### Conservative Mode (Safest)
-```bash
-Execute: {recovery_script} --conservative
-```
-
-**Only updates:**
-- High/very high confidence stories
-- Explicit Status: fields honored
-- Git commits with 3+ references
-- Won't infer or guess
-
-**Best for:** Quick fixes, first-time recovery, risk-averse
-
----
-
-### Aggressive Mode (Thorough)
-```bash
-Execute: {recovery_script} --aggressive --dry-run # Preview first!
-Execute: {recovery_script} --aggressive # Then apply
-```
-
-**Updates:**
-- Medium+ confidence stories
-- Infers from git commits (even 1 commit)
-- Uses task completion rate
-- Pre-fills brownfield checkboxes
-
-**Best for:** Major drift (30+ days), comprehensive recovery
-
----
-
-### Interactive Mode (Recommended)
-```bash
-Execute: {recovery_script}
-```
-
-**Process:**
-1. Shows all recommendations
-2. Groups by confidence level
-3. Asks for confirmation before each batch
-4. Allows selective application
-
-**Best for:** First-time use, learning the tool
-
----
-
-## Step 4: Validate Results
-
-```bash
-Execute: ./scripts/sync-sprint-status.sh --validate
-```
-
-**Should show:**
-- "β sprint-status.yaml is up to date!" (success)
-- OR discrepancy count (if issues remain)
-
----
-
-## Step 5: Commit Changes
-
-```bash
-git add docs/sprint-artifacts/sprint-status.yaml
-git add .sprint-status-backups/ # Include backup for audit trail
-git commit -m "fix(tracking): Recover sprint-status.yaml - {MODE} recovery"
-```
-
----
-
-## Recovery Scenarios
-
-### Scenario 1: Autonomous Epic Completed, Tracking Not Updated
-
-**Symptoms:**
-- Autonomous completion report exists
-- Git commits show work done
-- sprint-status.yaml shows "in-progress" or "backlog"
-
-**Solution:**
-```bash
-{recovery_script} --aggressive
-# Will find completion report, mark all stories done
-```
-
----
-
-### Scenario 2: Manual Work Over Past Week Not Tracked
-
-**Symptoms:**
-- Story Status: fields updated to "done"
-- sprint-status.yaml not synced
-- Git commits exist
-
-**Solution:**
-```bash
-./scripts/sync-sprint-status.sh
-# Standard sync (reads Status: fields)
-```
-
----
-
-### Scenario 3: Story Files Missing Status: Fields
-
-**Symptoms:**
-- 100+ stories with no Status: field
-- Some completed, some not
-- No autonomous reports
-
-**Solution:**
-```bash
-{recovery_script} --aggressive --dry-run # Preview inference
-# Review recommendations carefully
-{recovery_script} --aggressive # Apply if satisfied
-```
-
----
-
-### Scenario 4: Complete Chaos (Mix of All Above)
-
-**Symptoms:**
-- Some stories have Status:, some don't
-- Autonomous reports for some epics
-- Manual work on others
-- sprint-status.yaml very outdated
-
-**Solution:**
-```bash
-# Step 1: Run recovery in dry-run
-{recovery_script} --aggressive --dry-run
-
-# Step 2: Review /tmp/recovery_results.json
-
-# Step 3: Apply in conservative mode first (safest updates)
-{recovery_script} --conservative
-
-# Step 4: Manually review remaining stories
-# Update Status: fields for known completed work
-
-# Step 5: Run sync to catch manual updates
-./scripts/sync-sprint-status.sh
-
-# Step 6: Final validation
-./scripts/sync-sprint-status.sh --validate
-```
-
----
-
-## Quality Gates
-
-**Recovery script will DOWNGRADE status if:**
-- Story file < 10KB (not properly detailed)
-- Story file has < 5 tasks (incomplete story)
-- No git commits found (no evidence of work)
-- Explicit Status: contradicts other evidence
-
-**Recovery script will UPGRADE status if:**
-- Autonomous completion report lists story as done
-- 3+ git commits + 90%+ tasks checked
-- Explicit Status: field says "done"
-
----
-
-## Post-Recovery Checklist
-
-After running recovery:
-
-- [ ] Run validation: `./scripts/sync-sprint-status.sh --validate`
-- [ ] Review backup: Check `.sprint-status-backups/` for before state
-- [ ] Check epic statuses: Verify epic-level status matches story completion
-- [ ] Spot-check 5-10 stories: Confirm inferred status is accurate
-- [ ] Commit changes: Add recovery to version control
-- [ ] Document issues: Note why drift occurred, prevent recurrence
-
----
-
-## Preventing Future Drift
-
-**After recovery:**
-
-1. **Use workflows properly**
- - `/create-story` - Adds to sprint-status.yaml automatically
- - `/dev-story` - Updates both Status: and sprint-status.yaml
- - Autonomous workflows - Now update tracking
-
-2. **Run sync regularly**
- - Weekly: `pnpm sync:sprint-status:dry-run` (check health)
- - After manual Status: updates: `pnpm sync:sprint-status`
-
-3. **CI/CD validation** (coming soon)
- - Blocks PRs with out-of-sync tracking
- - Forces sync before merge
-
----
-
-## Troubleshooting
-
-### "Recovery script shows 0 updates"
-
-**Possible causes:**
-- sprint-status.yaml already accurate
-- Story files all have proper Status: fields
-- No git commits found (check date range)
-
-**Action:** Run `--dry-run` to see analysis, check `/tmp/recovery_results.json`
-
----
-
-### "Low confidence on stories I know are done"
-
-**Possible causes:**
-- Story file < 10KB (not properly detailed)
-- No git commits (work done outside git)
-- No explicit Status: field
-
-**Action:** Manually add Status: field to story, then run standard sync
-
----
-
-### "Recovery marks incomplete stories as done"
-
-**Possible causes:**
-- Git commits exist but work abandoned
-- Autonomous report lists story but implementation failed
-- Tasks pre-checked incorrectly (brownfield error)
-
-**Action:** Use conservative mode, manually verify, fix story files
-
----
-
-## Output Files
-
-**Created during recovery:**
-- `.sprint-status-backups/sprint-status-recovery-{timestamp}.yaml` - Backup
-- `/tmp/recovery_results.json` - Detailed analysis
-- Updated `sprint-status.yaml` - Recovered status
-
----
-
-**Last Updated:** 2026-01-02
-**Status:** Production Ready
-**Works On:** ANY BMAD project with sprint-status.yaml tracking
diff --git a/src/bmm/workflows/4-implementation/revalidate-epic/instructions.md b/src/bmm/workflows/4-implementation/revalidate-epic/instructions.md
deleted file mode 100644
index e229e944..00000000
--- a/src/bmm/workflows/4-implementation/revalidate-epic/instructions.md
+++ /dev/null
@@ -1,273 +0,0 @@
-# Revalidate Epic - Batch Story Revalidation with Semaphore Pattern
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-
-
-
-
- Verify epic_number parameter provided
-
-
-
- HALT
-
-
- Read {sprint_status} file
- Parse development_status map
-
- Filter stories starting with "{{epic_number}}-" (e.g., "2-1-", "2-2-", etc.)
- Exclude epics (keys starting with "epic-") and retrospectives
-
- Store as: epic_stories (list of story keys)
-
-
-
- HALT
-
-
-
-
- Proceed with revalidation? (yes/no):
-
-
-
- Exit workflow
-
-
-
-
-
-
- Initialize worker pool state:
-
- - story_queue = epic_stories
- - active_workers = {}
- - completed_stories = []
- - failed_stories = []
- - verification_results = {}
- - next_story_index = 0
- - max_workers = {{max_concurrent}}
-
-
- Fill initial worker slots:
-
- While next_story_index < min(max_workers, story_queue.length):
-
-
- story_key = story_queue[next_story_index]
- story_file = {sprint_artifacts}/{{story_key}}.md # Try multiple naming patterns if needed
- worker_id = next_story_index + 1
-
- Spawn Task agent:
- - subagent_type: "general-purpose"
- - description: "Revalidate story {{story_key}}"
- - prompt: "Execute revalidate-story workflow for {{story_key}}.
-
- CRITICAL INSTRUCTIONS:
- 1. Load workflow: _bmad/bmm/workflows/4-implementation/revalidate-story/workflow.yaml
- 2. Parameters: story_file={{story_file}}, fill_gaps={{fill_gaps}}
- 3. Clear all checkboxes
- 4. Verify each AC/Task/DoD against codebase
- 5. Re-check verified items
- 6. Report gaps
- {{#if fill_gaps}}7. Fill gaps and commit{{/if}}
- 8. Return verification summary"
- - run_in_background: true
-
- Store in active_workers[worker_id]:
- story_key: {{story_key}}
- task_id: {{returned_task_id}}
- started_at: {{timestamp}}
-
-
- Increment next_story_index
-
-
-
-
-
- SEMAPHORE PATTERN: Keep {{max_workers}} agents running continuously
-
- While active_workers.size > 0 OR next_story_index < story_queue.length:
-
- Poll for completed workers (non-blocking):
-
- For each worker_id in active_workers:
-
- Check worker status using TaskOutput(task_id, block=false)
-
-
- Get verification results from worker output
- Parse: verified_pct, gaps_found, gaps_filled
-
- Store in verification_results[story_key]
- Add to completed_stories
- Remove from active_workers
-
-
-
-
- Refill slot with next story (same pattern as batch-super-dev)
-
-
-
-
-
- Add to failed_stories with error
- Remove from active_workers
-
-
-
- Refill slot despite failure
-
-
-
- Display live progress every 30 seconds:
-
-
- Sleep 5 seconds before next poll
-
-
-
- Aggregate verification results across all stories:
-
- epic_total_items = sum of all items across stories
- epic_verified = sum of verified items
- epic_partial = sum of partial items
- epic_missing = sum of missing items
- epic_gaps_filled = sum of gaps filled
-
- epic_verified_pct = (epic_verified / epic_total_items) Γ 100
-
-
- Group stories by verification percentage:
-
- - complete_stories (β₯95% verified)
- - mostly_complete_stories (80-94% verified)
- - partial_stories (50-79% verified)
- - incomplete_stories (<50% verified)
-
-
-
-
-
- Write epic summary to: {sprint_artifacts}/revalidation-epic-{{epic_number}}-{{timestamp}}.md
-
-
-
-
- Update sprint-status.yaml with revalidation timestamp and results
- Add comment to epic entry: # Revalidated: {{epic_verified_pct}}% verified ({{timestamp}})
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/revalidate-story/instructions.md b/src/bmm/workflows/4-implementation/revalidate-story/instructions.md
deleted file mode 100644
index f5135606..00000000
--- a/src/bmm/workflows/4-implementation/revalidate-story/instructions.md
+++ /dev/null
@@ -1,510 +0,0 @@
-# Revalidate Story - Verify Checkboxes Against Codebase Reality
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-
-
-
-
- Verify story_file parameter provided
-
-
-
- HALT
-
-
- Read COMPLETE story file: {{story_file}}
- Parse sections: Acceptance Criteria, Tasks/Subtasks, Definition of Done, Dev Agent Record
-
- Extract story_key from filename (e.g., "2-7-image-file-handling")
-
- Create backup of current checkbox state:
- Count currently checked items:
- - ac_checked_before = count of [x] in Acceptance Criteria
- - tasks_checked_before = count of [x] in Tasks/Subtasks
- - dod_checked_before = count of [x] in Definition of Done
- - total_checked_before = sum of above
-
-
-
-
-
-
-
-
- Use Edit tool to replace all [x] with [ ] in Acceptance Criteria section
- Use Edit tool to replace all [x] with [ ] in Tasks/Subtasks section
- Use Edit tool to replace all [x] with [ ] in Definition of Done section
-
- Save story file with all boxes unchecked
-
-
-
-
-
-
-
- Extract all AC items from Acceptance Criteria section
-
- For each AC item:
-
-
- Extract AC description and identify artifacts:
- - File mentions (e.g., "UserProfile component")
- - Function names (e.g., "updateUser function")
- - Features (e.g., "dark mode toggle")
- - Test requirements (e.g., "unit tests covering edge cases")
-
-
-
-
-
-
- Use Glob to find relevant files:
- - If AC mentions specific file: glob for that file
- - If AC mentions component: glob for **/*ComponentName*
- - If AC mentions feature: glob for files in related directories
-
-
- Use Grep to search for symbols/functions/features
-
- Read found files to verify:
- - NOT a stub (check for "TODO", "Not implemented", "throw new Error")
- - Has actual implementation (not just empty function)
- - Tests exist (search for *.test.* or *.spec.* files)
- - Tests pass (if --fill-gaps mode, run tests)
-
-
-
-
- verification_status = VERIFIED
- Check box [x] in story file for this AC
- Record evidence: "β
VERIFIED: {{files_found}}, tests: {{test_files}}"
-
-
-
-
- verification_status = PARTIAL
- Check box [~] in story file for this AC
- Record gap: "πΆ PARTIAL: {{what_exists}}, missing: {{what_is_missing}}"
-
- Add to gaps_list with details
-
-
-
- verification_status = MISSING
- Leave box unchecked [ ] in story file
- Record gap: "β MISSING: No implementation found for {{ac_description}}"
-
- Add to gaps_list with details
-
-
-
- Save story file after each AC verification
-
-
-
-
-
-
-
- Extract all Task items from Tasks/Subtasks section
-
- For each Task item (same verification logic as ACs):
-
- Parse task description for artifacts
- Search codebase with Glob/Grep
- Read and verify (check for stubs, tests)
- Determine status: VERIFIED | PARTIAL | MISSING
- Update checkbox: [x] | [~] | [ ]
- Record evidence or gap
- Save story file
-
-
-
-
-
-
-
- Extract all DoD items from Definition of Done section
-
- For each DoD item:
-
- Parse DoD requirement:
- - "Type check passes" β Run type checker
- - "Unit tests 90%+ coverage" β Run coverage report
- - "Linting clean" β Run linter
- - "Build succeeds" β Run build
- - "All tests pass" β Run test suite
-
-
- Execute verification for this DoD item
-
-
- Check box [x]
- Record: "β
VERIFIED: {{verification_result}}"
-
-
-
- Leave unchecked [ ] or partial [~]
- Record gap if applicable
-
-
-
-
-
-
- Calculate overall completion:
-
- total_verified = ac_verified + tasks_verified + dod_verified
- total_partial = ac_partial + tasks_partial + dod_partial
- total_missing = ac_missing + tasks_missing + dod_missing
- total_items = ac_total + tasks_total + dod_total
-
- verified_pct = (total_verified / total_items) Γ 100
- completion_pct = ((total_verified + total_partial) / total_items) Γ 100
-
-
-
-
-
- Write detailed report to: {sprint_artifacts}/revalidation-{{story_key}}-{{timestamp}}.md
- Include: verification results, gaps list, evidence for each item, recommendations
-
-
-
-
-
-
-
- Exit workflow
-
-
-
-
- Exit workflow
-
-
-
-
-
- HALT
-
-
-
-
- Continue to Step 8
-
-
-
-
- For each gap in gaps_list:
-
-
-
-
-Fill this gap?
-
-**Item:** {{item_description}}
-**Type:** {{item_type}} ({{section}})
-**Missing:** {{what_is_missing}}
-
-[Y] Yes - Implement this item
-[A] Auto-fill - Implement this and all remaining gaps without asking
-[S] Skip - Leave this gap unfilled
-[H] Halt - Stop gap filling
-
-Your choice:
-
-
-
- Set require_confirmation = false (auto-fill remaining)
-
-
-
- Continue to next gap
-
-
-
- Exit gap filling loop
- Jump to Step 9 (Summary)
-
-
-
-
-
-
-
- Load story context (Technical Requirements, Architecture Compliance, Dev Notes)
- Implement missing item following story specifications
- Write tests if required
- Run tests to verify implementation
- Verify linting/type checking passes
-
-
- Check box [x] for this item in story file
- Update File List with new/modified files
- Add to Dev Agent Record: "Gap filled: {{item_description}}"
-
-
-
- Stage files for this gap
- Commit: "fix({{story_key}}): fill gap - {{item_description}}"
-
-
-
-
-
-
- Leave box unchecked
- Record failure in gaps_list
- Add to failed_gaps
-
-
-
- After all gaps processed:
-
-
-
-
-
-
-
- For each filled gap:
- Re-run verification for that item
- Ensure still VERIFIED after all changes
-
-
-
-
- Calculate final completion:
-
- final_verified = count of [x] across all sections
- final_partial = count of [~] across all sections
- final_missing = count of [ ] across all sections
- final_pct = (final_verified / total_items) Γ 100
-
-
-
- Stage all changed files
- Commit: "fix({{story_key}}): fill {{gaps_filled}} gaps from revalidation"
-
-
-
-
- Load {sprint_status} file
- Update entry with current progress:
- Format: {{story_key}}: {{current_status}} # Revalidated: {{final_verified}}/{{total_items}} ({{final_pct}}%) verified
- Save sprint-status.yaml
-
-
-
-
- Add to Dev Agent Record in story file:
-
-## Revalidation Record ({{timestamp}})
-
-**Revalidation Mode:** {{#if fill_gaps}}Verify & Fill{{else}}Verify Only{{/if}}
-
-**Results:**
-- Verified: {{final_verified}}/{{total_items}} ({{final_pct}}%)
-- Gaps Found: {{total_missing}}
-- Gaps Filled: {{gaps_filled}}
-
-**Evidence:**
-{{#each verification_evidence}}
-- {{item}}: {{evidence}}
-{{/each}}
-
-{{#if gaps_filled > 0}}
-**Gaps Filled:**
-{{#each filled_gaps}}
-- {{item}}: {{what_was_implemented}}
-{{/each}}
-{{/if}}
-
-{{#if failed_gaps.length > 0}}
-**Failed to Fill:**
-{{#each failed_gaps}}
-- {{item}}: {{error}}
-{{/each}}
-{{/if}}
-
- Save story file
-
-
-
-
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/super-dev-story/README.md b/src/bmm/workflows/4-implementation/super-dev-story/README.md
deleted file mode 100644
index 77786969..00000000
--- a/src/bmm/workflows/4-implementation/super-dev-story/README.md
+++ /dev/null
@@ -1,283 +0,0 @@
-# Super-Dev-Story Workflow
-
-**Enhanced story development with comprehensive quality validation**
-
-## What It Does
-
-Super-dev-story is `/dev-story` on steroids - it includes ALL standard development steps PLUS additional quality gates:
-
-```
-Standard dev-story:
- 1-8. Development cycle β Mark "review"
-
-Super-dev-story:
- 1-8. Development cycle
- 9.5. Post-dev gap analysis (verify work complete)
- 9.6. Automated code review (catch issues)
- β Fix issues if found (loop back to step 5)
- 9. Mark "review" (only after all validation passes)
-```
-
-## When to Use
-
-### Use `/super-dev-story` for:
-
-- β
Security-critical features (auth, payments, PII handling)
-- β
Complex business logic with many edge cases
-- β
Stories you want bulletproof before human review
-- β
High-stakes features (production releases, customer-facing)
-- β
When you want to minimize review cycles
-
-### Use standard `/dev-story` for:
-
-- Documentation updates
-- Simple UI tweaks
-- Configuration changes
-- Low-risk experimental features
-- When speed matters more than extra validation
-
-## Cost vs Benefit
-
-| Aspect | dev-story | super-dev-story |
-|--------|-----------|-----------------|
-| **Tokens** | 50K-100K | 80K-150K (+30-50%) |
-| **Time** | Normal | +20-30% |
-| **Quality** | Good | Excellent |
-| **Review cycles** | 1-3 iterations | 0-1 iterations |
-| **False completions** | Possible | Prevented |
-
-**ROI:** Extra 30K tokens (~$0.09) prevents hours of rework and multiple review cycles
-
-## What Gets Validated
-
-### Step 9.5: Post-Dev Gap Analysis
-
-**Checks:**
-- Tasks marked [x] β Code actually exists and works?
-- Required files β Actually created?
-- Claimed tests β Actually exist and pass?
-- Partial implementations β Marked complete prematurely?
-
-**Catches:**
-- β "Created auth service" β File doesn't exist
-- β "Added tests with 90% coverage" β Only 60% actual
-- β "Implemented login" β Function exists but incomplete
-
-**Actions if issues found:**
-- Unchecks false positive tasks
-- Adds tasks for missing work
-- Loops back to implementation
-
-### Step 9.6: Automated Code Review
-
-**Reviews:**
-- β
Correctness (logic errors, edge cases)
-- β
Security (vulnerabilities, input validation)
-- β
Architecture (pattern compliance, SOLID principles)
-- β
Performance (inefficiencies, optimization opportunities)
-- β
Testing (coverage gaps, test quality)
-- β
Code Quality (readability, maintainability)
-
-**Actions if issues found:**
-- Adds review findings as tasks
-- Loops back to implementation
-- Continues until issues resolved
-
-## Usage
-
-### Basic Usage
-
-```bash
-# Load any BMAD agent
-/super-dev-story
-
-# Follows same flow as dev-story, with extra validation
-```
-
-### Specify Story
-
-```bash
-/super-dev-story _bmad-output/implementation-artifacts/story-1.2.md
-```
-
-### Expected Flow
-
-```
-1. Pre-dev gap analysis
- ββ "Approve task updates? [Y/A/n/e/s/r]"
- ββ Select option
-
-2. Development (standard TDD cycle)
- ββ Implements all tasks
-
-3. Post-dev gap analysis
- ββ Scans codebase
- ββ If gaps: adds tasks, loops back
- ββ If clean: proceeds
-
-4. Code review
- ββ Analyzes all changes
- ββ If issues: adds tasks, loops back
- ββ If clean: proceeds
-
-5. Story marked "review"
- ββ Truly complete!
-```
-
-## Fix Iteration Safety
-
-Super-dev has a **max iteration limit** (default: 3) to prevent infinite loops:
-
-```yaml
-# workflow.yaml
-super_dev_settings:
- max_fix_iterations: 3 # Stop after 3 fix cycles
- fail_on_critical_issues: true # HALT if critical security issues
-```
-
-If exceeded:
-```
-π Maximum Fix Iterations Reached
-
-Attempted 3 fix cycles.
-Manual intervention required.
-
-Issues remaining:
-- [List of unresolved issues]
-```
-
-## Examples
-
-### Example 1: Perfect First Try
-
-```
-/super-dev-story
-
-Pre-gap: β
Tasks accurate
-Development: β
8 tasks completed
-Post-gap: β
All work verified
-Code review: β
No issues
-
-β Story complete! (45 minutes, 85K tokens)
-```
-
-### Example 2: Post-Dev Catches Incomplete Work
-
-```
-/super-dev-story
-
-Pre-gap: β
Tasks accurate
-Development: β
8 tasks completed
-Post-gap: β οΈ Tests claim 90% coverage, actual 65%
-
-β Adds task: "Increase test coverage to 90%"
-β Implements missing tests
-β Post-gap: β
Now 92% coverage
-β Code review: β
No issues
-
-β Story complete! (52 minutes, 95K tokens)
-```
-
-### Example 3: Code Review Finds Security Issue
-
-```
-/super-dev-story
-
-Pre-gap: β
Tasks accurate
-Development: β
10 tasks completed
-Post-gap: β
All work verified
-Code review: π¨ CRITICAL - SQL injection vulnerability
-
-β Adds task: "Fix SQL injection in user search"
-β Implements parameterized queries
-β Post-gap: β
Verified
-β Code review: β
Security issue resolved
-
-β Story complete! (58 minutes, 110K tokens)
-```
-
-## Comparison to Standard Workflow
-
-### Standard Flow (dev-story)
-
-```
-Day 1: Develop story (30 min)
-Day 2: Human review finds 3 issues
-Day 3: Fix issues (20 min)
-Day 4: Human review again
-Day 5: Approved
-
-Total: 5 days, 2 review cycles
-```
-
-### Super-Dev Flow
-
-```
-Day 1: Super-dev-story
- - Development (30 min)
- - Post-gap finds 1 issue (auto-fix 5 min)
- - Code review finds 2 issues (auto-fix 15 min)
- - Complete (50 min total)
-
-Day 2: Human review
-Day 3: Approved (minimal/no changes needed)
-
-Total: 3 days, 1 review cycle
-```
-
-**Savings:** 2 days, 1 fewer review cycle, higher initial quality
-
-## Troubleshooting
-
-### "Super-dev keeps looping forever"
-
-**Cause:** Each validation finds new issues
-**Solution:** This indicates quality problems. Review max_fix_iterations setting or manually intervene.
-
-### "Post-dev gap analysis keeps failing"
-
-**Cause:** Dev agent marking tasks complete prematurely
-**Solution:** This is expected! Super-dev catches this. The loop ensures actual completion.
-
-### "Code review too strict"
-
-**Cause:** Reviewing for issues standard dev-story would miss
-**Solution:** This is intentional. For less strict review, use standard dev-story.
-
-### "Too many tokens/too slow"
-
-**Cause:** Multi-stage validation adds overhead
-**Solution:** Use standard dev-story for non-critical stories. Reserve super-dev for important work.
-
-## Best Practices
-
-1. **Reserve for important stories** - Don't use for trivial changes
-2. **Trust the process** - Fix iterations mean it's working correctly
-3. **Review limits** - Adjust max_fix_iterations if stories are complex
-4. **Monitor costs** - Track token usage vs review cycle savings
-5. **Learn patterns** - Code review findings inform future architecture
-
-## Configuration Reference
-
-```yaml
-# _bmad/bmm/config.yaml or _bmad/bmgd/config.yaml
-
-# Per-project settings
-super_dev_settings:
- post_dev_gap_analysis: true # Enable post-dev validation
- auto_code_review: true # Enable automatic code review
- fail_on_critical_issues: true # HALT on security vulnerabilities
- max_fix_iterations: 3 # Maximum fix cycles before manual intervention
- auto_fix_minor_issues: false # Auto-fix LOW severity without asking
-```
-
-## See Also
-
-- [dev-story workflow](../dev-story/) - Standard development workflow
-- [gap-analysis workflow](../gap-analysis/) - Standalone audit tool
-- [Gap Analysis Guide](../../../../docs/gap-analysis.md) - Complete documentation
-- [Super-Dev Mode Concept](../../../../docs/super-dev-mode.md) - Vision and roadmap
-
----
-
-**Super-Dev-Story: Because "done" should mean DONE** β
diff --git a/src/bmm/workflows/4-implementation/super-dev-story/instructions.xml b/src/bmm/workflows/4-implementation/super-dev-story/instructions.xml
deleted file mode 100644
index b296847a..00000000
--- a/src/bmm/workflows/4-implementation/super-dev-story/instructions.xml
+++ /dev/null
@@ -1,299 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
- Generate all documents in {document_output_language}
- π SUPER-DEV MODE: Enhanced quality workflow with post-implementation validation and automated code review
- This workflow orchestrates existing workflows with additional validation steps
-
-
-
-
-
-
- π― RUN DEV-STORY - Complete all standard development steps
- This includes: story loading, pre-dev gap analysis, development, testing, and task completion
-
-
-
-
-
-
- Pass through any user-provided story file path and auto-accept setting
-
-
-
-
-
-
-
-
- HALT - dev-story must complete first
-
-
-
-
-
-
-
-
- π POST-DEV VALIDATION - Verify all work actually completed!
- This catches incomplete implementations that were prematurely marked done
-
-
-
-
- Re-read story file to get requirements and tasks
- Extract all tasks marked [x] complete
- For each completed task, identify what should exist in codebase
-
-
- Use Glob to find files that should have been created
- Use Grep to search for functions/classes that should exist
- Use Read to verify implementation completeness (not just existence)
- Run tests to verify claimed test coverage actually exists and passes
-
-
- Compare claimed work vs actual implementation:
-
- **POST-DEV VERIFICATION:**
- β
Verified Complete:
- - List tasks where code fully exists and works
- - Confirm tests exist and pass
- - Verify implementation matches requirements
-
-
- β False Positives Detected:
- - List tasks marked [x] but code missing or incomplete
- - Identify claimed tests that don't exist or fail
- - Note partial implementations marked as complete
-
-
-
-
-
-
- Uncheck false positive tasks in story file
- Add new tasks for missing work
- Update Gap Analysis section with post-dev findings
-
-
-
-
-
-
- Resume with added tasks for missing work
-
-
-
-
-
-
-
- Update Gap Analysis section with post-dev verification results
-
-
-
-
-
-
-
-
- π AUTO CODE REVIEW - Independent quality validation
-
-
-
-
-
- Run code review on completed story
-
-
- Parse code review results from story file "Code Review" section
- Extract issues by severity (Critical, High, Medium, Low)
- Count total issues found
-
-
-
-
- Add code review findings as tasks in story file
-
-
-
-
- Fix code review issues
-
-
-
-
-
-
-
-
- Auto-fix these minor issues? [Y/n/skip]:
-
-
- Add review findings as tasks
-
-
-
-
-
-
-
- Document issues in story file
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- π PUSH-ALL - Stage, commit, and push with safety validation
- β‘ TARGETED COMMIT: Only commit files from THIS story's File List (safe for parallel agents)
-
-
- Read story file and extract the "File List" section
- Parse all file paths listed (relative to repo root)
- Also include the story file itself in the list
- Store as {{story_files}} - space-separated list of all files
-
-
-
-
-
-
- Only commit files changed by this story
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Based on {user_skill_level}, ask if user needs explanations about implementation, decisions, or findings
-
-
- Provide clear, contextual explanations
-
-
-
-
-
-
diff --git a/src/bmm/workflows/4-implementation/super-dev-story/workflow.md b/src/bmm/workflows/4-implementation/super-dev-story/workflow.md
new file mode 100644
index 00000000..20dcfea4
--- /dev/null
+++ b/src/bmm/workflows/4-implementation/super-dev-story/workflow.md
@@ -0,0 +1,311 @@
+# Super Dev Story v3.0 - Development with Quality Gates
+
+
+Complete story development pipeline: dev-story β validation β code review β push.
+Automatically re-invokes dev-story if gaps or review issues found.
+Ensures production-ready code before pushing.
+
+
+
+**Quality Over Speed**
+
+Don't just implementβverify, review, fix.
+- Run dev-story for implementation
+- Validate with gap analysis
+- Code review for quality
+- Fix issues before pushing
+- Only push when truly ready
+
+
+
+name: super-dev-story
+version: 3.0.0
+
+stages:
+ - dev-story: "Implement the story"
+ - validate: "Run gap analysis"
+ - review: "Code review"
+ - push: "Safe commit and push"
+
+defaults:
+ max_rework_loops: 3
+ auto_push: false
+ review_depth: "standard" # quick | standard | deep
+ validation_depth: "quick"
+
+quality_gates:
+ validation_threshold: 90 # % tasks must be verified
+ review_threshold: "pass" # pass | pass_with_warnings
+
+
+
+@patterns/verification.md
+@patterns/hospital-grade.md
+
+
+
+
+
+**Load story and prepare pipeline**
+
+```bash
+STORY_FILE="{{story_file}}"
+[ -f "$STORY_FILE" ] || { echo "β story_file required"; exit 1; }
+```
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π SUPER DEV STORY PIPELINE
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{story_key}}
+Stages: dev-story β validate β review β push
+
+Quality Gates:
+- Validation: β₯{{validation_threshold}}% verified
+- Review: {{review_threshold}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Initialize:
+- rework_count = 0
+- stage = "dev-story"
+
+
+
+**Stage 1: Implement the story**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STAGE 1: DEV-STORY
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Invoke dev-story workflow:
+```
+/dev-story story_file={{story_file}}
+```
+
+Wait for completion. Capture:
+- files_created
+- files_modified
+- tasks_completed
+
+```
+β
Dev-story complete
+Files: {{file_count}} created/modified
+Tasks: {{tasks_completed}}/{{total_tasks}}
+```
+
+
+
+**Stage 2: Validate implementation**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STAGE 2: VALIDATION
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Invoke validation:
+```
+/validate scope=story target={{story_file}} depth={{validation_depth}}
+```
+
+Capture results:
+- verified_pct
+- false_positives
+- category
+
+**Check quality gate:**
+```
+if verified_pct < validation_threshold:
+ REWORK_NEEDED = true
+ reason = "Validation below {{validation_threshold}}%"
+
+if false_positives > 0:
+ REWORK_NEEDED = true
+ reason = "{{false_positives}} tasks marked done but missing"
+```
+
+```
+{{#if REWORK_NEEDED}}
+β οΈ Validation failed: {{reason}}
+{{else}}
+β
Validation passed: {{verified_pct}}% verified
+{{/if}}
+```
+
+
+
+**Stage 3: Code review**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STAGE 3: CODE REVIEW
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Invoke code review:
+```
+/multi-agent-review files={{files_modified}} depth={{review_depth}}
+```
+
+Capture results:
+- verdict (PASS, PASS_WITH_WARNINGS, NEEDS_REWORK)
+- issues
+
+**Check quality gate:**
+```
+if verdict == "NEEDS_REWORK":
+ REWORK_NEEDED = true
+ reason = "Code review found blocking issues"
+
+if review_threshold == "pass" AND verdict == "PASS_WITH_WARNINGS":
+ REWORK_NEEDED = true
+ reason = "Warnings not allowed in strict mode"
+```
+
+```
+{{#if REWORK_NEEDED}}
+β οΈ Review failed: {{reason}}
+Issues: {{issues}}
+{{else}}
+β
Review passed: {{verdict}}
+{{/if}}
+```
+
+
+
+**Handle rework loop**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π REWORK REQUIRED (Loop {{rework_count + 1}}/{{max_rework_loops}})
+βββββββββββββββββββββββββββββββββββββββββββ
+Reason: {{reason}}
+
+{{#if validation_issues}}
+Validation Issues:
+{{#each validation_issues}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+{{#if review_issues}}
+Review Issues:
+{{#each review_issues}}
+- {{this}}
+{{/each}}
+{{/if}}
+```
+
+**Check loop limit:**
+```
+rework_count++
+if rework_count > max_rework_loops:
+ echo "β Max rework loops exceeded"
+ echo "Manual intervention required"
+ HALT
+```
+
+**Re-invoke dev-story with issues:**
+```
+/dev-story story_file={{story_file}} fix_issues={{issues}}
+```
+
+After dev-story completes, return to validation stage.
+
+
+
+**Stage 4: Push changes**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π¦ STAGE 4: PUSH
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**Generate commit message from story:**
+```
+feat({{epic}}): {{story_title}}
+
+- Implemented {{task_count}} tasks
+- Verified: {{verified_pct}}%
+- Review: {{verdict}}
+
+Story: {{story_key}}
+```
+
+**If auto_push:**
+```
+/push-all commit_message="{{message}}" auto_push=true
+```
+
+**Otherwise, ask:**
+```
+Ready to push?
+
+[Y] Yes, push now
+[N] No, keep local (can push later)
+[R] Review changes first
+```
+
+
+
+**Display pipeline results**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
SUPER DEV STORY COMPLETE
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{story_key}}
+
+Pipeline Results:
+- Dev-Story: β
Complete
+- Validation: β
{{verified_pct}}% verified
+- Review: β
{{verdict}}
+- Push: {{pushed ? "β
Pushed" : "βΈοΈ Local only"}}
+
+Rework Loops: {{rework_count}}
+Files Changed: {{file_count}}
+Commit: {{commit_hash}}
+
+{{#if pushed}}
+Branch: {{branch}}
+Ready for PR: gh pr create
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+
+
+```bash
+# Standard pipeline
+/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md
+
+# With auto-push
+/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md auto_push=true
+
+# Strict review mode
+/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md review_threshold=pass
+```
+
+
+
+**Dev-story fails:** Report error, halt pipeline.
+**Validation below threshold:** Enter rework loop.
+**Review finds blocking issues:** Enter rework loop.
+**Max rework loops exceeded:** Halt, require manual intervention.
+**Push fails:** Report error, commit preserved locally.
+
+
+
+- [ ] Dev-story completed
+- [ ] Validation β₯ threshold
+- [ ] Review passed
+- [ ] Changes committed
+- [ ] Pushed (if requested)
+- [ ] Story status updated
+
diff --git a/src/bmm/workflows/4-implementation/super-dev-story/workflow.yaml b/src/bmm/workflows/4-implementation/super-dev-story/workflow.yaml
index 530f041c..7185b853 100644
--- a/src/bmm/workflows/4-implementation/super-dev-story/workflow.yaml
+++ b/src/bmm/workflows/4-implementation/super-dev-story/workflow.yaml
@@ -14,7 +14,7 @@ date: system-generated
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-story"
-instructions: "{installed_path}/instructions.xml"
+instructions: "{installed_path}/workflow.md"
validation: "{installed_path}/checklist.md"
story_file: "" # Explicit story path; auto-discovered if empty
diff --git a/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md b/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md
deleted file mode 100644
index c7fd4498..00000000
--- a/src/modules/bmm/workflows/4-implementation/batch-super-dev/instructions.md
+++ /dev/null
@@ -1,1270 +0,0 @@
-# Batch Super-Dev - Interactive Story Selector
-## AKA: "Mend the Gap" π
-
-**Primary Use Case:** Gap analysis and reconciliation workflow
-
-This workflow helps you "mind the gap" between story requirements and codebase reality, then "mend the gap" by building only what's truly missing.
-
-### What This Workflow Does
-
-1. **Scans codebase** to verify what's actually implemented vs what stories claim
-2. **Finds the gap** between story requirements and reality
-3. **Mends the gap** by building ONLY what's truly missing (no duplicate work)
-4. **Updates tracking** to reflect actual completion status (check boxes, sprint-status)
-
-### Common Use Cases
-
-**Reconciliation Mode (Most Common):**
-- Work was done but not properly tracked
-- Stories say "build X" but X is 60-80% already done
-- Need second set of eyes to find real gaps
-- Update story checkboxes to match reality
-
-**Greenfield Mode:**
-- Story says "build X", nothing exists
-- Build 100% from scratch with full quality gates
-
-**Brownfield Mode:**
-- Story says "modify X", X exists
-- Refactor carefully, add only new requirements
-
-### Execution Modes
-
-**Sequential (Recommended for Gap Analysis):**
-- Process stories ONE-BY-ONE in THIS SESSION
-- After each story: verify existing code β build only gaps β check boxes β move to next
-- Easier to monitor, can intervene if issues found
-- Best for reconciliation work
-
-**Parallel (For Greenfield Batch Implementation):**
-- Spawn autonomous Task agents to process stories concurrently
-- Faster completion but harder to monitor
-- Best when stories are independent and greenfield
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {project-root}/_bmad/bmm/workflows/4-implementation/batch-super-dev/workflow.yaml
-
-βοΈ HOSPITAL-GRADE CODE STANDARDS βοΈ
-This code may be used in healthcare settings where LIVES ARE AT STAKE.
-Every line of code must meet hospital-grade reliability standards.
-QUALITY >> SPEED. Take 5 hours to do it right, not 1 hour to do it poorly.
-
-
-
-
- Read {sprint_status} file
- Parse metadata: project, project_key, tracking_system
- Parse development_status map
-
- Filter stories with status = "ready-for-dev" OR "backlog"
- Exclude entries that are epics (keys starting with "epic-") or retrospectives (keys ending with "-retrospective")
- Group by status: ready_for_dev_stories, backlog_stories
-
-
- Further filter stories to only include those starting with "{filter_by_epic}-"
- If filter_by_epic = "3", only include stories like "3-1-...", "3-2-...", etc.
-
-
- Sort filtered stories by epic number, then story number (e.g., 1-1, 1-2, 2-1, 3-1)
- Store as: ready_for_dev_stories (list of story keys)
-
-
-
- Exit workflow
-
-
- Combine both lists: available_stories = ready_for_dev_stories + backlog_stories
-
-
-
- Read comment field for each story from sprint-status.yaml (text after # on the same line)
-
- For each story, verify story file exists using COMPREHENSIVE naming pattern detection:
-
-
- Parse story_key (e.g., "20-9-megamenu-navigation" or "20-9") to extract:
- - epic_num: first number (e.g., "20")
- - story_num: second number (e.g., "9")
- - optional_suffix: everything after second number (e.g., "-megamenu-navigation" or empty)
- Input: "20-9-megamenu-navigation" β epic=20, story=9, suffix="-megamenu-navigation"
- Input: "20-11" β epic=20, story=11, suffix=""
-
-
-
- Use Glob tool to search for files matching these patterns (in priority order):
-
- story-{epic_num}.{story_num}.md
- story-20.9.md (DOT notation, no suffix)
-
- story-{epic_num}.{story_num}*.md
- story-20.9-megamenu-navigation.md (DOT notation WITH suffix - use Glob wildcard)
-
- {epic_num}-{story_num}.md
- 20-9.md (HYPHEN notation, no "story-" prefix)
-
- {epic_num}-{story_num}*.md
- 20-9-megamenu-navigation.md (HYPHEN notation WITH suffix)
-
- story-{story_key}.md
- story-20-9-megamenu-navigation.md (literal story_key with "story-" prefix)
-
- {story_key}.md
- 20-9-megamenu-navigation.md (literal story_key)
-
- Stop at first match and store file_path
- If NO match found after all 6 patterns β file_status = β MISSING
- If match found β file_status = β
EXISTS
-
-
- Mark stories as: β
(file exists), β (file missing), π (already implemented but not marked done)
-
-
-
-
-
-
-
- For each story in available_stories (ready_for_dev + backlog):
-
-
- Check if story file exists (already done in Step 2)
-
-
-
-
- Mark story as needs_story_creation = true
- Mark story.creation_workflow = "/create-story" (lightweight, no gap analysis)
- Mark story as validated (will create in next step)
-
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "Story file missing (status ready-for-dev but no file)"
-
-
-
-
- Read story file: {{file_path}}
- Parse sections and validate BMAD format
-
- Check for all 12 required sections:
- 1. Business Context
- 2. Current State
- 3. Acceptance Criteria
- 4. Tasks and Subtasks
- 5. Technical Requirements
- 6. Architecture Compliance
- 7. Testing Requirements
- 8. Dev Agent Guardrails
- 9. Definition of Done
- 10. References
- 11. Dev Agent Record
- 12. Change Log
-
-
- Count sections present: sections_found
- Check Current State content length (word count)
- Check Acceptance Criteria item count: ac_count
- Count unchecked tasks ([ ]) in Tasks/Subtasks: task_count
- Look for gap analysis markers (β
/β) in Current State
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "INVALID - Only {{task_count}} tasks (need β₯3)"
-
-
-
-
-
-
- Regenerate story with codebase scan? (yes/no):
-
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "Story regeneration requires manual workflow (agents cannot invoke /create-story)"
- Add to manual_actions_required list: "Regenerate {{story_key}} with /create-story-with-gap-analysis"
-
-
-
-
- Mark story for removal from selection
- Add to skipped_stories list with reason: "User declined regeneration"
-
-
-
-
-
- Mark story as validated
-
-
-
-
-
- Mark story as validated (already done)
-
-
-
- Remove skipped stories from ready_for_dev_stories
- Update count of available stories
-
-
-
-
-
-
-
- Exit workflow
-
-
-
-
-
-
-
-
- For each validated story:
-
-
- Read story file: {{file_path}}
-
- Count unchecked tasks ([ ]) at top level only in Tasks/Subtasks section β task_count
- (See workflow.yaml complexity.task_counting.method = "top_level_only")
-
-
-
-
- Set {{story_key}}.complexity = {level: "INVALID", score: 0, task_count: {{task_count}}, reason: "Insufficient tasks ({{task_count}}/3 minimum)"}
- Continue to next story
-
-
- Extract file paths mentioned in tasks β file_count
- Scan story title and task descriptions for risk keywords using rules from workflow.yaml:
- - Case insensitive matching (require_word_boundaries: true)
- - Include keyword variants (e.g., "authentication" matches "auth")
- - Scan: story_title, task_descriptions, subtask_descriptions
-
-
- Calculate complexity score:
- - Base score = task_count
- - Add 5 for each HIGH risk keyword match (auth, security, payment, migration, database, schema, encryption)
- - Add 2 for each MEDIUM risk keyword match (api, integration, external, third-party, cache)
- - Add 0 for LOW risk keywords (ui, style, config, docs, test)
- - Count each keyword only once (no duplicates)
-
-
- Assign complexity level using mutually exclusive decision tree (priority order):
-
- 1. Check COMPLEX first (highest priority):
- IF (task_count β₯ 16 OR complexity_score β₯ 20 OR has ANY HIGH risk keyword)
- THEN level = COMPLEX
-
- 2. Else check MICRO (lowest complexity):
- ELSE IF (task_count β€ 3 AND complexity_score β€ 5 AND file_count β€ 5)
- THEN level = MICRO
-
- 3. Else default to STANDARD:
- ELSE level = STANDARD
-
- This ensures no overlaps:
- - Story with HIGH keyword β COMPLEX (never MICRO or STANDARD)
- - Story with 4-15 tasks or >5 files β STANDARD (not MICRO or COMPLEX)
- - Story with β€3 tasks, β€5 files, no HIGH keywords β MICRO
-
-
- Store complexity_level for story: {{story_key}}.complexity = {level, score, task_count, risk_keywords}
-
-
- Group stories by complexity level
-
- Filter out INVALID stories (those with level="INVALID"):
- For each INVALID story, add to skipped_stories with reason from complexity object
- Remove INVALID stories from complexity_groups and ready_for_dev_stories
-
-
-
-
-
-
-
-
-
- Exit workflow
-
-
-
-
-
-**Select stories to process:**
-
-Enter story numbers to process (examples):
- - Single: `1`
- - Multiple: `1,3,5`
- - Range: `1-5` (processes 1,2,3,4,5)
- - Mixed: `1,3-5,8` (processes 1,3,4,5,8)
- - All: `all` (processes all {{count}} stories)
-
-Or:
- - `cancel` - Exit without processing
-
-**Your selection:**
-
-
- Parse user input
-
-
-
- Exit workflow
-
-
-
- Set selected_stories = all ready_for_dev_stories
-
-
-
- Parse selection (handle commas, ranges)
- Input "1,3-5,8" β indexes [1,3,4,5,8] β map to story keys
- Map selected indexes to story keys from ready_for_dev_stories
- Store as: selected_stories
-
-
-
-
- Truncate selected_stories to first max_stories entries
-
-
- Display confirmation
-
-
-
-
-
-
- For each selected story:
-
-
- Read story file: {{story_file_path}}
-
-
-
-
- Mark story as needs_creation
- Continue to next story
-
-
-
-
- Add to validation_failures list
- Continue to next story
-
-
-
-
- Validate story completeness:
- - Count sections (need 12)
- - Check Current State word count (need β₯100)
- - Check gap analysis markers (β
/β)
- - Count Acceptance Criteria (need β₯3)
- - Count unchecked tasks (need β₯3)
-
-
-
-
- Add to validation_failures: "{{story_key}}: Only {{task_count}} tasks"
-
-
-
-
- Add to validation_warnings: "{{story_key}}: Needs regeneration"
-
-
-
-
- Add to validated_stories list
-
-
-
-
-
-
-
- Remove failed stories and continue? (yes/no):
-
-
- Remove validation_failures from selected_stories
-
-
-
-
-
- Exit workflow
-
-
-
-
-
-
- Continue with these stories anyway? (yes/no):
-
-
-
- Exit workflow
-
-
-
-
-
-
-
-
-
- Jump to Step 3
-
-
-
-
- Create these {{needs_creation.length}} story files now? (yes/no):
-
-
-
- Remove needs_creation stories from selected_stories
-
-
-
- Exit workflow
-
-
-
- For each story in needs_creation:
-
-
-
-
- Invoke workflow: /bmad_bmm_create-story
- Parameters:
- - story_key: {{story_key}}
- - epic_num: {{epic_num}}
- - mode: batch (auto-approve, minimal prompts)
-
-
-
-
- Mark story.needs_story_creation = false
-
-
-
-
- Add to failed_creations list
- Remove from selected_stories
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-**Choose execution mode:**
-
-[I] INTERACTIVE CHECKPOINT MODE
- - After each story completes, pause for your review
- - You approve before proceeding to next story
- - Allows course correction if issues detected
- - Best for: When you want to monitor progress
-
-[A] FULLY AUTONOMOUS MODE
- - Process all selected stories without pausing
- - No human interaction until completion
- - Best for: When stories are well-defined and you trust the process
-
-Which mode? [I/A]:
-
-
- Read user input
-
-
- Set execution_mode = "interactive_checkpoint"
-
-
-
-
- Set execution_mode = "fully_autonomous"
-
- Activate hospital_grade_mode = true
- Set quality_multiplier = 1.5
-
-
-
-**How should these stories be processed?**
-
-Options:
-- **sequential**: Run stories one-by-one in this session (slower, easier to monitor)
-- **parallel**: Spawn Task agents to process stories concurrently (faster, autonomous)
-
-Enter: sequential or parallel
-
-
- Capture response as: execution_mode
-
-
- Set parallel_count = 1
- Set use_task_agents = false
-
-
-
-
- Set use_task_agents = true
-
-
-**How many agents should run in parallel?**
-
-Options:
-- **2**: Conservative (low resource usage, easier debugging)
-- **4**: Moderate (balanced performance, recommended)
-- **8**: Aggressive (higher throughput)
-- **10**: Maximum (10 agent limit for safety)
-- **all**: Use all stories (max 10 agents)
-
-Enter number (2-10) or 'all':
-
-
- Capture response as: parallel_count
- If parallel_count == 'all': set parallel_count = min(count of selected_stories, 10)
- If parallel_count > 10: set parallel_count = 10 (safety limit)
-
-
-
-
-
-
-
-
- Confirm execution plan? (yes/no):
-
-
-
- Exit workflow
-
-
-
-
- Initialize counters: completed=0, failed=0, failed_stories=[], reconciliation_warnings=[], reconciliation_warnings_count=0
- Set start_time = current timestamp
-
-
- Jump to Step 4-Parallel (Task Agent execution)
-
-
-
- Continue to Step 4-Sequential (In-session execution)
-
-
-
-
-
-
- For each story in selected_stories:
-
-
-
-
- Invoke workflow: /bmad:bmm:workflows:super-dev-pipeline
- Parameters: mode=batch, story_key={{story_key}}, complexity_level={{story_key}}.complexity.level
-
-
-
-
- ORCHESTRATOR: You must execute reconciliation directly using Bash/Read/Edit tools.
- Do NOT delegate this to an agent. YOU do it.
-
-
- 1. Use Bash: `git log -3 --oneline | grep "{{story_key}}"` to find commit
- 2. Use Bash: `git diff HEAD~1 --name-only` to get files changed
- 3. Use Read: `docs/sprint-artifacts/{{story_key}}.md` to see tasks
- 4. Use Edit: Check off tasks (change `- [ ]` to `- [x]`) for completed work
- 5. Use Edit: Fill Dev Agent Record with files/date/summary
- 6. Use Bash: Verify with `grep -c "^- \[x\]"` (must be > 0)
- 7. Use Edit: Update sprint-status.yaml to "done" or "review"
-
-
-
-
- Increment completed counter
-
-
- PAUSE FOR USER REVIEW
-
-
- Read user input
-
-
-
-
-
-
-
- Display story file, test results, review findings
-
- Read user input
-
-
-
-
-
- Jump to Step 5 (Summary)
-
-
-
-
-
- Jump to Step 5 (Summary)
-
-
-
-
-
-
-
-
-
-
- Increment completed counter (implementation was successful)
- Add to reconciliation_warnings: {story_key: {{story_key}}, warning_message: "Reconciliation failed - manual verification needed"}
- Increment reconciliation_warnings_count
-
-
-
-
-
- Increment failed counter
- Add story_key to failed_stories list
-
-
-
- Jump to Step 5 (Summary)
-
-
-
-
-
-
-
-
-
- Wait {{pause_between_stories}} seconds
-
-
-
- After all stories processed, jump to Step 5 (Summary)
-
-
-
-
-
- Initialize worker pool state:
-
- - story_queue = selected_stories (all stories to process)
- - active_workers = {} (map of worker_id β {story_key, task_id, started_at})
- - completed_stories = []
- - failed_stories = []
- - next_story_index = 0
- - max_workers = {{parallel_count}}
-
-
-
-
-
- Spawn first {{max_workers}} agents (or fewer if less stories):
-
- While next_story_index < min(max_workers, story_queue.length):
-
-
- story_key = story_queue[next_story_index]
- worker_id = next_story_index + 1
-
- Spawn Task agent:
- - subagent_type: "general-purpose"
- - description: "Implement story {{story_key}}"
- - prompt: "Execute super-dev-pipeline workflow for story {{story_key}}.
-
- CRITICAL INSTRUCTIONS:
- 1. Load workflow.xml: _bmad/core/tasks/workflow.xml
- 2. Load workflow config: _bmad/bmm/workflows/4-implementation/super-dev-pipeline/workflow.yaml
- 3. Execute in BATCH mode with story_key={{story_key}} and complexity_level={{story_key}}.complexity.level
- 4. Follow all 7 pipeline steps (init, pre-gap, implement, post-validate, code-review, complete, summary)
- 5. Commit changes when complete
- 6. Report final status (done/failed) with file list
-
- Story file will be auto-resolved from multiple naming conventions."
- - run_in_background: true (non-blocking - critical for semaphore pattern)
-
- Store in active_workers[worker_id]:
- story_key: {{story_key}}
- task_id: {{returned_task_id}}
- started_at: {{timestamp}}
- status: "running"
-
-
- Increment next_story_index
-
-
-
- After spawning initial workers:
-
-
-
-
- SEMAPHORE PATTERN: Keep {{max_workers}} agents running continuously
-
- While active_workers.size > 0 OR next_story_index < story_queue.length:
-
- Poll for completed workers (check task outputs non-blocking):
-
- For each worker_id in active_workers:
-
- Check if worker task completed using TaskOutput(task_id, block=false)
-
-
- Continue to next worker (don't wait)
-
-
-
- Get worker details: story_key = active_workers[worker_id].story_key
-
-
-
- ORCHESTRATOR: You must execute reconciliation directly using Bash/Read/Edit tools.
-
-
- 1. Use Bash: `git log -3 --oneline | grep "{{story_key}}"` to find commit
- 2. Use Bash: `git diff HEAD~1 --name-only` to get files changed
- 3. Use Read: `docs/sprint-artifacts/{{story_key}}.md` to see tasks
- 4. Use Edit: Check off tasks (change `- [ ]` to `- [x]`) for completed work
- 5. Use Edit: Fill Dev Agent Record with files/date/summary
- 6. Use Bash: Verify with `grep -c "^- \[x\]"` (must be > 0)
- 7. Use Edit: Update sprint-status.yaml to "done" or "review"
-
-
-
-
- Add to completed_stories
-
-
-
-
- Add to completed_stories (implementation successful)
- Add to reconciliation_warnings: {story_key: {{story_key}}, warning_message: "Reconciliation failed - manual verification needed"}
-
-
- Remove worker_id from active_workers (free the slot)
-
- IMMEDIATELY refill slot if stories remain:
-
- story_key = story_queue[next_story_index]
-
-
-
- Spawn new Task agent for this worker_id (same parameters as init)
- Update active_workers[worker_id] with new task_id and story_key
- Increment next_story_index
-
-
-
-
- Get worker details: story_key = active_workers[worker_id].story_key
-
-
-
- Add to failed_stories
- Remove worker_id from active_workers (free the slot)
-
-
-
- Kill all active workers
- Clear story_queue
- Break worker pool loop
-
-
-
- story_key = story_queue[next_story_index]
-
-
-
- Spawn new Task agent for this worker_id
- Update active_workers[worker_id] with new task_id and story_key
- Increment next_story_index
-
-
-
- Display live progress every 30 seconds:
-
-
- Sleep 5 seconds before next poll (prevents tight loop)
-
-
-
- After worker pool drains (all stories processed), jump to Step 5 (Summary)
-
-
-
- Calculate end_time and total_duration
- Calculate success_rate = (completed / total_count) * 100
-
-
-
- Save batch log to {batch_log}
- Log contents: start_time, end_time, total_duration, selected_stories, completed_stories, failed_stories, success_rate
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md
deleted file mode 100644
index 08f41fa6..00000000
--- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# Create Story With Gap Analysis
-
-**Custom Workflow by Jonah Schulte**
-**Created:** December 24, 2025
-**Purpose:** Generate stories with SYSTEMATIC codebase gap analysis (not inference-based)
-
----
-
-## Problem This Solves
-
-**Standard `/create-story` workflow:**
-- β Reads previous stories and git commits (passive)
-- β Infers what probably exists (guessing)
-- β Gap analysis quality varies by agent thoroughness
-- β Checkboxes may not reflect reality
-
-**This custom workflow:**
-- β
Actively scans codebase with Glob/Read tools
-- β
Verifies file existence (not inference)
-- β
Reads key files to check implementation depth (mocked vs real)
-- β
Generates TRUTHFUL gap analysis
-- β
Checkboxes are FACTS verified by file system
-
----
-
-## Usage
-
-```bash
-/create-story-with-gap-analysis
-
-# Or via Skill tool:
-Skill: "create-story-with-gap-analysis"
-Args: "1.9" (epic.story number)
-```
-
-**Workflow will:**
-1. Load existing story + epic context
-2. **SCAN codebase systematically** (Glob for files, Read to verify implementation)
-3. Generate gap analysis with verified β
/β/β οΈ status
-4. Update story file with truthful checkboxes
-5. Save to _bmad-output/implementation-artifacts/
-
----
-
-## What It Scans
-
-**For each story, the workflow:**
-
-1. **Identifies target directories** (from story title/requirements)
- - Example: "admin-user-service" β apps/backend/admin-user-service/
-
-2. **Globs for all files**
- - `{target}/src/**/*.ts` - Find all TypeScript files
- - `{target}/src/**/*.spec.ts` - Find all tests
-
-3. **Checks specific required files**
- - Based on ACs, check if files exist
- - Example: `src/auth/controllers/bridgeid-auth.controller.ts` β β MISSING
-
-4. **Reads key files to verify depth**
- - Check if mocked: Search for "MOCK" string
- - Check if incomplete: Search for "TODO"
- - Verify real implementation exists
-
-5. **Checks package.json**
- - Verify required dependencies are installed
- - Identify missing packages
-
-6. **Counts tests**
- - How many test files exist
- - Coverage for each component
-
----
-
-## Output Format
-
-**Generates story with:**
-
-1. β
Standard BMAD 5 sections (Story, AC, Tasks, Dev Notes, Dev Agent Record)
-2. β
Enhanced Dev Notes with verified gap analysis subsections:
- - Gap Analysis: Current State vs Requirements
- - Library/Framework Requirements (from package.json)
- - File Structure Requirements (from Glob results)
- - Testing Requirements (from test file count)
- - Architecture Compliance
- - Previous Story Intelligence
-
-3. β
Truthful checkboxes based on verified file existence
-
----
-
-## Difference from Standard /create-story
-
-| Feature | /create-story | /create-story-with-gap-analysis |
-|---------|---------------|--------------------------------|
-| Reads previous story | β
| β
|
-| Reads git commits | β
| β
|
-| Loads epic context | β
| β
|
-| **Scans codebase with Glob** | β | β
SYSTEMATIC |
-| **Verifies files exist** | β | β
VERIFIED |
-| **Reads files to check depth** | β | β
MOCKED vs REAL |
-| **Checks package.json** | β | β
DEPENDENCIES |
-| **Counts test coverage** | β | β
COVERAGE |
-| Gap analysis quality | Variable (agent-dependent) | Systematic (tool-verified) |
-| Checkbox accuracy | Inference-based | File-existence-based |
-
----
-
-## When to Use
-
-**This workflow (planning-time gap analysis):**
-- Use when regenerating/auditing stories
-- Use when you want verified checkboxes upfront
-- Best for stories that will be implemented immediately
-- Manual verification at planning time
-
-**Standard /create-story + /dev-story (dev-time gap analysis):**
-- Recommended for most workflows
-- Stories start as DRAFT, validated when dev begins
-- Prevents staleness in batch planning
-- Automatic verification at development time
-
-**Use standard /create-story when:**
-- Greenfield project (nothing exists yet)
-- Backlog stories (won't be implemented for months)
-- Epic planning phase (just sketching ideas)
-
-**Tip:** Both approaches are complementary. You can use this workflow to regenerate stories, then use `/dev-story` which will re-validate at dev-time.
-
----
-
-## Examples
-
-**Regenerating Story 1.9:**
-```bash
-/create-story-with-gap-analysis
-
-Choice: 1.9
-
-# Workflow will:
-# 1. Load existing 1-9-admin-user-service-bridgeid-rbac.md
-# 2. Identify target: apps/backend/admin-user-service/
-# 3. Glob: apps/backend/admin-user-service/src/**/*.ts (finds 47 files)
-# 4. Check: src/auth/controllers/bridgeid-auth.controller.ts β β MISSING
-# 5. Read: src/bridgeid/services/bridgeid-client.service.ts β β οΈ MOCKED
-# 6. Read: package.json β axios β NOT INSTALLED
-# 7. Generate gap analysis with verified status
-# 8. Write story with truthful checkboxes
-```
-
-**Result:** Story with verified gap analysis showing:
-- β
7 components IMPLEMENTED (verified file existence)
-- β 6 components MISSING (verified file not found)
-- β οΈ 1 component PARTIAL (file exists but contains "MOCK")
-
----
-
-## Installation
-
-This workflow is auto-discovered when BMAD is installed.
-
-**To use:**
-```bash
-/bmad:bmm:workflows:create-story-with-gap-analysis
-```
-
----
-
-**Last Updated:** December 27, 2025
-**Status:** Integrated into BMAD-METHOD
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md
deleted file mode 100644
index 6212924b..00000000
--- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-01-initialize.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Step 1: Initialize and Extract Story Requirements
-
-## Goal
-Load epic context and identify what needs to be scanned in the codebase.
-
-## Execution
-
-### 1. Determine Story to Create
-
-**Ask user:**
-```
-Which story should I regenerate with gap analysis?
-
-Options:
-1. Provide story number (e.g., "1.9" or "1-9")
-2. Provide story filename (e.g., "story-1.9.md" or legacy "1-9-admin-user-service-bridgeid-rbac.md")
-
-Your choice:
-```
-
-**Parse input:**
-- Extract epic_num (e.g., "1")
-- Extract story_num (e.g., "9")
-- Locate story file: `{story_dir}/story-{epic_num}.{story_num}.md` (fallback: `{story_dir}/{epic_num}-{story_num}-*.md`)
-
-### 2. Load Existing Story Content
-
-```bash
-Read: {story_dir}/story-{epic_num}.{story_num}.md
-# If not found, fallback:
-Read: {story_dir}/{epic_num}-{story_num}-*.md
-```
-
-**Extract from existing story:**
-- Story title
-- User story text (As a... I want... So that...)
-- Acceptance criteria (the requirements, not checkboxes)
-- Any existing Dev Notes or technical context
-
-**Store for later use.**
-
-### 3. Load Epic Context
-
-```bash
-Read: {planning_artifacts}/epics.md
-```
-
-**Extract from epic:**
-- Epic business objectives
-- This story's original requirements
-- Technical constraints
-- Dependencies on other stories
-
-### 4. Determine Target Directories
-
-**From story title and requirements, identify:**
-- Which service/app this story targets
-- Which directories to scan
-
-**Examples:**
-- "admin-user-service" β `apps/backend/admin-user-service/`
-- "Widget Batch 1" β `packages/widgets/`
-- "POE Integration" β `apps/frontend/web/`
-
-**Store target directories for Step 2 codebase scan.**
-
-### 5. Ready for Codebase Scan
-
-**Output:**
-```
-β
Story Context Loaded
-
-Story: {epic_num}.{story_num} - {title}
-Target directories identified:
- - {directory_1}
- - {directory_2}
-
-Ready to scan codebase for gap analysis.
-
-[C] Continue to Codebase Scan
-```
-
-**WAIT for user to select Continue.**
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md
deleted file mode 100644
index 69f4022f..00000000
--- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-02-codebase-scan.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# Step 2: Systematic Codebase Gap Analysis
-
-## Goal
-VERIFY what code actually exists vs what's missing using Glob and Read tools.
-
-## CRITICAL
-This step uses ACTUAL file system tools to generate TRUTHFUL gap analysis.
-No guessing. No inference. VERIFY with tools.
-
-## Execution
-
-### 1. Scan Target Directories
-
-**For each target directory identified in Step 1:**
-
-```bash
-# List all TypeScript files
-Glob: {target_dir}/src/**/*.ts
-Glob: {target_dir}/src/**/*.tsx
-
-# Store file list
-```
-
-**Output:**
-```
-π Codebase Scan Results for {target_dir}
-
-Found {count} TypeScript files:
- - {file1}
- - {file2}
- ...
-```
-
-### 2. Check for Specific Required Components
-
-**Based on story Acceptance Criteria, check if required files exist:**
-
-**Example for Auth Story:**
-```bash
-# Check for OAuth endpoints
-Glob: {target_dir}/src/auth/controllers/*bridgeid*.ts
-Result: β MISSING (0 files found)
-
-# Check for BridgeID client
-Glob: {target_dir}/src/bridgeid/**/*.ts
-Result: β
EXISTS (found: bridgeid-client.service.ts, bridgeid-sync.service.ts)
-
-# Check for permission guards
-Glob: {target_dir}/src/auth/guards/permissions*.ts
-Result: β MISSING (0 files found)
-
-# Check for decorators
-Glob: {target_dir}/src/auth/decorators/*permission*.ts
-Result: β MISSING (0 files found)
-```
-
-### 3. Verify Implementation Depth
-
-**For files that exist, read them to check if MOCKED or REAL:**
-
-```bash
-# Read key implementation file
-Read: {target_dir}/src/bridgeid/services/bridgeid-client.service.ts
-
-# Search for indicators:
-- Contains "MOCK" or "mock" β β οΈ MOCKED (needs real implementation)
-- Contains "TODO" β β οΈ INCOMPLETE
-- Contains real HTTP client (axios) β β
IMPLEMENTED
-```
-
-### 4. Check Dependencies
-
-```bash
-# Read package.json
-Read: {target_dir}/package.json
-
-# Verify required dependencies exist:
-Required: axios
-Found in package.json? β β NO (needs to be added)
-
-Required: @aws-sdk/client-secrets-manager
-Found in package.json? β β NO (needs to be added)
-```
-
-### 5. Check Test Coverage
-
-```bash
-# Find test files
-Glob: {target_dir}/src/**/*.spec.ts
-Glob: {target_dir}/test/**/*.test.ts
-
-# Count tests
-Found {test_count} test files
-
-# Check for specific test coverage
-Glob: {target_dir}/src/**/*bridgeid*.spec.ts
-Result: β
EXISTS (found 3 test files)
-```
-
-### 6. Generate Truthful Gap Analysis
-
-**Create structured gap analysis:**
-
-```markdown
-## Gap Analysis: Current State vs Requirements
-
-**β
IMPLEMENTED (Verified by Codebase Scan):**
-
-1. **BridgeID Client Infrastructure** - MOCKED (needs real HTTP)
- - File: src/bridgeid/services/bridgeid-client.service.ts β
EXISTS
- - Implementation: Mock user data with circuit breaker
- - Status: β οΈ PARTIAL - Ready for real HTTP client
- - Tests: 15 tests passing β
-
-2. **User Synchronization Service**
- - File: src/bridgeid/services/bridgeid-sync.service.ts β
EXISTS
- - Implementation: Bulk sync BridgeID β admin_users
- - Status: β
COMPLETE
- - Tests: 6 tests passing β
-
-3. **Role Mapping Logic**
- - File: src/bridgeid/constants/role-mapping.constants.ts β
EXISTS
- - Implementation: 7-tier role mapping with priority selection
- - Status: β
COMPLETE
- - Tests: 10 tests passing β
-
-**β MISSING (Required for AC Completion):**
-
-1. **BridgeID OAuth Endpoints**
- - File: src/auth/controllers/bridgeid-auth.controller.ts β NOT FOUND
- - Need: POST /api/auth/bridgeid/login endpoint
- - Need: GET /api/auth/bridgeid/callback endpoint
- - Status: β NOT IMPLEMENTED
-
-2. **Permission Guards**
- - File: src/auth/guards/permissions.guard.ts β NOT FOUND
- - File: src/auth/decorators/require-permissions.decorator.ts β NOT FOUND
- - Status: β NOT IMPLEMENTED
-
-3. **Real OAuth HTTP Client**
- - Package: axios β NOT in package.json
- - Package: @aws-sdk/client-secrets-manager β NOT in package.json
- - Status: β DEPENDENCIES NOT ADDED
-```
-
-### 7. Update Acceptance Criteria Checkboxes
-
-**Based on verified gap analysis, mark checkboxes:**
-
-```markdown
-### AC1: BridgeID OAuth Integration
-- [ ] OAuth login endpoint (VERIFIED MISSING - file not found)
-- [ ] OAuth callback endpoint (VERIFIED MISSING - file not found)
-- [ ] Client configuration (VERIFIED PARTIAL - exists but mocked)
-
-### AC3: RBAC Permission System
-- [x] Role mapping defined (VERIFIED COMPLETE - file exists, tests pass)
-- [ ] Permission guard (VERIFIED MISSING - file not found)
-- [ ] Permission decorator (VERIFIED MISSING - file not found)
-```
-
-**Checkboxes are now FACTS, not guesses.**
-
-### 8. Present Gap Analysis
-
-**Output:**
-```
-β
Codebase Scan Complete
-
-Scanned: apps/backend/admin-user-service/
-Files found: 47 TypeScript files
-Tests found: 31 test files
-
-Gap Analysis Generated:
- β
7 components IMPLEMENTED (verified)
- β 6 components MISSING (verified)
- β οΈ 1 component PARTIAL (needs completion)
-
-Story checkboxes updated based on verified file existence.
-
-[C] Continue to Story Generation
-```
-
-**WAIT for user to continue.**
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md
deleted file mode 100644
index 34281465..00000000
--- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/step-03-generate-story.md
+++ /dev/null
@@ -1,181 +0,0 @@
-# Step 3: Generate Story with Verified Gap Analysis
-
-## Goal
-Generate complete 7-section story file using verified gap analysis from Step 2.
-
-## Execution
-
-### 1. Load Template
-
-```bash
-Read: {installed_path}/template.md
-```
-
-### 2. Fill Template Variables
-
-**Basic Story Info:**
-- `{{epic_num}}` - from Step 1
-- `{{story_num}}` - from Step 1
-- `{{story_title}}` - from existing story or epic
-- `{{priority}}` - from epic (P0, P1, P2)
-- `{{effort}}` - from epic or estimate
-
-**Story Section:**
-- `{{role}}` - from existing story
-- `{{action}}` - from existing story
-- `{{benefit}}` - from existing story
-
-**Business Context:**
-- `{{business_value}}` - from epic context
-- `{{scale_requirements}}` - from epic/architecture
-- `{{compliance_requirements}}` - from epic/architecture
-- `{{urgency}}` - from epic priority
-
-**Acceptance Criteria:**
-- `{{acceptance_criteria}}` - from epic + existing story
-- Update checkboxes based on Step 2 gap analysis:
- - [x] = Component verified EXISTS
- - [ ] = Component verified MISSING
- - [~] = Component verified PARTIAL (optional notation)
-
-**Tasks / Subtasks:**
-- `{{tasks_subtasks}}` - from epic + existing story
-- Add "β
DONE", "β οΈ PARTIAL", "β TODO" markers based on gap analysis
-
-**Gap Analysis Section:**
-- `{{implemented_components}}` - from Step 2 codebase scan (verified β
)
-- `{{missing_components}}` - from Step 2 codebase scan (verified β)
-- `{{partial_components}}` - from Step 2 codebase scan (verified β οΈ)
-
-**Architecture Compliance:**
-- `{{architecture_patterns}}` - from architecture doc + playbooks
-- Multi-tenant isolation requirements
-- Caching strategies
-- Error handling patterns
-- Performance requirements
-
-**Library/Framework Requirements:**
-- `{{current_dependencies}}` - from Step 2 package.json scan
-- `{{required_dependencies}}` - missing deps identified in Step 2
-
-**File Structure:**
-- `{{existing_files}}` - from Step 2 Glob results (verified β
)
-- `{{required_files}}` - from gap analysis (verified β)
-
-**Testing Requirements:**
-- `{{test_count}}` - from Step 2 test file count
-- `{{required_tests}}` - based on missing components
-- `{{coverage_target}}` - from architecture or default 90%
-
-**Dev Agent Guardrails:**
-- `{{guardrails}}` - from playbooks + previous story lessons
-- What NOT to do
-- Common mistakes to avoid
-
-**Previous Story Intelligence:**
-- `{{previous_story_learnings}}` - from Step 1 previous story Dev Agent Record
-
-**Project Structure Notes:**
-- `{{structure_alignment}}` - from architecture compliance
-
-**References:**
-- `{{references}}` - Links to epic, architecture, playbooks, related stories
-
-**Definition of Done:**
-- Standard DoD checklist with story-specific coverage target
-
-### 3. Generate Complete Story
-
-**Write filled template:**
-```bash
-Write: {story_dir}/story-{{epic_num}}.{{story_num}}.md
-[Complete 7-section story with verified gap analysis]
-```
-
-### 4. Validate Generated Story
-
-```bash
-# Check section count
-grep "^## " {story_dir}/story-{{epic_num}}.{{story_num}}.md | wc -l
-# Should output: 7
-
-# Check for gap analysis
-grep -q "Gap Analysis.*Current State" {story_dir}/story-{{epic_num}}.{{story_num}}.md
-# Should find it
-
-# Run custom validation
-./scripts/validate-bmad-format.sh {story_dir}/story-{{epic_num}}.{{story_num}}.md
-# Update script to expect 7 sections + gap analysis subsection
-```
-
-### 5. Update Sprint Status
-
-```bash
-Read: {sprint_status}
-
-# Find story entry
-# Update status to "ready-for-dev" if was "backlog"
-# Preserve all comments and structure
-
-Write: {sprint_status}
-```
-
-### 6. Report Completion
-
-**Output:**
-```
-β
Story {{epic_num}}.{{story_num}} Regenerated with Gap Analysis
-
-File: {story_dir}/story-{{epic_num}}.{{story_num}}.md
-Sections: 7/7 β
-Gap Analysis: VERIFIED with codebase scan
-
-Summary:
- β
{{implemented_count}} components IMPLEMENTED (verified by file scan)
- β {{missing_count}} components MISSING (verified file not found)
- β οΈ {{partial_count}} components PARTIAL (file exists but mocked/incomplete)
-
-Checkboxes in ACs and Tasks reflect VERIFIED status (not guesses).
-
-Next Steps:
-1. Review story file for accuracy
-2. Use /dev-story to implement missing components
-3. Story provides complete context for flawless implementation
-
-Story is ready for development. π
-```
-
-### 7. Cleanup
-
-**Ask user:**
-```
-Story regeneration complete!
-
-Would you like to:
-[N] Regenerate next story ({{next_story_num}})
-[Q] Quit workflow
-[R] Review generated story first
-
-Your choice:
-```
-
-**If N selected:** Loop back to Step 1 with next story number
-**If Q selected:** End workflow
-**If R selected:** Display story file, then show menu again
-
----
-
-## Success Criteria
-
-**Story generation succeeds when:**
-1. β
7 top-level ## sections present
-2. β
Gap Analysis subsection exists with β
/β/β οΈ verified status
-3. β
Checkboxes match codebase reality (spot-checked)
-4. β
Dev Notes has all mandatory subsections
-5. β
Definition of Done checklist included
-6. β
File saved to correct location
-7. β
Sprint status updated
-
----
-
-**WORKFLOW COMPLETE - Ready to execute.**
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md
deleted file mode 100644
index c0b7c87d..00000000
--- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/template.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Story {{epic_num}}.{{story_num}}: {{story_title}}
-
-**Status:** ready-for-dev
-**Epic:** {{epic_num}}
-**Priority:** {{priority}}
-**Estimated Effort:** {{effort}}
-
----
-
-## Story
-
-As a **{{role}}**,
-I want to **{{action}}**,
-So that **{{benefit}}**.
-
----
-
-## Business Context
-
-### Why This Matters
-
-{{business_value}}
-
-### Production Reality
-
-{{scale_requirements}}
-{{compliance_requirements}}
-{{urgency}}
-
----
-
-## Acceptance Criteria
-
-{{acceptance_criteria}}
-
----
-
-## Tasks / Subtasks
-
-{{tasks_subtasks}}
-
----
-
-## Dev Notes
-
-### Gap Analysis: Current State vs Requirements
-
-**β
IMPLEMENTED (Verified by Codebase Scan):**
-
-{{implemented_components}}
-
-**β MISSING (Required for AC Completion):**
-
-{{missing_components}}
-
-**β οΈ PARTIAL (Needs Enhancement):**
-
-{{partial_components}}
-
-### Architecture Compliance
-
-{{architecture_patterns}}
-
-### Library/Framework Requirements
-
-**Current Dependencies:**
-```json
-{{current_dependencies}}
-```
-
-**Required Additions:**
-```json
-{{required_dependencies}}
-```
-
-### File Structure Requirements
-
-**Completed Files:**
-```
-{{existing_files}}
-```
-
-**Required New Files:**
-```
-{{required_files}}
-```
-
-### Testing Requirements
-
-**Current Test Coverage:** {{test_count}} tests passing
-
-**Required Additional Tests:**
-{{required_tests}}
-
-**Target:** {{coverage_target}}
-
-### Dev Agent Guardrails
-
-{{guardrails}}
-
-### Previous Story Intelligence
-
-{{previous_story_learnings}}
-
-### Project Structure Notes
-
-{{structure_alignment}}
-
-### References
-
-{{references}}
-
----
-
-## Definition of Done
-
-### Code Quality (BLOCKING)
-- [ ] Type check passes: `pnpm type-check` (zero errors)
-- [ ] Zero `any` types in new code
-- [ ] Lint passes: `pnpm lint` (zero errors in new code)
-- [ ] Build succeeds: `pnpm build`
-
-### Testing (BLOCKING)
-- [ ] Unit tests: {{coverage_target}} coverage
-- [ ] Integration tests: Key workflows validated
-- [ ] All tests pass: New + existing (zero regressions)
-
-### Security (BLOCKING)
-- [ ] Dependency scan: `pnpm audit` (zero high/critical)
-- [ ] No hardcoded secrets
-- [ ] Input validation on all endpoints
-- [ ] Auth checks on protected endpoints
-- [ ] Audit logging on mutations
-
-### Architecture Compliance (BLOCKING)
-- [ ] Multi-tenant isolation: dealerId in all queries
-- [ ] Cache namespacing: Cache keys include siteId
-- [ ] Performance: External APIs cached, no N+1 queries
-- [ ] Error handling: No silent failures
-- [ ] Follows patterns from playbooks
-
-### Deployment Validation (BLOCKING)
-- [ ] Service starts: `pnpm dev` runs successfully
-- [ ] Health check: `/health` returns 200
-- [ ] Smoke test: Primary functionality verified
-
-### Documentation (BLOCKING)
-- [ ] API docs: Swagger decorators on endpoints
-- [ ] Inline comments: Complex logic explained
-- [ ] Story file: Dev Agent Record complete
-
----
-
-## Dev Agent Record
-
-### Agent Model Used
-
-(To be filled by dev agent)
-
-### Implementation Summary
-
-(To be filled by dev agent)
-
-### File List
-
-(To be filled by dev agent)
-
-### Test Results
-
-(To be filled by dev agent)
-
-### Completion Notes
-
-(To be filled by dev agent)
-
----
-
-**Generated by:** /create-story-with-gap-analysis
-**Date:** {{date}}
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md
new file mode 100644
index 00000000..b40462b5
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.md
@@ -0,0 +1,286 @@
+# Create Story with Gap Analysis v3.0 - Verified Story Generation
+
+
+Regenerate story with VERIFIED codebase gap analysis.
+Uses Glob/Read tools to determine what actually exists vs what's missing.
+Checkboxes reflect reality, not guesses.
+
+
+
+**Truth from Codebase, Not Assumptions**
+
+1. Scan codebase for actual implementations
+2. Verify files exist, check for stubs/TODOs
+3. Check test coverage
+4. Generate story with checkboxes matching reality
+5. No guessingβevery checkbox has evidence
+
+
+
+name: create-story-with-gap-analysis
+version: 3.0.0
+
+verification_status:
+ verified: "[x]" # File exists, real implementation, tests exist
+ partial: "[~]" # File exists but stub/TODO or no tests
+ missing: "[ ]" # File does not exist
+
+defaults:
+ update_sprint_status: true
+ create_report: false
+
+
+
+@patterns/verification.md
+@patterns/hospital-grade.md
+
+
+
+
+
+**Identify story and load context**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STORY REGENERATION WITH GAP ANALYSIS
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**Ask user for story:**
+```
+Which story should I regenerate with gap analysis?
+
+Provide:
+- Story number (e.g., "1.9" or "1-9")
+- OR story filename
+
+Your choice:
+```
+
+**Parse input:**
+- Extract epic_num, story_num
+- Locate story file
+
+**Load existing story:**
+```bash
+Read: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md
+```
+
+Extract:
+- Story title
+- User story (As a... I want... So that...)
+- Acceptance criteria
+- Tasks
+- Dev Notes
+
+**Load epic context:**
+```bash
+Read: {{planning_artifacts}}/epics.md
+```
+
+Extract:
+- Epic business objectives
+- Technical constraints
+- Dependencies
+
+**Determine target directories:**
+From story title/requirements, identify which directories to scan.
+
+```
+β
Story Context Loaded
+
+Story: {{epic_num}}.{{story_num}} - {{title}}
+Target directories:
+{{#each directories}}
+ - {{this}}
+{{/each}}
+
+[C] Continue to Codebase Scan
+```
+
+
+
+**VERIFY what code actually exists**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π CODEBASE SCAN
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**For each target directory:**
+
+1. **List all source files:**
+ ```bash
+ Glob: {{target_dir}}/src/**/*.ts
+ Glob: {{target_dir}}/src/**/*.tsx
+ ```
+
+2. **Check for specific required components:**
+ Based on story ACs, check if required files exist:
+ ```bash
+ Glob: {{target_dir}}/src/auth/controllers/*oauth*.ts
+ # Result: β
EXISTS or β MISSING
+ ```
+
+3. **Verify implementation depth:**
+ For files that exist, check quality:
+ ```bash
+ Read: {{file}}
+
+ # Check for stubs
+ Grep: "MOCK|TODO|FIXME|Not implemented" {{file}}
+ # If found: β οΈ STUB
+ ```
+
+4. **Check dependencies:**
+ ```bash
+ Read: {{target_dir}}/package.json
+
+ # Required: axios - Found? β
/β
+ # Required: @aws-sdk/client-secrets-manager - Found? β
/β
+ ```
+
+5. **Check test coverage:**
+ ```bash
+ Glob: {{target_dir}}/src/**/*.spec.ts
+ Glob: {{target_dir}}/test/**/*.test.ts
+ ```
+
+
+
+**Create verified gap analysis**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GAP ANALYSIS RESULTS
+βββββββββββββββββββββββββββββββββββββββββββ
+
+β
IMPLEMENTED (Verified):
+{{#each implemented}}
+{{@index}}. **{{name}}**
+ - File: {{file}} β
EXISTS
+ - Status: {{status}}
+ - Tests: {{test_count}} tests
+{{/each}}
+
+β MISSING (Verified):
+{{#each missing}}
+{{@index}}. **{{name}}**
+ - Expected: {{expected_file}} β NOT FOUND
+ - Needed for: {{requirement}}
+{{/each}}
+
+β οΈ PARTIAL (Stub/Incomplete):
+{{#each partial}}
+{{@index}}. **{{name}}**
+ - File: {{file}} β
EXISTS
+ - Issue: {{issue}}
+{{/each}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+**Generate story with verified checkboxes**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GENERATING STORY
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Use story template with:
+- `[x]` for VERIFIED items (evidence: file exists, not stub, has tests)
+- `[~]` for PARTIAL items (evidence: file exists but stub/no tests)
+- `[ ]` for MISSING items (evidence: file not found)
+
+**Write story file:**
+```bash
+Write: {{story_dir}}/story-{{epic_num}}.{{story_num}}.md
+```
+
+**Validate generated story:**
+```bash
+# Check 7 sections exist
+grep "^## " {{story_file}} | wc -l
+# Should be 7
+
+# Check gap analysis section exists
+grep "Gap Analysis" {{story_file}}
+```
+
+
+
+**Update sprint-status.yaml**
+
+```bash
+Read: {{sprint_status}}
+
+# Update story status to "ready-for-dev" if was "backlog"
+# Preserve comments and structure
+
+Write: {{sprint_status}}
+```
+
+
+
+**Report completion**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
STORY REGENERATED WITH GAP ANALYSIS
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{epic_num}}.{{story_num}} - {{title}}
+File: {{story_file}}
+Sections: 7/7 β
+
+Gap Analysis Summary:
+- β
{{implemented_count}} components VERIFIED complete
+- β {{missing_count}} components VERIFIED missing
+- β οΈ {{partial_count}} components PARTIAL (stub/no tests)
+
+Checkboxes reflect VERIFIED codebase state.
+
+Next Steps:
+1. Review story for accuracy
+2. Use /dev-story to implement missing components
+3. Story provides complete context for implementation
+
+[N] Regenerate next story
+[Q] Quit
+[R] Review generated story
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**If [N]:** Loop back to initialize with next story.
+**If [R]:** Display story content, then show menu.
+
+
+
+
+
+```bash
+# Regenerate specific story
+/create-story-with-gap-analysis
+> Which story? 1.9
+
+# With explicit story file
+/create-story-with-gap-analysis story_file=docs/sprint-artifacts/story-1.9.md
+```
+
+
+
+**Story not found:** HALT with clear error.
+**Target directory not found:** Warn, scan available directories.
+**Glob/Read fails:** Log warning, count as MISSING.
+**Write fails:** Report error, display generated content.
+
+
+
+- [ ] Codebase scanned for all story requirements
+- [ ] Gap analysis generated with evidence
+- [ ] Story written with verified checkboxes
+- [ ] 7 sections present
+- [ ] Sprint status updated (if enabled)
+
diff --git a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
index 19217943..d6297e95 100644
--- a/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/workflow.yaml
@@ -14,10 +14,9 @@ story_dir: "{implementation_artifacts}"
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/create-story-with-gap-analysis"
-template: "{installed_path}/template.md"
-instructions: "{installed_path}/step-01-initialize.md"
+instructions: "{installed_path}/workflow.md"
-# Variables and inputs
+# Variables
variables:
sprint_status: "{implementation_artifacts}/sprint-status.yaml"
epics_file: "{planning_artifacts}/epics.md"
@@ -28,12 +27,6 @@ project_context: "**/project-context.md"
default_output_file: "{story_dir}/{{story_key}}.md"
-# Workflow steps (processed in order)
-steps:
- - step-01-initialize.md
- - step-02-codebase-scan.md
- - step-03-generate-story.md
-
standalone: true
web_bundle: false
diff --git a/src/modules/bmm/workflows/4-implementation/detect-ghost-features/instructions.md b/src/modules/bmm/workflows/4-implementation/detect-ghost-features/instructions.md
deleted file mode 100644
index dc113271..00000000
--- a/src/modules/bmm/workflows/4-implementation/detect-ghost-features/instructions.md
+++ /dev/null
@@ -1,625 +0,0 @@
-# Detect Ghost Features - Reverse Gap Analysis (Who You Gonna Call?)
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-
-
-
-
- Determine scan scope based on parameters:
-
-
- Read {sprint_status}
- Filter stories starting with "{{epic_number}}-"
- Store as: stories_in_scope
-
-
-
-
- Read {sprint_status}
- Get ALL story keys (exclude epics and retrospectives)
- Store as: stories_in_scope
-
-
-
-
- Set stories_in_scope = ALL stories found in {sprint_artifacts}
-
-
-
- For each story in stories_in_scope:
- Read story file
- Extract documented artifacts:
- - File List (all paths mentioned)
- - Tasks (all file/component/service names mentioned)
- - ACs (all features/functionality mentioned)
- Store in: documented_artifacts[story_key] = {files, components, services, apis, features}
-
-
-
-
-
-
-
-
-
- Use Glob to find component files:
- - **/*.component.{tsx,jsx,ts,js,vue} (Angular/Vue pattern)
- - **/components/**/*.{tsx,jsx} (React pattern)
- - **/src/**/*{Component,View,Screen,Page}.{tsx,jsx} (Named pattern)
-
- For each found component file:
- Extract component name from filename or export
- Check file size (ignore <50 lines as trivial)
- Read file to determine if it's a significant feature
-
- Store as: codebase_components = [{name, path, size, purpose}]
-
-
-
-
-
-
-
- Use Glob to find API files:
- - **/api/**/*.{ts,js} (Next.js/Express pattern)
- - **/*.controller.{ts,js} (NestJS pattern)
- - **/routes/**/*.{ts,js} (Generic routes)
-
- Use Grep to find endpoint definitions:
- - @Get|@Post|@Put|@Delete decorators (NestJS)
- - export async function GET|POST|PUT|DELETE (Next.js App Router)
- - router.get|post|put|delete (Express)
- - app.route (Flask/FastAPI if Python)
-
- For each endpoint found:
- Extract: HTTP method, path, handler name
- Read file to understand functionality
-
- Store as: codebase_apis = [{method, path, handler, file}]
-
-
-
-
-
-
-
- Use Glob to find schema files:
- - **/prisma/schema.prisma (Prisma)
- - **/*.entity.{ts,js} (TypeORM)
- - **/models/**/*.{ts,js} (Mongoose/Sequelize)
- - **/*-table.ts (Custom)
-
- Use Grep to find table definitions:
- - model (Prisma)
- - @Entity (TypeORM)
- - createTable (Migrations)
-
- For each table found:
- Extract: table name, columns, relationships
-
- Store as: codebase_tables = [{name, file, columns}]
-
-
-
-
-
-
-
- Use Glob to find service files:
- - **/*.service.{ts,js}
- - **/services/**/*.{ts,js}
- - **/*Service.{ts,js}
-
- For each service found:
- Extract: service name, key methods, dependencies
- Ignore trivial services (<100 lines)
-
- Store as: codebase_services = [{name, file, methods}]
-
-
-
-
-
-
-
-
-
- Initialize: orphaned_features = []
-
-
- For each component in codebase_components:
-
- Search all stories for mentions of:
- - Component name in File Lists
- - Component name in Task descriptions
- - Component file path in File Lists
- - Feature described by component in ACs
-
-
- Add to orphaned_features:
-
- type: "component"
- name: {{component.name}}
- path: {{component.path}}
- size: {{component.size}} lines
- purpose: {{inferred_purpose_from_code}}
- severity: "HIGH" # Significant orphan
-
-
-
-
-
-
-
-
-
-
- For each API in codebase_apis:
-
- Search all stories for mentions of:
- - Endpoint path (e.g., "/api/users")
- - HTTP method + resource (e.g., "POST users")
- - Handler file in File Lists
- - API functionality in ACs (e.g., "Users can create account")
-
-
- Add to orphaned_features:
-
- type: "api"
- method: {{api.method}}
- path: {{api.path}}
- handler: {{api.handler}}
- file: {{api.file}}
- severity: "CRITICAL" # APIs are critical functionality
-
-
-
-
-
-
- For each table in codebase_tables:
-
- Search all stories for mentions of:
- - Table name
- - Migration file in File Lists
- - Data model in Tasks
-
-
- Add to orphaned_features:
-
- type: "database"
- name: {{table.name}}
- file: {{table.file}}
- columns: {{table.columns.length}}
- severity: "HIGH" # Database changes are significant
-
-
-
-
-
-
- For each service in codebase_services:
-
- Search all stories for mentions of:
- - Service name or class name
- - Service file in File Lists
- - Service functionality in Tasks/ACs
-
-
- Add to orphaned_features:
-
- type: "service"
- name: {{service.name}}
- file: {{service.file}}
- methods: {{service.methods.length}}
- severity: "MEDIUM" # Services are business logic
-
-
-
-
-
-
-
-
-
- Group orphans by type and severity:
-
- - critical_orphans (APIs, auth, payment)
- - high_orphans (Components, DB tables, services)
- - medium_orphans (Utilities, helpers)
- - low_orphans (Config files, constants)
-
-
- Estimate complexity for each orphan:
- Based on file size, dependencies, test coverage
-
- Suggest epic assignment based on functionality:
- - Auth components β Epic focusing on authentication
- - UI components β Epic focusing on frontend
- - API endpoints β Epic for that resource type
-
-
-
-
-
-
-
- Jump to Step 7 (Generate Report)
-
-
-
-
- Jump to Step 7
-
-
-
-
- For each orphaned feature (prioritized by severity):
-
-
- Analyze orphan to understand functionality:
- - Read implementation code
- - Identify dependencies and related files
- - Determine what it does (infer from code)
- - Find tests (if any) to understand use cases
-
- Generate story draft:
-
-Story Title: "Document existing {{name}} {{type}}"
-
-Story Description:
-This is a BACKFILL STORY documenting existing functionality found in the codebase
-that was not tracked in any story (likely vibe-coded or manually added).
-
-Business Context:
-{{inferred_business_purpose_from_code}}
-
-Current State:
-β
**Implementation EXISTS:** {{file}}
-- {{description_of_what_it_does}}
-- {{key_features_or_methods}}
-{{#if has_tests}}β
Tests exist: {{test_files}}{{else}}β No tests found{{/if}}
-
-Acceptance Criteria:
-{{#each inferred_acs_from_code}}
-- [ ] {{this}}
-{{/each}}
-
-Tasks:
-- [x] {{name}} implementation (ALREADY EXISTS - {{file}})
-{{#if missing_tests}}- [ ] Add tests for {{name}}{{/if}}
-{{#if missing_docs}}- [ ] Add documentation for {{name}}{{/if}}
-- [ ] Verify functionality works as expected
-- [ ] Add to relevant epic or create new epic for backfills
-
-Definition of Done:
-- [x] Implementation exists and works
-{{#if has_tests}}- [x] Tests exist{{else}}- [ ] Tests added{{/if}}
-- [ ] Documented in story (this story)
-- [ ] Assigned to appropriate epic
-
-Story Type: BACKFILL (documenting existing code)
-
-
-
-
-
-
-
- Create backfill story automatically
-
-
-
-
-
-Create backfill story for {{name}}?
-
-**Type:** {{type}}
-**File:** {{file}}
-**Suggested Epic:** {{suggested_epic}}
-**Complexity:** {{complexity_estimate}}
-
-[Y] Yes - Create this backfill story
-[A] Auto - Create this and all remaining backfill stories
-[E] Edit - Let me adjust the story draft first
-[S] Skip - Don't create story for this orphan
-[H] Halt - Stop backfill story creation
-
-Your choice:
-
-
-
- Create backfill story file: {sprint_artifacts}/backfill-{{type}}-{{name}}.md
- Add to backfill_stories_created list
-
-
-
-
- Set auto_create = true
- Create this story and auto-create remaining
-
-
-
- Provide your adjusted story content or instructions for modifications:
- Apply user's edits to story draft
- Create modified backfill story
-
-
-
- Add to skipped_backfills list
-
-
-
-
- Exit backfill story creation loop
- Jump to Step 6
-
-
-
-
-
- Load {sprint_status} file
-
- For each created backfill story:
- Add entry: {{backfill_story_key}}: backlog # BACKFILL - documents existing {{name}}
-
- Save sprint-status.yaml
-
-
-
-
-
-
-
-
-
- Group backfill stories by suggested epic:
-
- For each suggested_epic:
-
-
-
-
- How should backfill stories be organized?
-
-
- Create epic-backfill.md in epics directory
- Update sprint-status.yaml with epic-backfill entry
- Assign all backfill stories to epic-backfill
-
-
-
- For each backfill story:
- Assign to suggested_epic in sprint-status.yaml
- Update story_key to match epic (e.g., 2-11-backfill-userprofile)
-
-
-
- Leave stories in backlog
-
-
-
-
-
-
- Write report to: {sprint_artifacts}/ghost-features-report-{{timestamp}}.md
-
- Report structure:
-
-# Ghost Features Report (Reverse Gap Analysis)
-
-**Generated:** {{timestamp}}
-**Scope:** {{scan_scope}} {{#if epic_number}}(Epic {{epic_number}}){{/if}}
-
-## Executive Summary
-
-**Codebase Artifacts Scanned:** {{total_artifacts_scanned}}
-**Stories Cross-Referenced:** {{stories_in_scope.length}}
-**Orphaned Features Found:** {{orphaned_features.length}}
-**Documentation Coverage:** {{documented_pct}}%
-**Backfill Stories Created:** {{backfill_stories_created.length}}
-
-## Orphaned Features Detail
-
-### CRITICAL Orphans ({{critical_orphans.length}})
-[Full list with files, purposes, risks]
-
-### HIGH Priority Orphans ({{high_orphans.length}})
-[Full list]
-
-### MEDIUM Priority Orphans ({{medium_orphans.length}})
-[Full list]
-
-## Backfill Stories Created
-
-{{#each backfill_stories_created}}
-- {{story_key}}: {{story_file}}
-{{/each}}
-
-## Recommendations
-
-[Epic assignment suggestions, next steps]
-
-## Appendix: Scan Methodology
-
-[How detection worked, patterns used, confidence levels]
-
-
-
-
-
-
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml b/src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml
deleted file mode 100644
index 4af6db50..00000000
--- a/src/modules/bmm/workflows/4-implementation/gap-analysis/instructions.xml
+++ /dev/null
@@ -1,367 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language}
-
-
-
- Use {{story_file}} directly
- Read COMPLETE story file
- Extract story_key from filename or metadata
-
-
-
-
-
-
- Enter story file path, story key (e.g., "1-2-auth"), or status to scan (e.g., "done", "review", "in-progress"):
-
-
- Use provided file path as {{story_file}}
- Read COMPLETE story file
- Extract story_key from filename
-
-
-
-
- Search {story_dir} for file matching pattern {{story_key}}.md
- Set {{story_file}} to found file path
- Read COMPLETE story file
-
-
-
-
-
-
-
- Load the FULL file: {{sprint_status}}
- Parse development_status section
- Find all stories where status equals {{user_input}}
-
-
-
- HALT
-
-
-
-
- Which story would you like to validate? [Enter story key or 'all']:
-
-
- Set {{batch_mode}} = true
- Store list of all story keys to validate
- Set {{story_file}} to first story in list
- Read COMPLETE story file
-
-
-
-
- Set {{story_file}} to selected story path
- Read COMPLETE story file
-
-
-
-
-
- Set {{story_file}} to found story path
- Read COMPLETE story file
-
-
-
-
-
-
- HALT
-
-
-
-
-
-
-
- π CODEBASE REALITY CHECK - Validate tasks against actual code!
-
-
-
-
- Parse story sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Status
- Extract all tasks and subtasks from story file
- Identify technical areas mentioned in tasks (files, classes, functions, services, components)
-
-
- Determine scan targets from task descriptions:
- - For "Create X" tasks: Check if X already exists
- - For "Implement Y" tasks: Search for Y functionality
- - For "Add Z" tasks: Verify Z is missing
- - For test tasks: Check for existing test files
-
- Use Glob to find relevant files matching patterns from tasks (e.g., **/*.ts, **/*.tsx, **/*.test.ts)
- Use Grep to search for specific classes, functions, or components mentioned in tasks
- Use Read to verify implementation details and functionality in key discovered files
-
-
- Document scan results:
-
- **CODEBASE REALITY:**
- β
What Exists:
- - List verified files, classes, functions, services found
- - Note implementation completeness (partial vs full)
- - Identify code that tasks claim to create but already exists
-
-
- β What's Missing:
- - List features mentioned in tasks but NOT found in codebase
- - Identify claimed implementations that don't exist
- - Note tasks marked complete but code missing
-
-
-
- For each task in the story, determine:
- - ACCURATE: Task matches reality (code exists if task is checked, missing if unchecked)
- - FALSE POSITIVE: Task checked [x] but code doesn't exist (BS detection!)
- - FALSE NEGATIVE: Task unchecked [ ] but code already exists
- - NEEDS UPDATE: Task description doesn't match current implementation
-
- Generate validation report with:
- - Tasks that are accurate
- - Tasks that are false positives (marked done but not implemented) β οΈ
- - Tasks that are false negatives (not marked but already exist)
- - Recommended task updates
-
-
-
- π SHOW TRUTH - Compare story claims vs codebase reality
-
-
-
-
-
-
-
-
-
-
-
- **What would you like to do?**
-
- Options:
- [U] Update - Apply proposed changes to story file
- [A] Audit Report - Save findings to report file without updating story
- [N] No Changes - Just show me the findings
- [R] Review Details - Show me more details about specific findings
- [C] Continue to Next - Move to next story (batch mode only)
- [Q] Quit - Exit gap analysis
-
-
-
-
- Update story file with proposed changes:
- - Uncheck false positive tasks
- - Check false negative tasks
- - Update task descriptions as needed
- - Add or update "Gap Analysis" section with findings
- - Add Change Log entry: "Gap analysis performed - tasks validated against codebase ({{date}})"
-
-
- Story has false positives. Update status to 'in-progress'? [Y/n]:
-
- Update story Status to 'in-progress'
-
- Update sprint-status.yaml status for this story to 'in-progress'
-
-
-
-
-
-
-
- Continue to next story? [Y/n]:
-
- Load next story from batch list
- Analyze next story
-
-
-
- HALT - Gap analysis complete
-
-
-
-
- Generate audit report file: {{story_dir}}/gap-analysis-report-{{story_key}}-{{date}}.md
- Include full findings, accuracy scores, recommendations
-
-
-
- Continue to next story? [Y/n]:
-
- Load next story from batch list
- Analyze next story
-
-
-
- HALT - Gap analysis complete
-
-
-
-
-
- HALT - Gap analysis complete
-
-
-
-
- Which findings would you like more details about? (specify task numbers, file names, or areas):
- Provide detailed analysis of requested areas using Read tool for deeper code inspection
- After review, re-present the decision options
- Continue based on user's subsequent choice
-
-
-
-
- Load next story from batch list
- Analyze next story
-
-
-
-
- HALT
-
-
-
-
-
- HALT
-
-
-
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.md b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.md
new file mode 100644
index 00000000..c672b0be
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.md
@@ -0,0 +1,246 @@
+# Gap Analysis v3.0 - Verify Story Tasks Against Codebase
+
+
+Validate story checkbox claims against actual codebase reality.
+Find false positives (checked but not done) and false negatives (done but unchecked).
+Interactive workflow with options to update, audit, or review.
+
+
+
+**Evidence-Based Verification**
+
+Checkboxes lie. Code doesn't.
+- Search codebase for implementation evidence
+- Check for stubs, TODOs, empty functions
+- Verify tests exist for claimed features
+- Report accuracy of story completion claims
+
+
+
+name: gap-analysis
+version: 3.0.0
+
+defaults:
+ auto_update: false
+ create_audit_report: true
+ strict_mode: false # If true, stubs count as incomplete
+
+output:
+ update_story: "Modify checkbox state to match reality"
+ audit_report: "Generate detailed gap analysis document"
+ no_changes: "Display results only"
+
+
+
+@patterns/verification.md
+@patterns/hospital-grade.md
+
+
+
+
+
+**Load and parse story file**
+
+```bash
+STORY_FILE="{{story_file}}"
+[ -f "$STORY_FILE" ] || { echo "β story_file required"; exit 1; }
+```
+
+Use Read tool on story file. Extract:
+- All `- [ ]` and `- [x]` items
+- File references from Dev Agent Record
+- Task descriptions with expected artifacts
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GAP ANALYSIS: {{story_key}}
+βββββββββββββββββββββββββββββββββββββββββββ
+Tasks: {{total_tasks}}
+Currently checked: {{checked_count}}
+```
+
+
+
+**Verify each task against codebase**
+
+For each task item:
+
+1. **Extract artifacts** - File names, component names, function names
+2. **Search codebase:**
+ ```bash
+ # Check file exists
+ Glob: {{expected_file}}
+
+ # Check function/component exists
+ Grep: "{{function_or_component_name}}"
+ ```
+
+3. **If file exists, check quality:**
+ ```bash
+ # Check for stubs
+ Grep: "TODO|FIXME|Not implemented|throw new Error" {{file}}
+
+ # Check for tests
+ Glob: {{file_base}}.test.* OR {{file_base}}.spec.*
+ ```
+
+4. **Determine status:**
+ - **VERIFIED:** File exists, not a stub, tests exist
+ - **PARTIAL:** File exists but stub/TODO or no tests
+ - **MISSING:** File does not exist
+
+
+
+**Compare claimed vs actual**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π GAP ANALYSIS RESULTS
+βββββββββββββββββββββββββββββββββββββββββββ
+Tasks analyzed: {{total}}
+
+By Status:
+- β
Verified Complete: {{verified}} ({{verified_pct}}%)
+- β οΈ Partial: {{partial}} ({{partial_pct}}%)
+- β Missing: {{missing}} ({{missing_pct}}%)
+
+Accuracy Analysis:
+- Checked & Verified: {{correct_checked}}
+- Checked but MISSING: {{false_positives}} β FALSE POSITIVES
+- Unchecked but DONE: {{false_negatives}} β FALSE NEGATIVES
+
+Checkbox Accuracy: {{accuracy}}%
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**If false positives found:**
+```
+β οΈ FALSE POSITIVES DETECTED
+The following tasks are marked done but code is missing:
+
+{{#each false_positives}}
+- [ ] {{task}} β Expected: {{expected_file}} β β NOT FOUND
+{{/each}}
+```
+
+
+
+**Ask user how to proceed**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π OPTIONS
+βββββββββββββββββββββββββββββββββββββββββββ
+[U] Update - Fix checkboxes to match reality
+[A] Audit Report - Generate detailed report file
+[N] No Changes - Display only (already done)
+[R] Review Details - Show full evidence for each task
+
+Your choice:
+```
+
+
+
+**Update story file checkboxes**
+
+For false positives:
+- Change `[x]` to `[ ]` for tasks with missing code
+
+For false negatives:
+- Change `[ ]` to `[x]` for tasks with verified code
+
+Use Edit tool to make changes.
+
+```
+β
Story checkboxes updated
+- {{fp_count}} false positives unchecked
+- {{fn_count}} false negatives checked
+- New completion: {{new_pct}}%
+```
+
+
+
+**Generate audit report**
+
+Write to: `{{story_dir}}/gap-analysis-{{story_key}}-{{timestamp}}.md`
+
+Include:
+- Executive summary
+- Detailed task-by-task evidence
+- False positive/negative lists
+- Recommendations
+
+```
+β
Audit report generated: {{report_path}}
+```
+
+
+
+**Show detailed evidence**
+
+For each task:
+```
+Task: {{task_text}}
+Checkbox: {{checked_state}}
+Evidence:
+ - File: {{file}} - {{exists ? "β
EXISTS" : "β MISSING"}}
+ {{#if exists}}
+ - Stub check: {{is_stub ? "β οΈ STUB DETECTED" : "β
Real implementation"}}
+ - Tests: {{has_tests ? "β
Tests exist" : "β No tests"}}
+ {{/if}}
+Verdict: {{status}}
+```
+
+After review, return to options menu.
+
+
+
+**Display completion**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
GAP ANALYSIS COMPLETE
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{story_key}}
+Verified Completion: {{verified_pct}}%
+Checkbox Accuracy: {{accuracy}}%
+
+{{#if updated}}
+β
Checkboxes updated to match reality
+{{/if}}
+
+{{#if report_generated}}
+π Report: {{report_path}}
+{{/if}}
+
+{{#if false_positives > 0}}
+β οΈ {{false_positives}} tasks need implementation work
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+
+
+```bash
+# Quick gap analysis of single story
+/gap-analysis story_file=docs/sprint-artifacts/2-5-auth.md
+
+# With auto-update enabled
+/gap-analysis story_file=docs/sprint-artifacts/2-5-auth.md auto_update=true
+```
+
+
+
+**Story file not found:** HALT with clear error.
+**Search fails:** Log warning, count as MISSING.
+**Edit fails:** Report error, suggest manual update.
+
+
+
+- [ ] All tasks verified against codebase
+- [ ] False positives/negatives identified
+- [ ] Accuracy metrics calculated
+- [ ] User choice executed (update/audit/review)
+
diff --git a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml
index 88417f98..07eea0a2 100644
--- a/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/gap-analysis/workflow.yaml
@@ -11,7 +11,7 @@ story_dir: "{implementation_artifacts}"
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/gap-analysis"
-instructions: "{installed_path}/instructions.xml"
+instructions: "{installed_path}/workflow.md"
# Variables
story_file: "" # User provides story file path or auto-discover
diff --git a/src/modules/bmm/workflows/4-implementation/migrate-to-github/instructions.md b/src/modules/bmm/workflows/4-implementation/migrate-to-github/instructions.md
deleted file mode 100644
index d3ccab25..00000000
--- a/src/modules/bmm/workflows/4-implementation/migrate-to-github/instructions.md
+++ /dev/null
@@ -1,957 +0,0 @@
-# Migrate to GitHub - Production-Grade Story Migration
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-RELIABILITY FIRST: This workflow prioritizes data integrity over speed
-
-
-
-
- MUST verify all prerequisites before ANY migration operations
-
-
-
-
- Test GitHub MCP connection:
- Call: mcp__github__get_me()
-
-
-
- HALT
-
-
- Extract current user info:
- - username: {{user.login}}
- - user_id: {{user.id}}
-
-
-
-
-
- Verify github_owner and github_repo parameters provided
-
-
-
- HALT
-
-
- Test repository access:
- Call: mcp__github__list_issues({
- owner: {{github_owner}},
- repo: {{github_repo}},
- per_page: 1
- })
-
-
-
- HALT
-
-
-
-
-
-
- Check sprint-status.yaml exists:
- test -f {{sprint_status}}
-
-
-
- HALT
-
-
- Read and parse sprint-status.yaml
- Count total stories to migrate
-
-
-
- Verify story files exist:
- For each story, try multiple naming patterns to find file
-
- Report:
-
-
-
-
-β οΈ {{stories_without_files}} stories have no files
-
-Options:
-[C] Continue (only migrate stories with files)
-[S] Skip these stories (add to skip list)
-[H] Halt (fix missing files first)
-
-Choice:
-
-
-
- HALT
-
-
-
-
-
- Check if state file exists: {{state_file}}
-
-
- Read migration state
- Extract: stories_migrated, issues_created, last_completed, timestamp
-
-
-
- How to proceed?
-
-
- Set resume_mode = true
- Load list of already-migrated stories
- Filter them out from migration queue
-
-
-
-
-
- Confirm fresh start (will check for duplicates)? (yes/no):
-
- HALT
-
-
-
-
- Display migration state details
- Then re-prompt for choice
-
-
-
- Delete state file
- Set resume_mode = false
-
-
-
-
-
-
-
-
-
-
- Skip to Step 2 (Execute mode)
-
-
-
-
- For each story in sprint-status.yaml:
-
- For each story_key:
-
-
- Search GitHub: mcp__github__search_issues({
- query: "repo:{{github_owner}}/{{github_repo}} label:story:{{story_key}}"
- })
-
-
- would_update = {{update_existing}}
-
-
-
-
- would_create = true
- Read local story file
- Parse: title, ACs, tasks, epic, status
-
-
-
-
-
- Count actions:
-
-
- Exit workflow (dry-run complete)
-
-
-
-
- Skip to Step 3 (Verify mode)
-
-
-
-
-
-β οΈ FINAL CONFIRMATION
-
-You are about to create ~{{would_create_count}} GitHub Issues.
-
-This operation:
-- WILL create issues in {{github_owner}}/{{github_repo}}
-- WILL modify your GitHub repository
-- CAN be rolled back (we'll create rollback manifest)
-- CANNOT be undone automatically after issues are created
-
-Have you:
-- [ ] Run dry-run mode to preview?
-- [ ] Verified repository is correct?
-- [ ] Backed up sprint-status.yaml?
-- [ ] Confirmed you want to proceed?
-
-Type "I understand and want to proceed" to continue:
-
-
-
-
- HALT
-
-
- Initialize migration state:
-
-migration_state = {
- started_at: {{timestamp}},
- mode: "execute",
- github_owner: {{github_owner}},
- github_repo: {{github_repo}},
- total_stories: {{total_stories}},
- stories_migrated: [],
- issues_created: [],
- issues_updated: [],
- issues_failed: [],
- rollback_manifest: [],
- last_completed: null
-}
-
-
- Save initial state to {{state_file}}
-
- Initialize rollback manifest (for safety):
- rollback_manifest = {
- created_at: {{timestamp}},
- github_owner: {{github_owner}},
- github_repo: {{github_repo}},
- created_issues: [] # Will track issue numbers for rollback
- }
-
- For each story in sprint-status.yaml:
-
-
-
-
- Read local story file
-
-
-
- Add to migration_state.issues_failed with reason: "File not found"
- Continue to next story
-
-
- Parse story file:
- - Extract all 12 sections
- - Parse Acceptance Criteria (convert to checkboxes)
- - Parse Tasks (convert to checkboxes)
- - Extract metadata: epic_number, complexity
-
- Check if issue already exists (idempotent check):
- Call: mcp__github__search_issues({
- query: "repo:{{github_owner}}/{{github_repo}} label:story:{{story_key}}"
- })
-
-
-
- Add to migration_state.stories_migrated (already done)
- Continue to next story
-
-
-
-
-
- ATOMIC UPDATE with retry:
-
-attempt = 0
-max_attempts = {{max_retries}} + 1
-
-WHILE attempt < max_attempts:
- TRY:
- # Update issue
- result = mcp__github__issue_write({
- method: "update",
- owner: {{github_owner}},
- repo: {{github_repo}},
- issue_number: {{existing_issue.number}},
- title: "Story {{story_key}}: {{parsed_title}}",
- body: {{convertStoryToIssueBody(parsed)}},
- labels: {{generateLabels(story_key, status, parsed)}}
- })
-
- # Verify update succeeded (read back)
- sleep 1 second # GitHub eventual consistency
-
- verification = mcp__github__issue_read({
- method: "get",
- owner: {{github_owner}},
- repo: {{github_repo}},
- issue_number: {{existing_issue.number}}
- })
-
- # Check verification
- IF verification.title != expected_title:
- THROW "Write verification failed"
-
- # Success!
- output: " β
UPDATED and VERIFIED - Issue #{{existing_issue.number}}"
- BREAK
-
- CATCH error:
- attempt++
- IF attempt < max_attempts:
- sleep {{retry_backoff_ms[attempt]}}
- output: " β οΈ Retry {{attempt}}/{{max_retries}} after error: {{error}}"
- ELSE:
- output: " β FAILED after {{max_retries}} retries: {{error}}"
- add to migration_state.issues_failed
-
- IF halt_on_critical_error:
- HALT
- ELSE:
- CONTINUE to next story
-
-
- Add to migration_state.issues_updated
-
-
-
-
-
- Generate issue body from story file:
-
-issue_body = """
-**Story File:** [{{story_key}}.md]({{file_path_in_repo}})
-**Epic:** {{epic_number}}
-**Complexity:** {{complexity}} ({{task_count}} tasks)
-
-## Business Context
-{{parsed.businessContext}}
-
-## Acceptance Criteria
-{{#each parsed.acceptanceCriteria}}
-- [ ] AC{{@index + 1}}: {{this}}
-{{/each}}
-
-## Tasks
-{{#each parsed.tasks}}
-- [ ] {{this}}
-{{/each}}
-
-## Technical Requirements
-{{parsed.technicalRequirements}}
-
-## Definition of Done
-{{#each parsed.definitionOfDone}}
-- [ ] {{this}}
-{{/each}}
-
----
-_Migrated from BMAD local files_
-_Sync timestamp: {{timestamp}}_
-_Local file: `{{story_file_path}}`_
-"""
-
-
- Generate labels:
-
-labels = [
- "type:story",
- "story:{{story_key}}",
- "status:{{current_status}}",
- "epic:{{epic_number}}",
- "complexity:{{complexity}}"
-]
-
-{{#if has_high_risk_keywords}}
-labels.push("risk:high")
-{{/if}}
-
-
- ATOMIC CREATE with retry and verification:
-
-attempt = 0
-
-WHILE attempt < max_attempts:
- TRY:
- # Create issue
- created_issue = mcp__github__issue_write({
- method: "create",
- owner: {{github_owner}},
- repo: {{github_repo}},
- title: "Story {{story_key}}: {{parsed_title}}",
- body: {{issue_body}},
- labels: {{labels}}
- })
-
- issue_number = created_issue.number
-
- # CRITICAL: Verify creation succeeded (read back)
- sleep 2 seconds # GitHub eventual consistency
-
- verification = mcp__github__issue_read({
- method: "get",
- owner: {{github_owner}},
- repo: {{github_repo}},
- issue_number: {{issue_number}}
- })
-
- # Verify all fields
- IF verification.title != expected_title:
- THROW "Title mismatch after create"
-
- IF NOT verification.labels.includes("story:{{story_key}}"):
- THROW "Story label missing after create"
-
- # Success - record for rollback capability
- output: " β
CREATED and VERIFIED - Issue #{{issue_number}}"
-
- rollback_manifest.created_issues.push({
- story_key: {{story_key}},
- issue_number: {{issue_number}},
- created_at: {{timestamp}}
- })
-
- migration_state.issues_created.push({
- story_key: {{story_key}},
- issue_number: {{issue_number}}
- })
-
- BREAK
-
- CATCH error:
- attempt++
-
- # Check if issue was created despite error (orphaned issue)
- check_result = mcp__github__search_issues({
- query: "repo:{{github_owner}}/{{github_repo}} label:story:{{story_key}}"
- })
-
- IF check_result.length > 0:
- # Issue was created, verification failed - treat as success
- output: " β
CREATED (verification had transient error)"
- BREAK
-
- IF attempt < max_attempts:
- sleep {{retry_backoff_ms[attempt]}}
- output: " β οΈ Retry {{attempt}}/{{max_retries}}"
- ELSE:
- output: " β FAILED after {{max_retries}} retries: {{error}}"
-
- migration_state.issues_failed.push({
- story_key: {{story_key}},
- error: {{error}},
- attempts: {{attempt}}
- })
-
- IF halt_on_critical_error:
- output: "HALTING - Critical error during migration"
- save migration_state
- HALT
- ELSE:
- output: "Continuing despite failure (continue_on_failure=true)"
- CONTINUE to next story
-
-
-
- Update migration state:
- migration_state.stories_migrated.push({{story_key}})
- migration_state.last_completed = {{story_key}}
-
-
- Save migration state to {{state_file}}
- Save rollback manifest to {{output_folder}}/migration-rollback-{{timestamp}}.yaml
-
-
-
-
-
-
-
-
-
- Continue to Step 3 (Verify)
-
-
-
-
- Skip to Step 4
-
-
-
-
-Migration complete. Run verification to double-check accuracy? (yes/no):
-
-
-
- Skip to Step 5 (Report)
-
-
-
-
-
- Load migration state from {{state_file}}
-
- For each migrated story in migration_state.stories_migrated:
-
- Fetch issue from GitHub:
- Search: label:story:{{story_key}}
-
-
-
- Add to verification_failures
-
-
-
- Verify fields match expected:
- - Title contains story_key β
- - Label "story:{{story_key}}" exists β
- - Status label matches sprint-status.yaml β
- - AC count matches local file β
-
-
-
-
-
-
-
-
-
- Add to verification_warnings
-
-
-
-
-
-
-
-
- Skip to Step 5 (Report)
-
-
-
-
- Load rollback manifest from {{output_folder}}/migration-rollback-*.yaml
-
-
-
- HALT
-
-
-
-
-
-Type "DELETE ALL ISSUES" to proceed with rollback:
-
-
-
-
- HALT
-
-
- For each issue in manifest.created_issues:
-
- Delete issue (GitHub API doesn't support delete, so close + lock):
-
-# GitHub doesn't allow issue deletion via API
-# Best we can do: close, lock, and add label "migrated:rolled-back"
-
-mcp__github__issue_write({
- method: "update",
- issue_number: {{issue_number}},
- state: "closed",
- labels: ["migrated:rolled-back", "do-not-use"],
- state_reason: "not_planned"
-})
-
-# Add comment explaining
-mcp__github__add_issue_comment({
- issue_number: {{issue_number}},
- body: "Issue closed - migration was rolled back. Do not use."
-})
-
-
-
-
-
-
-
-
- Calculate final statistics:
-
-final_stats = {
- total_stories: {{total_stories}},
- migrated_successfully: {{issues_created.length + issues_updated.length}},
- failed: {{issues_failed.length}},
- success_rate: ({{migrated_successfully}} / {{total_stories}}) * 100,
- duration: {{end_time - start_time}},
- avg_time_per_story: {{duration / total_stories}}
-}
-
-
-
- Write comprehensive report to {{report_path}}
-
- Report structure:
-
-# GitHub Migration Report
-
-**Date:** {{timestamp}}
-**Repository:** {{github_owner}}/{{github_repo}}
-**Mode:** {{mode}}
-
-## Executive Summary
-
-- **Total Stories:** {{total_stories}}
-- **β
Migrated:** {{migrated_successfully}} ({{success_rate}}%)
-- **β Failed:** {{failed}}
-- **Duration:** {{duration}}
-- **Avg per story:** {{avg_time_per_story}}
-
-## Created Issues
-
-{{#each issues_created}}
-- Story {{story_key}} β Issue #{{issue_number}}
- URL:
-{{/each}}
-
-## Updated Issues
-
-{{#each issues_updated}}
-- Story {{story_key}} β Issue #{{issue_number}} (updated)
-{{/each}}
-
-## Failed Migrations
-
-{{#if issues_failed.length > 0}}
-{{#each issues_failed}}
-- Story {{story_key}}: {{error}}
- Attempts: {{attempts}}
-{{/each}}
-
-**Recovery Steps:**
-1. Fix underlying issues (check error messages)
-2. Re-run migration (will skip already-migrated stories)
-{{else}}
-None - all stories migrated successfully!
-{{/if}}
-
-## Rollback Information
-
-**Rollback Manifest:** {{rollback_manifest_path}}
-
-To rollback this migration:
-```bash
-/migrate-to-github mode=rollback
-```
-
-## Next Steps
-
-1. **Verify migration:** /migrate-to-github mode=verify
-2. **Test story checkout:** /checkout-story story_key=2-5-auth
-3. **Enable GitHub sync:** Update workflow.yaml with github_sync_enabled=true
-4. **Product Owner setup:** Share GitHub Issues URL with PO team
-
-## Migration Details
-
-**API Calls Made:** ~{{total_api_calls}}
-**Rate Limit Used:** {{api_calls_used}}/5000
-**Errors Encountered:** {{error_count}}
-**Retries Performed:** {{retry_count}}
-
----
-_Generated by BMAD migrate-to-github workflow_
-
-
-
-
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/multi-agent-review/instructions.md b/src/modules/bmm/workflows/4-implementation/multi-agent-review/instructions.md
deleted file mode 100644
index bb51d72c..00000000
--- a/src/modules/bmm/workflows/4-implementation/multi-agent-review/instructions.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# Multi-Agent Code Review
-
-**Purpose:** Perform unbiased code review using multiple specialized AI agents in FRESH CONTEXT, with agent count based on story complexity.
-
-## Overview
-
-**Key Principle: FRESH CONTEXT**
-- Review happens in NEW session (not the agent that wrote the code)
-- Prevents bias from implementation decisions
-- Provides truly independent perspective
-
-**Variable Agent Count by Complexity:**
-- **MICRO** (2 agents): Security + Code Quality - Quick sanity check
-- **STANDARD** (4 agents): + Architecture + Testing - Balanced review
-- **COMPLEX** (6 agents): + Performance + Domain Expert - Comprehensive analysis
-
-**Available Specialized Agents:**
-- **Security Agent**: Identifies vulnerabilities and security risks
-- **Code Quality Agent**: Reviews style, maintainability, and best practices
-- **Architecture Agent**: Reviews system design, patterns, and structure
-- **Testing Agent**: Evaluates test coverage and quality
-- **Performance Agent**: Analyzes efficiency and optimization opportunities
-- **Domain Expert**: Validates business logic and domain constraints
-
-## Workflow
-
-### Step 1: Determine Agent Count
-
-Based on {complexity_level}:
-
-```
-If complexity_level == "micro":
- agent_count = 2
- agents = ["security", "code_quality"]
- Display: π MICRO Review (2 agents: Security + Code Quality)
-
-Else if complexity_level == "standard":
- agent_count = 4
- agents = ["security", "code_quality", "architecture", "testing"]
- Display: π STANDARD Review (4 agents: Multi-perspective)
-
-Else if complexity_level == "complex":
- agent_count = 6
- agents = ["security", "code_quality", "architecture", "testing", "performance", "domain_expert"]
- Display: π¬ COMPLEX Review (6 agents: Comprehensive analysis)
-```
-
-### Step 2: Load Story Context
-
-```bash
-# Read story file
-story_file="{story_file}"
-test -f "$story_file" || (echo "β Story file not found: $story_file" && exit 1)
-```
-
-Read the story file to understand:
-- What was supposed to be implemented
-- Acceptance criteria
-- Tasks and subtasks
-- File list
-
-### Step 3: Invoke Multi-Agent Review Skill (Fresh Context + Smart Agent Selection)
-
-**CRITICAL:** This review MUST happen in a FRESH CONTEXT (new session, different agent).
-
-**Smart Agent Selection:**
-- Skill analyzes changed files and selects MOST RELEVANT agents
-- Touching payments code? β Add financial-security agent
-- Touching auth code? β Add auth-security agent
-- Touching file uploads? β Add file-security agent
-- Touching performance-critical code? β Add performance agent
-- Agent count determined by complexity, but agents chosen by code analysis
-
-```xml
-
- {story_id}
- {base_branch}
- {agent_count}
- smart
- true
-
-```
-
-The skill will:
-1. Create fresh context (unbiased review session)
-2. Analyze changed files in the story
-3. Detect code categories (auth, payments, file handling, etc.)
-4. Select {agent_count} MOST RELEVANT specialized agents
-5. Run parallel reviews from selected agents
-6. Each agent reviews from their expertise perspective
-7. Aggregate findings with severity ratings
-8. Return comprehensive review report
-
-### Step 3: Save Review Report
-
-```bash
-# The skill returns a review report
-# Save it to: {review_report}
-```
-
-Display summary:
-```
-π€ MULTI-AGENT CODE REVIEW COMPLETE
-
-Agents Used: {agent_count}
-- Architecture Agent
-- Security Agent
-- Performance Agent
-- Testing Agent
-- Code Quality Agent
-
-Findings:
-- π΄ CRITICAL: {critical_count}
-- π HIGH: {high_count}
-- π‘ MEDIUM: {medium_count}
-- π΅ LOW: {low_count}
-- βΉοΈ INFO: {info_count}
-
-Report saved to: {review_report}
-```
-
-### Step 4: Present Findings
-
-For each finding, display:
-```
-[{severity}] {title}
-Agent: {agent_name}
-Location: {file}:{line}
-
-{description}
-
-Recommendation:
-{recommendation}
-
----
-```
-
-### Step 5: Next Steps
-
-Suggest actions based on findings:
-```
-π RECOMMENDED NEXT STEPS:
-
-If CRITICAL findings exist:
- β οΈ MUST FIX before proceeding
- - Address all critical security/correctness issues
- - Re-run review after fixes
-
-If only HIGH/MEDIUM findings:
- β
Story may proceed
- - Consider addressing high-priority items
- - Create follow-up tasks for medium items
- - Document LOW items as tech debt
-
-If only LOW/INFO findings:
- β
Code quality looks good
- - Optional: Address style/optimization suggestions
- - Proceed to completion
-```
-
-## Integration with Super-Dev-Pipeline
-
-This workflow is designed to be called from super-dev-pipeline step 7 (code review) when the story complexity is COMPLEX or when user explicitly requests multi-agent review.
-
-**When to Use:**
-- Complex stories (β₯16 tasks or high-risk keywords)
-- Stories involving security-sensitive code
-- Stories with significant architectural changes
-- When single-agent review has been inconclusive
-- User explicitly requests comprehensive review
-
-**When NOT to Use:**
-- Micro stories (β€3 tasks)
-- Standard stories with simple changes
-- Stories that passed adversarial review cleanly
-
-## Output Files
-
-- `{review_report}`: Full review findings in markdown
-- Integrated into story completion summary
-- Referenced in audit trail
-
-## Error Handling
-
-If multi-agent-review skill fails:
-- Fall back to adversarial code review
-- Log the failure reason
-- Continue pipeline with warning
diff --git a/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml b/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml
deleted file mode 100644
index 9e5b715d..00000000
--- a/src/modules/bmm/workflows/4-implementation/push-all/instructions.xml
+++ /dev/null
@@ -1,549 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language}
- π PUSH-ALL - Stage, commit, and push changes with comprehensive safety validation
-
-
- β‘ PARALLEL AGENT MODE: When {{target_files}} is provided:
- - ONLY stage and commit the specified files
- - Do NOT use `git add .` or `git add -A`
- - Use `git add [specific files]` instead
- - This prevents committing work from other parallel agents
-
- π ALL FILES MODE: When {{target_files}} is empty:
- - Stage ALL changes with `git add .`
- - Original behavior for single-agent execution
-
-
-
-
-
-
- Run git commands in parallel:
- - git status - Show modified/added/deleted/untracked files
- - git diff --stat - Show change statistics
- - git log -1 --oneline - Show recent commit for message style
- - git branch --show-current - Confirm current branch
-
- Parse git status output to identify:
- - Modified files
- - Added files
- - Deleted files
- - Untracked files
- - Total insertion/deletion counts
-
-
-
-
- HALT - No work to do
-
-
-
-
- π SAFETY CHECKS - Validate changes before committing
-
- Scan all changed files for dangerous patterns:
-
- **Secret Detection:**
- Check for files matching secret patterns:
- - .env*, *.key, *.pem, credentials.json, secrets.yaml
- - id_rsa, *.p12, *.pfx, *.cer
- - Any file containing: _API_KEY=, _SECRET=, _TOKEN= with real values (not placeholders)
-
-
- Validate API keys are placeholders only:
- β
Acceptable placeholders:
- - API_KEY=your-api-key-here
- - SECRET=placeholder
- - TOKEN=xxx
- - API_KEY=${{YOUR_KEY}}
- - SECRET_KEY=<your-key>
-
-
- β BLOCK real keys:
- - OPENAI_API_KEY=sk-proj-xxxxx (real OpenAI key)
- - AWS_SECRET_KEY=AKIA... (real AWS key)
- - STRIPE_API_KEY=sk_live_... (real Stripe key)
- - Any key with recognizable provider prefix + actual value
-
-
- **File Size Check:**
- Check for files >10MB without Git LFS configuration
-
- **Build Artifacts:**
- Check for unwanted directories/files that should be gitignored:
- - node_modules/, dist/, build/, .next/, __pycache__/, *.pyc, .venv/
- - .DS_Store, Thumbs.db, *.swp, *.tmp, *.log (in root)
- - *.class, target/, bin/ (Java)
- - vendor/ (unless dependency managed)
-
-
- **Git State:**
- Verify:
- - .gitignore exists and properly configured
- - No unresolved merge conflicts
- - Git repository initialized
-
-
-
-
-
- HALT - Cannot proceed with secrets
-
-
-
-
-
- Proceed with large files anyway? [y/n]:
-
-
-
- HALT
-
-
-
-
-
-
- Commit build artifacts anyway? [y/n]:
-
-
-
- HALT
-
-
-
-
-
-
- Push directly to {{branch_name}}? [y/n]:
-
-
-
- HALT
-
-
-
-
-
-
-
-
-
- **Proceed with commit and push?**
-
- Options:
- [yes] - Proceed with commit and push
- [no] - Cancel (leave changes unstaged)
- [review] - Show detailed diff first
-
-
-
- Execute: git diff --stat
- Execute: git diff | head -100 (show first 100 lines of changes)
-
- After reviewing, proceed with commit and push? [yes/no]:
-
-
-
-
- HALT - User cancelled
-
-
-
-
-
-
-
- Execute: git add {{target_files}}
- Execute: git status
-
-
-
-
-
- Execute: git add .
- Execute: git status
-
-
-
-
-
- π COMMIT MESSAGE - Generate conventional commit format
-
- Analyze changes to determine commit type:
- - feat: New features (new files with functionality)
- - fix: Bug fixes (fixing broken functionality)
- - docs: Documentation only (*.md, comments)
- - style: Formatting, missing semicolons (no code change)
- - refactor: Code restructuring (no feature/fix)
- - test: Adding/updating tests
- - chore: Tooling, configs, dependencies
- - perf: Performance improvements
-
- Determine scope (optional):
- - Component/feature name if changes focused on one area
- - Omit if changes span multiple areas
-
-
- Generate message summary (max 72 chars):
- - Use imperative mood: "add feature" not "added feature"
- - Lowercase except proper nouns
- - No period at end
-
-
- Generate message body (if changes >5 files):
- - List key changes as bullet points
- - Max 3-5 bullets
- - Keep concise
-
-
- Reference recent commits for style consistency
-
-
-
- **Use this commit message?**
-
- Options:
- [yes] - Use generated message
- [edit] - Let me write custom message
- [cancel] - Cancel push-all (leave staged)
-
-
-
- Enter your commit message (use conventional commit format if possible):
- Store user input as {{commit_message}}
-
-
-
-
-
- HALT
-
-
-
- Use {{generated_commit_message}} as {{commit_message}}
-
-
-
-
- Execute git commit with heredoc for multi-line message safety:
- git commit -m "$(cat <<'EOF'
-{{commit_message}}
-EOF
-)"
-
-
-
-
- HALT - Fix errors before proceeding
-
-
- Parse commit output for hash
-
-
-
-
-
-
- Execute: git push
-
-
-
-
-
- Execute: git pull --rebase
-
-
-
- HALT - Resolve conflicts manually
-
-
- Execute: git push
-
-
-
-
-
- Execute: git push -u origin {{current_branch}}
-
-
-
-
- HALT - Use PR workflow for protected branches
-
-
-
-
- HALT - Fix authentication
-
-
-
-
- HALT - Manual push required
-
-
-
-
-
-
- Execute: git log -1 --oneline --decorate
-
-
-
-
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/push-all/workflow.md b/src/modules/bmm/workflows/4-implementation/push-all/workflow.md
new file mode 100644
index 00000000..44637b79
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/push-all/workflow.md
@@ -0,0 +1,366 @@
+# Push All v3.0 - Safe Git Staging, Commit, and Push
+
+
+Safely stage, commit, and push changes with comprehensive validation.
+Detects secrets, large files, build artifacts. Handles push failures gracefully.
+Supports targeted mode for specific files (parallel agent coordination).
+
+
+
+**Safe by Default, No Surprises**
+
+- Validate BEFORE committing (secrets, size, artifacts)
+- Show exactly what will be committed
+- Handle push failures with recovery options
+- Never force push without explicit confirmation
+
+
+
+name: push-all
+version: 3.0.0
+
+modes:
+ full: "Stage all changes (default)"
+ targeted: "Only stage specified files"
+
+defaults:
+ max_file_size_kb: 500
+ check_secrets: true
+ check_build_artifacts: true
+ auto_push: false
+ allow_force_push: false
+
+secret_patterns:
+ - "AKIA[0-9A-Z]{16}" # AWS Access Key
+ - "sk-[a-zA-Z0-9]{48}" # OpenAI Key
+ - "ghp_[a-zA-Z0-9]{36}" # GitHub Personal Token
+ - "xox[baprs]-[a-zA-Z0-9-]+" # Slack Token
+ - "-----BEGIN.*PRIVATE KEY" # Private Keys
+ - "password\\s*=\\s*['\"][^'\"]{8,}" # Hardcoded passwords
+
+build_artifacts:
+ - "node_modules/"
+ - "dist/"
+ - "build/"
+ - ".next/"
+ - "*.min.js"
+ - "*.bundle.js"
+
+
+
+@patterns/hospital-grade.md
+
+
+
+
+
+**Verify git repository state**
+
+```bash
+# Check we're in a git repo
+git rev-parse --is-inside-work-tree || { echo "β Not a git repository"; exit 1; }
+
+# Get current branch
+git branch --show-current
+
+# Check for uncommitted changes
+git status --porcelain
+```
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π¦ PUSH-ALL: {{mode}} mode
+βββββββββββββββββββββββββββββββββββββββββββ
+Branch: {{branch}}
+Mode: {{mode}}
+{{#if targeted}}Files: {{file_list}}{{/if}}
+```
+
+**If no changes:**
+```
+β
Working directory clean - nothing to commit
+```
+Exit successfully.
+
+
+
+**Identify files to be staged**
+
+**Full mode:**
+```bash
+git status --porcelain | awk '{print $2}'
+```
+
+**Targeted mode:**
+Only include files specified in `target_files` parameter.
+
+**Categorize changes:**
+- New files (A)
+- Modified files (M)
+- Deleted files (D)
+- Renamed files (R)
+
+
+
+**Scan for secrets in staged content**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π SECRET SCAN
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+For each file to be staged:
+```bash
+# Check for secret patterns
+Grep: "{{pattern}}" {{file}}
+```
+
+**If secrets found:**
+```
+β POTENTIAL SECRETS DETECTED
+
+{{#each secrets}}
+File: {{file}}
+Line {{line}}: {{preview}} (pattern: {{pattern_name}})
+{{/each}}
+
+β οΈ BLOCKING COMMIT
+Remove secrets before proceeding.
+
+Options:
+[I] Ignore (I know what I'm doing)
+[E] Exclude these files
+[H] Halt
+```
+
+**If [I] selected:** Require explicit confirmation text.
+
+
+
+**Check for oversized files**
+
+```bash
+# Find files larger than max_file_size_kb
+find . -type f -size +{{max_file_size}}k -not -path "./.git/*"
+```
+
+**If large files found:**
+```
+β οΈ LARGE FILES DETECTED
+
+{{#each large_files}}
+- {{file}} ({{size_kb}}KB)
+{{/each}}
+
+Options:
+[I] Include anyway
+[E] Exclude large files
+[H] Halt
+```
+
+
+
+**Check for build artifacts**
+
+```bash
+# Check if any staged files match artifact patterns
+git status --porcelain | grep -E "{{artifact_pattern}}"
+```
+
+**If artifacts found:**
+```
+β οΈ BUILD ARTIFACTS DETECTED
+
+{{#each artifacts}}
+- {{file}}
+{{/each}}
+
+These should typically be in .gitignore.
+
+Options:
+[E] Exclude artifacts (recommended)
+[I] Include anyway
+[H] Halt
+```
+
+
+
+**Show what will be committed**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π COMMIT PREVIEW
+βββββββββββββββββββββββββββββββββββββββββββ
+Files to commit: {{count}}
+
+Added ({{added_count}}):
+{{#each added}}
+ + {{file}}
+{{/each}}
+
+Modified ({{modified_count}}):
+{{#each modified}}
+ M {{file}}
+{{/each}}
+
+Deleted ({{deleted_count}}):
+{{#each deleted}}
+ - {{file}}
+{{/each}}
+
+{{#if excluded}}
+Excluded: {{excluded_count}} files
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+**Generate or request commit message**
+
+**If commit_message provided:** Use it.
+
+**Otherwise, generate from changes:**
+```
+Analyzing changes to generate commit message...
+
+Changes detected:
+- {{summary_of_changes}}
+
+Suggested message:
+"{{generated_message}}"
+
+[Y] Use this message
+[E] Edit message
+[C] Custom message
+```
+
+If user selects [C] or [E], prompt for message.
+
+
+
+**Stage and commit changes**
+
+```bash
+# Stage files (targeted or full)
+{{#if targeted}}
+git add {{#each target_files}}{{this}} {{/each}}
+{{else}}
+git add -A
+{{/if}}
+
+# Commit with message
+git commit -m "{{commit_message}}"
+```
+
+**Verify commit:**
+```bash
+# Check commit was created
+git log -1 --oneline
+```
+
+```
+β
Commit created: {{commit_hash}}
+```
+
+
+
+**Push to remote with error handling**
+
+```bash
+git push origin {{branch}}
+```
+
+**If push fails:**
+
+**Case: Behind remote**
+```
+β οΈ Push rejected - branch is behind remote
+
+Options:
+[P] Pull and retry (git pull --rebase)
+[F] Force push (DESTRUCTIVE - overwrites remote)
+[H] Halt (commit preserved locally)
+```
+
+**Case: No upstream**
+```
+β οΈ No upstream branch
+
+Setting upstream and pushing:
+git push -u origin {{branch}}
+```
+
+**Case: Auth failure**
+```
+β Authentication failed
+
+Check:
+1. SSH key configured?
+2. Token valid?
+3. Repository access?
+```
+
+**Case: Protected branch**
+```
+β Cannot push to protected branch
+
+Use pull request workflow instead:
+gh pr create --title "{{commit_message}}"
+```
+
+
+
+**Display completion status**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
PUSH-ALL COMPLETE
+βββββββββββββββββββββββββββββββββββββββββββ
+Branch: {{branch}}
+Commit: {{commit_hash}}
+Files: {{file_count}}
+{{#if pushed}}
+Remote: β
Pushed to origin/{{branch}}
+{{else}}
+Remote: βΈοΈ Not pushed (commit preserved locally)
+{{/if}}
+
+{{#if excluded_count > 0}}
+Excluded: {{excluded_count}} files (secrets/artifacts/size)
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+
+
+```bash
+# Stage all, commit, and push
+/push-all commit_message="feat: add user authentication" auto_push=true
+
+# Targeted mode - only specific files
+/push-all mode=targeted target_files="src/auth.ts,src/auth.test.ts" commit_message="fix: auth bug"
+
+# Dry run - see what would be committed
+/push-all auto_push=false
+```
+
+
+
+**Secrets detected:** BLOCK commit, require explicit override.
+**Large files:** Warn, allow exclude or include.
+**Build artifacts:** Warn, recommend exclude.
+**Push rejected:** Offer pull/rebase, force push (with confirmation), or halt.
+**Auth failure:** Report, suggest troubleshooting.
+
+
+
+- [ ] Changes validated (secrets, size, artifacts)
+- [ ] Files staged correctly
+- [ ] Commit created with message
+- [ ] Push successful (if requested)
+- [ ] No unintended files included
+
diff --git a/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml b/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml
index 1eedfe30..5875d911 100644
--- a/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/push-all/workflow.yaml
@@ -9,7 +9,7 @@ communication_language: "{config_source}:communication_language"
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/push-all"
-instructions: "{installed_path}/instructions.xml"
+instructions: "{installed_path}/workflow.md"
# Target files to commit (for parallel agent execution)
# When empty/not provided: commits ALL changes (original behavior)
diff --git a/src/modules/bmm/workflows/4-implementation/recover-sprint-status/instructions.md b/src/modules/bmm/workflows/4-implementation/recover-sprint-status/instructions.md
deleted file mode 100644
index 7ec69cd7..00000000
--- a/src/modules/bmm/workflows/4-implementation/recover-sprint-status/instructions.md
+++ /dev/null
@@ -1,306 +0,0 @@
-# Sprint Status Recovery - Instructions
-
-**Workflow:** recover-sprint-status
-**Purpose:** Fix sprint-status.yaml when tracking has drifted for days/weeks
-
----
-
-## What This Workflow Does
-
-Analyzes multiple sources to rebuild accurate sprint-status.yaml:
-
-1. **Story File Quality** - Validates size (>=10KB), task lists, checkboxes
-2. **Explicit Status: Fields** - Reads story Status: when present
-3. **Git Commits** - Searches last 30 days for story references
-4. **Autonomous Reports** - Checks .epic-*-completion-report.md files
-5. **Task Completion Rate** - Analyzes checkbox completion in story files
-
-**Infers Status Based On:**
-- Explicit Status: field (highest priority)
-- Git commits referencing story (strong signal)
-- Autonomous completion reports (very high confidence)
-- Task checkbox completion rate (90%+ = done)
-- File quality (poor quality prevents "done" marking)
-
----
-
-## Step 1: Run Recovery Analysis
-
-```bash
-Execute: {recovery_script} --dry-run
-```
-
-**This will:**
-- Analyze all story files (quality, tasks, status)
-- Search git commits for completion evidence
-- Check autonomous completion reports
-- Infer status from all evidence
-- Report recommendations with confidence levels
-
-**No changes** made in dry-run mode - just analysis.
-
----
-
-## Step 2: Review Recommendations
-
-**Check the output for:**
-
-### High Confidence Updates (Safe)
-- Stories with explicit Status: fields
-- Stories in autonomous completion reports
-- Stories with 3+ git commits + 90%+ tasks complete
-
-### Medium Confidence Updates (Verify)
-- Stories with 1-2 git commits
-- Stories with 50-90% tasks complete
-- Stories with file size >=10KB
-
-### Low Confidence Updates (Question)
-- Stories with no Status: field, no commits
-- Stories with file size <10KB
-- Stories with <5 tasks total
-
----
-
-## Step 3: Choose Recovery Mode
-
-### Conservative Mode (Safest)
-```bash
-Execute: {recovery_script} --conservative
-```
-
-**Only updates:**
-- High/very high confidence stories
-- Explicit Status: fields honored
-- Git commits with 3+ references
-- Won't infer or guess
-
-**Best for:** Quick fixes, first-time recovery, risk-averse
-
----
-
-### Aggressive Mode (Thorough)
-```bash
-Execute: {recovery_script} --aggressive --dry-run # Preview first!
-Execute: {recovery_script} --aggressive # Then apply
-```
-
-**Updates:**
-- Medium+ confidence stories
-- Infers from git commits (even 1 commit)
-- Uses task completion rate
-- Pre-fills brownfield checkboxes
-
-**Best for:** Major drift (30+ days), comprehensive recovery
-
----
-
-### Interactive Mode (Recommended)
-```bash
-Execute: {recovery_script}
-```
-
-**Process:**
-1. Shows all recommendations
-2. Groups by confidence level
-3. Asks for confirmation before each batch
-4. Allows selective application
-
-**Best for:** First-time use, learning the tool
-
----
-
-## Step 4: Validate Results
-
-```bash
-Execute: ./scripts/sync-sprint-status.sh --validate
-```
-
-**Should show:**
-- "β sprint-status.yaml is up to date!" (success)
-- OR discrepancy count (if issues remain)
-
----
-
-## Step 5: Commit Changes
-
-```bash
-git add docs/sprint-artifacts/sprint-status.yaml
-git add .sprint-status-backups/ # Include backup for audit trail
-git commit -m "fix(tracking): Recover sprint-status.yaml - {MODE} recovery"
-```
-
----
-
-## Recovery Scenarios
-
-### Scenario 1: Autonomous Epic Completed, Tracking Not Updated
-
-**Symptoms:**
-- Autonomous completion report exists
-- Git commits show work done
-- sprint-status.yaml shows "in-progress" or "backlog"
-
-**Solution:**
-```bash
-{recovery_script} --aggressive
-# Will find completion report, mark all stories done
-```
-
----
-
-### Scenario 2: Manual Work Over Past Week Not Tracked
-
-**Symptoms:**
-- Story Status: fields updated to "done"
-- sprint-status.yaml not synced
-- Git commits exist
-
-**Solution:**
-```bash
-./scripts/sync-sprint-status.sh
-# Standard sync (reads Status: fields)
-```
-
----
-
-### Scenario 3: Story Files Missing Status: Fields
-
-**Symptoms:**
-- 100+ stories with no Status: field
-- Some completed, some not
-- No autonomous reports
-
-**Solution:**
-```bash
-{recovery_script} --aggressive --dry-run # Preview inference
-# Review recommendations carefully
-{recovery_script} --aggressive # Apply if satisfied
-```
-
----
-
-### Scenario 4: Complete Chaos (Mix of All Above)
-
-**Symptoms:**
-- Some stories have Status:, some don't
-- Autonomous reports for some epics
-- Manual work on others
-- sprint-status.yaml very outdated
-
-**Solution:**
-```bash
-# Step 1: Run recovery in dry-run
-{recovery_script} --aggressive --dry-run
-
-# Step 2: Review /tmp/recovery_results.json
-
-# Step 3: Apply in conservative mode first (safest updates)
-{recovery_script} --conservative
-
-# Step 4: Manually review remaining stories
-# Update Status: fields for known completed work
-
-# Step 5: Run sync to catch manual updates
-./scripts/sync-sprint-status.sh
-
-# Step 6: Final validation
-./scripts/sync-sprint-status.sh --validate
-```
-
----
-
-## Quality Gates
-
-**Recovery script will DOWNGRADE status if:**
-- Story file < 10KB (not properly detailed)
-- Story file has < 5 tasks (incomplete story)
-- No git commits found (no evidence of work)
-- Explicit Status: contradicts other evidence
-
-**Recovery script will UPGRADE status if:**
-- Autonomous completion report lists story as done
-- 3+ git commits + 90%+ tasks checked
-- Explicit Status: field says "done"
-
----
-
-## Post-Recovery Checklist
-
-After running recovery:
-
-- [ ] Run validation: `./scripts/sync-sprint-status.sh --validate`
-- [ ] Review backup: Check `.sprint-status-backups/` for before state
-- [ ] Check epic statuses: Verify epic-level status matches story completion
-- [ ] Spot-check 5-10 stories: Confirm inferred status is accurate
-- [ ] Commit changes: Add recovery to version control
-- [ ] Document issues: Note why drift occurred, prevent recurrence
-
----
-
-## Preventing Future Drift
-
-**After recovery:**
-
-1. **Use workflows properly**
- - `/create-story` - Adds to sprint-status.yaml automatically
- - `/dev-story` - Updates both Status: and sprint-status.yaml
- - Autonomous workflows - Now update tracking
-
-2. **Run sync regularly**
- - Weekly: `pnpm sync:sprint-status:dry-run` (check health)
- - After manual Status: updates: `pnpm sync:sprint-status`
-
-3. **CI/CD validation** (coming soon)
- - Blocks PRs with out-of-sync tracking
- - Forces sync before merge
-
----
-
-## Troubleshooting
-
-### "Recovery script shows 0 updates"
-
-**Possible causes:**
-- sprint-status.yaml already accurate
-- Story files all have proper Status: fields
-- No git commits found (check date range)
-
-**Action:** Run `--dry-run` to see analysis, check `/tmp/recovery_results.json`
-
----
-
-### "Low confidence on stories I know are done"
-
-**Possible causes:**
-- Story file < 10KB (not properly detailed)
-- No git commits (work done outside git)
-- No explicit Status: field
-
-**Action:** Manually add Status: field to story, then run standard sync
-
----
-
-### "Recovery marks incomplete stories as done"
-
-**Possible causes:**
-- Git commits exist but work abandoned
-- Autonomous report lists story but implementation failed
-- Tasks pre-checked incorrectly (brownfield error)
-
-**Action:** Use conservative mode, manually verify, fix story files
-
----
-
-## Output Files
-
-**Created during recovery:**
-- `.sprint-status-backups/sprint-status-recovery-{timestamp}.yaml` - Backup
-- `/tmp/recovery_results.json` - Detailed analysis
-- Updated `sprint-status.yaml` - Recovered status
-
----
-
-**Last Updated:** 2026-01-02
-**Status:** Production Ready
-**Works On:** ANY BMAD project with sprint-status.yaml tracking
diff --git a/src/modules/bmm/workflows/4-implementation/revalidate-epic/instructions.md b/src/modules/bmm/workflows/4-implementation/revalidate-epic/instructions.md
deleted file mode 100644
index e229e944..00000000
--- a/src/modules/bmm/workflows/4-implementation/revalidate-epic/instructions.md
+++ /dev/null
@@ -1,273 +0,0 @@
-# Revalidate Epic - Batch Story Revalidation with Semaphore Pattern
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-
-
-
-
- Verify epic_number parameter provided
-
-
-
- HALT
-
-
- Read {sprint_status} file
- Parse development_status map
-
- Filter stories starting with "{{epic_number}}-" (e.g., "2-1-", "2-2-", etc.)
- Exclude epics (keys starting with "epic-") and retrospectives
-
- Store as: epic_stories (list of story keys)
-
-
-
- HALT
-
-
-
-
- Proceed with revalidation? (yes/no):
-
-
-
- Exit workflow
-
-
-
-
-
-
- Initialize worker pool state:
-
- - story_queue = epic_stories
- - active_workers = {}
- - completed_stories = []
- - failed_stories = []
- - verification_results = {}
- - next_story_index = 0
- - max_workers = {{max_concurrent}}
-
-
- Fill initial worker slots:
-
- While next_story_index < min(max_workers, story_queue.length):
-
-
- story_key = story_queue[next_story_index]
- story_file = {sprint_artifacts}/{{story_key}}.md # Try multiple naming patterns if needed
- worker_id = next_story_index + 1
-
- Spawn Task agent:
- - subagent_type: "general-purpose"
- - description: "Revalidate story {{story_key}}"
- - prompt: "Execute revalidate-story workflow for {{story_key}}.
-
- CRITICAL INSTRUCTIONS:
- 1. Load workflow: _bmad/bmm/workflows/4-implementation/revalidate-story/workflow.yaml
- 2. Parameters: story_file={{story_file}}, fill_gaps={{fill_gaps}}
- 3. Clear all checkboxes
- 4. Verify each AC/Task/DoD against codebase
- 5. Re-check verified items
- 6. Report gaps
- {{#if fill_gaps}}7. Fill gaps and commit{{/if}}
- 8. Return verification summary"
- - run_in_background: true
-
- Store in active_workers[worker_id]:
- story_key: {{story_key}}
- task_id: {{returned_task_id}}
- started_at: {{timestamp}}
-
-
- Increment next_story_index
-
-
-
-
-
- SEMAPHORE PATTERN: Keep {{max_workers}} agents running continuously
-
- While active_workers.size > 0 OR next_story_index < story_queue.length:
-
- Poll for completed workers (non-blocking):
-
- For each worker_id in active_workers:
-
- Check worker status using TaskOutput(task_id, block=false)
-
-
- Get verification results from worker output
- Parse: verified_pct, gaps_found, gaps_filled
-
- Store in verification_results[story_key]
- Add to completed_stories
- Remove from active_workers
-
-
-
-
- Refill slot with next story (same pattern as batch-super-dev)
-
-
-
-
-
- Add to failed_stories with error
- Remove from active_workers
-
-
-
- Refill slot despite failure
-
-
-
- Display live progress every 30 seconds:
-
-
- Sleep 5 seconds before next poll
-
-
-
- Aggregate verification results across all stories:
-
- epic_total_items = sum of all items across stories
- epic_verified = sum of verified items
- epic_partial = sum of partial items
- epic_missing = sum of missing items
- epic_gaps_filled = sum of gaps filled
-
- epic_verified_pct = (epic_verified / epic_total_items) Γ 100
-
-
- Group stories by verification percentage:
-
- - complete_stories (β₯95% verified)
- - mostly_complete_stories (80-94% verified)
- - partial_stories (50-79% verified)
- - incomplete_stories (<50% verified)
-
-
-
-
-
- Write epic summary to: {sprint_artifacts}/revalidation-epic-{{epic_number}}-{{timestamp}}.md
-
-
-
-
- Update sprint-status.yaml with revalidation timestamp and results
- Add comment to epic entry: # Revalidated: {{epic_verified_pct}}% verified ({{timestamp}})
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/revalidate-story/instructions.md b/src/modules/bmm/workflows/4-implementation/revalidate-story/instructions.md
deleted file mode 100644
index f5135606..00000000
--- a/src/modules/bmm/workflows/4-implementation/revalidate-story/instructions.md
+++ /dev/null
@@ -1,510 +0,0 @@
-# Revalidate Story - Verify Checkboxes Against Codebase Reality
-
-The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
-You MUST have already loaded and processed: {installed_path}/workflow.yaml
-
-
-
-
- Verify story_file parameter provided
-
-
-
- HALT
-
-
- Read COMPLETE story file: {{story_file}}
- Parse sections: Acceptance Criteria, Tasks/Subtasks, Definition of Done, Dev Agent Record
-
- Extract story_key from filename (e.g., "2-7-image-file-handling")
-
- Create backup of current checkbox state:
- Count currently checked items:
- - ac_checked_before = count of [x] in Acceptance Criteria
- - tasks_checked_before = count of [x] in Tasks/Subtasks
- - dod_checked_before = count of [x] in Definition of Done
- - total_checked_before = sum of above
-
-
-
-
-
-
-
-
- Use Edit tool to replace all [x] with [ ] in Acceptance Criteria section
- Use Edit tool to replace all [x] with [ ] in Tasks/Subtasks section
- Use Edit tool to replace all [x] with [ ] in Definition of Done section
-
- Save story file with all boxes unchecked
-
-
-
-
-
-
-
- Extract all AC items from Acceptance Criteria section
-
- For each AC item:
-
-
- Extract AC description and identify artifacts:
- - File mentions (e.g., "UserProfile component")
- - Function names (e.g., "updateUser function")
- - Features (e.g., "dark mode toggle")
- - Test requirements (e.g., "unit tests covering edge cases")
-
-
-
-
-
-
- Use Glob to find relevant files:
- - If AC mentions specific file: glob for that file
- - If AC mentions component: glob for **/*ComponentName*
- - If AC mentions feature: glob for files in related directories
-
-
- Use Grep to search for symbols/functions/features
-
- Read found files to verify:
- - NOT a stub (check for "TODO", "Not implemented", "throw new Error")
- - Has actual implementation (not just empty function)
- - Tests exist (search for *.test.* or *.spec.* files)
- - Tests pass (if --fill-gaps mode, run tests)
-
-
-
-
- verification_status = VERIFIED
- Check box [x] in story file for this AC
- Record evidence: "β
VERIFIED: {{files_found}}, tests: {{test_files}}"
-
-
-
-
- verification_status = PARTIAL
- Check box [~] in story file for this AC
- Record gap: "πΆ PARTIAL: {{what_exists}}, missing: {{what_is_missing}}"
-
- Add to gaps_list with details
-
-
-
- verification_status = MISSING
- Leave box unchecked [ ] in story file
- Record gap: "β MISSING: No implementation found for {{ac_description}}"
-
- Add to gaps_list with details
-
-
-
- Save story file after each AC verification
-
-
-
-
-
-
-
- Extract all Task items from Tasks/Subtasks section
-
- For each Task item (same verification logic as ACs):
-
- Parse task description for artifacts
- Search codebase with Glob/Grep
- Read and verify (check for stubs, tests)
- Determine status: VERIFIED | PARTIAL | MISSING
- Update checkbox: [x] | [~] | [ ]
- Record evidence or gap
- Save story file
-
-
-
-
-
-
-
- Extract all DoD items from Definition of Done section
-
- For each DoD item:
-
- Parse DoD requirement:
- - "Type check passes" β Run type checker
- - "Unit tests 90%+ coverage" β Run coverage report
- - "Linting clean" β Run linter
- - "Build succeeds" β Run build
- - "All tests pass" β Run test suite
-
-
- Execute verification for this DoD item
-
-
- Check box [x]
- Record: "β
VERIFIED: {{verification_result}}"
-
-
-
- Leave unchecked [ ] or partial [~]
- Record gap if applicable
-
-
-
-
-
-
- Calculate overall completion:
-
- total_verified = ac_verified + tasks_verified + dod_verified
- total_partial = ac_partial + tasks_partial + dod_partial
- total_missing = ac_missing + tasks_missing + dod_missing
- total_items = ac_total + tasks_total + dod_total
-
- verified_pct = (total_verified / total_items) Γ 100
- completion_pct = ((total_verified + total_partial) / total_items) Γ 100
-
-
-
-
-
- Write detailed report to: {sprint_artifacts}/revalidation-{{story_key}}-{{timestamp}}.md
- Include: verification results, gaps list, evidence for each item, recommendations
-
-
-
-
-
-
-
- Exit workflow
-
-
-
-
- Exit workflow
-
-
-
-
-
- HALT
-
-
-
-
- Continue to Step 8
-
-
-
-
- For each gap in gaps_list:
-
-
-
-
-Fill this gap?
-
-**Item:** {{item_description}}
-**Type:** {{item_type}} ({{section}})
-**Missing:** {{what_is_missing}}
-
-[Y] Yes - Implement this item
-[A] Auto-fill - Implement this and all remaining gaps without asking
-[S] Skip - Leave this gap unfilled
-[H] Halt - Stop gap filling
-
-Your choice:
-
-
-
- Set require_confirmation = false (auto-fill remaining)
-
-
-
- Continue to next gap
-
-
-
- Exit gap filling loop
- Jump to Step 9 (Summary)
-
-
-
-
-
-
-
- Load story context (Technical Requirements, Architecture Compliance, Dev Notes)
- Implement missing item following story specifications
- Write tests if required
- Run tests to verify implementation
- Verify linting/type checking passes
-
-
- Check box [x] for this item in story file
- Update File List with new/modified files
- Add to Dev Agent Record: "Gap filled: {{item_description}}"
-
-
-
- Stage files for this gap
- Commit: "fix({{story_key}}): fill gap - {{item_description}}"
-
-
-
-
-
-
- Leave box unchecked
- Record failure in gaps_list
- Add to failed_gaps
-
-
-
- After all gaps processed:
-
-
-
-
-
-
-
- For each filled gap:
- Re-run verification for that item
- Ensure still VERIFIED after all changes
-
-
-
-
- Calculate final completion:
-
- final_verified = count of [x] across all sections
- final_partial = count of [~] across all sections
- final_missing = count of [ ] across all sections
- final_pct = (final_verified / total_items) Γ 100
-
-
-
- Stage all changed files
- Commit: "fix({{story_key}}): fill {{gaps_filled}} gaps from revalidation"
-
-
-
-
- Load {sprint_status} file
- Update entry with current progress:
- Format: {{story_key}}: {{current_status}} # Revalidated: {{final_verified}}/{{total_items}} ({{final_pct}}%) verified
- Save sprint-status.yaml
-
-
-
-
- Add to Dev Agent Record in story file:
-
-## Revalidation Record ({{timestamp}})
-
-**Revalidation Mode:** {{#if fill_gaps}}Verify & Fill{{else}}Verify Only{{/if}}
-
-**Results:**
-- Verified: {{final_verified}}/{{total_items}} ({{final_pct}}%)
-- Gaps Found: {{total_missing}}
-- Gaps Filled: {{gaps_filled}}
-
-**Evidence:**
-{{#each verification_evidence}}
-- {{item}}: {{evidence}}
-{{/each}}
-
-{{#if gaps_filled > 0}}
-**Gaps Filled:**
-{{#each filled_gaps}}
-- {{item}}: {{what_was_implemented}}
-{{/each}}
-{{/if}}
-
-{{#if failed_gaps.length > 0}}
-**Failed to Fill:**
-{{#each failed_gaps}}
-- {{item}}: {{error}}
-{{/each}}
-{{/if}}
-
- Save story file
-
-
-
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/README.md b/src/modules/bmm/workflows/4-implementation/super-dev-story/README.md
deleted file mode 100644
index 77786969..00000000
--- a/src/modules/bmm/workflows/4-implementation/super-dev-story/README.md
+++ /dev/null
@@ -1,283 +0,0 @@
-# Super-Dev-Story Workflow
-
-**Enhanced story development with comprehensive quality validation**
-
-## What It Does
-
-Super-dev-story is `/dev-story` on steroids - it includes ALL standard development steps PLUS additional quality gates:
-
-```
-Standard dev-story:
- 1-8. Development cycle β Mark "review"
-
-Super-dev-story:
- 1-8. Development cycle
- 9.5. Post-dev gap analysis (verify work complete)
- 9.6. Automated code review (catch issues)
- β Fix issues if found (loop back to step 5)
- 9. Mark "review" (only after all validation passes)
-```
-
-## When to Use
-
-### Use `/super-dev-story` for:
-
-- β
Security-critical features (auth, payments, PII handling)
-- β
Complex business logic with many edge cases
-- β
Stories you want bulletproof before human review
-- β
High-stakes features (production releases, customer-facing)
-- β
When you want to minimize review cycles
-
-### Use standard `/dev-story` for:
-
-- Documentation updates
-- Simple UI tweaks
-- Configuration changes
-- Low-risk experimental features
-- When speed matters more than extra validation
-
-## Cost vs Benefit
-
-| Aspect | dev-story | super-dev-story |
-|--------|-----------|-----------------|
-| **Tokens** | 50K-100K | 80K-150K (+30-50%) |
-| **Time** | Normal | +20-30% |
-| **Quality** | Good | Excellent |
-| **Review cycles** | 1-3 iterations | 0-1 iterations |
-| **False completions** | Possible | Prevented |
-
-**ROI:** Extra 30K tokens (~$0.09) prevents hours of rework and multiple review cycles
-
-## What Gets Validated
-
-### Step 9.5: Post-Dev Gap Analysis
-
-**Checks:**
-- Tasks marked [x] β Code actually exists and works?
-- Required files β Actually created?
-- Claimed tests β Actually exist and pass?
-- Partial implementations β Marked complete prematurely?
-
-**Catches:**
-- β "Created auth service" β File doesn't exist
-- β "Added tests with 90% coverage" β Only 60% actual
-- β "Implemented login" β Function exists but incomplete
-
-**Actions if issues found:**
-- Unchecks false positive tasks
-- Adds tasks for missing work
-- Loops back to implementation
-
-### Step 9.6: Automated Code Review
-
-**Reviews:**
-- β
Correctness (logic errors, edge cases)
-- β
Security (vulnerabilities, input validation)
-- β
Architecture (pattern compliance, SOLID principles)
-- β
Performance (inefficiencies, optimization opportunities)
-- β
Testing (coverage gaps, test quality)
-- β
Code Quality (readability, maintainability)
-
-**Actions if issues found:**
-- Adds review findings as tasks
-- Loops back to implementation
-- Continues until issues resolved
-
-## Usage
-
-### Basic Usage
-
-```bash
-# Load any BMAD agent
-/super-dev-story
-
-# Follows same flow as dev-story, with extra validation
-```
-
-### Specify Story
-
-```bash
-/super-dev-story _bmad-output/implementation-artifacts/story-1.2.md
-```
-
-### Expected Flow
-
-```
-1. Pre-dev gap analysis
- ββ "Approve task updates? [Y/A/n/e/s/r]"
- ββ Select option
-
-2. Development (standard TDD cycle)
- ββ Implements all tasks
-
-3. Post-dev gap analysis
- ββ Scans codebase
- ββ If gaps: adds tasks, loops back
- ββ If clean: proceeds
-
-4. Code review
- ββ Analyzes all changes
- ββ If issues: adds tasks, loops back
- ββ If clean: proceeds
-
-5. Story marked "review"
- ββ Truly complete!
-```
-
-## Fix Iteration Safety
-
-Super-dev has a **max iteration limit** (default: 3) to prevent infinite loops:
-
-```yaml
-# workflow.yaml
-super_dev_settings:
- max_fix_iterations: 3 # Stop after 3 fix cycles
- fail_on_critical_issues: true # HALT if critical security issues
-```
-
-If exceeded:
-```
-π Maximum Fix Iterations Reached
-
-Attempted 3 fix cycles.
-Manual intervention required.
-
-Issues remaining:
-- [List of unresolved issues]
-```
-
-## Examples
-
-### Example 1: Perfect First Try
-
-```
-/super-dev-story
-
-Pre-gap: β
Tasks accurate
-Development: β
8 tasks completed
-Post-gap: β
All work verified
-Code review: β
No issues
-
-β Story complete! (45 minutes, 85K tokens)
-```
-
-### Example 2: Post-Dev Catches Incomplete Work
-
-```
-/super-dev-story
-
-Pre-gap: β
Tasks accurate
-Development: β
8 tasks completed
-Post-gap: β οΈ Tests claim 90% coverage, actual 65%
-
-β Adds task: "Increase test coverage to 90%"
-β Implements missing tests
-β Post-gap: β
Now 92% coverage
-β Code review: β
No issues
-
-β Story complete! (52 minutes, 95K tokens)
-```
-
-### Example 3: Code Review Finds Security Issue
-
-```
-/super-dev-story
-
-Pre-gap: β
Tasks accurate
-Development: β
10 tasks completed
-Post-gap: β
All work verified
-Code review: π¨ CRITICAL - SQL injection vulnerability
-
-β Adds task: "Fix SQL injection in user search"
-β Implements parameterized queries
-β Post-gap: β
Verified
-β Code review: β
Security issue resolved
-
-β Story complete! (58 minutes, 110K tokens)
-```
-
-## Comparison to Standard Workflow
-
-### Standard Flow (dev-story)
-
-```
-Day 1: Develop story (30 min)
-Day 2: Human review finds 3 issues
-Day 3: Fix issues (20 min)
-Day 4: Human review again
-Day 5: Approved
-
-Total: 5 days, 2 review cycles
-```
-
-### Super-Dev Flow
-
-```
-Day 1: Super-dev-story
- - Development (30 min)
- - Post-gap finds 1 issue (auto-fix 5 min)
- - Code review finds 2 issues (auto-fix 15 min)
- - Complete (50 min total)
-
-Day 2: Human review
-Day 3: Approved (minimal/no changes needed)
-
-Total: 3 days, 1 review cycle
-```
-
-**Savings:** 2 days, 1 fewer review cycle, higher initial quality
-
-## Troubleshooting
-
-### "Super-dev keeps looping forever"
-
-**Cause:** Each validation finds new issues
-**Solution:** This indicates quality problems. Review max_fix_iterations setting or manually intervene.
-
-### "Post-dev gap analysis keeps failing"
-
-**Cause:** Dev agent marking tasks complete prematurely
-**Solution:** This is expected! Super-dev catches this. The loop ensures actual completion.
-
-### "Code review too strict"
-
-**Cause:** Reviewing for issues standard dev-story would miss
-**Solution:** This is intentional. For less strict review, use standard dev-story.
-
-### "Too many tokens/too slow"
-
-**Cause:** Multi-stage validation adds overhead
-**Solution:** Use standard dev-story for non-critical stories. Reserve super-dev for important work.
-
-## Best Practices
-
-1. **Reserve for important stories** - Don't use for trivial changes
-2. **Trust the process** - Fix iterations mean it's working correctly
-3. **Review limits** - Adjust max_fix_iterations if stories are complex
-4. **Monitor costs** - Track token usage vs review cycle savings
-5. **Learn patterns** - Code review findings inform future architecture
-
-## Configuration Reference
-
-```yaml
-# _bmad/bmm/config.yaml or _bmad/bmgd/config.yaml
-
-# Per-project settings
-super_dev_settings:
- post_dev_gap_analysis: true # Enable post-dev validation
- auto_code_review: true # Enable automatic code review
- fail_on_critical_issues: true # HALT on security vulnerabilities
- max_fix_iterations: 3 # Maximum fix cycles before manual intervention
- auto_fix_minor_issues: false # Auto-fix LOW severity without asking
-```
-
-## See Also
-
-- [dev-story workflow](../dev-story/) - Standard development workflow
-- [gap-analysis workflow](../gap-analysis/) - Standalone audit tool
-- [Gap Analysis Guide](../../../../docs/gap-analysis.md) - Complete documentation
-- [Super-Dev Mode Concept](../../../../docs/super-dev-mode.md) - Vision and roadmap
-
----
-
-**Super-Dev-Story: Because "done" should mean DONE** β
diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml b/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml
deleted file mode 100644
index b296847a..00000000
--- a/src/modules/bmm/workflows/4-implementation/super-dev-story/instructions.xml
+++ /dev/null
@@ -1,299 +0,0 @@
-
- The workflow execution engine is governed by: {project-root}/_bmad/core/tasks/workflow.xml
- You MUST have already loaded and processed: {installed_path}/workflow.yaml
- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
- Generate all documents in {document_output_language}
- π SUPER-DEV MODE: Enhanced quality workflow with post-implementation validation and automated code review
- This workflow orchestrates existing workflows with additional validation steps
-
-
-
-
-
-
- π― RUN DEV-STORY - Complete all standard development steps
- This includes: story loading, pre-dev gap analysis, development, testing, and task completion
-
-
-
-
-
-
- Pass through any user-provided story file path and auto-accept setting
-
-
-
-
-
-
-
-
- HALT - dev-story must complete first
-
-
-
-
-
-
-
-
- π POST-DEV VALIDATION - Verify all work actually completed!
- This catches incomplete implementations that were prematurely marked done
-
-
-
-
- Re-read story file to get requirements and tasks
- Extract all tasks marked [x] complete
- For each completed task, identify what should exist in codebase
-
-
- Use Glob to find files that should have been created
- Use Grep to search for functions/classes that should exist
- Use Read to verify implementation completeness (not just existence)
- Run tests to verify claimed test coverage actually exists and passes
-
-
- Compare claimed work vs actual implementation:
-
- **POST-DEV VERIFICATION:**
- β
Verified Complete:
- - List tasks where code fully exists and works
- - Confirm tests exist and pass
- - Verify implementation matches requirements
-
-
- β False Positives Detected:
- - List tasks marked [x] but code missing or incomplete
- - Identify claimed tests that don't exist or fail
- - Note partial implementations marked as complete
-
-
-
-
-
-
- Uncheck false positive tasks in story file
- Add new tasks for missing work
- Update Gap Analysis section with post-dev findings
-
-
-
-
-
-
- Resume with added tasks for missing work
-
-
-
-
-
-
-
- Update Gap Analysis section with post-dev verification results
-
-
-
-
-
-
-
-
- π AUTO CODE REVIEW - Independent quality validation
-
-
-
-
-
- Run code review on completed story
-
-
- Parse code review results from story file "Code Review" section
- Extract issues by severity (Critical, High, Medium, Low)
- Count total issues found
-
-
-
-
- Add code review findings as tasks in story file
-
-
-
-
- Fix code review issues
-
-
-
-
-
-
-
-
- Auto-fix these minor issues? [Y/n/skip]:
-
-
- Add review findings as tasks
-
-
-
-
-
-
-
- Document issues in story file
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- π PUSH-ALL - Stage, commit, and push with safety validation
- β‘ TARGETED COMMIT: Only commit files from THIS story's File List (safe for parallel agents)
-
-
- Read story file and extract the "File List" section
- Parse all file paths listed (relative to repo root)
- Also include the story file itself in the list
- Store as {{story_files}} - space-separated list of all files
-
-
-
-
-
-
- Only commit files changed by this story
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Based on {user_skill_level}, ask if user needs explanations about implementation, decisions, or findings
-
-
- Provide clear, contextual explanations
-
-
-
-
-
-
diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.md b/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.md
new file mode 100644
index 00000000..20dcfea4
--- /dev/null
+++ b/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.md
@@ -0,0 +1,311 @@
+# Super Dev Story v3.0 - Development with Quality Gates
+
+
+Complete story development pipeline: dev-story β validation β code review β push.
+Automatically re-invokes dev-story if gaps or review issues found.
+Ensures production-ready code before pushing.
+
+
+
+**Quality Over Speed**
+
+Don't just implementβverify, review, fix.
+- Run dev-story for implementation
+- Validate with gap analysis
+- Code review for quality
+- Fix issues before pushing
+- Only push when truly ready
+
+
+
+name: super-dev-story
+version: 3.0.0
+
+stages:
+ - dev-story: "Implement the story"
+ - validate: "Run gap analysis"
+ - review: "Code review"
+ - push: "Safe commit and push"
+
+defaults:
+ max_rework_loops: 3
+ auto_push: false
+ review_depth: "standard" # quick | standard | deep
+ validation_depth: "quick"
+
+quality_gates:
+ validation_threshold: 90 # % tasks must be verified
+ review_threshold: "pass" # pass | pass_with_warnings
+
+
+
+@patterns/verification.md
+@patterns/hospital-grade.md
+
+
+
+
+
+**Load story and prepare pipeline**
+
+```bash
+STORY_FILE="{{story_file}}"
+[ -f "$STORY_FILE" ] || { echo "β story_file required"; exit 1; }
+```
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π SUPER DEV STORY PIPELINE
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{story_key}}
+Stages: dev-story β validate β review β push
+
+Quality Gates:
+- Validation: β₯{{validation_threshold}}% verified
+- Review: {{review_threshold}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Initialize:
+- rework_count = 0
+- stage = "dev-story"
+
+
+
+**Stage 1: Implement the story**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STAGE 1: DEV-STORY
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Invoke dev-story workflow:
+```
+/dev-story story_file={{story_file}}
+```
+
+Wait for completion. Capture:
+- files_created
+- files_modified
+- tasks_completed
+
+```
+β
Dev-story complete
+Files: {{file_count}} created/modified
+Tasks: {{tasks_completed}}/{{total_tasks}}
+```
+
+
+
+**Stage 2: Validate implementation**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STAGE 2: VALIDATION
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Invoke validation:
+```
+/validate scope=story target={{story_file}} depth={{validation_depth}}
+```
+
+Capture results:
+- verified_pct
+- false_positives
+- category
+
+**Check quality gate:**
+```
+if verified_pct < validation_threshold:
+ REWORK_NEEDED = true
+ reason = "Validation below {{validation_threshold}}%"
+
+if false_positives > 0:
+ REWORK_NEEDED = true
+ reason = "{{false_positives}} tasks marked done but missing"
+```
+
+```
+{{#if REWORK_NEEDED}}
+β οΈ Validation failed: {{reason}}
+{{else}}
+β
Validation passed: {{verified_pct}}% verified
+{{/if}}
+```
+
+
+
+**Stage 3: Code review**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π STAGE 3: CODE REVIEW
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+Invoke code review:
+```
+/multi-agent-review files={{files_modified}} depth={{review_depth}}
+```
+
+Capture results:
+- verdict (PASS, PASS_WITH_WARNINGS, NEEDS_REWORK)
+- issues
+
+**Check quality gate:**
+```
+if verdict == "NEEDS_REWORK":
+ REWORK_NEEDED = true
+ reason = "Code review found blocking issues"
+
+if review_threshold == "pass" AND verdict == "PASS_WITH_WARNINGS":
+ REWORK_NEEDED = true
+ reason = "Warnings not allowed in strict mode"
+```
+
+```
+{{#if REWORK_NEEDED}}
+β οΈ Review failed: {{reason}}
+Issues: {{issues}}
+{{else}}
+β
Review passed: {{verdict}}
+{{/if}}
+```
+
+
+
+**Handle rework loop**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π REWORK REQUIRED (Loop {{rework_count + 1}}/{{max_rework_loops}})
+βββββββββββββββββββββββββββββββββββββββββββ
+Reason: {{reason}}
+
+{{#if validation_issues}}
+Validation Issues:
+{{#each validation_issues}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+{{#if review_issues}}
+Review Issues:
+{{#each review_issues}}
+- {{this}}
+{{/each}}
+{{/if}}
+```
+
+**Check loop limit:**
+```
+rework_count++
+if rework_count > max_rework_loops:
+ echo "β Max rework loops exceeded"
+ echo "Manual intervention required"
+ HALT
+```
+
+**Re-invoke dev-story with issues:**
+```
+/dev-story story_file={{story_file}} fix_issues={{issues}}
+```
+
+After dev-story completes, return to validation stage.
+
+
+
+**Stage 4: Push changes**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+π¦ STAGE 4: PUSH
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+**Generate commit message from story:**
+```
+feat({{epic}}): {{story_title}}
+
+- Implemented {{task_count}} tasks
+- Verified: {{verified_pct}}%
+- Review: {{verdict}}
+
+Story: {{story_key}}
+```
+
+**If auto_push:**
+```
+/push-all commit_message="{{message}}" auto_push=true
+```
+
+**Otherwise, ask:**
+```
+Ready to push?
+
+[Y] Yes, push now
+[N] No, keep local (can push later)
+[R] Review changes first
+```
+
+
+
+**Display pipeline results**
+
+```
+βββββββββββββββββββββββββββββββββββββββββββ
+β
SUPER DEV STORY COMPLETE
+βββββββββββββββββββββββββββββββββββββββββββ
+Story: {{story_key}}
+
+Pipeline Results:
+- Dev-Story: β
Complete
+- Validation: β
{{verified_pct}}% verified
+- Review: β
{{verdict}}
+- Push: {{pushed ? "β
Pushed" : "βΈοΈ Local only"}}
+
+Rework Loops: {{rework_count}}
+Files Changed: {{file_count}}
+Commit: {{commit_hash}}
+
+{{#if pushed}}
+Branch: {{branch}}
+Ready for PR: gh pr create
+{{/if}}
+βββββββββββββββββββββββββββββββββββββββββββ
+```
+
+
+
+
+
+```bash
+# Standard pipeline
+/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md
+
+# With auto-push
+/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md auto_push=true
+
+# Strict review mode
+/super-dev-story story_file=docs/sprint-artifacts/2-5-auth.md review_threshold=pass
+```
+
+
+
+**Dev-story fails:** Report error, halt pipeline.
+**Validation below threshold:** Enter rework loop.
+**Review finds blocking issues:** Enter rework loop.
+**Max rework loops exceeded:** Halt, require manual intervention.
+**Push fails:** Report error, commit preserved locally.
+
+
+
+- [ ] Dev-story completed
+- [ ] Validation β₯ threshold
+- [ ] Review passed
+- [ ] Changes committed
+- [ ] Pushed (if requested)
+- [ ] Story status updated
+
diff --git a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml b/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml
index 530f041c..7185b853 100644
--- a/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/super-dev-story/workflow.yaml
@@ -14,7 +14,7 @@ date: system-generated
# Workflow components
installed_path: "{project-root}/_bmad/bmm/workflows/4-implementation/super-dev-story"
-instructions: "{installed_path}/instructions.xml"
+instructions: "{installed_path}/workflow.md"
validation: "{installed_path}/checklist.md"
story_file: "" # Explicit story path; auto-discovered if empty