siesa-agents 2.1.78 → 2.1.80

package/siesa-agents/bmm/workflows/4-implementation/create-story/steps/step-01-determine-story.md

@@ -0,0 +1,85 @@
+---
+name: 'step-01-determine-story'
+description: 'Determine which story to work on next'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/create-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-determine-story.md'
+nextStepFile: '{workflow_path}/steps/step-02-analyze.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Variables
+sprint_status: '{implementation_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step 1: Determine Target Story
+
+## STEP GOAL:
+To identify exactly which user story needs to be created, either from user input or by auto-discovering the next backlog item from the sprint status.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Step-Specific Rules:
+- 🎯 Focus only on identifying the story ID (e.g., "1-2") and Title
+- 🚫 FORBIDDEN to analyze deep context yet
+- 💬 Ask strictly for story ID if not found automatically
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Identify story to create
+- 💾 Set {{story_id}}, {{epic_num}}, {{story_num}}, {{story_key}} memory variables
+- 📖 No file output in this step, only memory state
+
+## INSTRUCTIONS:
+
+### 1. Check User Input
+Check if the user provided a story path or ID (e.g., "1-2-user-auth").
+- IF YES: Parse it, set {{story_id}} variables, and [GO TO Section 4]
+- IF NO: Proceed to Section 2
+
+### 2. Auto-Discovery
+Check if `{sprint_status}` file exists.
+- IF NO: Display options to user:
+  1. Run `sprint-planning` (Recommended)
+  2. Enter specific epic-story number
+  3. Quit
+  [Wait for selection]
+
+- IF YES: Load and read `{sprint_status}`.
+  - Parse `development_status` section.
+  - Find FIRST story where status is "backlog".
+  - IF NONE FOUND: Display "No backlog stories found" and HALT.
+  - IF FOUND: Extract `epic_num`, `story_num`, `story_title`.
+  - Set variables.
+
+### 3. Verify Epic Status
+Check the status of the Epic {{epic_num}} in `sprint_status`.
+- If "done": HALT. Cannot add to done epic.
+- If "backlog": Update to "in-progress" in `sprint_status` (save file).
+- If "in-progress": Continue.
+
+### 4. Present MENU OPTIONS
+
+Display: "**Target Story Identified: {{story_id}} - {{story_title}}**"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Analysis"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'

package/siesa-agents/bmm/workflows/4-implementation/create-story/steps/step-02-analyze.md

@@ -0,0 +1,67 @@
+---
+name: 'step-02-analyze'
+description: 'Load and analyze core artifacts'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/create-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-02-analyze.md'
+nextStepFile: '{workflow_path}/steps/step-03-architecture.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Variables
+output_folder: '{implementation_artifacts}'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step 2: Load and Analyze Core Artifacts
+
+## STEP GOAL:
+To gather all necessary context from Epics, previous stories, and Git history to build a solid foundation for the new story.
+
+## EXECUTION PROTOCOLS:
+- 🎯 Deep analysis of available artifacts
+- 💾 Extract key requirements into memory/context
+
+## INSTRUCTIONS:
+
+### 1. Discover Inputs
+Identify available files matching patterns:
+- Epics: `{output_folder}/*epic*.md`
+- PRD: `{output_folder}/*prd*.md`
+- Architecture: `{output_folder}/*architecture*.md`
+- Review findings.
+
+### 2. Epic Analysis
+Load the relevant Epic file ({{epic_num}}).
+- Extract "Epic Objectives" and "Business Value".
+- Extract THIS specific story's requirements (User Story, AC).
+- Extract technical constraints listed in the Epic.
+
+### 3. Previous Story Intelligence
+Check if {{story_num}} > 1.
+- IF YES: Look for `{{story_dir}}/{{epic_num}}-{{previous_story_num}}-*.md`.
+- IF FOUND: Read it. Extract "Dev Notes", "Learnings", "Testing Approaches".
+
+### 4. Git Intelligence
+Check if this is a git repo.
+- IF YES: Get last 5 commit titles.
+- Analyze patterns relevant to this story (naming, file locations).
+
+### 5. Present MENU OPTIONS
+
+Display: "**Artifact Analysis Complete.**"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Architecture"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'

package/siesa-agents/bmm/workflows/4-implementation/create-story/steps/step-03-architecture.md

