zhongwei/gh-ninthspace-claude-code-marketplace-sdd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97a70be331ab765e3a939a4d772797f37f783bc
gh-ninthspace-claude-code-m…/commands/story-new.md
Zhongwei Li d97a70be33 Initial commit
2025-11-30 08:44:27 +08:00

11 KiB
Raw Blame History

/sdd:story-new

Meta

  • Version: 2.0
  • Category: story-management
  • Complexity: medium
  • Purpose: Create new story with auto-populated template and place in backlog

Definition

Purpose: Create a new story using project context and place it in the backlog folder for future development.

Syntax: /sdd:story-new [story_id_number]

Parameters

Parameter Type Required Default Description Validation
story_id_number number No auto-increment Story number (used as STORY-YYYY-NNN) Positive integer

INSTRUCTION: Create New Story

INPUTS

  • story_id_number: Optional story number (auto-increments if not provided)
  • Project context from /docs/project-context/ directory
  • User-provided story details (if not in project brief)

PROCESS

Phase 1: Project Context Loading

  1. CHECK if /docs/project-context/ directory exists
  2. IF missing:
    • SUGGEST running /sdd:project-init first
    • EXIT with initialization guidance
  3. LOAD project context from:
    • /docs/project-context/project-brief.md - Existing story definitions, goals
    • /docs/project-context/technical-stack.md - Technology implementation requirements
    • /docs/project-context/coding-standards.md - Testing and quality requirements

Phase 2: Story ID Generation

  1. GENERATE story ID in format STORY-YYYY-NNN:

    • YYYY = current year
    • NNN = sequential number (001, 002, etc.)

  2. IF user provides story_id_number:

    • USE as basis: STORY-YYYY-[story_id_number]
    • EXAMPLE: Input "5" → "STORY-2025-005"

  3. CHECK for existing IDs across all directories:

    • SCAN /docs/stories/backlog/
    • SCAN /docs/stories/development/
    • SCAN /docs/stories/review/
    • SCAN /docs/stories/qa/
    • SCAN /docs/stories/completed/
    • CHECK /docs/project-context/project-brief.md for planned stories

  4. IF no specific number provided:

    • INCREMENT to next available number
    • ENSURE uniqueness across all locations

Phase 3: Story Information Gathering

  1. SEARCH /docs/project-context/project-brief.md for story with generated ID

  2. IF story exists in project brief:

    • EXTRACT comprehensive story details:
      • Story title and description
      • User scenarios and use cases
      • Technical implementation requirements
      • Acceptance criteria (pass/fail conditions)
      • Edge cases and error handling requirements
      • UI/UX considerations
      • Testing requirements and test scenarios
      • Integration points with other stories/systems
      • Dependencies on other stories

  3. IF story NOT found in project brief:

    • ASK user for story title
    • ASK user for story description and purpose
    • ASK user for acceptance criteria
    • ASK user for technical approach (optional)
    • ASK user for dependencies (optional)

Phase 4: Story File Creation

  1. ENSURE /docs/stories/backlog/ directory exists

    • CREATE directory if missing
    • ADD .gitkeep file if directory was created

  2. CREATE story file at /docs/stories/backlog/[story-id].md

  3. POPULATE template with:

    • Story ID and title
    • Status: backlog
    • Today's date as "Started" date
    • Empty "Completed" date
    • Note: "(none - in backlog)" for branch
    • What & Why section (from project brief or user input)
    • Success Criteria (from project brief or user input)
    • Technical Notes with:
      • Approach (from project brief or user input)
      • Stack (auto-populated from technical-stack.md)
      • Concerns (from project brief edge cases or user input)
      • Dependencies (from project brief or user input)
    • Implementation Checklist (standard items)
    • Progress Log with creation entry
    • Test Cases (from project brief or default scenarios)
    • UI/UX Considerations (from project brief if applicable)
    • Integration Points (from project brief if applicable)
    • Rollback Plan section (empty template)
    • Lessons Learned section (empty template)

  4. REFERENCE project context in template:

    • Pull technology stack from technical-stack.md
    • Note coding standards that will apply
    • Reference testing framework requirements
    • Include project goals and constraints from project-brief.md

Phase 5: Completion Summary

  1. DISPLAY creation summary:

    ✅ Story Created
═══════════════════════════════════

Story ID: [STORY-YYYY-NNN]
Title: [Story Title]
Location: /docs/stories/backlog/[story-id].md
Status: backlog

[If from project brief:]
Source: Extracted from project brief
- Acceptance criteria: [count] criteria defined
- Test scenarios: [count] scenarios defined
- Dependencies: [list or "None"]

[If from user input:]
Source: User-provided details
- Ready for refinement before development

  2. SUGGEST next steps:

    💡 NEXT STEPS:
1. /sdd:story-start [story-id]     # Move to development and create branch
2. /sdd:story-implement [story-id]  # Generate implementation code
3. /sdd:project-status              # View all project stories

OUTPUTS

  • /docs/stories/backlog/[story-id].md - New story file with populated template
  • .gitkeep file in /docs/stories/backlog/ if directory was created

RULES

  • MUST generate unique story ID across all story directories
  • MUST create backlog directory if it doesn't exist
  • MUST auto-populate template with project context
  • SHOULD extract story details from project brief if available
  • SHOULD reference technical stack in story template
  • NEVER create feature branch (stories start in backlog)
  • ALWAYS add progress log entry for creation
  • MUST include today's date as "Started" date

