devflow-kit 0.9.0 → 1.0.0

package/plugins/devflow-core-skills/skills/git-workflow/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: git-workflow
+description: This skill should be used when the user asks to "commit changes", "create a pull request", "stage files", "prepare for review", "write a commit message", or runs git add, git commit, git push, or gh pr operations. Provides atomic commit patterns, conventional commit formatting, PR description templates, and honest change documentation.
+user-invocable: false
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Git Workflow
+
+Atomic commits and honest PR descriptions. Complements git-safety with commit and PR-specific patterns.
+
+## Iron Law
+
+> **ATOMIC COMMITS WITH HONEST DESCRIPTIONS**
+>
+> Every commit MUST represent a single logical change. Every PR description MUST accurately
+> reflect ALL changes, risks, and testing gaps. Mixed concerns, hidden limitations, and
+> dishonest descriptions are violations. No exceptions.
+
+---
+
+## Commit Message Format
+
+### Structure
+
+```
+<type>(<scope>): <short summary> (max 50 chars)
+
+<optional body explaining what and why>
+<wrap at 72 characters>
+
+<optional footer with references>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+### Types
+
+| Type | Use When |
+|------|----------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only changes |
+| `style` | Code style/formatting (no logic change) |
+| `refactor` | Code change that neither fixes nor adds |
+| `test` | Adding or updating tests |
+| `chore` | Build, dependencies, tooling |
+| `perf` | Performance improvements |
+
+### HEREDOC Format (Required)
+
+Always use HEREDOC for commit messages to handle special characters:
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(auth): add JWT token validation
+
+Implement token validation middleware with:
+- Signature verification
+- Expiration checking
+- Role-based access control
+
+Closes #123
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Atomic Commit Grouping
+
+1. **By Feature/Module**: Changes within same directory or module
+2. **By Type**: Source code, tests, docs, config separately
+3. **By Relationship**: Files that change together for single logical purpose
+
+### Anti-Patterns
+
+- **Grab-bag commits**: "Various fixes and updates" - VIOLATION
+- **Mixed concerns**: Feature + refactor + fix in one commit - VIOLATION
+- **Blind staging**: `git add .` without review - VIOLATION
+
+---
+
+## Pull Request
+
+### PR Title Format
+
+```
+<type>(<scope>): <description>
+```
+
+**Rules**: Under 72 characters, imperative mood, specific but concise.
+
+### PR Description Structure
+
+Every PR description MUST include these sections:
+
+| Section | Purpose |
+|---------|---------|
+| Summary | 2-3 sentences: what and why |
+| Changes | Features, fixes, refactoring by category |
+| Breaking Changes | User action required (or "None") |
+| Testing | Coverage, manual steps, gaps |
+| Related Issues | Closes/relates to links |
+
+### Size Assessment
+
+| Size | Lines Changed | Action |
+|------|---------------|--------|
+| Small | < 200 | Proceed normally |
+| Medium | 200-500 | Consider splitting if unrelated changes |
+| Large | 500-1000 | Recommend splitting |
+| Very Large | > 1000 | **WARN**: Split into smaller PRs |
+
+---
+
+## Safety Checks
+
+Before staging files, apply sensitive file detection and content scanning patterns from `git-safety` skill.
+
+## Pre-Commit Checklist
+
+- [ ] Changes are atomic (single logical change)
+- [ ] No sensitive files included
+- [ ] No secrets in file content
+- [ ] Commit message follows format
+- [ ] Message explains "what" and "why"
+- [ ] Related files grouped together
+
+## Description Quality Checklist
+
+- [ ] Summary clearly explains what and why
+- [ ] Breaking changes documented (or explicitly "None")
+- [ ] Testing gaps honestly disclosed
+- [ ] Related issues linked
+- [ ] Size assessed and split recommended if needed
+
+---
+
+## Extended References
+
+For extended examples and templates:
+
+| Reference | Contents |
+|-----------|----------|
+| `references/commit-patterns.md` | Multi-commit flows, bug fix patterns, breaking changes |
+| `references/commit-violations.md` | Grab-bag commits, blind staging, vague messages |
+| `references/pr-patterns.md` | Full PR template, key change detection, pre-flight scripts |
+| `references/pr-violations.md` | Vague descriptions, hidden breaking changes, massive PRs |
+
+---
+
+## Related Skills
+
+| Skill | Use For |
+|-------|---------|
+| `git-safety` | Lock handling, sequential ops, sensitive file detection |
+| `github-patterns` | GitHub API, rate limits, PR comments, releases |

package/plugins/devflow-core-skills/skills/git-workflow/references/commit-patterns.md

@@ -0,0 +1,115 @@
+# Commit Patterns
+
+Correct commit practices for atomic, well-documented history.
+
+---
+
+## Message Format
+
+```
+<type>(<scope>): <short summary> (max 50 chars)
+
+<optional body explaining what and why>
+<wrap at 72 characters>
+
+<optional footer with references>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Always use HEREDOC for commit messages:
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(auth): add JWT token validation
+
+Implement token validation middleware with:
+- Signature verification
+- Expiration checking
+- Role-based access control
+
+Closes #123
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Atomic Commit Examples
+
+### Feature Implementation (Multi-Commit Flow)
+
+```bash
+# Step 1: Core implementation
+git add src/services/user-service.ts src/models/user.ts && \
+git commit -m "feat(users): add user service with CRUD operations"
+
+# Step 2: Tests for the feature
+git add tests/services/user-service.test.ts && \
+git commit -m "test(users): add comprehensive user service tests"
+
+# Step 3: API endpoint
+git add src/routes/users.ts src/middleware/user-validation.ts && \
+git commit -m "feat(api): add user API endpoints"
+
+# Step 4: Documentation
+git add docs/api/users.md && \
+git commit -m "docs(api): document user endpoints"
+```
+
+### Bug Fix (Isolated Change)
+
+```bash
+git add src/utils/date-parser.ts tests/utils/date-parser.test.ts && \
+git commit -m "$(cat <<'EOF'
+fix(dates): handle timezone offset in ISO date parsing
+
+Previous implementation assumed UTC, causing off-by-one errors
+for dates near midnight in non-UTC timezones.
+
+Fixes #456
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Breaking Changes
+
+```bash
+git commit -m "$(cat <<'EOF'
+feat(api)!: change response format to JSON:API spec
+
+BREAKING CHANGE: API responses now follow JSON:API specification.
+All clients must update to handle new response structure.
+
+Migration guide: docs/migration/v2-response-format.md
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Splitting Mixed Changes
+
+```bash
+# Check what's changed
+git status
+git diff --stat
+
+# Stage only related files for first commit
+git add src/auth/*.ts
+git commit -m "feat(auth): add session management"
+
+# Stage tests for that feature
+git add tests/auth/*.ts
+git commit -m "test(auth): add session management tests"
+
+# Stage unrelated refactoring
+git add src/utils/string-helpers.ts
+git commit -m "refactor(utils): simplify string helper functions"
+```