@@ -0,0 +1,71 @@
+---
+name: 'step-03-architecture'
+description: 'Architecture analysis and tech stack validation'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/create-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-03-architecture.md'
+nextStepFile: '{workflow_path}/steps/step-04-web-research.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Variables
+output_folder: '{implementation_artifacts}'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step 3: Architecture Intelligence & Compliance
+
+## STEP GOAL:
+To extract architectural constraints and SPECIFICALLY detect Frontend/UI requirements to enforce `siesa-ui-kit` usage.
+
+## EXECUTION PROTOCOLS:
+- 🎯 Analyze architecture documents
+- 🕵️ Detect UI/Frontend requirements in the current story
+- 💾 Set {{has_ui_component}} flag and {{siesa_instructions}}
+
+## INSTRUCTIONS:
+
+### 1. Load Architecture
+Load `{output_folder}/*architecture*.md`.
+- Analyze: Technical Stack, Code Structure, API Patterns, Database Schemas.
+
+### 2. UI/Frontend Detection (CRITICAL)
+Analyze the Story Requirements (from previous step) and Architecture.
+- ASK: "Does this story involve creating views, components, or user interfaces?"
+- LOOK FOR keywords: "Page", "View", "Button", "Form", "Screen", "UI", "Frontend", "React", "Vue", "Component".
+
+### 3. Siesa UI Kit Enforcement
+IF {{has_ui_component}} IS TRUE:
+- **MANDATE**: Store the following requirements for the final story:
+  1.  **Installation**: `npm install siesa-ui-kit` for installation.
+  2.  **Usage**: "You MUST use components and patterns from `siesa-ui-kit` for all UI elements."
+  3.  **Pattern**: "Do not build custom UI components if a `siesa-ui-kit` equivalent exists."
+- Log: "✅ UI Story Detected - siesa-ui-kit requirements injected."
+
+IF {{has_ui_component}} IS FALSE:
+- Log: "ℹ️ No specific UI requirements detected. Standard backend/logic rules apply."
+
+### 4. Extract Other Constraints
+- Security: Auth/Authz rules.
+- Performance: Caching, specific queries.
+- Testing: Standards for this module.
+
+### 5. Present MENU OPTIONS
+
+Display: "**Architecture & UI Analysis Complete.**"
+Display: "**UI Detected:** {{has_ui_component}}"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Research"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'

package/siesa-agents/bmm/workflows/4-implementation/create-story/steps/step-04-web-research.md

@@ -0,0 +1,58 @@
+---
+name: 'step-04-web-research'
+description: 'Web research for latest technical specifics'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/create-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-04-web-research.md'
+nextStepFile: '{workflow_path}/steps/step-05-create-file.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step 4: Web Research & Verification
+
+## STEP GOAL:
+To ensure the developer has the absolute latest information on libraries (including `siesa-ui-kit` if relevant) and APIs.
+
+## EXECUTION PROTOCOLS:
+- 🎯 Research latest versions and best practices
+- 💾 Summarize technical specifics for the story
+
+## INSTRUCTIONS:
+
+### 1. Identify Research Targets
+Based on Architecture and Story:
+- List critical libraries/frameworks.
+- **Siesa Check**: If {{has_ui_component}} is TRUE, include `siesa-ui-kit` in research list (check for specific version requirements if public, or internal docs).
+
+### 2. Execute Research
+For each target:
+- Find latest stable version.
+- check for breaking changes relevant to this story.
+- Find specific documentation links for required components.
+
+### 3. Synthesize Findings
+Create a "Latest Tech Info" block:
+- "Library X v.Y.Z recommended"
+- "Specific API endpoint documentation: [Link]"
+- "Security alerts: [Details]"
+
+### 4. Present MENU OPTIONS
+
+Display: "**Tech Research Complete.**"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Creation"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'

package/siesa-agents/bmm/workflows/4-implementation/create-story/steps/step-05-create-file.md

