Initial commit

2025-11-30 09:07:10 +08:00
commit 169a5fc5cd
99 changed files with 25560 additions and 0 deletions
--- a/skills/agileflow-commit-messages/SKILL.md
+++ b/skills/agileflow-commit-messages/SKILL.md
@@ -0,0 +1,241 @@
+---
+name: agileflow-commit-messages
+description: Formats git commit messages following Conventional Commits and respects user's attribution preferences from CLAUDE.md. Loads when creating commits or discussing code changes to commit.
+allowed-tools: Read, Bash
+---
+
+# agileflow-commit-messages
+
+ROLE & IDENTITY
+- Skill ID: COMMIT-MSG
+- Specialization: Git commit message formatting with Conventional Commits + attribution policy compliance
+- Part of the AgileFlow docs-as-code system
+
+OBJECTIVE
+Format git commit messages following Conventional Commits specification while respecting user's Claude Code attribution preferences from CLAUDE.md. Ensure commits are clear, concise, and follow project conventions for type, scope, and footer formatting.
+
+INPUTS
+- User request to commit changes
+- Files staged for commit (from git status)
+- Change descriptions or diff context
+- CLAUDE.md (optional) - Attribution policy
+
+FIRST ACTION
+**Deterministic boot sequence**:
+1. Check if CLAUDE.md exists: `[ -f CLAUDE.md ] && echo "Found" || echo "Not found"`
+2. If found, read attribution policy: `grep -A 20 "Git Commit Attribution Policy" CLAUDE.md`
+3. Scan git status: `git status --short` to understand scope of changes
+4. Check for staged changes: `git diff --cached --stat`
+
+PROACTIVE KNOWLEDGE LOADING
+**Before generating commit message:**
+- Read CLAUDE.md for attribution policy (CRITICAL - respect user preference)
+- Read .git/config for repo context (if available)
+- Scan staged files to determine commit type and scope
+- Check recent commit history: `git log --oneline -5` to match style
+
+**Attribution Policy Detection**:
+- IF `grep -q "DO NOT ADD AI ATTRIBUTION" CLAUDE.md` → No attribution
+- ELSE → Add default attribution footer
+
+WORKFLOW
+1. **Analyze staged changes**:
+   - Run `git diff --cached --stat` to see files
+   - Determine primary change type (feat, fix, refactor, etc.)
+   - Identify affected scope (api, ui, auth, db, config, etc.)
+
+2. **Check attribution policy** (CRITICAL):
+   - Read CLAUDE.md for "Git Commit Attribution Policy"
+   - IF "DO NOT ADD AI ATTRIBUTION" found → skip footer
+   - ELSE → prepare attribution footer
+
+3. **Format commit message** following Conventional Commits:
+   ```
+   <type>(<scope>): <subject>
+
+   <body>
+
+   <footer>
+   ```
+   - **Type**: feat, fix, docs, style, refactor, perf, test, chore, ci, revert
+   - **Scope** (optional): api, ui, auth, db, config, etc.
+   - **Subject**: Imperative mood, lowercase, <50 chars, no period
+   - **Body** (optional): Explain WHAT and WHY (not HOW), wrap at 72 chars
+   - **Footer**: Issue refs (Closes #123), breaking changes, attribution
+
+4. **Add attribution footer** (if policy allows):
+   ```
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+   Co-Authored-By: Claude <noreply@anthropic.com>
+   ```
+
+5. **Show commit message** to user for approval (diff-first pattern)
+
+6. **Execute commit** after YES confirmation:
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   <formatted message>
+   EOF
+   )"
+   ```
+
+RELATED COMMANDS
+- `/AgileFlow:setup` - Creates CLAUDE.md with attribution policy during setup
+- `/AgileFlow:ai-code-review` - Use before committing to verify quality
+- `/AgileFlow:generate-changelog` - Parses commit messages for changelog generation
+- `/AgileFlow:status STORY=... STATUS=in-review` - Update story status after commit
+
+**When to use slash commands**:
+- After committing code changes → `/AgileFlow:status` to update story
+- After completing story → `/AgileFlow:generate-changelog` for release notes
+
+OUTPUTS
+- Formatted commit message (shown to user for approval)
+- Git commit executed (if user says YES)
+- Commit SHA (from git output)
+
+HANDOFFS
+**AgileFlow Coordination** (optional - if working within AgileFlow system):
+- DOES NOT update docs/09-agents/status.json directly (commit is atomic)
+- DOES NOT append to bus/log.jsonl (commits don't trigger coordination)
+- **Story lifecycle**: Commits typically happen during `in-progress` phase
+- **After commit**: Dev agent should update status.json to `in-review` if story complete
+
+**Security Note**: NEVER commit secrets to git
+- Check for .env, credentials.json, tokens, API keys
+- Warn user if sensitive files are staged
+- Suggest adding to .gitignore instead
+
+QUALITY CHECKLIST
+Before suggesting commit message:
+- [ ] Type is appropriate (feat/fix/refactor/docs/chore/etc.)
+- [ ] Subject is imperative mood ("add" not "added" or "adds")
+- [ ] Subject is lowercase, <50 chars, no period at end
+- [ ] Body explains WHY (not just WHAT), wrapped at 72 chars
+- [ ] Footer includes issue references if applicable (Closes #123)
+- [ ] **Attribution policy checked in CLAUDE.md** (CRITICAL)
+- [ ] No secrets in staged files (.env, tokens, credentials)
+- [ ] Breaking changes marked with `!` and `BREAKING CHANGE:` footer
+
+## Conventional Commits Format
+
+### Types
+- **feat**: New feature
+- **fix**: Bug fix
+- **docs**: Documentation only changes
+- **style**: Code style (formatting, missing semicolons, whitespace)
+- **refactor**: Code refactor (neither fixes bug nor adds feature)
+- **perf**: Performance improvements
+- **test**: Adding/modifying tests
+- **chore**: Build process, dependencies, tooling
+- **ci**: CI/CD configuration changes
+- **revert**: Reverts a previous commit
+
+### Scope (Optional)
+- `(api)`, `(ui)`, `(auth)`, `(db)`, `(config)`, etc.
+- Can be omitted if change affects multiple areas
+
+### Subject Rules
+- Imperative mood: "add feature" not "added feature" or "adds feature"
+- No capitalization of first letter
+- No period at the end
+- Max 50 characters
+- Clear and concise
+
+### Body (Optional but Recommended)
+- Explain WHAT changed and WHY (not HOW - code shows that)
+- Wrap at 72 characters per line
+- Separate from subject with blank line
+- Use bullet points for multiple changes
+
+### Footer (Optional)
+- **Breaking changes**: `BREAKING CHANGE: description`
+- **Issue references**: `Closes #123`, `Fixes #456`
+- **Attribution**: Add if CLAUDE.md allows (see attribution policy)
+
+## Attribution Examples
+
+**WITH attribution** (default if no policy):
+```
+feat(auth): add two-factor authentication
+
+Implemented TOTP-based 2FA with QR code generation
+for enhanced user account security.
+
+Closes #234
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+**WITHOUT attribution** (if CLAUDE.md says "DO NOT ADD AI ATTRIBUTION"):
+```
+feat(auth): add two-factor authentication
+
+Implemented TOTP-based 2FA with QR code generation
+for enhanced user account security.
+
+Closes #234
+```
+
+## Multi-File Commits
+
+For commits affecting multiple files:
+- Choose the most significant type (feat > fix > refactor > chore)
+- Use scope that represents the feature/module
+- List key changes in body as bullet points
+
+Example:
+```
+feat(user-profile): add profile editing and avatar upload
+
+- Implemented profile form with validation
+- Added avatar upload with image cropping
+- Created API endpoints for profile updates
+- Added unit tests for profile service
+
+Closes #123, #124
+```
+
+## Breaking Changes
+
+When introducing breaking changes, use `!` and `BREAKING CHANGE:`:
+```
+feat(api)!: change authentication endpoint structure
+
+BREAKING CHANGE: The /auth/login endpoint now returns a different
+response format. Clients must update to handle the new structure.
+
+Old: { token: "..." }
+New: { accessToken: "...", refreshToken: "...", expiresIn: 3600 }
+
+Migration guide: docs/migrations/auth-response-v2.md
+```
+
+## Revert Commits
+
+```
+revert: feat(auth): add two-factor authentication
+
+This reverts commit abc1234def5678.
+
+Reason: 2FA implementation caused login failures for users with
+certain browser configurations. Reverting to investigate and fix.
+```
+
+## Integration with Other Skills
+
+- **agileflow-changelog**: Commit messages inform changelog entries
+- **agileflow-story-writer**: Reference story IDs in commits (Closes STORY-042)
+- **agileflow-adr-writer**: Link ADRs in footer (Refs: ADR-0005)
+
+## Notes
+
+- **ALWAYS** check CLAUDE.md first before formatting commit message
+- Respect user preferences - attribution is a sensitive topic
+- If unsure about type, ask the user
+- For large commits, suggest breaking into smaller logical commits
+- Include context in body - future developers will thank you
+- Keep line lengths: subject <50 chars, body <72 chars
--- a/skills/agileflow-commit-messages/reference/bad-examples.md
+++ b/skills/agileflow-commit-messages/reference/bad-examples.md
@@ -0,0 +1,168 @@
+# Bad Commit Message Examples (and How to Fix Them)
+
+## ❌ Too Vague
+
+```
+fix: fix bug
+```
+
+**Problem**: Doesn't explain what bug was fixed
+**Better**:
+```
+fix(auth): prevent session timeout during active use
+
+Fixed bug where user sessions expired after 30 minutes
+even during active usage. Now sessions extend while user
+is interacting with the application.
+
+Fixes #456
+```
+
+## ❌ Wrong Tense
+
+```
+feat: added dark mode
+```
+
+**Problem**: Should be imperative mood ("add" not "added")
+**Better**:
+```
+feat(ui): add dark mode toggle
+
+Implemented dark mode with localStorage persistence
+and system preference detection.
+
+Closes #789
+```
+
+## ❌ Subject Too Long
+
+```
+feat: add a new user profile editing feature that allows users to update their name, email, and profile picture
+```
+
+**Problem**: Subject exceeds 50 characters, should be concise
+**Better**:
+```
+feat(profile): add user profile editing
+
+Users can now update their name, email, and profile
+picture from the settings page. Changes are validated
+server-side and saved to the database.
+
+Closes #123
+```
+
+## ❌ No Type
+
+```
+update README
+```
+
+**Problem**: Missing type prefix
+**Better**:
+```
+docs(readme): add API authentication examples
+
+Added code examples showing how to authenticate API
+requests using JWT tokens.
+```
+
+## ❌ Multiple Unrelated Changes
+
+```
+feat: add login and fix cart bug and update dependencies
+```
+
+**Problem**: Should be 3 separate commits
+**Better**: Split into:
+```
+feat(auth): add user login functionality
+```
+```
+fix(cart): resolve item duplication issue
+```
+```
+chore(deps): update npm packages to latest versions
+```
+
+## ❌ Description of HOW Instead of WHY
+
+```
+fix: changed if statement to switch statement
+```
+
+**Problem**: Describes implementation detail, not the reason
+**Better**:
+```
+refactor(validation): simplify input validation logic
+
+Replaced nested if statements with switch statement
+for better readability and easier maintenance. No
+functional changes.
+```
+
+## ❌ Capitalized Subject
+
+```
+feat: Add Dark Mode Support
+```
+
+**Problem**: Subject should be lowercase
+**Better**:
+```
+feat(ui): add dark mode support
+```
+
+## ❌ Period at End of Subject
+
+```
+fix: resolve login timeout issue.
+```
+
+**Problem**: Subject shouldn't end with period
+**Better**:
+```
+fix(auth): resolve login timeout issue
+
+Increased session timeout from 15 to 30 minutes to
+prevent premature logouts during form filling.
+
+Fixes #567
+```
+
+## ❌ No Context
+
+```
+fix: it works now
+```
+
+**Problem**: Completely uninformative
+**Better**:
+```
+fix(payment): resolve Stripe webhook signature validation
+
+Fixed HMAC signature verification by using raw request
+body instead of parsed JSON. Webhooks now process correctly.
+
+Fixes #890
+```
+
+## ❌ Missing Issue Reference
+
+```
+feat: add two-factor authentication
+
+Implemented TOTP-based 2FA with QR code generation.
+```
+
+**Problem**: Should reference the issue/story
+**Better**:
+```
+feat(auth): add two-factor authentication
+
+Implemented TOTP-based 2FA with QR code generation
+for enhanced account security.
+
+Closes #234, STORY-042
+```
--- a/skills/agileflow-commit-messages/reference/good-examples.md
+++ b/skills/agileflow-commit-messages/reference/good-examples.md
@@ -0,0 +1,120 @@
+# Good Commit Message Examples
+
+## Simple Feature Addition
+
+```
+feat(auth): add password reset via email
+
+Users can now request a password reset link sent to their
+registered email address. The link expires after 1 hour.
+
+Closes #456
+```
+
+## Bug Fix with Context
+
+```
+fix(cart): prevent duplicate items in shopping cart
+
+Fixed race condition where clicking "Add to Cart" rapidly
+could add the same item multiple times. Added debouncing
+and server-side validation.
+
+Fixes #789
+```
+
+## Refactoring with Explanation
+
+```
+refactor(api): extract authentication middleware
+
+Moved authentication logic from individual route handlers
+into reusable middleware. This reduces code duplication
+and makes auth logic easier to maintain and test.
+
+No behavioral changes.
+```
+
+## Breaking Change
+
+```
+feat(api)!: migrate to v2 response format
+
+BREAKING CHANGE: All API endpoints now return data wrapped
+in a standardized envelope format.
+
+Before: { id: 1, name: "..." }
+After: { data: { id: 1, name: "..." }, meta: { version: 2 } }
+
+Migration guide: docs/api-v2-migration.md
+
+Closes #234
+```
+
+## Multiple Related Changes
+
+```
+feat(profile): add profile editing and avatar upload
+
+- Implemented profile form with field validation
+- Added avatar upload with client-side image cropping
+- Created PUT /api/users/:id endpoint
+- Added error handling for file size limits
+- Wrote unit tests for profile update logic
+
+Closes #123, #124
+```
+
+## Documentation
+
+```
+docs(readme): add installation instructions for Docker
+
+Added step-by-step guide for running the application
+in Docker containers, including environment variable
+configuration and volume mounting.
+```
+
+## Performance Improvement
+
+```
+perf(db): add index on user email column
+
+Query performance for user lookup by email improved from
+~500ms to ~5ms. Added composite index on (email, status)
+for common query patterns.
+```
+
+## Dependency Update
+
+```
+chore(deps): upgrade React to v18.2
+
+Updated React and React DOM to latest stable version.
+Migrated deprecated lifecycle methods in UserProfile
+and Dashboard components.
+
+Tested with full E2E suite - all tests passing.
+```
+
+## CI/CD Change
+
+```
+ci(github): add automated dependency updates
+
+Configured Dependabot to create PRs for npm package
+updates weekly. Auto-merge enabled for patch updates
+that pass all tests.
+```
+
+## Revert
+
+```
+revert: feat(payments): add Stripe integration
+
+This reverts commit abc123def456.
+
+Stripe webhook validation is failing in production.
+Reverting to investigate HMAC signature verification
+before re-deploying.
+```
--- a/skills/agileflow-commit-messages/scripts/check-attribution.sh
+++ b/skills/agileflow-commit-messages/scripts/check-attribution.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# check-attribution.sh
+# Determines if Claude Code attribution should be added to git commits
+# Returns "yes" if attribution should be added, "no" if it should not
+
+if [ -f CLAUDE.md ]; then
+  if grep -q "DO NOT ADD AI ATTRIBUTION" CLAUDE.md; then
+    echo "no"
+  else
+    echo "yes"
+  fi
+else
+  # Default to adding attribution if no CLAUDE.md exists
+  echo "yes"
+fi