package/plugins/devflow-core-skills/skills/git-workflow/references/commit-violations.md

@@ -0,0 +1,77 @@
+# Commit Violations
+
+Common commit anti-patterns to avoid.
+
+---
+
+## Summary Table
+
+| Violation | Example | Impact |
+|-----------|---------|--------|
+| Grab-bag commits | "Various fixes and updates" | Hard to review, revert, bisect |
+| Blind staging | `git add .` | Accidental sensitive file commits |
+| Vague messages | "Fix bug" | Lost context, unclear history |
+| Missing context | "Update user.ts" | No explanation of why |
+| Sensitive files | Committing .env | Security breach |
+| Mixed concerns | Feature + fix + chore | Impossible atomic reverts |
+| No type prefix | "Add login" | Inconsistent changelog |
+| Force push shared | `--force` to main | Team work destroyed |
+
+---
+
+## Grab-Bag Commits
+
+```bash
+# VIOLATION: Multiple unrelated changes
+git add . && git commit -m "Various fixes and updates"
+
+# FIX: Split into atomic commits by concern
+git add src/auth/*.ts && git commit -m "feat(auth): add login handler"
+git add src/components/button.tsx && git commit -m "fix(ui): correct button color"
+```
+
+## Blind Staging
+
+```bash
+# VIOLATION: No review of what's being committed
+git add .
+git add -A
+
+# FIX: Review and stage specific files
+git status && git diff
+git add src/services/user.ts src/models/user.ts
+```
+
+## Vague Messages
+
+```bash
+# VIOLATION: No context
+git commit -m "Fix bug"
+git commit -m "WIP"
+git commit -m "stuff"
+
+# FIX: Describe what and why
+git commit -m "fix(auth): prevent session timeout during active use"
+```
+
+## Sensitive Files
+
+```bash
+# VIOLATION: Committing secrets
+git add .env
+git add config/credentials.json
+
+# FIX: Add to .gitignore and commit example config
+git add .env.example
+```
+
+## Force Push to Shared Branches
+
+```bash
+# VIOLATION: Rewriting shared history
+git push --force origin main
+
+# FIX: Create new commits for fixes
+git commit -m "fix(auth): correct typo in previous commit"
+git push  # Normal push
+```

package/plugins/devflow-core-skills/skills/git-workflow/references/pr-patterns.md

