devflow-kit 1.8.3 → 2.0.0

package/src/assets/skills/git/references/patterns.md

@@ -0,0 +1,324 @@
+# Git Patterns
+
+Correct patterns for safe git operations, atomic commits, and pull requests.
+
+---
+
+## Safety Patterns
+
+### Sequential Operations
+
+```bash
+# Always chain git commands with &&
+git add file.ts && git commit -m "message" && git push
+
+# Never run in parallel - use sequential execution
+```
+
+### Lock Handling
+
+```bash
+# Full implementation: wait for lock file release
+wait_for_lock_release() {
+    local max_wait=10
+    local waited=0
+    while [ -f .git/index.lock ]; do
+        if [ $waited -ge $max_wait ]; then
+            echo "ERROR: .git/index.lock still exists after ${max_wait}s"
+            echo "Another git process may be running, or a process crashed."
+            echo "Check: ps aux | grep git"
+            return 1
+        fi
+        echo "Waiting for git lock to be released... (${waited}s)"
+        sleep 1
+        waited=$((waited + 1))
+    done
+    return 0
+}
+
+# Always call before git operations
+wait_for_lock_release || exit 1
+```
+
+### Safe Amend
+
+```bash
+# Only amend if not pushed
+if ! git log origin/$(git branch --show-current)..HEAD | grep -q .; then
+  git commit --amend  # Safe - not pushed
+fi
+```
+
+### Protected Branch Check
+
+```bash
+PROTECTED_BRANCHES="main master develop integration trunk staging production"
+
+check_protected_branch() {
+    local branch="$1"
+    for protected in $PROTECTED_BRANCHES; do
+        if [ "$branch" = "$protected" ]; then
+            echo "ERROR: Cannot force push to $branch"
+            return 1
+        fi
+    done
+    case "$branch" in
+        release/*) echo "ERROR: Cannot force push to $branch"; return 1 ;;
+    esac
+    return 0
+}
+```
+
+---
+
+## Complete Commit Flow
+
+```bash
+# 1. Wait for lock
+wait_for_lock_release || exit 1
+
+# 2. Check what's changing
+git status --porcelain
+
+# 3. Review changes
+git diff HEAD --stat
+
+# 4. Stage specific files (not blind 'git add .')
+git add src/specific-file.ts
+
+# 5. Create commit with proper message
+git commit -m "$(cat <<'EOF'
+type(scope): summary
+
+Description
+
+EOF
+)"
+
+# 6. Verify
+git log -1 --stat
+git status
+```
+
+---
+
+## Safe Push Workflow
+
+```bash
+# Check remote status first
+git fetch origin
+git status
+
+# If behind, pull first
+if git status | grep -q "behind"; then
+    git pull --rebase origin $(git branch --show-current)
+fi
+
+# Push
+git push -u origin $(git branch --show-current)
+```
+
+---
+
+## Pre-commit Hook Handling
+
+### If Hook Modifies Files
+
+```bash
+# Run commit
+git commit -m "message"
+
+# If hook modified files, amend to include them
+git add .
+git commit --amend --no-edit
+```
+
+### If Hook Rejects Commit
+
+```bash
+# DO NOT amend - fix the issue and create new commit
+eslint --fix src/
+git add .
+git commit -m "fix: resolve linting issues"
+```
+
+---
+
+## Commit Patterns
+
+### 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
+git add src/auth/*.ts
+git commit -m "feat(auth): add session management"
+
+git add tests/auth/*.ts
+git commit -m "test(auth): add session management tests"
+
+git add src/utils/string-helpers.ts
+git commit -m "refactor(utils): simplify string helper functions"
+```
+
+---
+
+## PR Patterns
+
+### Full PR Description Template
+
+```markdown
+## Summary
+{2-3 sentence overview}
+
+## Changes
+### Features
+- Feature 1 with brief description
+### Bug Fixes
+- Fix 1 with impact description
+
+## Breaking Changes
+{List or "None"}
+
+## Testing
+### Test Coverage
+- {N} test files modified/added
+### Testing Gaps
+{Honest assessment}
+
+## Related Issues
+Closes #{issue}
+
+## Reviewer Focus Areas
+1. {file:line} - {why this needs attention}
+```
+
+### Creating 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 |
+
+### Pre-Flight Check
+
+```bash
+COMMITS_AHEAD=$(git rev-list --count main..HEAD)
+[ "$COMMITS_AHEAD" -eq 0 ] && echo "ERROR: No commits to review" && exit 1
+
+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
+
+git ls-remote --exit-code --heads origin "$(git branch --show-current)" || git push -u origin "$(git branch --show-current)"
+```
+
+---
+
+## Recovery Workflows
+
+### Undo Last Commit (not pushed)
+
+```bash
+git reset --soft HEAD~1  # Keep changes staged
+git reset HEAD~1         # Keep changes unstaged
+git reset --hard HEAD~1  # Discard changes (DANGEROUS)
+```
+
+### Recover Deleted Branch
+
+```bash
+git reflog
+git checkout -b recovered-branch <commit-sha>
+```
+
+### Fix Wrong Branch
+
+```bash
+git reset --soft HEAD~1
+git stash
+git checkout correct-branch
+git stash pop
+git commit -m "message"
+```
+
+### Stash Handling
+
+```bash
+git stash push -m "description of changes"
+git stash list
+git stash apply          # Keep in stash list
+git stash pop            # Apply and remove
+git stash apply stash@{2}
+git stash drop stash@{0}
+```

package/src/assets/skills/git/references/sources.md

@@ -0,0 +1,16 @@
+# Git & GitHub — Sources
+
+Bibliography for the `git` skill.
+
+---
+
+## References
+
+1. **Pro Git** — Chacon & Straub (2014). Authoritative git internals, branching model, index/lock mechanics. [git-scm.com/book](https://git-scm.com/book/en/v2)
+2. **Conventional Commits 1.0.0** — Specification for structured commit messages with type prefixes. [conventionalcommits.org](https://www.conventionalcommits.org/en/v1.0.0/)
+3. **Git Documentation** — Official reference for `git-lock`, `git-reset`, `git-rebase`, `git-stash`. [git-scm.com/docs](https://git-scm.com/docs)
+4. **GitHub REST API** — Endpoints for pulls, issues, releases, rate limits. [docs.github.com/rest](https://docs.github.com/en/rest)
+5. **GitHub GraphQL API** — Schema for efficient queries and mutations. [docs.github.com/graphql](https://docs.github.com/en/graphql)
+6. **Semantic Versioning 2.0.0** — Version format specification (MAJOR.MINOR.PATCH). [semver.org](https://semver.org/)
+7. **gh CLI Manual** — GitHub's official CLI for PR, issue, release, and workflow operations. [cli.github.com/manual](https://cli.github.com/manual/)
+8. **OWASP Secrets Management** — Patterns for preventing credential leaks in version control. [cheatsheetseries.owasp.org](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)

package/src/assets/skills/git/references/violations.md

@@ -0,0 +1,128 @@
+# Git Violations
+
+Common anti-patterns for git safety, commits, and pull requests.
+
+---
+
+## Safety Violations
+
+| Violation | Risk | Fix |
+|-----------|------|-----|
+| Parallel git commands | Index corruption | Run git commands sequentially |
+| Force push to main | Lost commits | Never force push protected branches |
+| Committing secrets | Security breach | Use detection.md patterns |
+| Amending after push | History rewrite | Create new commit instead |
+| Skipping hooks | Quality bypass | Never use `--no-verify` |
+| Ignoring lock files | Corruption | Wait for lock release |
+
+---
+
+## Commit Violations
+
+| 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 .
+
+# 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"
+
+# FIX: Describe what and why
+git commit -m "fix(auth): prevent session timeout during active use"
+```
+
+---
+
+## PR Violations
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Vague descriptions | Reviewers can't understand | 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 test steps |
+| No related issues | Lost context | Link to issues/tickets |
+| Dishonest limitations | Technical debt hidden | Disclose honestly |
+
+### Vague Description
+
+```markdown
+# BAD
+## Summary
+Fixed some bugs and added features.
+
+# GOOD
+## 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
+## Summary
+Refactored authentication module.
+
+# GOOD
+## 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
+
+```markdown
+PR SIZE WARNING
+
+This PR changes {X} files and {Y} lines. Consider splitting:
+1. PR 1: {Component A}
+2. PR 2: {Component B}
+3. PR 3: {Tests}
+```
+
+### Missing Test Plan
+
+```markdown
+# BAD
+Added new payment processing.
+
+# GOOD
+## Testing
+### Automated
+- 12 unit tests for PaymentService
+- 3 integration tests for Stripe webhook
+### Gaps
+- Edge case: Partial refunds not tested (tracked in #456)
+```

package/src/assets/skills/go/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: go
+description: This skill should be used when the user works with Go files (.go), asks about "error handling", "interfaces", "goroutines", "channels", "packages", or discusses Go idioms and concurrency. Provides patterns for error handling, interface design, concurrency, and package organization.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.go"
+  exclude:
+    - "vendor/**"
+---
+
+# Go Patterns
+
+Reference for Go-specific patterns, idioms, and best practices. Full bibliography: `references/sources.md`.
+
+## Iron Law
+
+> **ERRORS ARE VALUES** [5][7]
+>
+> Never ignore errors. `if err != nil` is correctness, not boilerplate. Every error
+> return must be checked, wrapped with context, or explicitly documented as intentionally
+> ignored with `_ = fn()`. "Errors are values. Values can be programmed." — Rob Pike [5]
+
+## When This Skill Activates
+
+Working with Go codebases — error handling, interfaces, goroutines, channels, packages.
+
+---
+
+## Error Handling [5][6]
+
+```go
+// BAD: return err  — caller loses context
+// GOOD: return fmt.Errorf("reading config %s: %w", path, err)
+
+var ErrNotFound = errors.New("not found")
+
+func FindUser(id string) (*User, error) {
+    u, err := db.Get(id)
+    if err != nil {
+        return nil, fmt.Errorf("finding user %s: %w", id, err)
+    }
+    if u == nil { return nil, ErrNotFound }
+    return u, nil
+}
+// Caller: if errors.Is(err, ErrNotFound) { ... }
+```
+
+---
+
+## Interface Design [7][14]
+
+```go
+// "The bigger the interface, the weaker the abstraction" — Rob Pike [7]
+// BAD: func NewService(repo *PostgresRepo) *Service
+// GOOD: func NewService(repo Repository) *Service — accept interfaces [14]
+
+// Small interfaces compose cleanly [1]
+type Reader interface { Read(p []byte) (n int, err error) }
+type Writer interface { Write(p []byte) (n int, err error) }
+type ReadWriter interface { Reader; Writer }
+```
+
+---
+
+## Concurrency [9][10][13]
+
+CSP (Hoare [9]): "Do not communicate by sharing memory; share memory by communicating." [10]
+
+```go
+// Context cancellation with errgroup [16][22]
+func Process(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    for _, item := range items {
+        g.Go(func() error { return processItem(ctx, item) })
+    }
+    return g.Wait()
+}
+
+// Channel direction prevents misuse at compile time [1][8]
+func producer(ch chan<- int) { ch <- 42 }
+func consumer(ch <-chan int) { v := <-ch; _ = v }
+```
+
+---
+
+## Package Design [15][17]
+
+```go
+// BAD: models/, controllers/, services/
+// GOOD: user/, order/, payment/  — organize by domain [15]
+
+func (s *Service) validate(u *User) error { ... }   // unexported — internal only
+func (s *Service) CreateUser(ctx context.Context, req CreateUserReq) (*User, error) { ... }
+```
+
+---
+
+## Zero Values [1]
+
+```go
+var mu sync.Mutex; var buf bytes.Buffer  // Ready to use — no init needed
+
+type Config struct {
+    Timeout time.Duration // zero = no timeout
+    Retries int           // zero = no retries
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Violation | Source |
+|---------|-----------|--------|
+| Ignoring error | `val, _ := fn()` | [5][2] |
+| Naked return | `return` in named returns | [2][4] |
+| init() abuse | Complex `init()` with side effects | [1][12] |
+| Interface pollution | Interface defined before use | [14][7] |
+| Goroutine leak | `go fn()` without lifecycle | [13][16] |
+| Panic in library | `panic(err)` in non-main code | [1][4] |
+
+---
+
+## Extended References
+
+- `references/sources.md` — Full bibliography (25 sources)
+- `references/violations.md` — Violations with citations [5][6][7][12][13]
+- `references/patterns.md` — Extended patterns with citations [1][3][11][18][19]
+- `references/detection.md` — Grep patterns for automated detection
+- `references/concurrency.md` — CSP-grounded concurrency patterns [9][10][13][22]
+
+---
+
+## Checklist
+
+- [ ] All errors checked or explicitly ignored with `_ =` [5]
+- [ ] Errors wrapped with `fmt.Errorf("context: %w", err)` [6]
+- [ ] Interfaces defined at consumer, not producer [14]
+- [ ] Interfaces kept small (1-3 methods) [7]
+- [ ] Context as first parameter [16]
+- [ ] Goroutines have clear lifecycle/cancellation [13]
+- [ ] Channel direction specified in signatures [8]
+- [ ] Packages organized by domain, not by type [15]
+- [ ] No `init()` with side effects [1]
+- [ ] No `panic` or `log.Fatal` in library code [4]