zhongwei/gh-ninthspace-claude-code-marketplace-sdd

Files

Zhongwei Li d97a70be33 Initial commit

2025-11-30 08:44:27 +08:00

18 KiB

Raw Permalink Blame History

/sdd:story-save

Definition

Purpose: Save current progress by creating a properly formatted git commit with automatic commit type detection, story context integration, and story file progress logging.

Syntax: /sdd:story-save [message]

Parameters

Parameter	Type	Required	Default	Description	Validation
message	string	No	auto-generated	Custom commit message or description	Max 500 chars

INSTRUCTION: Save Story Progress

INPUTS

Current git working directory changes
Story ID from branch name or active story
Story file from /docs/stories/development/, /docs/stories/review/, or /docs/stories/qa/
Optional: User-provided commit message
Project context from /docs/project-context/ (optional for enhanced commit messages)

PROCESS

Phase 1: Git Status Analysis

CHECK git repository status:
- RUN: git status --porcelain
- IF no changes exist:
  - SHOW: "✅ Working tree clean - nothing to commit"
  - SUGGEST: Continue working or use /sdd:story-review
  - EXIT gracefully
CATEGORIZE changes:
- MODIFIED files: List files with 'M' status
- UNTRACKED files: List files with '??' status
- DELETED files: List files with 'D' status
- RENAMED files: List files with 'R' status
ANALYZE file sizes:
- CHECK for large files (> 5MB)
- WARN about potentially sensitive files (.env, credentials.json, etc.)
- FLAG binary files that might bloat repository

DISPLAY changes summary:

📝 CHANGES TO COMMIT
════════════════════════════════════
Modified: [count] files
- [file1]
- [file2]

Untracked: [count] files
- [file3]
- [file4]

[If warnings exist:]
⚠️ WARNINGS:
- Large file detected: [file] ([size]MB)
- Potential secret: [file]

Phase 2: Story Context Discovery

IDENTIFY current story:
- ATTEMPT 1: Extract from current git branch name
  - PATTERN: feature/[story-id]-[description]
  - EXAMPLE: feature/STORY-AUTH-001-login-form → STORY-AUTH-001
- ATTEMPT 2: Find most recently modified story in /docs/stories/development/
- ATTEMPT 3: Check /docs/stories/review/ and /docs/stories/qa/
- IF no story found: PROCEED without story context
READ story file (if found):
- EXTRACT story title
- EXTRACT current status
- EXTRACT branch name
- EXTRACT last progress log entry
- EXTRACT implementation checklist status
VALIDATE story alignment:
- IF story branch doesn't match current branch:
  - WARN: "Current branch doesn't match story branch"
  - ASK: Continue with commit anyway? (y/n)

Phase 3: Commit Type Detection

ANALYZE changed files to determine commit type:

Detection Rules:
- feat: New feature files, new components, new functionality
  - New files in app/, src/, lib/
  - New Livewire components, React components, Vue components
  - New controllers, models, services
- fix: Bug fixes, error corrections
  - Modifications to fix issues
  - Changes to error handling
  - Corrections to logic
- refactor: Code restructuring without behavior change
  - File moves, renames
  - Code organization changes
  - Performance improvements without new features
- test: Test additions or modifications
  - New or modified files in tests/, tests/
  - Test files (.test.js, .spec.js, Test.php)
- docs: Documentation only
  - Changes to .md files only
  - README updates
  - Comment updates only
- style: Formatting, whitespace, linting
  - Style files only (.css, .scss, .sass)
  - Formatting changes (after running Pint, Prettier)
- perf: Performance improvements
  - Optimization changes
  - Database query improvements
  - Caching additions
- chore: Maintenance, dependencies, configuration
  - package.json, composer.json updates
  - Config file changes
  - Build script updates
SELECT primary commit type:
- IF multiple types apply: SELECT most significant
- PRIORITY ORDER: feat > fix > refactor > test > perf > docs > style > chore
DETERMINE scope from changes:
- IF story exists: USE story context (e.g., "auth", "profile", "cart")
- ELSE: USE directory/module name
- EXAMPLES: "auth", "api", "ui", "database", "tests"

Phase 4: Commit Message Generation

