| name | git-commit-helper |
| description | Generates meaningful git commit messages for Spec-Driven Development workflows. Use when creating commits, suggesting commit messages, or helping with task-based version control. Automatically links commits to work packages. |
| allowed-tools | ["Bash","Read","Grep","Glob"] |
Git Commit Helper Skill
Purpose
Automatically generates well-structured commit messages that follow Spec-Kit conventions and link commits to Work Packages (WP). This ensures consistent version control practices and enables automatic task history tracking in the dashboard.
When to Activate
This skill activates when users ask questions like:
- "suggest a commit message" / "커밋 메시지 추천해줘"
- "what should I commit" / "뭐라고 커밋해야 해?"
- "help me commit this" / "커밋 도와줘"
- "generate commit message" / "커밋 메시지 생성해줘"
- "commit this task" / "이 작업 커밋해줘"
Commit Message Generation Process
1. Analyze Git Status
Check current repository state:
BRANCH=$(git branch --show-current)
git diff --cached --name-status
git diff --name-status
git status --short
```text
**If no changes staged:**
- Inform user: "No changes staged for commit. Stage files with `git add` first."
- Optionally show unstaged changes and ask if they should be staged
Determine which task/WP the changes relate to:
```bash
FEATURE=$(echo $BRANCH | grep -oE '[0-9]{3}-[a-z-]+')
```text
```bash
find specs/*/tasks/doing/ -name "WP*.md" -type f -printf '%T+ %p\n' | sort -r | head -1
```text
If unclear, ask: "Which Work Package (WP) are you working on? (e.g., WP01, WP02)"
Once WP is identified, read the WP file to understand context:
```bash
cat specs/{feature}/tasks/doing/WP01.md
```text
**Extract from WP file:**
- Task ID (from frontmatter `id:` or filename)
- Task title (from frontmatter `title:` or H1 heading)
- Task phase (from frontmatter `phase:`)
- Acceptance criteria (to understand what changes accomplish)
Understand what was modified:
```bash
git diff --cached --stat
git diff --cached
```text
**Categorize Changes:**
- New files added (A)
- Files modified (M)
- Files deleted (D)
- Renamed files (R)
**Group by Type:**
- Source code (*.py, *.js, *.ts, etc.)
- Tests (test_*.py, *.test.js, etc.)
- Documentation (*.md, *.txt)
- Configuration (*.json, *.yaml, *.toml)
- Assets (*.css, *.png, etc.)
Follow Spec-Kit commit message convention:
**Format:**
```text
[TASK_ID] Brief description (imperative mood, <50 chars)
- Detailed change 1
- Detailed change 2
- Detailed change 3
Files modified:
- path/to/file1.py
- path/to/file2.js
```text
**Best Practices:**
- **Subject Line:**
- Start with `[WP01]` or task ID in brackets
- Use imperative mood: "Add feature" not "Added feature"
- Keep under 50 characters
- Capitalize first word
- No period at end
- **Body:**
- Separate from subject with blank line
- Use bullet points for multiple changes
- Explain WHAT and WHY, not HOW
- Reference related WPs if applicable
- Keep lines under 72 characters
- **Task ID Pattern:**
- Essential for automatic tracking: `[WP01]`, `[WP01.1]`, `[T005]`
- The dashboard uses this to link commits to tasks
- move-task.sh script auto-detects these commits
**Examples:**
```text
[WP01.1] Add HttpMethod enum to models
- Created src/models/enums.py with HttpMethod class
- Added GET, POST, PUT, DELETE, PATCH methods
- Added type hints and docstrings for all methods
Related to Phase 1.1: Core API models
```text
```text
[WP03] Fix user authentication timeout issue
- Increased session timeout from 15min to 30min
- Added session refresh on user activity
- Updated auth middleware to handle expired sessions gracefully
Fixes acceptance criterion
```text
```text
[WP05.2] Refactor database connection pooling
- Extracted connection logic to db/pool.py
- Implemented connection pool with max 20 connections
- Added automatic retry on connection failure
- Migrated all models to use new pool
No functional changes, improves performance and maintainability
```text
```text
[WP02] Add unit tests for password validation
- Created tests/test_auth_validator.py
- Added 12 test cases covering edge cases
- Tests for min length, special chars, common passwords
- All tests passing (100% coverage on validator.py)
```text
```text
[WP04] Update API documentation for v2 endpoints
- Added OpenAPI specs for /api/v2/users
- Updated README with authentication flow diagram
- Added code examples for Python and JavaScript clients
```text
**Multiple WPs in One Commit:**
```text
[WP01][WP02] Implement login and signup endpoints
Changes for WP01 (Login):
- Created POST /api/login endpoint
- Added JWT token generation
Changes for WP02 (Signup):
- Created POST /api/signup endpoint
- Added email validation
```text
**No Active WP (General Maintenance):**
```text
chore: Update dependencies to latest versions
- Updated Flask from 2.0.1 to 2.3.0
- Updated pytest from 7.0 to 7.4
- All tests still passing
```text
**Emergency Hotfix:**
```text
hotfix: Fix critical security vulnerability in auth
- Patched SQL injection in login endpoint
- Added input sanitization
- Deployed immediately to production
Not linked to specific WP - emergency fix
```text
Show the generated message and ask for confirmation:
```text
I've generated this commit message based on your changes:
---
[WP01.1] Add HttpMethod enum to models
- Created src/models/enums.py with HttpMethod class
- Added GET, POST, PUT, DELETE, PATCH methods
- Added type hints and docstrings
Related to Phase 1.1: Core API models
---
Staged files:
- src/models/enums.py (new file)
- src/models/__init__.py (modified)
Would you like to:
1. Use this message as-is
2. Edit the message
3. See a different suggestion
4. Cancel
```text
### 8. Optional: Execute Commit
If user approves and requests execution:
```bash
git commit -m "[WP01.1] Add HttpMethod enum to models
- Created src/models/enums.py with HttpMethod class
- Added GET, POST, PUT, DELETE, PATCH methods
- Added type hints and docstrings
Related to Phase 1.1: Core API models"
```text
**Important:** Only execute git commit if explicitly requested by user. Default behavior is to suggest the message.
## Integration with Spec-Kit Workflow
This skill integrates with the SDD workflow:
**Automatic Task Tracking:**
- Commits with `[TASK_ID]` pattern are auto-detected by `move-task.sh`
- Git history appears in dashboard's "Git History" tab
- File changes are automatically logged in Work Package
**Workflow Stages:**
1. User implements task (WP01)
2. User asks: "suggest commit message"
3. Skill analyzes changes and generates message with `[WP01]`
4. User commits with suggested message
5. When WP01 moves to for_review, git history is automatically appended
6. Dashboard displays all commits for WP01
- Detect user's language from their question
- If asked in Korean, provide explanation in Korean
- Commit message itself stays in English (universal convention)
- File paths and technical terms remain in English
## Error Handling
**No staged changes:**
```text
No changes staged for commit.
You have 3 modified files:
- src/models/enums.py
- src/api/routes.py
- tests/test_models.py
Stage them with: git add <file>
Or stage all: git add -A
```text
**Cannot identify WP:**
```text
I couldn't automatically determine which Work Package you're working on.
Current branch: main (no feature branch detected)
Recent WP files in doing: None
Please specify the WP ID (e.g., WP01) or describe what this commit is for.
```text
**Too many unrelated changes:**
```text
⚠️ Warning: You have changes across 15 files spanning multiple features.
Consider splitting into multiple commits:
- Commit 1: API changes (5 files)
- Commit 2: Database migrations (3 files)
- Commit 3: Tests (7 files)
This makes the history clearer and easier to review.
```text
## Smart Features
**1. Conventional Commit Detection:**
Recognize conventional commit types and adapt:
- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation
- `refactor:` for code refactoring
- `test:` for adding tests
- `chore:` for maintenance
**2. File Pattern Recognition:**
Automatically infer commit type from files:
- Only `*.md` files → `docs:`
- Only `test_*.py` files → `test:`
- Mix of source + tests → `feat:` or `fix:`
**3. Emoji Suggestions (Optional):**
If user prefers emojis in commits:
- ✨ feat: New feature
- 🐛 fix: Bug fix
- 📝 docs: Documentation
- ♻️ refactor: Refactoring
- ✅ test: Tests
## Example Interactions
**User:** "커밋 메시지 추천해줘"
**Claude (using this skill):**
1. Checks git status: 2 files staged
2. Identifies branch: `002-password-reset`
3. Finds WP: `specs/002-password-reset/tasks/doing/WP01.md`
4. Reads WP title: "Implement password reset email"
5. Analyzes changes: Added email template + email service
6. Generates:
```text
[WP01] Implement password reset email flow
- Added password_reset_email.html template
- Created EmailService class in services/email.py
- Integrated SendGrid API for email delivery
- Added environment variables for SMTP config
Fulfills acceptance criterion: "User receives reset link via email"
```text
**User:** "what should I commit for this bugfix?"
**Claude:**
1. Checks changes: 1 file modified (auth.py)
2. Asks: "Which WP is this bugfix for?"
3. User: "WP03"
4. Reads WP03: "Fix session timeout bug"
5. Generates commit message with `[WP03]` and bugfix description
## Notes
- This skill generates suggestions but does NOT auto-commit (unless explicitly requested)
- Commit messages follow spec-kit conventions for dashboard integration
- The `[TASK_ID]` pattern is critical for automatic task tracking
- Well-crafted commits improve team collaboration and project history
