bmad-auto-copilot 1.2.3 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-auto-copilot",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Automated BMAD story development loop using GitHub Copilot CLI — install into any BMAD project",
   "keywords": [
     "bmad",

package/templates/bmad-loop.ps1

@@ -3,7 +3,8 @@
     BMAD Auto Loop — GitHub Copilot CLI Edition (Windows PowerShell)
 .DESCRIPTION
     Executes the BMAD workflow in a loop using GitHub Copilot CLI:
-      create-story (SM agent) → dev-story (Dev agent) → code-review (Dev agent) → commit
+    create-story (CS) → validate-story (VS) → dev-story (DS) → code-review (CR)
+    → qa-generate-e2e-tests (QA, optional) → sprint-status (SS) → commit
     Each step runs as a NEW Copilot CLI session (fresh context window).
     Continues until all stories reach 'done' state in sprint-status.yaml.
 
@@ -65,8 +66,23 @@ if (-not $ReasoningEffort) {
     $ReasoningEffort = "xhigh"
 }
 
-# Delay between iterations (seconds)
-$IterationDelay = if ($env:ITERATION_DELAY) { [int]$env:ITERATION_DELAY } else { 10 }
+# Delay between iterations (seconds) with enforced minimum
+$IterationDelay = if ($env:ITERATION_DELAY) { [int]$env:ITERATION_DELAY } else { 60 }
+if ($IterationDelay -lt 60) {
+    $IterationDelay = 60
+}
+
+# Canonical loop controls
+$EnableValidateGate = if ($env:ENABLE_VALIDATE_GATE) { $env:ENABLE_VALIDATE_GATE } else { "true" }
+$EnableQAStep = if ($env:ENABLE_QA_STEP) { $env:ENABLE_QA_STEP } else { "true" }
+$EnableSprintStatusStep = if ($env:ENABLE_SPRINT_STATUS_STEP) { $env:ENABLE_SPRINT_STATUS_STEP } else { "true" }
+
+function Test-Enabled {
+    param([string]$Value)
+    if (-not $Value) { return $false }
+    $v = $Value.ToLowerInvariant()
+    return $v -eq "true" -or $v -eq "1" -or $v -eq "yes" -or $v -eq "y"
+}
 
 # ============================================================
 # CONFIGURATION LOADING
@@ -220,7 +236,8 @@ function Invoke-CopilotSession {
     param(
         [string]$Agent,
         [string]$PromptFile,
-        [string]$ActionLabel
+        [string]$ActionLabel,
+        [string]$StoryKey = ""
     )
 
     if (-not (Test-Path $PromptFile)) {
@@ -230,6 +247,7 @@ function Invoke-CopilotSession {
 
     $prompt = Get-Content $PromptFile -Raw
     $prompt = $prompt -replace '\{TIMESTAMP\}', (Get-Date -Format "yyyy-MM-dd HH:mm:ss")
+    $prompt = $prompt -replace '\{STORY_KEY\}', $StoryKey
 
     Write-Log "[SESSION] New Copilot CLI session -> Agent: $Agent | Model: $Model | Reasoning: $ReasoningEffort | Action: $ActionLabel" "Magenta"
 
@@ -280,6 +298,31 @@ function Get-StoryKeyForState {
     return "unknown"
 }
 
+function Get-StoryStateByKey {
+    param([string]$StoryKey)
+
+    if (-not $StoryKey) { return "" }
+
+    $line = Get-Content $SprintStatusPath |
+        Where-Object { $_ -match "^\s*${StoryKey}:" } |
+        Select-Object -First 1
+
+    if (-not $line) { return "" }
+
+    $line = $line -replace '\s*#.*$', ''
+    $line = $line -replace '^[^:]*:\s*', ''
+    return $line.Trim()
+}
+
+function Get-StoryStateToken {
+    param([string]$RawState)
+    if (-not $RawState) { return "" }
+    if ($RawState -match '^\s*([A-Za-z-]+)') {
+        return $Matches[1].ToLowerInvariant()
+    }
+    return $RawState.Trim().ToLowerInvariant()
+}
+
 # ============================================================
 # GIT COMMIT
 # ============================================================
@@ -356,6 +399,10 @@ Write-Log "[START] BMAD Auto Loop Started" "Green"
 Write-Log "Max iterations: $MaxIterations" "Gray"
 Write-Log "Model: $Model" "Gray"
 Write-Log "Reasoning effort: $ReasoningEffort" "Gray"
+Write-Log "Delay between steps: ${IterationDelay}s" "Gray"
+Write-Log "Validate gate enabled: $EnableValidateGate" "Gray"
+Write-Log "QA step enabled: $EnableQAStep" "Gray"
+Write-Log "Sprint-status step enabled: $EnableSprintStatusStep" "Gray"
 Write-Log "Project root: $ProjectRoot" "Gray"
 Write-Log "Sprint status: $SprintStatusPath" "Gray"
 if ($DryRun) {
@@ -377,6 +424,14 @@ for ($iteration = 1; $iteration -le $MaxIterations; $iteration++) {
         "create-story" {
             Write-Log "[ACTION] CREATE STORY (SM Agent -> new session)" "Yellow"
             Invoke-CopilotSession -Agent "bmad-agent-bmm-sm" -PromptFile (Join-Path $PromptDir "create-story.md") -ActionLabel "create-story"
+
+            if (Test-Enabled $EnableValidateGate) {
+                Write-Log "[ACTION] VALIDATE STORY READINESS (VS gate)" "Yellow"
+                $validateOk = Invoke-CopilotSession -Agent "bmad-agent-bmm-sm" -PromptFile (Join-Path $PromptDir "validate-story.md") -ActionLabel "validate-story"
+                if (-not $validateOk) {
+                    Write-Log "[WARN] Validate-story step failed; will retry canonical CS->VS cycle next iteration" "Yellow"
+                }
+            }
         }
         "dev-story" {
             Write-Log "[ACTION] DEVELOP STORY (Dev Agent -> new session)" "Yellow"
@@ -389,12 +444,42 @@ for ($iteration = 1; $iteration -le $MaxIterations; $iteration++) {
             Invoke-CopilotSession -Agent "bmad-agent-bmm-dev" -PromptFile (Join-Path $PromptDir "code-review.md") -ActionLabel "code-review"
 
             # Only commit if the story actually moved to 'done'
-            $currentState = (Get-Content $SprintStatusPath | Where-Object { $_ -match "^\s*${reviewStoryKey}:" } | Select-Object -First 1) -replace '.*:\s*', '' | ForEach-Object { $_.Trim() }
-            if ($currentState -eq "done") {
-                Write-Log "[VERIFIED] Story $reviewStoryKey confirmed DONE" "Green"
-                Invoke-GitCommit -StoryKey $reviewStoryKey
+            if (-not $reviewStoryKey -or $reviewStoryKey -eq "unknown") {
+                Write-Log "[WARN] Could not determine review story key; skipping auto-commit this iteration" "Yellow"
             } else {
-                Write-Log "[RETRY] Story $reviewStoryKey still in '$currentState' (not done) - will retry next iteration" "Yellow"
+                $currentState = Get-StoryStateByKey -StoryKey $reviewStoryKey
+                $currentStateToken = Get-StoryStateToken -RawState $currentState
+
+                if ($currentStateToken -ne $currentState) {
+                    Write-Log "[WARN] Non-canonical sprint status value for $reviewStoryKey: '$currentState' (parsed token: '$currentStateToken')" "Yellow"
+                }
+
+                if ($currentStateToken -eq "done") {
+                    Write-Log "[VERIFIED] Story $reviewStoryKey confirmed DONE" "Green"
+
+                    $qaPassed = $true
+                    if (Test-Enabled $EnableQAStep) {
+                        Write-Log "[ACTION] QA GENERATE E2E TESTS (recommended)" "Yellow"
+                        $qaPassed = Invoke-CopilotSession -Agent "bmad-agent-bmm-qa" -PromptFile (Join-Path $PromptDir "qa-generate-e2e-tests.md") -ActionLabel "qa-generate-e2e-tests" -StoryKey $reviewStoryKey
+                        if (-not $qaPassed) {
+                            Write-Log "[WARN] QA step failed; skipping commit and continuing loop for remediation" "Yellow"
+                        }
+                    }
+
+                    if ($qaPassed -and (Test-Enabled $EnableSprintStatusStep)) {
+                        Write-Log "[ACTION] SPRINT STATUS UPDATE + NEXT STORY" "Yellow"
+                        $ssOk = Invoke-CopilotSession -Agent "bmad-agent-bmm-sm" -PromptFile (Join-Path $PromptDir "sprint-status.md") -ActionLabel "sprint-status" -StoryKey $reviewStoryKey
+                        if (-not $ssOk) {
+                            Write-Log "[WARN] Sprint-status step failed; continuing to commit because story is done" "Yellow"
+                        }
+                    }
+
+                    if ($qaPassed) {
+                        Invoke-GitCommit -StoryKey $reviewStoryKey
+                    }
+                } else {
+                    Write-Log "[RETRY] Story $reviewStoryKey still in '$currentState' (token: '$currentStateToken', not done) - will retry next iteration" "Yellow"
+                }
             }
         }
         "complete" {

package/templates/bmad-loop.sh

@@ -5,7 +5,8 @@
 #
 # DESCRIPTION:
 #   Executes the BMAD workflow in a loop using GitHub Copilot CLI:
-#     create-story (SM agent) → dev-story (Dev agent) → code-review (Dev agent) → commit
+#     create-story (CS) → validate-story (VS) → dev-story (DS) → code-review (CR)
+#     → qa-generate-e2e-tests (QA, optional) → sprint-status (SS) → commit
 #   Each step runs as a NEW Copilot CLI session (fresh context window).
 #   Continues until all stories reach 'done' state in sprint-status.yaml.
 #
@@ -63,6 +64,18 @@ if ! [[ "$ITERATION_DELAY" =~ ^[0-9]+$ ]] || [[ "$ITERATION_DELAY" -lt 60 ]]; th
     ITERATION_DELAY=60
 fi
 
+# Canonical loop controls
+# VS gate runs after CS. QA and SS run after CR when story reaches done.
+ENABLE_VALIDATE_GATE="${ENABLE_VALIDATE_GATE:-true}"
+ENABLE_QA_STEP="${ENABLE_QA_STEP:-true}"
+ENABLE_SPRINT_STATUS_STEP="${ENABLE_SPRINT_STATUS_STEP:-true}"
+
+is_enabled() {
+    local value
+    value=$(echo "$1" | tr '[:upper:]' '[:lower:]')
+    [[ "$value" == "true" || "$value" == "1" || "$value" == "yes" || "$value" == "y" ]]
+}
+
 # ============================================================
 # CONFIGURATION LOADING
 # ============================================================
@@ -226,6 +239,7 @@ invoke_copilot() {
     local agent="$1"
     local prompt_file="$2"
     local action_label="$3"
+    local story_key="${4:-}"
 
     if [[ ! -f "$prompt_file" ]]; then
         log "[ERROR] Prompt file not found: $prompt_file" "red"
@@ -235,6 +249,7 @@ invoke_copilot() {
     # Read prompt and substitute timestamp
     local prompt=$(cat "$prompt_file")
     prompt="${prompt//\{TIMESTAMP\}/$(date "+%Y-%m-%d %H:%M:%S")}"
+    prompt="${prompt//\{STORY_KEY\}/$story_key}"
 
     log "[SESSION] New Copilot CLI session → Model: $COPILOT_MODEL | Reasoning: $COPILOT_REASONING_EFFORT | Action: $action_label" "magenta"
 
@@ -286,6 +301,13 @@ get_story_state_by_key() {
         | sed 's/[[:space:]]*$//'
 }
 
+get_story_state_token() {
+    local raw_state="$1"
+
+    # Extract leading canonical token (letters/hyphen), normalize to lowercase.
+    echo "$raw_state" | sed -E 's/^[[:space:]]*([A-Za-z-]+).*$/\1/' | tr '[:upper:]' '[:lower:]'
+}
+
 # ============================================================
 # GIT COMMIT
 # ============================================================
@@ -356,6 +378,9 @@ log "Max iterations: $MAX_ITERATIONS" "gray"
 log "Model: $COPILOT_MODEL" "gray"
 log "Reasoning effort: $COPILOT_REASONING_EFFORT" "gray"
 log "Delay between steps: ${ITERATION_DELAY}s" "gray"
+log "Validate gate enabled: $ENABLE_VALIDATE_GATE" "gray"
+log "QA step enabled: $ENABLE_QA_STEP" "gray"
+log "Sprint-status step enabled: $ENABLE_SPRINT_STATUS_STEP" "gray"
 log "Project root: $PROJECT_ROOT" "gray"
 log "Sprint status: $SPRINT_STATUS_PATH" "gray"
 if $DRY_RUN; then
@@ -377,6 +402,13 @@ for ((iteration=1; iteration<=MAX_ITERATIONS; iteration++)); do
         "create-story")
             log "[ACTION] CREATE STORY (SM Agent → new session)" "yellow"
             invoke_copilot "bmad-agent-bmm-sm" "$PROMPT_DIR/create-story.md" "create-story"
+
+            if is_enabled "$ENABLE_VALIDATE_GATE"; then
+                log "[ACTION] VALIDATE STORY READINESS (VS gate)" "yellow"
+                if ! invoke_copilot "bmad-agent-bmm-sm" "$PROMPT_DIR/validate-story.md" "validate-story"; then
+                    log "[WARN] Validate-story step failed; will retry canonical CS→VS cycle next iteration" "yellow"
+                fi
+            fi
             ;;
         "dev-story")
             log "[ACTION] DEVELOP STORY (Dev Agent → new session)" "yellow"
@@ -393,11 +425,36 @@ for ((iteration=1; iteration<=MAX_ITERATIONS; iteration++)); do
                 log "[WARN] Could not determine review story key; skipping auto-commit this iteration" "yellow"
             else
                 current_state=$(get_story_state_by_key "$review_story_key")
-                if [[ "$current_state" == "done" ]]; then
+                current_state_token=$(get_story_state_token "$current_state")
+
+                if [[ "$current_state_token" != "$current_state" ]]; then
+                    log "[WARN] Non-canonical sprint status value for $review_story_key: '$current_state' (parsed token: '$current_state_token')" "yellow"
+                fi
+
+                if [[ "$current_state_token" == "done" ]]; then
                     log "[VERIFIED] Story $review_story_key confirmed DONE" "green"
-                    invoke_git_commit "$review_story_key"
+
+                    qa_passed=true
+                    if is_enabled "$ENABLE_QA_STEP"; then
+                        log "[ACTION] QA GENERATE E2E TESTS (recommended)" "yellow"
+                        if ! invoke_copilot "bmad-agent-bmm-qa" "$PROMPT_DIR/qa-generate-e2e-tests.md" "qa-generate-e2e-tests" "$review_story_key"; then
+                            qa_passed=false
+                            log "[WARN] QA step failed; skipping commit and continuing loop for remediation" "yellow"
+                        fi
+                    fi
+
+                    if $qa_passed && is_enabled "$ENABLE_SPRINT_STATUS_STEP"; then
+                        log "[ACTION] SPRINT STATUS UPDATE + NEXT STORY" "yellow"
+                        if ! invoke_copilot "bmad-agent-bmm-sm" "$PROMPT_DIR/sprint-status.md" "sprint-status" "$review_story_key"; then
+                            log "[WARN] Sprint-status step failed; continuing to commit because story is done" "yellow"
+                        fi
+                    fi
+
+                    if $qa_passed; then
+                        invoke_git_commit "$review_story_key"
+                    fi
                 else
-                    log "[RETRY] Story $review_story_key still in '$current_state' (not done) — will retry next iteration" "yellow"
+                    log "[RETRY] Story $review_story_key still in '$current_state' (token: '$current_state_token', not done) — will retry next iteration" "yellow"
                 fi
             fi
             ;;

package/templates/prompts/code-review.md

@@ -6,12 +6,13 @@ Timestamp: {TIMESTAMP}
 
 ## Step 1: Load Configuration and Workflow
 Read the BMAD config from: `_bmad/bmm/config.yaml` — resolve all variables ({project-root}, {output_folder}, etc.)
-Read the workflow definition from: `_bmad/bmm/workflows/4-implementation/bmad-code-review/workflow.md`
-Read and follow these review step files:
-- `_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-01-gather-context.md`
-- `_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-02-review.md`
-- `_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-03-triage.md`
-- `_bmad/bmm/workflows/4-implementation/bmad-code-review/steps/step-04-present.md`
+Prefer these BMAD workflow paths:
+- `_bmad/bmm/4-implementation/bmad-code-review/workflow.md`
+- `_bmad/bmm/4-implementation/bmad-code-review/steps/step-01-gather-context.md`
+- `_bmad/bmm/4-implementation/bmad-code-review/steps/step-02-review.md`
+- `_bmad/bmm/4-implementation/bmad-code-review/steps/step-03-triage.md`
+- `_bmad/bmm/4-implementation/bmad-code-review/steps/step-04-present.md`
+If they do not exist, fallback to legacy paths under `_bmad/bmm/workflows/4-implementation/...`.
 
 ## Step 2: Find Next Story
 Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and find the FIRST story in `review` state (scan top to bottom, exclude retrospectives).
@@ -38,6 +39,8 @@ Based on review outcome:
 - If ALL HIGH and MEDIUM issues are fixed AND all ACs implemented: update status from `review` to `done`
 - If issues remain unfixable: update status from `review` to `in-progress` (will re-enter dev cycle)
 - Preserve ALL comments and structure in `_bmad-output/implementation-artifacts/sprint-status.yaml`
+- The status value MUST be a literal token only: exactly `done` or `in-progress` (never prose, counts, or summaries)
+- After saving, re-read the same story entry and verify the value is exactly `done` or `in-progress`; if not, correct it immediately and save again
 
 ## Rules
 - Use best judgment for ALL decisions — never ask the user
@@ -46,3 +49,4 @@ Based on review outcome:
 - Document issues you cannot auto-fix in the story file
 - All tests must pass after any fixes
 - Follow the workflow checklist to verify completeness
+- NEVER write explanatory text into sprint status values; write explanations only in story Dev Agent Record / Change Log

package/templates/prompts/create-story.md

@@ -6,10 +6,12 @@ Timestamp: {TIMESTAMP}
 
 ## Step 1: Load Configuration and Workflow
 Read the BMAD config from: `_bmad/bmm/config.yaml` — resolve all variables ({project-root}, {output_folder}, etc.)
-Read the workflow definition from: `_bmad/bmm/workflows/4-implementation/bmad-create-story/workflow.md`
-Read the input discovery protocol from: `_bmad/bmm/workflows/4-implementation/bmad-create-story/discover-inputs.md`
-Read the workflow template from: `_bmad/bmm/workflows/4-implementation/bmad-create-story/template.md`
-Read the workflow checklist from: `_bmad/bmm/workflows/4-implementation/bmad-create-story/checklist.md`
+Prefer these BMAD workflow paths:
+- `_bmad/bmm/4-implementation/bmad-create-story/workflow.md`
+- `_bmad/bmm/4-implementation/bmad-create-story/discover-inputs.md`
+- `_bmad/bmm/4-implementation/bmad-create-story/template.md`
+- `_bmad/bmm/4-implementation/bmad-create-story/checklist.md`
+If they do not exist, fallback to legacy paths under `_bmad/bmm/workflows/4-implementation/...`.
 
 ## Step 2: Find Next Story
 Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and find the FIRST story in `backlog` state (scan top to bottom, exclude retrospectives).

package/templates/prompts/dev-story.md

@@ -6,8 +6,10 @@ Timestamp: {TIMESTAMP}
 
 ## Step 1: Load Configuration and Workflow
 Read the BMAD config from: `_bmad/bmm/config.yaml` — resolve all variables ({project-root}, {output_folder}, etc.)
-Read the workflow definition from: `_bmad/bmm/workflows/4-implementation/bmad-dev-story/workflow.md`
-Read the workflow checklist from: `_bmad/bmm/workflows/4-implementation/bmad-dev-story/checklist.md`
+Prefer these BMAD workflow paths:
+- `_bmad/bmm/4-implementation/bmad-dev-story/workflow.md`
+- `_bmad/bmm/4-implementation/bmad-dev-story/checklist.md`
+If they do not exist, fallback to legacy paths under `_bmad/bmm/workflows/4-implementation/...`.
 
 ## Step 2: Find Next Story
 Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and find the FIRST story in `ready-for-dev` or `in-progress` state (scan top to bottom, exclude retrospectives).

package/templates/prompts/qa-generate-e2e-tests.md

@@ -0,0 +1,36 @@
+You are an automated BMAD workflow executor. Your task is to execute QA automation tests (`bmad-qa-generate-e2e-tests`).
+
+IMPORTANT: This is a non-interactive automated execution. Do NOT show menus, greetings, or ask questions. Execute continuously.
+
+Timestamp: {TIMESTAMP}
+Story key hint: {STORY_KEY}
+
+## Step 1: Load Configuration and QA Workflow
+Read `_bmad/bmm/config.yaml` and resolve variables.
+Prefer path: `_bmad/bmm/4-implementation/bmad-qa-generate-e2e-tests/workflow.md`
+Fallback to legacy path under `_bmad/bmm/workflows/4-implementation/...` if needed.
+
+## Step 2: Select Story Context
+Read `_bmad-output/implementation-artifacts/sprint-status.yaml`.
+Target story in this order:
+1) `{STORY_KEY}` if provided and present
+2) Else first story in `done`
+3) Else halt with clear reason
+
+## Step 3: Generate and Run QA Tests
+Generate and run API/E2E automation tests for the target story's critical flows.
+- Follow existing test framework conventions
+- Keep tests readable and maintainable
+- Run tests and fix immediate test issues where possible
+
+## Step 4: QA Outcome Handling
+- If QA passes: keep story status as `done`
+- If QA fails and can be remediated now: implement fixes and re-run QA until pass
+- If QA still fails with unresolved blockers: set story status to `in-progress` and record blockers for DS remediation
+- If remediation changed core logic materially, run a CR pass before final status confirmation
+
+## Rules
+- Status values must be literal tokens only (`in-progress` or `done` here)
+- Preserve sprint-status.yaml comments/structure
+- Write details in story Dev Agent Record / Change Log, not in status value
+- Do NOT pause between steps

package/templates/prompts/sprint-status.md

@@ -0,0 +1,28 @@
+You are an automated BMAD workflow executor. Your task is to execute sprint-status (`bmad-sprint-status`) as the per-story closure step.
+
+IMPORTANT: This is a non-interactive automated execution. Do NOT show menus, greetings, or ask questions. Execute continuously.
+
+Timestamp: {TIMESTAMP}
+Story key hint: {STORY_KEY}
+
+## Step 1: Load Configuration and Workflow
+Read `_bmad/bmm/config.yaml` and resolve variables.
+Prefer path: `_bmad/bmm/4-implementation/bmad-sprint-status/workflow.md`
+Fallback to legacy path under `_bmad/bmm/workflows/4-implementation/...` if needed.
+
+## Step 2: Update and Validate Sprint Status
+Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and update status transitions based on evidence from this story:
+- `ready-for-dev`
+- `in-progress`
+- `review`
+- `done`
+Ensure all status values are canonical literal tokens and file structure/comments are preserved.
+
+## Step 3: Recommend Next Story
+Show the next highest-priority story and key dependencies/risks.
+If there are blockers or unknown status values, surface them explicitly with corrective actions.
+
+## Rules
+- Non-interactive execution only
+- No status prose in YAML values
+- Do NOT pause between steps

package/templates/prompts/validate-story.md

@@ -0,0 +1,35 @@
+You are an automated BMAD workflow executor. Your task is to execute the Validate Story gate (`bmad-create-story` with action: validate).
+
+IMPORTANT: This is a non-interactive automated execution. Do NOT show menus, greetings, or ask questions. Execute continuously until the gate result is final.
+
+Timestamp: {TIMESTAMP}
+Story key hint: {STORY_KEY}
+
+## Step 1: Load Configuration and Validation Workflow
+Read `_bmad/bmm/config.yaml` and resolve variables.
+Prefer these paths:
+- `_bmad/bmm/4-implementation/bmad-create-story/workflow.md`
+- `_bmad/bmm/4-implementation/bmad-create-story/checklist.md`
+Fallback to legacy `_bmad/bmm/workflows/4-implementation/...` paths if needed.
+
+## Step 2: Select Target Story
+Read `_bmad-output/implementation-artifacts/sprint-status.yaml` and select target in this order:
+1) `{STORY_KEY}` if provided and present
+2) Else first story in `ready-for-dev`
+3) Else halt with clear reason
+
+## Step 3: Run Validation Gate (VS)
+Run create-story validation against the selected story using the checklist quality criteria.
+- Validate readiness/completeness for implementation
+- Produce concrete blockers and fixes if any
+
+## Step 4: Gate Handling
+- If validation PASSES: ensure sprint status for the story is exactly `ready-for-dev` (literal token only)
+- If validation FAILS with fixable blockers: refine story context and re-run validation in the same session
+- If validation still fails after remediation attempts: set story status back to `backlog` (literal token), record blockers in story file, and stop
+
+## Rules
+- Never proceed to implementation from this prompt
+- Status values in sprint-status must be literal tokens only (`backlog`, `ready-for-dev`, `in-progress`, `review`, `done`)
+- Preserve sprint-status.yaml structure/comments
+- Do NOT pause between steps