Develop Story

---
description: Complete story lifecycle from drafting through implementation with quality gates
argument-hint: "[story-number]"
---

Story: $ARGUMENTS

# Complete Story Lifecycle Workflow

## CRITICAL: Orchestration-Only Workflow

**THIS WORKFLOW IS AN ORCHESTRATOR ONLY. It coordinates agents but NEVER implements directly.**

**Workflow Rules:**
1. **ONLY use agents** - All work must be done by specialized agents
2. **NEVER implement** - No direct code writing, file editing, or feature implementation
3. **ORCHESTRATE phases** - Manage the flow between agents and phases
4. **MONITOR progress** - Check statuses and make decisions on next steps
5. **DELEGATE all work** - Every technical task goes to the appropriate agent

**Remember: You are the conductor, not the musician. Direct the agents, don't play the instruments.**

## Phase 1: Story Preparation
**Checking if story exists and determining starting point...**

### Check Story Status
First, check if story `$ARGUMENTS.story.md` exists in `docs/stories/`:

**If story DOES NOT exist:**
- **ORCHESTRATE:** Call the story-drafter agent to create story $ARGUMENTS
- The story-drafter agent will handle:
  - Reading epic requirements from `docs/epics/`
  - Creating a comprehensive story with all technical details
  - Saving the story as `$ARGUMENTS.story.md` in draft status
- After creation, proceed to Phase 2

**If story EXISTS:**
- Read the current status from `docs/stories/$ARGUMENTS.story.md`
- **Status = "Draft"**: Proceed to Phase 2 (Review and Refinement)
- **Status = "Todo"**: Skip to Phase 3 (Implementation)
- **Status = "In Progress"**: Resume at Phase 3 (Implementation)
- **Status = "In Review"**: Resume at Phase 3, Step 2 (Code Review)
- **Status = "Done"**: Story already complete, workflow ends
- **Status = "Blocked"**: Alert user about blocker and await resolution

## Phase 2: Review and Refinement Loop
**Iteratively reviewing and refining the story until ready...**

### Review Cycle
Repeat until story is approved:

1. **Story Validation**
   Use the story-validator agent to review story $ARGUMENTS for:
   - Completeness of requirements
   - Technical accuracy
   - Implementation readiness
   - Missing information or context

2. **Story Refinement** (if needed)
   If validation finds issues:
   Use the story-refiner agent to enhance story $ARGUMENTS based on validation report:
   - Add missing technical context
   - Clarify acceptance criteria
   - Improve task decomposition
   - Add citations from architecture docs

3. **Check Status**
   - If story status is now "Todo": Proceed to Phase 3
   - If status remains "Draft" or "Need Work": Return to step 1

## Phase 3: Implementation and Quality Gate Loop
**Implementing the story with continuous quality checks...**

### Implementation Cycle
Repeat until story status is "Done":

1. **Story Development (MANDATORY - AGENT ONLY)**
   **CRITICAL: This workflow MUST ONLY orchestrate. NEVER implement directly.**
   
   **For stories with status "Todo" or "In Progress":**
   Use the story-developer agent to implement story $ARGUMENTS:
   - The agent will read the existing story from `docs/stories/$ARGUMENTS.story.md`
   - The agent will handle ALL implementation tasks
   - The agent will execute ALL tasks sequentially
   - The agent will track progress with TodoWrite
   - The agent will update story sections continuously
   - The agent will mark completed tasks in the story
   - The agent will continue until ALL tasks are attempted
   - The agent sets status to "In Review" when ALL tasks complete
   
   **WORKFLOW RULE: This workflow ONLY calls agents. It NEVER:**
   - Writes code directly
   - Modifies files directly
   - Implements features directly
   - All implementation MUST be done by story-developer agent

2. **Code Review**
   Use the story-code-reviewer agent to validate the implementation:
   - VSCode diagnostics validation (zero errors required)
   - Code quality and complexity analysis
   - Duplicate code detection
   - Third-party package validation via Context7
   - Unit test quality assessment (minimal mocking)
   - Language coding guidelines compliance
   - Reviewer validates but does NOT modify code or set status to "Done"

3. **Quality Gate Decision**
   Use the quality-gate-manager agent to create gate for story $ARGUMENTS:
   - Document review findings
   - Set gate status (PASS/CONCERNS/FAIL/WAIVED)
   - Provide actionable recommendations
   - Create gate YAML file
   - **Update story status based on gate:**
     - PASS/WAIVED → "Done" 
     - FAIL/CONCERNS → "Need Work"

4. **Check Story Status**
   Check the actual story status in the story file:
   - If status is "Done": Story complete! 🎉 Workflow ends.
   - If status is "Need Work": Return to step 1 for fixes
   - If status is "In Review": Continue to step 2
   - If status is "blocked": Alert user and request unblocking
   
   **Important**: The quality-gate-manager controls final status transition to "Done" or "Need Work"

## Summary Output

After workflow completion (when story status is "Done"), provide summary:
- Story location: [file path]
- Final status: Done
- Final gate decision: [PASS/WAIVED]
- Gate file: [gate file path]
- Total implementation iterations: [count]
- Total review cycles: [count]
- Key decisions made: [list]
- Time to completion: [if trackable]

## Error Handling

If any agent encounters blockers:
- Draft story missing requirements → Alert user to provide PRD/Architecture
- Validation continuously fails → Escalate to Product Owner
- Implementation blocked → Request technical clarification
- Story status stuck in "blocked" → Alert user to resolve blockers
- Story not progressing after N iterations → Escalate to team lead
- Gate repeatedly fails but story not progressing → Schedule team review session

**Note**: The workflow will continue attempting to complete the story until its status is marked as "Done", regardless of how many iterations are needed.

## Usage Notes

This workflow ensures:
-