IF user provided message:
- USE provided message as description
- FORMAT: [type]([scope]): [user message]
- EXAMPLE: "feat(auth): add two-factor authentication"
ELSE auto-generate message:
- ANALYZE changes to create descriptive message
- USE story title if available
- INCLUDE key changes summary
- FORMAT: [type]([scope]): [auto-generated description]

CREATE full commit message:

[type]([scope]): [description]

[If story exists:]
Story: [STORY-ID] - [Story Title]

Changes:
- [Change 1]
- [Change 2]
- [Change 3]

[If applicable:]
Files: [count] modified, [count] added, [count] deleted

VALIDATE commit message format:
- TYPE must be valid conventional commit type
- SCOPE should be lowercase, hyphen-separated
- DESCRIPTION should be lowercase, imperative mood
- LENGTH should be under 72 chars for first line

Phase 5: Story File Update

IF story file exists:

ADD progress log entry:

- [YYYY-MM-DD HH:MM]: [commit description]
  * Files: [list key files]
  * Type: [commit type]
  * [Additional context if significant changes]

UPDATE checklist items (if applicable):
- DETECT completed work from commit type
- IF commit type is "test": Mark "Unit tests" or "Integration tests" as complete
- IF commit type is "feat": Check if feature implementation complete
- IF commit type is "docs": Mark "Documentation" as complete
NOTE implementation decisions (if significant):
- ADD to Technical Notes section if architectural changes
- DOCUMENT trade-offs or important decisions
- REFERENCE commit hash (will be added after commit)

Phase 6: Staging and Commit

STAGE changes:
- IF story file was updated: INCLUDE story file in commit
- ADD all relevant modified files
- ADD all relevant untracked files
- EXCLUDE files from .gitignore
- SKIP large files or sensitive files (with warning)
CREATE commit:
- RUN: git add [files]
- RUN: git commit -m "[commit message]"
- CAPTURE commit hash
- CAPTURE commit timestamp
UPDATE story file with commit hash:
- ADD commit hash to latest progress log entry
- FORMAT: Commit: [hash]
VERIFY commit succeeded:
- RUN: git log -1 --oneline
- CONFIRM commit appears in history

Phase 7: Commit Summary Display

DISPLAY comprehensive commit summary:

✅ CHANGES COMMITTED
════════════════════════════════════
Commit: [hash]
Type: [type]
Scope: [scope]
Message: [description]

[If story exists:]
Story: [STORY-ID] - [Story Title]

Files Changed: [count]
📄 Modified: [count]
- [file1] ([+X/-Y lines])
- [file2] ([+X/-Y lines])

➕ Added: [count]
- [file3] ([+X lines])

➖ Deleted: [count]
- [file4] ([X lines])

Statistics:
Lines Added: [count]
Lines Removed: [count]

💡 NEXT STEPS:
1. /sdd:story-implement [story-id] - Continue development
2. /sdd:story-review - Move to code review when ready
3. git push - Push to remote when ready to share

OUTPUTS

Git commit with formatted conventional commit message
Updated story file with progress log entry
Commit statistics and file change summary
Next action suggestions based on story status

RULES

MUST check for uncommitted changes before proceeding
MUST determine appropriate commit type from changes
MUST create properly formatted conventional commit message
MUST update story file before committing (include in same commit)
MUST warn about large files or potential secrets
SHOULD auto-detect story context from branch name
SHOULD provide meaningful auto-generated messages
SHOULD include story context in commit body
MUST NOT commit files that likely contain secrets
MUST NOT proceed if no changes exist
NEVER force push or amend commits without confirmation

Examples

Example 1: Feature Implementation Commit

INPUT:
/sdd:story-save

PROCESS:
→ Checking git status...
→ Found 5 modified files, 2 new files
→ Detecting story context...
→ Current branch: feature/STORY-AUTH-001-login-form
→ Story: STORY-AUTH-001 - Implement Login Form
→ Analyzing changes...
→ Detected commit type: feat
→ Generating commit message...
→ Updating story file...
→ Staging changes...
→ Creating commit...

OUTPUT:
✅ CHANGES COMMITTED
════════════════════════════════════
Commit: abc1234
Type: feat
Scope: auth
Message: implement login form with validation

Story: STORY-AUTH-001 - Implement Login Form

Files Changed: 7
📄 Modified: 5
- app/Livewire/Auth/LoginForm.php (+145/-0 lines)
- resources/views/livewire/auth/login-form.blade.php (+67/-0 lines)
- routes/web.php (+5/-0 lines)
- tests/Feature/Auth/LoginTest.php (+89/-0 lines)
- stories/development/STORY-AUTH-001.md (+8/-1 lines)

