11 KiB
11 KiB
/sdd:story-start
Meta
- Version: 2.0
- Category: workflow
- Complexity: comprehensive
- Purpose: Initialize story development with branch creation, context loading, and boilerplate generation
Definition
Purpose: Start development on a specified story by creating a feature branch, loading project context, optionally generating boilerplate, and preparing the development environment.
Syntax: /sdd:story-start <story_id> [--boilerplate]
Parameters
| Parameter | Type | Required | Default | Description | Validation |
|---|---|---|---|---|---|
| story_id | string | Yes | - | Story identifier (e.g., "STORY-001") | Must match pattern STORY-\d{3,} |
| --boilerplate | flag | No | false | Generate initial boilerplate files | Boolean flag |
Behavior
INSTRUCTION: Initialize story development environment with context-aware setup
INPUTS:
- story_id: Story identifier from /docs/stories/development/ or /docs/stories/backlog/
- --boilerplate: Optional flag to generate framework-specific starter files
PROCESS:
Phase 1: Project Context Loading
1. CHECK if /docs/project-context/ directory exists
2. IF missing:
- SUGGEST running /sdd:project-init first
- HALT execution
3. ELSE:
- LOAD /docs/project-context/technical-stack.md
- LOAD /docs/project-context/coding-standards.md
- LOAD /docs/project-context/development-process.md
4. PARSE technical stack to identify:
- ACTUAL frontend framework (React/Vue/Svelte/Laravel Blade/etc.)
- ACTUAL backend framework and runtime
- ACTUAL testing framework and tools
- ACTUAL build tools and package manager
- ACTUAL database system
Phase 2: Story File Discovery
1. SEARCH for story file in order:
- CHECK /docs/stories/development/[story_id].md
- IF NOT FOUND: CHECK /docs/stories/backlog/[story_id].md
- IF NOT FOUND: OFFER to create with /sdd:story-new
2. READ story file and extract:
- Branch name (or generate from story ID)
- Success criteria
- Technical requirements
- Implementation approach
Phase 3: Git Branch Setup
1. CHECK if feature branch exists:
- RUN: git branch --list [branch-name]
2. IF branch exists:
- SWITCH to existing branch
- SHOW: "Switched to existing branch: [branch-name]"
3. ELSE:
- CREATE new branch from main/master
- CHECKOUT new branch
- SHOW: "Created and switched to: [branch-name]"
4. DISPLAY current branch status:
- Branch name
- Last commit
- Uncommitted changes (if any)
Phase 4: Boilerplate Generation (IF --boilerplate flag present)
1. IDENTIFY framework from technical-stack.md
2. GENERATE framework-specific files:
IF React:
- Component files (.jsx/.tsx)
- Hook files (use[Feature].js)
- Style files (CSS/SCSS/Tailwind)
- Test files (.test.jsx/.spec.tsx)
IF Vue:
- Component files (.vue)
- Composable files (use[Feature].js)
- Style files (scoped styles)
- Test files (.spec.js)
IF Laravel + Livewire:
- Livewire component classes (app/Livewire/)
- Blade view files (resources/views/livewire/)
- Migration files (database/migrations/)
- Test files (tests/Feature/, tests/Browser/)
IF Django:
- View files (views.py)
- Model files (models.py)
- Template files (templates/)
- Form files (forms.py)
- Test files (tests/)
IF Express:
- Route files (routes/)
- Controller files (controllers/)
- Middleware files (middleware/)
- Test files (.test.js)
IF Next.js:
- Page/route files (pages/ or app/)
- API route files (api/)
- Component files
- Test files
3. APPLY coding standards from coding-standards.md:
- Follow DISCOVERED file naming conventions
- Apply DISCOVERED directory structure
- Use DISCOVERED code formatting
- Include DISCOVERED file headers/comments
4. GENERATE test structure for DISCOVERED testing framework:
- Jest/Vitest: .test.js/.spec.js with describe/it blocks
- Pest: .php test files with it() syntax
- Pytest: test_*.py with test_ functions
- JUnit: *Test.java with @Test annotations
5. SET UP development environment:
- Install dependencies using DISCOVERED package manager
- Run initial build using DISCOVERED build tools
- Verify setup with basic test
Phase 5: Story File Update
1. UPDATE story file with:
- Progress log entry: "Development started - [timestamp]"
- Status: "development" (if was "backlog")
- Branch name: [branch-name]
- Tech stack used: [list of technologies from context]
2. IF boilerplate generated:
- LIST generated files in progress log
- NOTE initial setup completion
Phase 6: Next Steps Display
1. SHOW next steps in numbered format:
1. Review success criteria
2. Use /sdd:story-implement to generate code for DISCOVERED stack
3. Use /sdd:story-save to commit progress
4. Use /sdd:story-review when ready
2. MENTION relevant development commands for DISCOVERED stack:
- npm run dev / composer dev / python manage.py runserver / etc.
- Test commands for DISCOVERED framework
- Linting commands for DISCOVERED tools
OUTPUT FORMAT:
✅ STORY DEVELOPMENT STARTED
Story: [story_id] - [Title] Branch: [branch-name] Stack: [DISCOVERED framework + technologies]
Project Context Loaded:
- Frontend: [DISCOVERED frontend framework]
- Backend: [DISCOVERED backend framework]
- Testing: [DISCOVERED testing tools]
- Build: [DISCOVERED build system]
[IF boilerplate generated:] Generated Files:
- [list of created files with paths]
Next Steps:
- Review success criteria
- /sdd:story-implement to generate implementation
- /sdd:story-save to commit progress
- /sdd:story-review when ready for review
Development Commands:
- Server: [DISCOVERED dev server command]
- Tests: [DISCOVERED test command]
- Lint: [DISCOVERED lint command]
RULES:
- MUST load project context before proceeding
- MUST adapt all generated code to DISCOVERED stack
- NEVER assume framework - ALWAYS read technical-stack.md
- MUST create branch if it doesn't exist
- MUST update story file with start timestamp
- SHOULD generate boilerplate only if --boilerplate flag present
- MUST follow DISCOVERED coding standards exactly
Examples
Example 1: Start Story Without Boilerplate
INPUT:
/sdd:story-start STORY-AUTH-001
PROCESS:
→ Loading project context from /docs/project-context/
→ Technical stack: Laravel + Livewire + Tailwind + Pest
→ Found story: /docs/stories/backlog/STORY-AUTH-001.md
→ Creating branch: feature/auth-001-login-form
→ Switched to new branch
OUTPUT:
✅ STORY DEVELOPMENT STARTED
============================
Story: STORY-AUTH-001 - Implement Login Form
Branch: feature/auth-001-login-form
Stack: Laravel 12 + Livewire 3 + Tailwind CSS 4 + Pest 4
Project Context Loaded:
- Frontend: Laravel Blade + Livewire + Alpine.js
- Backend: Laravel 12 (PHP 8.4)
- Testing: Pest (Unit, Feature, Browser)
- Build: Vite 7
Next Steps:
1. Review success criteria in story file
2. /sdd:story-implement to generate Livewire component
3. /sdd:story-save to commit progress
4. /sdd:story-review when ready for code review
Development Commands:
- Server: composer dev (or php artisan serve)
- Tests: vendor/bin/pest
- Lint: vendor/bin/pint
Example 2: Start Story With Boilerplate
INPUT:
/sdd:story-start STORY-PROFILE-002 --boilerplate
PROCESS:
→ Loading project context
→ Technical stack: React + TypeScript + Vite + Jest
→ Found story: /docs/stories/development/STORY-PROFILE-002.md
→ Branch already exists: feature/profile-002-settings
→ Switched to existing branch
→ Generating React boilerplate...
OUTPUT:
✅ STORY DEVELOPMENT STARTED
============================
Story: STORY-PROFILE-002 - User Profile Settings
Branch: feature/profile-002-settings (existing)
Stack: React 18 + TypeScript + Vite + Jest
Project Context Loaded:
- Frontend: React 18 (TypeScript)
- State: Redux Toolkit
- Testing: Jest + React Testing Library
- Build: Vite 5
Generated Files:
- src/components/ProfileSettings.tsx
- src/components/ProfileSettings.module.css
- src/hooks/useProfileSettings.ts
- src/tests/ProfileSettings.test.tsx
Next Steps:
1. Review success criteria in story file
2. /sdd:story-implement to add implementation logic
3. /sdd:story-save to commit boilerplate
4. /sdd:story-review when feature complete
Development Commands:
- Server: npm run dev
- Tests: npm test
- Lint: npm run lint
Example 3: Story Not Found
INPUT:
/sdd:story-start STORY-UNKNOWN-999
PROCESS:
→ Loading project context
→ Searching for STORY-UNKNOWN-999
→ Not found in /docs/stories/development/
→ Not found in /docs/stories/backlog/
→ Story does not exist
OUTPUT:
❌ Story Not Found
==================
Story ID: STORY-UNKNOWN-999
The story file was not found in:
- /docs/stories/development/
- /docs/stories/backlog/
Would you like to create this story?
→ Use: /sdd:story-new "Story title and description"
Example 4: Missing Project Context
INPUT:
/sdd:story-start STORY-API-003
PROCESS:
→ Checking for /docs/project-context/ directory
→ Directory not found
OUTPUT:
⚠️ Project Context Missing
==========================
Cannot start story without project context.
The /docs/project-context/ directory does not exist.
This directory defines your technical stack and coding standards.
Please run: /sdd:project-init
This will create:
- /docs/project-context/technical-stack.md
- /docs/project-context/coding-standards.md
- /docs/project-context/development-process.md
After initialization, run /sdd:story-start again.
Edge Cases
Story Already in Development
IF story found in /docs/stories/development/:
- SWITCH to story branch
- SHOW: "Story already in development"
- DISPLAY: Current progress
- SUGGEST: /sdd:story-continue to resume
Branch Exists But Diverged
IF branch exists AND has diverged from main:
- SHOW: Warning about diverged branch
- OFFER options:
1. Continue on current branch
2. Rebase on main
3. Create new branch with suffix (-v2)
Boilerplate with Existing Files
IF --boilerplate flag AND files already exist:
- CHECK for conflicts
- SHOW: List of existing files
- ASK: Overwrite, skip, or merge?
- PROCEED based on user choice
Error Handling
- Story ID missing: Return "Error: Story ID required. Usage: /sdd:story-start <story_id>"
- Invalid story ID format: Return "Error: Invalid story ID format. Expected: STORY-XXX-NNN"
- Project context missing: Halt and suggest /sdd:project-init
- Context files corrupted: Show error and suggest manual review
- Git branch error: Show git error and suggest manual resolution
- File generation error: Show which files failed and suggest manual creation
Performance Considerations
- Load project context files only once at start
- Cache parsed technical stack for session
- Generate boilerplate asynchronously to avoid blocking
- Skip dependency installation if package.json/composer.json unchanged
Related Commands
/sdd:story-new- Create a new story before starting/sdd:story-continue- Resume work on existing story/sdd:story-implement- Generate implementation code/sdd:story-save- Commit progress/sdd:project-init- Initialize project context
Notes
- Project context is mandatory for story development
- Branch naming follows convention: feature/[story-id-kebab-case]
- Boilerplate generation is framework-aware and respects coding standards
- All generated code must match the DISCOVERED technical stack
- Never assume technology choices - always read and adapt