384 lines
11 KiB
Markdown
384 lines
11 KiB
Markdown
# /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:
|
|
1. Review success criteria
|
|
2. /sdd:story-implement to generate implementation
|
|
3. /sdd:story-save to commit progress
|
|
4. /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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|