Initial commit

2025-11-29 17:55:13 +08:00
commit 02de918865
11 changed files with 2014 additions and 0 deletions
--- a/skills/git-commit/references/examples.md
+++ b/skills/git-commit/references/examples.md
@@ -0,0 +1,161 @@
+# Commit Examples Reference
+
+Quick examples for Claude to reference when helping users.
+
+## Common Scenarios
+
+### New Feature
+```
+feat(auth): add OAuth2 login support
+
+Integrate Google and GitHub OAuth providers with
+automatic account linking for existing users.
+
+Closes #234
+```
+
+### Bug Fix
+```
+fix(api): prevent null pointer in user lookup
+
+Add null check before accessing user.profile to avoid
+crashes when profile hasn't been initialized yet.
+```
+
+### Breaking Change
+```
+feat(api)!: change response format to include metadata
+
+BREAKING CHANGE:
+
+All API responses now return {data, meta} instead of
+raw data. Update clients to access response.data.
+
+Migration: https://docs.example.com/v2-migration
+```
+
+### Performance
+```
+perf(database): add composite index on user queries
+
+Reduces average query time from 2.1s to 45ms for
+user search endpoint.
+```
+
+### Refactor
+```
+refactor(auth): extract validation to separate module
+
+Move authentication validation logic from controllers
+to dedicated service for better testability.
+```
+
+### Documentation
+```
+docs(api): add OpenAPI specification
+
+Add complete API documentation with request/response
+examples for all endpoints.
+```
+
+### Simple Commits
+```
+feat: add email notifications
+fix: correct timezone handling  
+docs: update README
+style: format with prettier
+test: add unit tests for auth
+build: update dependencies
+chore: update .gitignore
+```
+
+## Edge Cases
+
+### Multiple Related Issues
+```
+fix(payment): resolve duplicate charge issues
+
+Fixes #123, #456, #789
+```
+
+### Revert
+```
+revert: "feat(api): add caching layer"
+
+This reverts commit a1b2c3d. Caching caused data
+staleness issues in production.
+```
+
+### Initial Commit
+```
+chore: init
+```
+
+## Breaking Change Patterns
+
+### API Change
+```
+feat(api)!: remove deprecated v1 endpoints
+
+BREAKING CHANGE:
+
+Removed endpoints:
+- GET /v1/users
+- POST /v1/users  
+
+Use /v2/users instead with updated auth headers.
+```
+
+### Database Schema
+```
+refactor(db)!: normalize user table structure
+
+BREAKING CHANGE:
+
+Split user.name into user.firstName and user.lastName.
+Run migration: npm run migrate:user-schema
+```
+
+### Config Change
+```
+build!: require Node.js 18+
+
+BREAKING CHANGE:
+
+Node.js 16 is no longer supported. Upgrade to Node 18
+before deploying this version.
+```
+
+## What NOT to Do
+
+### Too Vague
+```
+❌ fix: bug fix
+✅ fix(auth): prevent session timeout on refresh
+```
+
+### Past Tense
+```
+❌ feat: added new feature
+✅ feat: add new feature
+```
+
+### Capitalized
+```
+❌ feat: Add new feature
+✅ feat: add new feature
+```
+
+### With Period
+```
+❌ feat: add new feature.
+✅ feat: add new feature
+```
+
+### Issue as Scope
+```
+❌ feat(#123): add feature
+✅ feat(api): add feature
+
+Closes #123
+```
--- a/skills/git-commit/references/slash-commands.md
+++ b/skills/git-commit/references/slash-commands.md
@@ -0,0 +1,451 @@
+# Slash Commands Reference
+
+Detailed workflows for each slash command.
+
+## /commit - Smart Commit Helper
+
+**Trigger:** User types `/commit` or says "help me commit"
+
+**Smart Workflow (Adaptive):**
+
+### Stage 1: Detection
+Check for staged changes:
+```bash
+git diff --staged --name-only
+```
+
+### Stage 2: Path Selection
+
+**If staged changes exist → Smart Analysis Path**
+
+1. **Run analysis:**
+   ```bash
+   python scripts/analyze-diff.py --json
+   ```
+
+2. **Present suggestion:**
+   ```
+   📊 Analyzed your staged changes:
+   
+   Files changed: 3
+    auth/oauth.py   | 45 +++++++++++++++
+    auth/tokens.py  | 23 ++++++++
+    tests/auth.py   | 67 ++++++++++++++++++++++
+   
+   Detected:
+   • Type: feat (new functions found)
+   • Scope: auth (from file paths)
+   • Description: add OAuth2 authentication
+   • Confidence: High (85%)
+   
+   Suggested commit:
+   git commit -m"feat(auth): add OAuth2 authentication"
+   
+   Does this look good? (y/n/edit/help)
+   ```
+
+3. **Handle response:**
+   - **`y` or "yes" or "looks good"** → Provide final command or execute
+   - **`n` or "no"** → Ask "What should I change?" then rebuild
+   - **`edit`** → Let them modify specific parts (type, scope, description)
+   - **`help`** → Explain why each part was suggested
+   - **Low confidence (<50%)** → Add warning: "⚠️ Low confidence. Would you like to build it step-by-step instead?"
+
+**If no staged changes → Interactive Builder Path**
+
+1. **Inform user:**
+   ```
+   No staged changes found.
+   
+   Tip: Stage your changes first with:
+     git add <files>
+   
+   Or I can help you build the message. What did you change?
+   ```
+
+2. **Get description:**
+   - Wait for user to describe their change
+   - If they want to stage first, guide them
+
+3. **Build interactively:**
+   - Suggest type based on description
+   - Ask for scope (optional)
+   - Check breaking change
+   - Refine description
+   - Add body if needed
+   - Add footer if needed
+
+4. **Present final:**
+   ```
+   Your commit message:
+   
+   feat(auth): add OAuth2 login
+   
+   Git command:
+   git commit -m"feat(auth): add OAuth2 login"
+   ```
+
+**If user provided description in request → Manual Path**
+
+Example: "help me commit - I added OAuth login"
+
+1. **Extract information:**
+   - What they did: "added OAuth login"
+   - Infer type: feat (adding something new)
+   - Suggest scope: auth (OAuth is authentication)
+
+2. **Build message:**
+   ```
+   Based on your description:
+   
+   git commit -m"feat(auth): add OAuth login"
+   
+   Want me to add more details? (y/n)
+   ```
+
+3. **Offer refinement:**
+   - If yes: ask about body, footer
+   - If no: done
+
+### Key Principles
+
+1. **Be smart:** Use automation when possible
+2. **Be flexible:** Fall back to interactive when needed
+3. **Be clear:** Always show what was detected and why
+4. **Be helpful:** Offer next steps at each stage
+
+## /analyze - REMOVED
+
+**Note:** This command has been merged into `/commit`. The smart analysis is now the default first step when using `/commit` with staged changes.
+
+Users can still trigger it by:
+- Typing `/commit`
+- Saying "help me commit"
+- Saying "analyze my changes"
+
+## /validate - Message Validation
+
+**Trigger:** User types `/validate <message>` or "Is this valid: ..."
+
+**Workflow:**
+1. Extract message (after `/validate` or from context)
+2. Run validation checks:
+   - Format: matches `type(scope): description` pattern
+   - Type: in approved list
+   - Scope: valid format if present
+   - Description: lowercase, no period, under 100 chars
+   - Breaking change: indicator matches footer
+3. Present results:
+   
+   **If valid:**
+   ```
+   ✅ Valid commit message!
+   
+   Type: feat
+   Scope: auth
+   Description: add OAuth login
+   ```
+   
+   **If invalid:**
+   ```
+   ❌ Invalid commit message
+   
+   Issues:
+   • Description starts with uppercase (should be lowercase)
+   • Description ends with period (should not)
+   
+   Suggested fix:
+   feat(auth): add OAuth login
+   
+   Original:
+   feat(auth): Add OAuth login.
+   ```
+
+## /types - Show Commit Types
+
+**Trigger:** User types `/types` or asks "what commit types..."
+
+**Response:**
+```
+📝 Conventional Commit Types:
+
+🆕 feat - New feature for users/API
+   Example: feat(auth): add OAuth login
+
+🐛 fix - Bug fix for users/API  
+   Example: fix(api): prevent null pointer
+
+♻️  refactor - Code change without behavior change
+   Example: refactor(auth): extract validation logic
+
+⚡ perf - Performance improvement
+   Example: perf(db): add index to user queries
+
+💄 style - Code formatting only
+   Example: style: apply prettier formatting
+
+✅ test - Add or fix tests
+   Example: test(auth): add OAuth flow tests
+
+📚 docs - Documentation changes
+   Example: docs: update API reference
+
+📦 build - Build system or dependencies
+   Example: build: upgrade to React 18
+
+🔧 ops - Infrastructure or deployment
+   Example: ops(k8s): increase replica count
+
+🏗️  chore - Miscellaneous maintenance
+   Example: chore: update .gitignore
+
+Need help choosing? Describe your change and I'll suggest the right type.
+```
+
+## /scopes - Scope Guide
+
+**Trigger:** User types `/scopes` or asks about scopes
+
+**Response:**
+```
+📍 Scopes in Conventional Commits
+
+A scope provides context about what part of the codebase changed.
+
+**Format:**
+- Optional (can omit)
+- Lowercase
+- Alphanumeric + hyphens
+- 1-20 characters
+- Based on your project structure
+
+**Common patterns:**
+
+By module/component:
+  feat(auth): ...
+  fix(api): ...
+  refactor(database): ...
+  
+By feature area:
+  feat(payments): ...
+  fix(checkout): ...
+  
+By technical layer:
+  refactor(ui): ...
+  perf(backend): ...
+
+**Examples:**
+  ✅ feat(auth): add login
+  ✅ fix(shopping-cart): prevent empty checkout
+  ✅ refactor(api-v2): restructure endpoints
+  
+  ❌ feat(#123): add feature  (don't use issue numbers)
+  ❌ feat(AUTHENTICATION): ... (not uppercase)
+  ❌ feat(this-is-way-too-long-scope): ... (max 20 chars)
+
+**Your project:**
+Based on your file structure, consider scopes like:
+[analyze their repo structure and suggest relevant scopes]
+```
+
+## /breaking - Breaking Change Guide
+
+**Trigger:** User types `/breaking` or mentions breaking changes
+
+**Response:**
+```
+⚠️  Breaking Changes Guide
+
+A breaking change is any modification that requires users to change their code.
+
+**When to mark as breaking:**
+• Removed public API endpoints
+• Changed function signatures
+• Modified response formats
+• Removed configuration options
+• Changed database schema
+• Updated minimum version requirements
+
+**How to mark breaking changes:**
+
+1. Add `!` before the colon:
+   feat(api)!: remove deprecated endpoints
+
+2. Add BREAKING CHANGE in footer:
+   
+   feat(api)!: remove deprecated v1 endpoints
+   
+   BREAKING CHANGE:
+   
+   All v1 API endpoints have been removed. Clients must
+   migrate to v2 API with updated authentication.
+   
+   Migration guide: docs/v1-to-v2-migration.md
+
+**Template:**
+```
+<type>(<scope>)!: <description>
+
+<optional body explaining the change>
+
+BREAKING CHANGE:
+
+What broke: <explain what no longer works>
+Why: <reason for the breaking change>
+Migration: <how to update code>
+```
+
+**Example:**
+```
+refactor(auth)!: change token format to JWT
+
+Replace custom token format with industry-standard JWT
+for better security and third-party integration.
+
+BREAKING CHANGE:
+
+Auth tokens are now JWT format instead of custom base64.
+
+Migration steps:
+1. Update token parsing: use jwt.decode() instead of base64
+2. Update token validation: verify JWT signature
+3. Existing tokens will be invalidated - users must re-login
+
+See: docs/jwt-migration.md
+```
+
+**Version impact:**
+Breaking changes trigger a MAJOR version bump (1.x.x → 2.0.0)
+```
+
+## /changelog - Generate Changelog
+
+**Trigger:** User types `/changelog` or asks to generate changelog
+
+**Workflow:**
+1. Get version info: "From which version/tag? (default: last tag)"
+2. Run git log: `git log <version>..HEAD --format=%s`
+3. Parse conventional commits
+4. Group by type:
+   - Breaking Changes (top priority)
+   - Features
+   - Bug Fixes
+   - Other (refactor, perf, docs, etc.)
+5. Format as markdown:
+   ```markdown
+   ## [2.0.0] - 2025-11-15
+   
+   ### ⚠️ BREAKING CHANGES
+   
+   - **auth**: change token format to JWT (#234)
+     Migration required. See docs/jwt-migration.md
+   
+   ### ✨ Features
+   
+   - **auth**: add OAuth2 login (#123)
+   - **api**: add user search endpoint (#145)
+   - **ui**: add dark mode toggle (#167)
+   
+   ### 🐛 Bug Fixes
+   
+   - **api**: prevent null pointer in user lookup (#156)
+   - **ui**: fix date picker timezone issue (#178)
+   
+   ### ⚡ Performance
+   
+   - **database**: add index to user queries (#189)
+   
+   ### 📚 Documentation
+   
+   - update API reference (#190)
+   - add authentication guide (#191)
+   ```
+
+## /version - Semantic Versioning
+
+**Trigger:** User types `/version` or asks "what should the next version be"
+
+**Workflow:**
+1. Get current version: `git describe --tags --abbrev=0` or ask user
+2. Analyze commits since that version
+3. Apply semantic versioning rules:
+   - **Major** (X.0.0): Has breaking changes
+   - **Minor** (0.X.0): Has features or fixes, no breaking changes
+   - **Patch** (0.0.X): Only other changes
+4. Present analysis:
+   ```
+   📊 Version Analysis
+   
+   Current version: 1.2.3
+   Analyzing commits since v1.2.3...
+   
+   Found:
+   • 1 breaking change
+   • 5 features
+   • 3 bug fixes
+   • 7 other commits
+   
+   Recommended: 2.0.0 (Major)
+   Reason: Breaking change detected
+   
+   Breaking commits:
+   • feat(api)!: remove deprecated v1 endpoints
+   
+   Create this version?
+   git tag -a v2.0.0 -m "Release 2.0.0"
+   git push origin v2.0.0
+   ```
+
+## /examples - Show Examples
+
+**Trigger:** User types `/examples` or asks for examples
+
+**Response:**
+Load and display relevant examples from references/examples.md based on context:
+- If discussing features → show feature examples
+- If discussing fixes → show fix examples
+- If discussing breaking changes → show breaking change examples
+- Default → show variety of examples
+
+## /fix - Amend Last Commit
+
+**Trigger:** User types `/fix` or "I need to fix my last commit"
+
+**Workflow:**
+1. Get last commit: `git log -1 --format=%s`
+2. Show current message: "Your last commit: `feat: add login`"
+3. Ask: "What needs fixing?"
+4. Common scenarios:
+   
+   **Wrong message:**
+   ```
+   Current: feat: add login
+   New message: feat(auth): add OAuth login
+   
+   Command:
+   git commit --amend -m"feat(auth): add OAuth login"
+   ```
+   
+   **Forgot files:**
+   ```
+   Stage missing files:
+   git add forgotten-file.py
+   git commit --amend --no-edit
+   ```
+   
+   **Older commit:**
+   ```
+   To fix an older commit, use interactive rebase:
+   git rebase -i HEAD~3
+   
+   Then mark the commit as 'edit' or 'reword'
+   ```
+
+## General Response Pattern
+
+For all slash commands:
+1. Acknowledge the command
+2. Execute the workflow
+3. Present clear, actionable output
+4. Offer next steps
+5. Be concise but complete