➕ Added: 2
- app/Http/Controllers/Auth/LoginController.php (+52 lines)
- tests/Browser/Auth/LoginFormTest.php (+43 lines)

Statistics:
Lines Added: 409
Lines Removed: 1

💡 NEXT STEPS:
1. /sdd:story-implement STORY-AUTH-001 - Continue development
2. /sdd:story-review - Move to code review when ready
3. git push - Push to remote when ready to share

Example 2: Custom Commit Message

INPUT:
/sdd:story-save "add rate limiting to login endpoint"

PROCESS:
→ Checking git status...
→ Found 2 modified files
→ Using custom message: "add rate limiting to login endpoint"
→ Detecting story context...
→ Story: STORY-AUTH-001 - Implement Login Form
→ Analyzing changes...
→ Detected commit type: feat
→ Generating commit message...
→ Updating story file...
→ Creating commit...

OUTPUT:
✅ CHANGES COMMITTED
════════════════════════════════════
Commit: def5678
Type: feat
Scope: auth
Message: add rate limiting to login endpoint

Story: STORY-AUTH-001 - Implement Login Form

Changes:
- Added rate limiting middleware (5 attempts per minute)
- Updated login controller to use rate limiter
- Added rate limit exceeded error message

Files Changed: 2
📄 Modified: 2
- app/Http/Middleware/RateLimitLogin.php (+28/-0 lines)
- app/Livewire/Auth/LoginForm.php (+12/-3 lines)

Statistics:
Lines Added: 40
Lines Removed: 3

💡 NEXT STEPS:
1. /sdd:story-implement STORY-AUTH-001 - Continue development
2. /sdd:story-review - Move to code review when ready
3. git push - Push to remote when ready to share

Example 3: Test Addition Commit

INPUT:
/sdd:story-save

PROCESS:
→ Checking git status...
→ Found 3 new files (all tests)
→ Detecting story context...
→ Story: STORY-PROFILE-002 - User Profile Settings
→ Analyzing changes...
→ Detected commit type: test
→ Generating commit message...
→ Updating story file (marking test checklist items complete)...
→ Creating commit...

OUTPUT:
✅ CHANGES COMMITTED
════════════════════════════════════
Commit: ghi9012
Type: test
Scope: profile
Message: add comprehensive unit and browser tests

Story: STORY-PROFILE-002 - User Profile Settings

Files Changed: 4
➕ Added: 3
- tests/Unit/ProfileSettingsTest.php (+76 lines)
- tests/Feature/ProfileUpdateTest.php (+92 lines)
- tests/Browser/ProfileSettingsTest.php (+58 lines)

📄 Modified: 1
- stories/development/STORY-PROFILE-002.md (+3/-3 lines)
  * Marked "Unit tests" as complete
  * Marked "Browser tests" as complete

Statistics:
Lines Added: 229
Lines Removed: 3

💡 NEXT STEPS:
1. /sdd:story-implement STORY-PROFILE-002 - Continue development
2. /sdd:story-review - Move to code review when ready
3. git push - Push to remote when ready to share

Example 4: No Changes to Commit

INPUT:
/sdd:story-save

PROCESS:
→ Checking git status...
→ No uncommitted changes found

OUTPUT:
✅ WORKING TREE CLEAN
════════════════════════════════════

No changes to commit.

Current Status:
Branch: feature/STORY-AUTH-001-login-form
Story: STORY-AUTH-001 - Implement Login Form
Last Commit: abc1234 (2 hours ago)

💡 NEXT STEPS:
1. /sdd:story-implement STORY-AUTH-001 - Continue implementation
2. /sdd:story-review - Move to code review if complete
3. /sdd:story-continue - Resume work on story

Example 5: Warning About Large Files

INPUT:
/sdd:story-save

PROCESS:
→ Checking git status...
→ Found 3 modified files, 1 large file
→ Warning: Large file detected

OUTPUT:
⚠️ LARGE FILE DETECTED
════════════════════════════════════

Found large file that may bloat repository:
- public/videos/demo.mp4 (12.5 MB)

Changes to commit:
📄 Modified: 2
- app/Livewire/VideoPlayer.php
- resources/views/livewire/video-player.blade.php