@@ -0,0 +1,76 @@
+---
+name: 'step-05-create-file'
+description: 'Create comprehensive story file'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/create-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-05-create-file.md'
+nextStepFile: '{workflow_path}/steps/step-06-finalize.md'
+workflowFile: '{workflow_path}/workflow.md'
+templateFile: '{workflow_path}/template.md'
+
+# Variables
+story_dir: '{implementation_artifacts}'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step 5: Create Ultimate Story File
+
+## STEP GOAL:
+To generate the final `.md` story file containing ALL gathered context, requirements, and specifically the `siesa-ui-kit` mandates if applicable.
+
+## EXECUTION PROTOCOLS:
+- 🎯 Assemble the story file
+- 💾 Write to `{{story_dir}}/{{story_key}}.md`
+
+## INSTRUCTIONS:
+
+### 1. Initialize File
+Create/Overwrite: `{{story_dir}}/{{story_key}}.md`.
+
+### 2. Write Header & Status
+- Title: Story {{epic_num}}.{{story_num}}: {{story_title}}
+- Status: **ready-for-dev**
+
+### 3. Write Story & AC
+- User Story Format (As a... I want... So that...)
+- Detailed Acceptance Criteria (from Step 2).
+
+### 4. Write Technical Implementation Guide (CRITICAL)
+- Architecture Patterns (from Step 3).
+- **Tech Stack & Libraries**:
+  - List all required libraries.
+  - **UI MANDATE**: IF {{has_ui_component}} is TRUE:
+    ```markdown
+    ### 🎨 UI Implementation Requirements (MANDATORY)
+    - **Library**: `siesa-ui-kit`
+    - **Install**: `npm install siesa-ui-kit` (Ensure dependency is present)
+    - **Usage**: You MUST use `siesa-ui-kit` components for all UI elements.
+    - **Constraint**: Do not create custom components if a Kit equivalent exists.
+    ```
+- Testing Requirements.
+- File Structure requirements.
+
+### 5. Write Contextual Intelligence
+- Previous Story Learnings (from Step 2).
+- Git History Context (from Step 2).
+- Latest Web Research (from Step 4).
+
+### 6. Present MENU OPTIONS
+
+Display: "**Story File Created: {{story_key}}.md**"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Finalize"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: Load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'

package/siesa-agents/bmm/workflows/4-implementation/create-story/steps/step-06-finalize.md

@@ -0,0 +1,106 @@
+---
+name: 'step-06-finalize'
+description: 'Update sprint status and finalize'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/create-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-06-finalize.md'
+workflowFile: '{workflow_path}/workflow.md'
+
+# Variables
+sprint_status: '{implementation_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml'
+
+# Task References
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step 6: Finalize & Handover
+
+## STEP GOAL:
+To update the project tracking (sprint status) and confirm the story is ready for development.
+
+## EXECUTION PROTOCOLS:
+- 🎯 Update sprint-status.yaml
+- 🏁 Complete workflow
+
+## INSTRUCTIONS:
+
+### 1. Update Sprint Status
+Load `{sprint_status}`.
+- Find `development_status` for {{story_key}}.
+- Update status from "backlog" to "ready-for-dev".
+
+#### 1a. Update Epic Last-Update Date (MANDATORY)
+Execute the following algorithm every time, without exception:
+
+```
+ALGORITHM: epic-last-update
+─────────────────────────────────────────────────────────────
+INPUT  : story_key  (e.g. "2-1-units-of-measure-listview")
+         epic_num   (already in memory from step-01)
+OUTPUT : sprint-status.yaml updated (only the epic field)
+
+STEP 1 — Derive field key
+  field_key = "epic-" + {{epic_num}} + "-last-update"
+  // e.g. epic_num=2  →  field_key = "epic-2-last-update"
+
+STEP 2 — Get today's date
+  today = system date in format DD-MM-YYYY
+  // e.g. 24-02-2026
+
+STEP 3 — Locate field in sprint-status.yaml
+  Search development_status section for a line that matches:
+    /^\s*{field_key}:\s*.*/
+  CASE A — line found:
+    Replace the value with today's date.
+    Result: "  epic-2-last-update: 24-02-2026"
+  CASE B — line NOT found:
+    LOG warning: "WARNING: {field_key} not found in sprint-status.yaml"
+    Do NOT create the field. Do NOT modify any other line. Continue.
+
+STEP 4 — Safety constraints (STRICT)
+  ✅ Only modify the single line matching {field_key}
+  ✅ Only update the epic corresponding to {{epic_num}}
+  ❌ Do NOT touch other epic-*-last-update fields
+  ❌ Do NOT alter story status entries
+  ❌ Do NOT change epic status (backlog / in-progress / done)
+  ❌ Do NOT reformat or reorder the YAML file
+
+STEP 5 — Save file
+  Write the updated sprint-status.yaml to disk.
+─────────────────────────────────────────────────────────────
+```
+
+### 2. Validation (Optional)
+Run validation check on the generated story file (structure check).
+
+### 3. Final Report
+Display:
+```markdown
+**🎯 TARGET LOCKED: Story {{story_key}} Ready for Dev!**
+
+**Details:**
+- File: {{story_file}}
+- Status: ready-for-dev
+- UI Mode: {{has_ui_component}} (siesa-ui-kit required: {{has_ui_component}})
+
+**Next Action:**
+- Run `dev-story` to begin implementation.
+```
+
+### 4. Present MENU OPTIONS
+
+Display: "**Workflow Complete.**"
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Finish"
+
+#### Menu Handling Logic:
+- IF A: Execute {advancedElicitationTask}
+- IF P: Execute {partyModeWorkflow}
+- IF C: EXIT workflow (Process Complete)
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed/exit when user selects 'C'

