/sdd:story-start

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

/story-start