@@ -0,0 +1,127 @@
+# Pull Request Patterns
+
+Correct patterns for high-quality PRs.
+
+---
+
+## Full PR Description Template
+
+```markdown
+## Summary
+
+{2-3 sentence overview of what this PR does and why}
+
+## Changes
+
+### Features
+- Feature 1 with brief description
+
+### Bug Fixes
+- Fix 1 with impact description
+
+### Refactoring
+- Refactor 1 with rationale
+
+## Breaking Changes
+
+{List breaking changes that require user action, or "None"}
+
+## Testing
+
+### Test Coverage
+- {N} test files modified/added
+- {What's tested}
+
+### Manual Testing
+1. Test scenario 1: steps
+2. Test scenario 2: steps
+
+### Testing Gaps
+{Honest assessment of what's NOT tested}
+
+## Security Considerations
+
+{Security-relevant changes, or "No security impact"}
+
+## Performance Impact
+
+{Expected performance changes, or "No performance impact expected"}
+
+## Deployment Notes
+
+{Special deployment instructions, or "No special deployment steps"}
+
+## Related Issues
+
+Closes #{issue}
+Related to #{issue}
+
+## Reviewer Focus Areas
+
+1. {file:line} - {why this needs attention}
+2. {file:line} - {why this needs attention}
+
+---
+
+Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+---
+
+## Creating the PR with HEREDOC
+
+```bash
+gh pr create \
+  --base main \
+  --title "feat(auth): add authentication middleware" \
+  --body "$(cat <<'EOF'
+## Summary
+
+Implements JWT-based authentication...
+
+[Full description content]
+
+Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+---
+
+## Key Change Detection
+
+| Change Type | Detection | Action |
+|-------------|-----------|--------|
+| Breaking Changes | `grep -i "BREAKING CHANGE" commits` | **MANDATORY** section |
+| Database Migrations | `migration\|schema` in file names | Highlight + deployment notes |
+| Dependency Changes | `package.json`, `Cargo.toml`, etc. | List versions changed |
+| Config Changes | `.config.`, `.yml`, `.toml` | Note configuration impact |
+| Missing Tests | Source changed, no test files | **WARN** in Testing Gaps |
+
+---
+
+## Size Guidelines
+
+| Size | Lines Changed | Review Time | Recommendation |
+|------|---------------|-------------|----------------|
+| Small | < 200 | 15 min | Ideal |
+| Medium | 200-500 | 30 min | Acceptable |
+| Large | 500-1000 | 1 hour | Consider splitting |
+| XL | > 1000 | Hours | **Must split** |
+
+---
+
+## Pre-Flight Check Script
+
+```bash
+# 1. Verify commits exist
+COMMITS_AHEAD=$(git rev-list --count main..HEAD)
+[ "$COMMITS_AHEAD" -eq 0 ] && echo "ERROR: No commits to review" && exit 1
+
+# 2. Check for existing PR
+PR_EXISTS=$(gh pr list --head "$(git branch --show-current)" --json number --jq '.[0].number')
+[ -n "$PR_EXISTS" ] && echo "PR #$PR_EXISTS already exists" && exit 1
+
+# 3. Ensure branch is pushed
+git ls-remote --exit-code --heads origin "$(git branch --show-current)" || git push -u origin "$(git branch --show-current)"
+```

package/plugins/devflow-core-skills/skills/git-workflow/references/pr-violations.md

@@ -0,0 +1,96 @@
+# Pull Request Violations
+
+Common PR anti-patterns and how to fix them.
+
+---
+
+## Violation Table
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Vague descriptions | Reviewers can't understand changes | Use structured template |
+| Hidden breaking changes | Consumers surprised | Document explicitly |
+| Massive PRs (>1000 lines) | Impossible to review | Split into smaller PRs |
+| Missing test plan | Unknown coverage | Include manual/automated test steps |
+| No related issues | Lost context | Link to issues/tickets |
+| Dishonest limitations | Technical debt hidden | Disclose honestly |
+
+---
+
+## Vague Description Examples
+
+```markdown
+# BAD: Vague
+## Summary
+Fixed some bugs and added features.
+
+# GOOD: Specific
+## Summary
+- Fix: Null pointer exception in UserService when email is empty
+- Feat: Add rate limiting to /api/login endpoint (5 req/min)
+```
+
+---
+
+## Hidden Breaking Changes
+
+```markdown
+# BAD: Breaking change buried in code
+## Summary
+Refactored authentication module.
+
+# GOOD: Breaking changes called out
+## Breaking Changes
+- `authenticate(token)` now returns `Result<User, AuthError>` instead of `User | null`
+- Required migration: Run `npm run migrate:auth` before deploying
+```
+
+---
+
+## Massive PR Split Recommendation
+
+```markdown
+PR SIZE WARNING
+
+This PR changes {X} files and {Y} lines. Consider splitting:
+
+1. PR 1: {Component A} - {files}
+2. PR 2: {Component B} - {files}
+3. PR 3: {Tests} - {files}
+
+Rationale: Smaller PRs are easier to review, safer to merge.
+```
+
+---
+
+## Missing Test Plan
+
+```markdown
+# BAD: No testing information
+## Summary
+Added new payment processing.
+
+# GOOD: Clear test plan
+## Testing
+### Automated
+- 12 unit tests for PaymentService
+- 3 integration tests for Stripe webhook
+
+### Gaps
+- Edge case: Partial refunds not tested (tracked in #456)
+```
+
+---
+
+## Dishonest Limitations
+
+```markdown
+# BAD: Hiding technical debt
+## Summary
+Implemented caching layer.
+
+# GOOD: Honest about limitations
+## Limitations
+- Cache invalidation not implemented (tracked in #789)
+- Memory usage not bounded - add eviction policy before production load
+```