486 lines
15 KiB
Markdown
486 lines
15 KiB
Markdown
# /sdd:story-flow
|
|
|
|
## Meta
|
|
- Version: 1.0
|
|
- Category: workflow-automation
|
|
- Complexity: high
|
|
- Purpose: Automate the complete story lifecycle from creation to deployment and archival
|
|
|
|
## Definition
|
|
**Purpose**: Execute the complete story development workflow in sequence, automating the progression through all stages from story creation to production deployment, retrospective completion, and archival.
|
|
|
|
**Syntax**: `/sdd:story-flow <prompt|story_id> [--start-at=step] [--stop-at=step] [--auto]`
|
|
|
|
## Parameters
|
|
| Parameter | Type | Required | Default | Description | Validation |
|
|
|-----------|------|----------|---------|-------------|------------|
|
|
| prompt\|story_id | string | Yes | - | Story prompt/title or existing story ID (e.g., STORY-2025-001, STORY-DUE-001) | Non-empty string |
|
|
| --start-at | string | No | new | Start at specific step (new\|start\|implement\|review\|qa\|validate\|save\|ship\|complete) | Valid step name |
|
|
| --stop-at | string | No | complete | Stop at specific step | Valid step name |
|
|
| --auto | flag | No | false | Skip confirmations between steps | Boolean flag |
|
|
|
|
## INSTRUCTION: Execute Story Workflow Sequence
|
|
|
|
### INPUTS
|
|
- prompt\|story_id: Either a new story description or an existing story ID
|
|
- --start-at: Optional step to begin from (default: new)
|
|
- --stop-at: Optional step to end at (default: complete)
|
|
- --auto: Optional flag to run all steps without confirmation
|
|
|
|
### PROCESS
|
|
|
|
#### Phase 1: Initialization
|
|
1. **PARSE** input to determine if it's a new prompt or existing story ID:
|
|
- IF matches pattern `STORY-[A-Z0-9]+-\d+`: Use as existing story ID
|
|
* Supports: STORY-2025-001 (year-based)
|
|
* Supports: STORY-DUE-001 (phase-based)
|
|
* Supports: STORY-AUTH-001 (feature-based)
|
|
- ELSE: Treat as new story prompt
|
|
|
|
2. **VALIDATE** start-at and stop-at parameters:
|
|
- ENSURE start-at comes before stop-at in sequence
|
|
- VALID SEQUENCE: new → start → implement → review → qa → validate → save → ship → complete
|
|
- IF invalid: SHOW error and exit
|
|
|
|
3. **DISPLAY** workflow plan:
|
|
```
|
|
📋 STORY WORKFLOW PLAN
|
|
═══════════════════════
|
|
Story: [prompt or ID]
|
|
Sequence: [start-at] → [stop-at]
|
|
Mode: [auto ? "Automatic" : "Interactive"]
|
|
|
|
Steps to execute:
|
|
[list of steps that will run]
|
|
```
|
|
|
|
#### Phase 2: Sequential Execution
|
|
|
|
**STEP 1: /sdd:story-new** (IF start-at is "new")
|
|
1. **DETECT** if input is existing story ID:
|
|
- CHECK pattern: `STORY-[A-Z0-9]+-\d+`
|
|
- SEARCH for story file in all story directories:
|
|
* /docs/stories/backlog/
|
|
* /docs/stories/development/
|
|
* /docs/stories/review/
|
|
* /docs/stories/qa/
|
|
* /docs/stories/completed/
|
|
* /docs/project-context/phases/*/
|
|
2. IF story file found:
|
|
- SKIP story creation
|
|
- USE found story_id
|
|
- PROCEED to next step
|
|
3. ELSE (new story):
|
|
- EXECUTE: `/sdd:story-new` with prompt as story title
|
|
- CAPTURE: Generated story ID
|
|
- IF --auto flag NOT set:
|
|
- SHOW: Story creation summary
|
|
- ASK: "Continue to next step? (y/n)"
|
|
- IF no: EXIT workflow
|
|
- UPDATE: Current story_id variable
|
|
|
|
**STEP 2: /sdd:story-start** (IF in range)
|
|
1. EXECUTE: `/sdd:story-start [story_id]`
|
|
2. VERIFY: Branch created and checked out
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Branch and environment status
|
|
- ASK: "Continue to implementation? (y/n)"
|
|
- IF no: EXIT with current status
|
|
4. IF error:
|
|
- LOG: Error details
|
|
- OFFER: Skip this step, retry, or abort
|
|
- PROCEED based on user choice
|
|
|
|
**STEP 3: /sdd:story-implement** (IF in range)
|
|
1. EXECUTE: `/sdd:story-implement [story_id]`
|
|
2. VERIFY: Code generated successfully
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Files created/modified summary
|
|
- ASK: "Continue to review? (y/n)"
|
|
- IF no: EXIT with suggestion to run `/sdd:story-save`
|
|
4. IF error:
|
|
- SHOW: Implementation issues
|
|
- OFFER: Retry implementation or manual fix
|
|
- WAIT for user decision
|
|
|
|
**STEP 4: /sdd:story-review** (IF in range)
|
|
1. EXECUTE: `/sdd:story-review [story_id]`
|
|
2. VERIFY: Code quality checks passed
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Review results
|
|
- ASK: "Continue to QA? (y/n)"
|
|
- IF no: EXIT with refactor suggestions
|
|
4. IF review finds issues:
|
|
- DISPLAY: Issues found
|
|
- IF --auto: CONTINUE anyway with warning
|
|
- ELSE: OFFER to fix before continuing
|
|
|
|
**STEP 5: /sdd:story-qa** (IF in range)
|
|
1. EXECUTE: `/sdd:story-qa [story_id]`
|
|
2. VERIFY: All tests passed
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Test results summary
|
|
- ASK: "Continue to validation? (y/n)"
|
|
- IF no: EXIT with test failure details
|
|
4. IF tests fail:
|
|
- DISPLAY: Failed tests
|
|
- HALT workflow (QA must pass)
|
|
- SUGGEST: Fix tests and run `/sdd:story-flow [story_id] --start-at=qa`
|
|
- EXIT
|
|
|
|
**STEP 6: /sdd:story-validate** (IF in range)
|
|
1. EXECUTE: `/sdd:story-validate [story_id]`
|
|
2. VERIFY: All acceptance criteria met
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Validation checklist
|
|
- ASK: "Ready to save and ship? (y/n)"
|
|
- IF no: EXIT with validation details
|
|
4. IF validation fails:
|
|
- DISPLAY: Unmet criteria
|
|
- HALT workflow
|
|
- SUGGEST: Address issues and retry
|
|
- EXIT
|
|
|
|
**STEP 7: /sdd:story-save** (IF in range)
|
|
1. EXECUTE: `/sdd:story-save` with auto-generated commit message
|
|
2. VERIFY: Changes committed successfully
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Commit summary
|
|
- ASK: "Continue to ship? (y/n)"
|
|
- IF no: EXIT with ship instructions
|
|
4. IF commit fails:
|
|
- SHOW: Git errors
|
|
- OFFER: Resolve conflicts or abort
|
|
- WAIT for resolution
|
|
|
|
**STEP 8: /sdd:story-ship** (IF in range)
|
|
1. EXECUTE: `/sdd:story-ship [story_id]`
|
|
2. VERIFY: Merged and deployed successfully
|
|
3. IF --auto flag NOT set:
|
|
- SHOW: Deployment summary
|
|
- ASK: "Complete story and archive? (y/n)"
|
|
- IF no: EXIT with completion instructions
|
|
4. IF error:
|
|
- HALT before deployment
|
|
- SHOW: Deployment errors
|
|
- SUGGEST: `/sdd:story-rollback [story_id]` if needed
|
|
- MANUAL intervention required
|
|
|
|
**STEP 9: /sdd:story-complete** (IF in range AND is stop-at)
|
|
1. EXECUTE: `/sdd:story-complete [story_id]`
|
|
2. VERIFY: Story file fully populated with:
|
|
- Retrospective notes
|
|
- Lessons learned
|
|
- Performance metrics
|
|
- Final documentation
|
|
3. VERIFY: Story archived to /docs/stories/completed/
|
|
4. SHOW: Final completion summary
|
|
5. IF error:
|
|
- SHOW: Archive errors
|
|
- SUGGEST: Manual completion via `/sdd:story-complete [story_id]`
|
|
- EXIT with partial completion status
|
|
|
|
#### Phase 3: Completion Summary
|
|
|
|
**DISPLAY** workflow completion status:
|
|
```
|
|
✅ STORY WORKFLOW COMPLETED
|
|
═══════════════════════════
|
|
Story: [story_id] - [Title]
|
|
Status: [current stage]
|
|
|
|
Completed Steps:
|
|
✓ Story created/loaded
|
|
✓ Development started (branch: [name])
|
|
✓ Implementation generated
|
|
✓ Code review passed
|
|
✓ QA tests passed
|
|
✓ Validation successful
|
|
✓ Changes committed
|
|
✓ Deployed to production
|
|
✓ Story completed and archived
|
|
|
|
[IF stopped before complete:]
|
|
⏸️ Workflow Paused
|
|
Next Step: /sdd:story-flow [story_id] --start-at=[next-step]
|
|
|
|
[IF any warnings:]
|
|
⚠️ Warnings:
|
|
[list of non-blocking issues]
|
|
|
|
Total Duration: [time elapsed]
|
|
Next Actions:
|
|
[context-appropriate suggestions]
|
|
```
|
|
|
|
### OUTPUTS
|
|
- Fully executed story workflow from specified start to stop
|
|
- Progress updates at each step
|
|
- Error handling with recovery options
|
|
- Final summary with deployment status
|
|
|
|
### RULES
|
|
- MUST execute steps in correct sequence order
|
|
- MUST validate each step before proceeding to next
|
|
- MUST halt on QA or validation failures
|
|
- SHOULD ask for confirmation between steps (unless --auto)
|
|
- MUST provide clear error messages and recovery options
|
|
- NEVER skip critical validation steps
|
|
- ALWAYS save work before shipping
|
|
- MUST update story file status at each stage
|
|
- MUST complete story retrospective and archive after shipping
|
|
|
|
## Examples
|
|
|
|
### Example 1: Full Workflow from New Story
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-flow "Add user registration form with email verification"
|
|
|
|
PROCESS:
|
|
→ Step 1/9: Creating story...
|
|
✅ Story created: STORY-2025-015
|
|
→ Prompt: Continue to start development? (y/n) y
|
|
|
|
→ Step 2/9: Starting development...
|
|
✅ Branch created: feature/registration-015
|
|
→ Prompt: Continue to implementation? (y/n) y
|
|
|
|
→ Step 3/9: Generating implementation...
|
|
✅ Files created: RegistrationForm.php, registration-form.blade.php, RegistrationTest.php
|
|
→ Prompt: Continue to review? (y/n) y
|
|
|
|
→ Step 4/9: Running code review...
|
|
✅ Review passed: 0 issues found
|
|
→ Prompt: Continue to QA? (y/n) y
|
|
|
|
→ Step 5/9: Running QA tests...
|
|
✅ All tests passed (Unit: 5, Feature: 3, Browser: 2)
|
|
→ Prompt: Continue to validation? (y/n) y
|
|
|
|
→ Step 6/9: Validating story...
|
|
✅ All acceptance criteria met
|
|
→ Prompt: Ready to save and ship? (y/n) y
|
|
|
|
→ Step 7/9: Committing changes...
|
|
✅ Committed: "feat: add user registration form with email verification"
|
|
→ Prompt: Continue to ship? (y/n) y
|
|
|
|
→ Step 8/9: Shipping to production...
|
|
✅ Merged to main, deployed successfully
|
|
→ Prompt: Complete story and archive? (y/n) y
|
|
|
|
→ Step 9/9: Completing and archiving story...
|
|
✅ Story file updated with retrospective and metrics
|
|
✅ Story archived to /docs/stories/completed/
|
|
|
|
OUTPUT:
|
|
✅ STORY WORKFLOW COMPLETED
|
|
═══════════════════════════
|
|
Story: STORY-2025-015 - Add user registration form
|
|
Status: completed
|
|
|
|
All steps completed successfully ✓
|
|
Total Duration: 13 minutes
|
|
```
|
|
|
|
### Example 2: Resume from Existing Story (Year-based ID)
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-flow STORY-2025-010 --start-at=qa --auto
|
|
|
|
PROCESS:
|
|
→ Loading story: STORY-2025-010
|
|
→ Starting from: qa
|
|
→ Auto mode: enabled
|
|
|
|
→ Step 1/5: Running QA tests...
|
|
✅ All tests passed
|
|
|
|
→ Step 2/5: Validating story...
|
|
✅ Validation successful
|
|
|
|
→ Step 3/5: Committing changes...
|
|
✅ Changes committed
|
|
|
|
→ Step 4/5: Shipping to production...
|
|
✅ Deployed successfully
|
|
|
|
→ Step 5/5: Completing and archiving story...
|
|
✅ Story completed and archived
|
|
|
|
OUTPUT:
|
|
✅ STORY WORKFLOW COMPLETED
|
|
Story: STORY-2025-010
|
|
Executed: qa → validate → save → ship → complete
|
|
Duration: 4 minutes
|
|
```
|
|
|
|
### Example 2b: Phase-based Story ID
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-flow STORY-DUE-001 --start-at=start
|
|
|
|
PROCESS:
|
|
→ Detected phase-based story: STORY-DUE-001
|
|
→ Found in: /docs/project-context/phases/phase-due-dates/
|
|
→ Starting from: start
|
|
→ Skipping story creation (already exists)
|
|
|
|
→ Step 1/7: Starting development...
|
|
✅ Branch created: feature/due-001-database-schema
|
|
→ Prompt: Continue to implementation? (y/n) y
|
|
|
|
→ Step 2/7: Generating implementation...
|
|
✅ Migration and model files created
|
|
→ Prompt: Continue to review? (y/n) y
|
|
|
|
[continues through workflow...]
|
|
|
|
OUTPUT:
|
|
✅ STORY WORKFLOW COMPLETED
|
|
Story: STORY-DUE-001 - Add Due Date Database Schema
|
|
Phase: due-dates
|
|
Duration: 8 minutes
|
|
```
|
|
|
|
### Example 3: Partial Workflow
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-flow "Fix login page responsive layout" --stop-at=review
|
|
|
|
PROCESS:
|
|
→ Step 1/4: Creating story...
|
|
✅ Story created: STORY-2025-016
|
|
|
|
→ Step 2/4: Starting development...
|
|
✅ Branch created: feature/login-layout-016
|
|
|
|
→ Step 3/4: Generating implementation...
|
|
✅ Implementation complete
|
|
|
|
→ Step 4/4: Running code review...
|
|
✅ Review passed
|
|
|
|
OUTPUT:
|
|
⏸️ WORKFLOW PAUSED AT: review
|
|
═══════════════════════════
|
|
Story: STORY-2025-016 - Fix login page layout
|
|
Status: in-review
|
|
|
|
Completed: new → start → implement → review
|
|
Next: /sdd:story-flow STORY-2025-016 --start-at=qa
|
|
|
|
To resume full workflow:
|
|
/sdd:story-flow STORY-2025-016 --start-at=qa --auto
|
|
```
|
|
|
|
### Example 4: QA Failure Handling
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-flow STORY-2025-012 --start-at=qa --auto
|
|
|
|
PROCESS:
|
|
→ Step 1/4: Running QA tests...
|
|
❌ Tests failed: 2 failures in Feature tests
|
|
|
|
OUTPUT:
|
|
❌ WORKFLOW HALTED AT: qa
|
|
═══════════════════════════
|
|
Story: STORY-2025-012
|
|
|
|
Failed Tests:
|
|
- Feature\TaskCompletionTest::test_task_can_be_marked_complete
|
|
- Feature\TaskCompletionTest::test_completed_task_updates_timestamp
|
|
|
|
QA must pass before proceeding.
|
|
|
|
Next Actions:
|
|
1. Review test failures above
|
|
2. Fix implementation issues
|
|
3. Run tests: vendor/bin/pest --filter=TaskCompletion
|
|
4. Resume workflow: /sdd:story-flow STORY-2025-012 --start-at=qa
|
|
```
|
|
|
|
## Edge Cases
|
|
|
|
### Story Already Shipped
|
|
```
|
|
IF story_id found in /docs/stories/completed/:
|
|
- SHOW: Story already completed
|
|
- OFFER: View story details or create new version
|
|
- SUGGEST: /sdd:story-new for related feature
|
|
- EXIT workflow
|
|
```
|
|
|
|
### Workflow Interrupted
|
|
```
|
|
IF user cancels mid-workflow:
|
|
- SHOW: Current step and status
|
|
- SAVE: Workflow state
|
|
- SUGGEST: Resume command with --start-at
|
|
- EXIT gracefully
|
|
```
|
|
|
|
### Mixed Mode (Some Steps Already Done)
|
|
```
|
|
IF starting mid-workflow and previous steps incomplete:
|
|
- DETECT: Missing prerequisites
|
|
- WARN: "Story implementation not found, cannot run QA"
|
|
- SUGGEST: Start from earlier step
|
|
- OFFER: Continue anyway (risky) or restart
|
|
```
|
|
|
|
## Error Handling
|
|
- **Invalid step name**: Show valid step names and exit
|
|
- **Story not found**: Search all story locations (backlog, development, review, qa, completed, phases), suggest `/sdd:story-new` or check story ID
|
|
- **Ambiguous story ID**: If multiple stories found with similar IDs, list them and ask user to specify
|
|
- **Step prerequisites missing**: Show missing requirements and suggest order
|
|
- **Git conflicts**: Halt workflow, show conflict files, require manual resolution
|
|
- **Test failures**: Always halt, never auto-continue on failures
|
|
- **Deployment errors**: Halt before merge, offer rollback option
|
|
|
|
## Performance Considerations
|
|
- Each step executes sequentially (no parallelization)
|
|
- Expected total time: 10-20 minutes for full workflow
|
|
- Auto mode reduces interaction time by ~50%
|
|
- Can pause/resume at any step without data loss
|
|
|
|
## Related Commands
|
|
- `/sdd:story-new` - Create individual story (Step 1)
|
|
- `/sdd:story-start` - Start development (Step 2)
|
|
- `/sdd:story-implement` - Generate code (Step 3)
|
|
- `/sdd:story-review` - Code review (Step 4)
|
|
- `/sdd:story-qa` - Run tests (Step 5)
|
|
- `/sdd:story-validate` - Final validation (Step 6)
|
|
- `/sdd:story-save` - Commit changes (Step 7)
|
|
- `/sdd:story-ship` - Deploy to production (Step 8)
|
|
- `/sdd:story-complete` - Complete story with retrospective and archive (Step 9)
|
|
- `/sdd:story-rollback` - Rollback if issues arise
|
|
|
|
## Constraints
|
|
- ✅ MUST execute steps in correct order
|
|
- ✅ MUST halt on test or validation failures
|
|
- ✅ MUST support flexible story ID patterns (year-based, phase-based, feature-based)
|
|
- ✅ MUST search all story locations (backlog, development, review, qa, completed, phases)
|
|
- ⚠️ NEVER skip QA or validation steps
|
|
- ⚠️ NEVER auto-continue on errors in auto mode
|
|
- 📋 MUST save work before shipping
|
|
- 🔧 SHOULD provide resume options on failure
|
|
- 💾 MUST update story status at each step
|
|
- 🚀 MUST verify deployment success before completion
|
|
- 📚 MUST complete story retrospective and archive after shipping
|
|
|
|
## Notes
|
|
- This command automates the entire story lifecycle
|
|
- Interactive mode (default) allows review at each step
|
|
- Auto mode (`--auto`) speeds up workflow but still halts on errors
|
|
- Partial workflows supported via --start-at and --stop-at
|
|
- All individual commands can still be run separately
|
|
- Workflow state is preserved for resume capability
|
|
- Supports multiple story ID formats:
|
|
* Year-based: STORY-2025-001
|
|
* Phase-based: STORY-DUE-001, STORY-AUTH-001
|
|
* Feature-based: STORY-API-001
|
|
- Searches all story locations including project-context/phases/
|