➕ Added: 1
- public/videos/demo.mp4 (12.5 MB) ⚠️

Recommendation:
Large files should be stored externally (S3, CDN) or
use Git LFS for version control.

Continue with commit? [y/n]
> n

Commit cancelled.

💡 SUGGESTIONS:
1. Move large files to external storage
2. Add to .gitignore if not needed in repository
3. Use Git LFS for large binary files
4. /sdd:story-save (retry after removing large files)

Example 6: Fix Commit with Auto-Detection

INPUT:
/sdd:story-save

PROCESS:
→ Checking git status...
→ Found 2 modified files
→ Detecting story context...
→ Story: STORY-CART-003 - Shopping Cart Checkout
→ Analyzing changes...
→ Detected commit type: fix (error handling changes detected)
→ Generating commit message...
→ Creating commit...

OUTPUT:
✅ CHANGES COMMITTED
════════════════════════════════════
Commit: jkl3456
Type: fix
Scope: cart
Message: fix cart total calculation rounding error

Story: STORY-CART-003 - Shopping Cart Checkout

Changes:
- Fixed rounding error in cart total calculation
- Changed to use Decimal for currency calculations
- Updated tests to verify correct rounding

Files Changed: 2
📄 Modified: 2
- app/Services/CartService.php (+8/-4 lines)
- tests/Unit/CartServiceTest.php (+15/-2 lines)

Statistics:
Lines Added: 23
Lines Removed: 6

💡 NEXT STEPS:
1. /sdd:story-implement STORY-CART-003 - Continue development
2. /sdd:story-review - Move to code review when ready
3. git push - Push to remote when ready to share

Edge Cases

No Story Context Available

IF no story can be determined from branch or files:
- PROCEED with commit using generic scope
- USE directory name or "app" as scope
- SKIP story file update
- WARN: "No story context found - commit without story reference"

Multiple Stories Detected

IF branch name doesn't match active story:
- WARN: "Branch name suggests [STORY-A] but active story is [STORY-B]"
- ASK: Which story should this commit be associated with?
- USE selected story for commit message and file update

Untracked Story File

IF story file exists but is untracked:
- INCLUDE story file in commit
- NOTE: "Adding story file to repository"
- PROCEED with normal commit flow

Commit Message Too Long

IF generated message exceeds 72 characters:
- TRUNCATE first line to 72 chars
- MOVE details to commit body
- ENSURE proper formatting

Detached HEAD State

IF in detached HEAD state:
- WARN: "Currently in detached HEAD state"
- SHOW current commit
- SUGGEST: Create branch or checkout existing branch
- OFFER: Continue commit anyway? (y/n)

Merge Conflicts Present

IF merge conflicts detected:
- HALT: "Cannot commit with unresolved merge conflicts"
- LIST conflicted files
- SUGGEST: Resolve conflicts first using git mergetool
- EXIT with error

Error Handling

Not in git repository: Return "Error: Not in a git repository. Run 'git init' first"
No changes to commit: Show "Working tree clean" and exit gracefully
Git command fails: Show git error and suggest manual resolution
Story file read error: Warn and proceed without story context
Story file write error: Show error but continue with commit (story update optional)
Large file detected: Warn and ask for confirmation before proceeding
Sensitive file detected: Warn strongly and require explicit confirmation

Performance Considerations

Use git status --porcelain for fast, parseable output
Read only necessary parts of story file (don't parse everything)
Cache story context within command execution
Run git commands in sequence (they're fast enough)
Skip expensive diff calculations for very large commits
Use git diff --stat instead of full diff for summary

/sdd:story-implement - Generate implementation before saving
/sdd:story-continue - Resume work before saving
/sdd:story-review - Move to review after saving
/sdd:story-start - Begin development before implementation
/sdd:project-status - View all stories and their status

Constraints

✅ MUST check for uncommitted changes
✅ MUST generate proper conventional commit message
✅ MUST update story file before committing
✅ MUST include story file in commit
⚠️ NEVER commit secrets or sensitive files without warning
⚠️ NEVER commit large files without confirmation
📋 SHOULD auto-detect commit type from changes
💡 SHOULD provide meaningful commit messages
🔧 SHOULD include story context in commit
💾 MUST verify commit succeeded before reporting success

18 KiB Raw Permalink Blame History Unescape Escape