Story Template Structure

# [STORY-ID]: [Title]

## Status: backlog
**Started:** [Today's Date]
**Completed:**
**Branch:** (none - in backlog)

## What & Why
[Story description and purpose]

## Success Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Technical Notes
**Approach:** [Implementation approach]
**Stack:** [Auto-populated from technical-stack.md]
**Concerns:** [Risks and edge cases]
**Dependencies:** [External services/libraries/other stories]

## Implementation Checklist
- [ ] Feature implementation
- [ ] Unit tests
- [ ] Integration tests
- [ ] Error handling
- [ ] Loading states
- [ ] Documentation
- [ ] Performance optimization
- [ ] Accessibility
- [ ] Security review

## Progress Log
- [Today]: Created story, added to backlog

## Test Cases
1. Happy path: [scenario]
2. Error case: [scenario]
3. Edge case: [scenario]

## UI/UX Considerations
[User interface and experience requirements]

## Integration Points
[Dependencies and integration with other systems]

## Rollback Plan
[How to rollback if issues arise]

## Lessons Learned
[To be filled when complete]

Examples

Example 1: Create from Project Brief

INPUT:
/sdd:story-new

OUTPUT:
→ Checking project context...
→ Generating story ID: STORY-2025-001
→ Found story definition in project brief

✅ Story Created
═══════════════════════════════════

Story ID: STORY-2025-001
Title: User Authentication System
Location: /docs/stories/backlog/STORY-2025-001.md
Status: backlog

Source: Extracted from project brief
- Acceptance criteria: 5 criteria defined
- Test scenarios: 8 scenarios defined
- Dependencies: None

💡 NEXT STEPS:
1. /sdd:story-start STORY-2025-001     # Move to development and create branch
2. /sdd:story-implement STORY-2025-001  # Generate implementation code
3. /sdd:project-status                  # View all project stories

Example 2: Create with Specific ID

INPUT:
/sdd:story-new 10

OUTPUT:
→ Checking project context...
→ Using story ID: STORY-2025-010
→ Story not found in project brief, gathering details...

What is the story title?
> Add Dark Mode Toggle

What are you building and why?
> Implement a dark mode toggle in the settings page to allow users to switch between light and dark themes.

What are the acceptance criteria? (Enter each, then empty line when done)
> Toggle is visible in settings page
> Theme persists across sessions
> All UI components support both themes
>

✅ Story Created
═══════════════════════════════════

Story ID: STORY-2025-010
Title: Add Dark Mode Toggle
Location: /docs/stories/backlog/STORY-2025-010.md
Status: backlog

Source: User-provided details
- Ready for refinement before development

💡 NEXT STEPS:
1. /sdd:story-start STORY-2025-010      # Move to development and create branch
2. /sdd:story-implement STORY-2025-010   # Generate implementation code
3. /sdd:project-status                   # View all project stories

Example 3: Auto-Increment ID

INPUT:
/sdd:story-new

OUTPUT:
→ Checking project context...
→ Found existing stories: STORY-2025-001 through STORY-2025-005
→ Auto-incrementing to: STORY-2025-006
→ Story not found in project brief, gathering details...

[Interactive prompts for story details...]

✅ Story Created
═══════════════════════════════════

Story ID: STORY-2025-006
Title: Payment Processing Integration
Location: /docs/stories/backlog/STORY-2025-006.md
Status: backlog

Edge Cases

No Project Context

  • DETECT missing /docs/project-context/ directory
  • SUGGEST running /sdd:project-init
  • OFFER to create story with minimal template
  • WARN that template won't be auto-populated

Duplicate Story ID

  • DETECT ID conflict across all directories
  • INCREMENT to next available number automatically
  • LOG warning about skipped number
  • ENSURE final ID is unique

Empty Project Brief

  • DETECT missing story definitions
  • GATHER all details from user interactively
  • CREATE story with user-provided information
  • SUGGEST adding stories to project brief

Malformed Project Brief

  • DETECT parsing errors
  • LOG warning about brief issues
  • FALL BACK to user input mode
  • CONTINUE with story creation

Error Handling

  • Missing /docs/project-context/: Suggest /sdd:project-init with guidance
  • Permission errors: Report specific file/directory with access issue
  • Invalid story ID: Sanitize and suggest corrected version
  • User cancels: Clean up partial creation, exit gracefully

Performance Considerations

  • Story ID checking optimizes by scanning directories once
  • Project brief parsing caches results for session
  • Template population is fast (< 100ms typically)
  • Interactive prompts allow user to control pace

Related Commands

  • /sdd:project-init - Initialize project structure first
  • /sdd:project-brief - Create/update project documentation with stories
  • /sdd:story-start [id] - Begin development on story
  • /sdd:story-implement [id] - Generate implementation code
  • /sdd:project-status - View all project stories

Constraints

  • ✅ MUST generate unique story ID
  • ✅ MUST create story in backlog directory
  • ⚠️ NEVER create feature branch (stories start in backlog)
  • 📋 MUST auto-populate from project context when available
  • 🔧 SHOULD extract from project brief before asking user
  • 💾 MUST add creation entry to progress log
  • 📅 MUST include today's date as "Started" date
Reference in New Issue View Git Blame Copy Permalink