package/siesa-agents/bmm/workflows/4-implementation/create-story/template.md

@@ -0,0 +1,49 @@
+# Story {{epic_num}}.{{story_num}}: {{story_title}}
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a {{role}},
+I want {{action}},
+so that {{benefit}}.
+
+## Acceptance Criteria
+
+1. [Add acceptance criteria from epics/PRD]
+
+## Tasks / Subtasks
+
+- [ ] Task 1 (AC: #)
+  - [ ] Subtask 1.1
+- [ ] Task 2 (AC: #)
+  - [ ] Subtask 2.1
+
+## Dev Notes
+
+- Relevant architecture patterns and constraints
+- Source tree components to touch
+- Testing standards summary
+
+### Project Structure Notes
+
+- Alignment with unified project structure (paths, modules, naming)
+- Detected conflicts or variances (with rationale)
+
+### References
+
+- Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+{{agent_model_name_version}}
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/siesa-agents/bmm/workflows/4-implementation/create-story/workflow_ext.md

@@ -24,7 +24,7 @@
 **STEP 3: INJECT CONTEXT FROM FILES**
 1. If the specific feature folder exists, **USE YOUR READ TOOL** to read ALL markdown files inside it, especially `technical-preference.md` or any architectural/domain rule file.
 2. If the folder does not exist, acknowledge it and proceed normally.
-3. LOAD the FULL `@{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/data/company-standards/mastercrud-use-reference.md` — MasterCrud is the highest-level orchestrator component in Siesa UI Kit. It coordinates data grids, forms, filters, and CRUD operations into a unified, configurable interface. **You MUST apply its API contract and configuration patterns whenever the story involves a CRUD screen,   data grid, or form-based UI.** 
+3. LOAD the FULL `@{project-root}/_siesa-agents/bmm/workflows/3-solutioning/create-architecture/data/company-standards/mastercrud-use-reference.md` — MasterCrud is the highest-level orchestrator component in Siesa UI Kit. It coordinates data grids, forms, filters, and CRUD operations into a unified, configurable interface. **You MUST apply its API contract and configuration patterns whenever the story involves a CRUD screen,   data grid, or form-based UI.** 
 
 **STEP 4: APPLY TO THE STORY**
 - You MUST enforce any system rules, design patterns, testing requirements, or UI guidelines found in the `technical-preference.md` file into the Acceptance Criteria and Technical Details of the user story you are writing. DO NOT write the story without integrating these rules if they exist.
@@ -39,7 +39,7 @@ The following rules must be kept in memory and applied at the appropriate moment
 
 ## 1. Sub-agents: only when invoked via quick-dev
 
-Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/create-story`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
+Sub-agents **must NOT be used** when the code review workflow is invoked directly (e.g., `/sa-create-story`). Sub-agents are only permitted when the workflow is triggered as part of **quick-dev** (e.g., `/quick-dev`).
 
 - If invoked directly → follow the standard sequential workflow steps without spawning any sub-agents.
 - If invoked from quick-dev → sub-agents may be used as defined by the quick-dev orchestration.

package/siesa-agents/bmm/workflows/4-implementation/dev-story/checklist_ext.md

@@ -0,0 +1,13 @@
+# DEV STORY — SIESA ADDITIONAL CHECKLIST ITEMS
+
+These items extend the base BMAD dev-story checklist. Apply them as additional acceptance gates before marking a story as complete.
+
+---
+
+## Siesa-Specific Completion Criteria
+
+- [ ] **Dependency Management:** Any new npm/NuGet packages installed are documented in the story's Dev Agent Record. Auto-install scripts (if applicable) have run successfully.
+- [ ] **Strict AI Instruction for UI Kit usage:** Followed the mandatory rule to check `siesa-ui-kit` FIRST for every UI component need before creating any custom component or using another library directly.
+- [ ] **Intelligent Exception Handling for custom components:** For any component NOT found in `siesa-ui-kit`, an exception was logged in the story with justification (shadcn direct use or siesa-ui-kit MR request).
+- [ ] **Validation of UI requirements vs UI Kit usage:** All UI components used in implementation match the agreed component strategy from the UX design document.
+- [ ] **UI Kit Compliance:** All UI elements use `siesa-ui-kit`. No custom styles or components were introduced without an approved exception logged in the story's Dev Agent Record.

package/siesa-agents/bmm/workflows/4-implementation/dev-story/steps/step-01-find-story.md

@@ -0,0 +1,109 @@
+---
+name: 'step-01-find-story'
+description: 'Find next ready story and load it'
+
+# Path Definitions
+workflow_path: '{project-root}/_siesa-agents/bmm/workflows/4-implementation/dev-story'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-find-story.md'
+nextStepFile: '{workflow_path}/steps/step-02-check-branch.md'
+configSource: '{project-root}/_bmad/bmm/config.yaml'
+
+# Context References
+sprintStatusFile: '{implementation_artifacts}/sprint-status.yaml'
+---
+
+# Step 1: Find Next Ready Story
+
+## STEP GOAL:
+
+To identify, locate, and load the correct story file for development, either from the sprint status or by direct search.
+
+## MANDATORY EXECUTION RULES:
+
+- 🛑 NEVER proceed without a valid story file
+- 📖 Read the entire step file first
+- 💾 Store `story_path` and `story_key` in memory for subsequent steps
+
+## EXECUTION PROTOCOLS:
+
+### 1. Check for Provided Story Path
+
+If `story_path` variable is already provided (e.g., passed by user):
+
+1.  Use `story_path` directly.
+2.  Read the COMPLETE story file.
+3.  Extract `story_key` from filename or metadata.
+4.  Proceed to **Completion**.
+
+### 2. Sprint-Based Discovery (Priority)
+
+Check if `{sprintStatusFile}` exists.
+
+**IF EXISTS:**
+
+1.  Load the FULL file `{sprintStatusFile}`.
+2.  Read all lines to understand story order.
+3.  Find the **FIRST** story where:
+    *   Key matches pattern: `number-number-name` (e.g., `1-2-user-auth`).
+    *   NOT an epic key (`epic-X`) or retrospective.
+    *   Status value equals `ready-for-dev`.
+
+**IF NO ready-for-dev story found:**
+
+1.  Display:
+    ```
+    📋 No ready-for-dev stories found in sprint-status.yaml
+    Current Sprint Status: [Summary]
+    ```
+2.  Ask user to choose:
+    *   [1] Run `create-story` (HALT and suggest command).
+    *   [2] Run `validate-create-story` (HALT and suggest command).
+    *   [3] Specify story file path manually.
+    *   [4] Review detailed sprint status.
+3.  **HALT** and wait for input.
+
+**IF ready-for-dev story found:**
+
+1.  Store `story_key` (e.g., "1-2-user-auth").
+2.  Find matching story file in `{story_dir}` (from config) using pattern `{{story_key}}.md`.
+3.  Read COMPLETE story file.
+4.  Proceed to **Completion**.
+
+### 3. Non-Sprint Discovery (Fallback)
+
+If `{sprintStatusFile}` does **NOT** exist:
+
+1.  Search `{story_dir}` for markdown files `*-*-*.md`.
+2.  Read files to find one with Status: `ready-for-dev`.
+3.  If none found, Ask user to specify path or run creation tools.
+4.  If found, use that file, extract `story_key`, and read content.
+
+### 4. Story Context Extraction
+
+Once story file is loaded (from any method above):
+
+1.  Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status.
+2.  Load comprehensive context from Dev Notes (architecture, learnings, specs).
+3.  Identify first incomplete task (unchecked `[ ]`).
+    *   If no incomplete tasks: Inform user story seems complete.
+    *   If incomplete task found: Proceed.
+
+### 5. Completion and Next Step
+
+Once story is identified and loaded:
+
+1.  Display:
+    ```
+    ✅ Story Selected: {{story_key}}
+    Task: {{first_incomplete_task}}
+    ```
+2.  Load, read entire file, then execute `{nextStepFile}` (`step-02-check-branch.md`).
+
+---
+
+## CRITICAL:
+
+- Do NOT load next step if story is not found or file is unreadable.
+- If user input is required to pick a story, wait for it.