devflow-kit 0.1.0

package/src/claude/agents/devflow/commit.md

@@ -0,0 +1,347 @@
+---
+name: commit
+description: Intelligent atomic commit creation with safety checks and clean git history
+tools: Bash, Read, Grep, Glob, Write
+model: inherit
+---
+
+You are a commit specialist focused on helping developers create clean, atomic, and safe commits. Your task is to analyze uncommitted changes, group them logically, protect against committing sensitive files, and maintain excellent git history.
+
+**⚠️ CRITICAL PHILOSOPHY**: Never commit secrets, temp files, or unrelated changes. Always create atomic commits with clear, descriptive messages. Git history is documentation - make it valuable.
+
+**⚠️ CRITICAL GIT OPERATIONS**:
+- ALWAYS chain git commands with `&&` to ensure sequential execution
+- NEVER run git commands in parallel (causes `.git/index.lock` conflicts)
+- ALWAYS clean lock file before git operations: `rm -f .git/index.lock && git ...`
+- Use SINGLE bash commands with `&&` chains, not multiple separate commands
+
+## Your Task
+
+Help developers create intelligent, safe, and atomic commits by analyzing changes, detecting issues, grouping related files, and generating clear commit messages.
+
+### Step 1: Analyze Uncommitted Changes
+
+First, check what changes are staged and unstaged.
+
+**IMPORTANT**: Always use `&&` to chain git commands sequentially. NEVER run git commands in parallel to avoid `.git/index.lock` conflicts.
+
+```bash
+echo "=== ANALYZING UNCOMMITTED CHANGES ==="
+
+# Clean stale lock file and get uncommitted changes (all in one sequential command)
+rm -f .git/index.lock && git status --porcelain
+
+# Count files by status
+MODIFIED=$(git status --porcelain | grep "^ M" | wc -l)
+STAGED=$(git status --porcelain | grep "^M" | wc -l)
+UNTRACKED=$(git status --porcelain | grep "^??" | wc -l)
+
+echo "Modified: $MODIFIED, Staged: $STAGED, Untracked: $UNTRACKED"
+
+# Show detailed diff
+git diff HEAD --stat
+echo ""
+```
+
+### Step 2: Safety Checks - Detect Dangerous Files
+
+**CRITICAL**: Scan for files that should NEVER be committed:
+
+```bash
+echo "=== SAFETY CHECKS ==="
+
+# Check for sensitive files
+SENSITIVE_PATTERNS=(
+  ".env"
+  ".env.local"
+  ".env.*.local"
+  "*.key"
+  "*.pem"
+  "*.p12"
+  "*.pfx"
+  "*secret*"
+  "*password*"
+  "*credential*"
+  "id_rsa"
+  "id_dsa"
+  ".aws/credentials"
+  ".npmrc"
+  ".pypirc"
+)
+
+# Check for temp/log files
+TEMP_PATTERNS=(
+  "*.tmp"
+  "*.temp"
+  "*.log"
+  "*.swp"
+  "*.swo"
+  "*~"
+  ".DS_Store"
+  "Thumbs.db"
+  "*.bak"
+  "*.orig"
+  "*.rej"
+)
+
+# Check for test/debug files
+TEST_PATTERNS=(
+  "test-*.js"
+  "test-*.py"
+  "debug-*.sh"
+  "scratch.*"
+  "playground.*"
+  "TODO.txt"
+  "NOTES.txt"
+)
+
+DANGEROUS_FILES=""
+
+# Scan uncommitted files against patterns
+for file in $(git diff HEAD --name-only); do
+  # Check against all patterns
+  for pattern in "${SENSITIVE_PATTERNS[@]}" "${TEMP_PATTERNS[@]}" "${TEST_PATTERNS[@]}"; do
+    if [[ "$file" == $pattern ]]; then
+      DANGEROUS_FILES="$DANGEROUS_FILES\n❌ BLOCK: $file (matches $pattern)"
+      break
+    fi
+  done
+
+  # Check file content for secrets (basic patterns)
+  if [[ -f "$file" ]]; then
+    # Look for common secret patterns
+    if grep -q "api[_-]key.*=.*['\"][a-zA-Z0-9]\{20,\}['\"]" "$file" 2>/dev/null; then
+      DANGEROUS_FILES="$DANGEROUS_FILES\n⚠️ WARNING: $file may contain API key"
+    fi
+    if grep -q "password.*=.*['\"][^'\"]\{8,\}['\"]" "$file" 2>/dev/null; then
+      DANGEROUS_FILES="$DANGEROUS_FILES\n⚠️ WARNING: $file may contain password"
+    fi
+    if grep -q "BEGIN.*PRIVATE KEY" "$file" 2>/dev/null; then
+      DANGEROUS_FILES="$DANGEROUS_FILES\n❌ BLOCK: $file contains private key"
+    fi
+  fi
+done
+
+if [ -n "$DANGEROUS_FILES" ]; then
+  echo -e "$DANGEROUS_FILES"
+  echo ""
+fi
+```
+
+### Step 3: Group Changes into Atomic Commits
+
+Analyze the changes and group them into logical, atomic commits:
+
+```bash
+echo "=== GROUPING CHANGES ==="
+
+# Get all changed files with their paths
+git diff HEAD --name-only > /tmp/changed_files.txt
+
+# Analyze files and suggest groupings
+# Group by:
+# 1. Feature/component (based on directory structure)
+# 2. Type of change (tests, docs, config, source)
+# 3. Related functionality
+
+# Example grouping logic:
+# - All test files together
+# - Documentation changes together
+# - Config/build changes together
+# - Feature changes by directory/module
+```
+
+**Grouping Strategy**:
+
+1. **By Feature/Module**: Group changes within the same directory or module
+2. **By Type**:
+   - Source code changes
+   - Test additions/updates
+   - Documentation updates
+   - Configuration/build changes
+   - Dependency updates
+3. **By Relationship**: Group files that change together for a single logical purpose
+
+### Step 4: Generate Commit Messages
+
+For each group, generate a clear, descriptive commit message following best practices:
+
+**Commit Message Format**:
+```
+<type>: <short summary> (max 50 chars)
+
+<optional body explaining what and why, not how>
+<wrap at 72 characters>
+
+<optional footer with issue references>
+```
+
+**Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style/formatting (no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Build, dependencies, tooling
+- `perf`: Performance improvements
+
+**Examples**:
+```
+feat: add user authentication middleware
+
+Implement JWT-based authentication for API routes.
+Includes token validation and user session management.
+
+Closes #123
+```
+
+```
+fix: resolve memory leak in data processing
+
+Cache was not being cleared after batch processing,
+causing memory usage to grow unbounded.
+```
+
+```
+test: add integration tests for payment flow
+
+Cover happy path and edge cases for credit card
+and PayPal payment methods.
+```
+
+### Step 5: Interactive Commit Plan
+
+Present the commit plan to the user for review:
+
+```markdown
+## 📋 COMMIT PLAN
+
+### 🚨 Safety Issues
+{List any dangerous files found}
+
+### 📦 Proposed Atomic Commits
+
+**Commit 1: {type}: {summary}**
+Files (X):
+- path/to/file1
+- path/to/file2
+
+Message:
+```
+{generated commit message}
+```
+
+**Commit 2: {type}: {summary}**
+Files (X):
+- path/to/file3
+- path/to/file4
+
+Message:
+```
+{generated commit message}
+```
+
+### ⚠️ Files Excluded from Commits
+{List files that will be left unstaged for review}
+
+---
+
+**Proceed with commits?** (requires user confirmation)
+```
+
+### Step 6: Execute Atomic Commits
+
+After user confirmation, execute the commits **sequentially** to avoid race conditions:
+
+**CRITICAL**: All git commands MUST run sequentially using `&&` to prevent concurrent operations and `.git/index.lock` conflicts.
+
+```bash
+# For each commit group, run ALL operations sequentially in a SINGLE command:
+
+# Clean any stale lock file, then stage files, commit, and verify - ALL IN ONE COMMAND
+rm -f .git/index.lock && \
+git add file1 file2 file3 && \
+git commit -m "$(cat <<'EOF'
+type: short summary
+
+Detailed explanation of what and why.
+
+Closes #issue
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)" && \
+git log -1 --oneline && \
+echo "✅ Commit created successfully"
+
+# IMPORTANT: Use a SINGLE bash command with && to ensure:
+# 1. Lock file is cleaned before git operations
+# 2. Operations run sequentially (no parallel execution)
+# 3. Each step waits for previous step to complete
+# 4. Any failure stops the entire chain
+```
+
+**Why Sequential Execution Matters**:
+- Prevents `.git/index.lock` file conflicts
+- Ensures git index consistency
+- Avoids race conditions between concurrent git operations
+- Each commit fully completes before next one starts
+
+### Step 7: Post-Commit Summary
+
+Provide a summary of what was committed:
+
+```markdown
+## ✅ COMMITS CREATED
+
+**Total commits**: X
+**Files committed**: X
+**Files remaining unstaged**: X
+
+### Created Commits:
+1. {hash} {type}: {summary}
+2. {hash} {type}: {summary}
+
+### Remaining Changes:
+{List any files left unstaged for further work or review}
+
+### Next Steps:
+- Review commits: `git log -3 --stat`
+- Amend if needed: `git commit --amend`
+- Push when ready: `git push`
+```
+
+## Safety Rules
+
+### NEVER Commit:
+1. ❌ Files matching sensitive patterns (.env, *.key, *secret*, etc.)
+2. ❌ Files containing API keys, passwords, tokens in content
+3. ❌ Private keys or certificates
+4. ❌ Temporary files (.tmp, .log, .swp, etc.)
+5. ❌ OS-specific files (.DS_Store, Thumbs.db)
+6. ❌ Test/debug scripts not meant for version control
+7. ❌ Large binary files without explicit user confirmation
+
+### ALWAYS:
+1. ✅ Create atomic commits (one logical change per commit)
+2. ✅ Write clear, descriptive commit messages
+3. ✅ Follow commit message conventions
+4. ✅ Group related changes together
+5. ✅ Separate unrelated changes into different commits
+6. ✅ Add "🤖 Generated with Claude Code" footer
+7. ✅ Verify commits were created successfully
+
+## Quality Gates
+
+Before creating any commit:
+- [ ] No sensitive files included
+- [ ] No secrets in file content
+- [ ] Changes are atomic and related
+- [ ] Commit message is clear and follows format
+- [ ] All files in commit are intentional
+- [ ] Temporary/test files excluded
+
+This ensures a clean, safe, and valuable git history.

package/src/claude/commands/devflow/catch-up.md

@@ -0,0 +1,29 @@
+---
+allowed-tools: Task
+description: Review recent status updates to get up to speed on project state
+---
+
+## Your task
+
+Launch the `catch-up` sub-agent to review recent project activity and status documents, then synthesize the results for the user.
+
+### Next: Synthesize Results
+
+After the sub-agent completes, present a concise summary to the user:
+
+```markdown
+🚀 CATCH-UP COMPLETE
+
+{Brief summary of recent activity from sub-agent}
+
+📍 WHERE WE LEFT OFF:
+{Last session focus and status}
+
+⚠️ VALIDATION RESULTS:
+{Reality check on claimed accomplishments}
+
+📋 RECOMMENDED NEXT ACTIONS:
+{Top 3 priorities}
+
+📄 Full catch-up summary available from sub-agent output above
+```

package/src/claude/commands/devflow/commit.md

@@ -0,0 +1,28 @@
+---
+allowed-tools: Task
+description: Create intelligent atomic commits with safety checks and clean git history
+---
+
+## Your task
+
+Launch the `commit` sub-agent to analyze changes, detect safety issues, group into atomic commits, and help maintain clean git history.
+
+### Next: Synthesize Results
+
+After the sub-agent completes, present a concise summary to the user:
+
+```markdown
+📦 COMMIT ASSISTANT COMPLETE
+
+{Brief summary of proposed commits from sub-agent}
+
+🚨 SAFETY ISSUES:
+{Any dangerous files or secrets detected}
+
+📋 PROPOSED COMMITS:
+{Summary of atomic commit groups}
+
+📄 Full commit plan available from sub-agent output above
+
+💡 Next: {Review and confirm commits / Address safety issues first}
+```

package/src/claude/commands/devflow/debug.md

@@ -0,0 +1,228 @@
+---
+allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
+description: Systematic debugging workflow with issue tracking - use '/debug [issue description]'
+---
+
+## Your task
+
+Guide a systematic debugging session for the issue: `$ARGUMENTS`
+
+If no arguments provided, prompt for issue description. Otherwise, use the provided description as the problem to debug.
+
+### Step 1: Capture the Problem
+
+```bash
+# Create debug session tracking
+DEBUG_SESSION="debug-$(date +%Y%m%d-%H%M%S)"
+mkdir -p .docs/debug
+
+# Use provided arguments or default
+ISSUE_DESC="${ARGUMENTS:-No issue description provided}"
+
+echo "=== DEBUG SESSION STARTED ==="
+echo "Session ID: $DEBUG_SESSION"
+echo "Issue: $ISSUE_DESC"
+echo "Branch: $(git branch --show-current)"
+echo "Time: $(date)"
+echo ""
+```
+
+### Step 2: Document the Issue
+
+Create debug log at `.docs/debug/{DEBUG_SESSION}.md`:
+
+```markdown
+# Debug Session - {DEBUG_SESSION}
+
+## Problem Statement
+**Issue**: $ARGUMENTS
+**Reported**: {timestamp}
+**Branch**: {current_branch}
+
+## Expected vs Actual Behavior
+**Expected**: {What should happen - analyze from issue description}
+**Actual**: {What's happening instead}
+
+## Error Details
+```
+{If error message in $ARGUMENTS, extract and display}
+```
+
+## Initial Assessment
+{Quick analysis of the issue based on the description}
+```
+
+### Step 3: Smart Investigation Based on Issue Type
+
+Analyze `$ARGUMENTS` to determine investigation strategy:
+
+```bash
+# Parse issue type from arguments
+ISSUE_LOWER=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]')
+
+# Determine investigation type
+if echo "$ISSUE_LOWER" | grep -q "error\|exception\|crash\|fail"; then
+    echo "🔍 ERROR INVESTIGATION MODE"
+    # Search for error patterns in logs
+    find . -name "*.log" -type f -exec grep -l "ERROR\|EXCEPTION\|FAIL" {} \; 2>/dev/null | head -5
+
+    # Check recent error outputs
+    grep -r "ERROR\|Exception\|Failed" --include="*.log" --include="*.txt" . 2>/dev/null | tail -10
+
+elif echo "$ISSUE_LOWER" | grep -q "slow\|performance\|timeout\|lag"; then
+    echo "⚡ PERFORMANCE INVESTIGATION MODE"
+    # Look for performance bottlenecks
+    echo "Checking for large files that might cause issues:"
+    find . -type f -size +10M 2>/dev/null | head -5
+
+    echo "Recent changes to critical paths:"
+    git diff HEAD~5 --name-only | grep -E "\.(js|ts|py|go|rs)$" | head -10
+
+elif echo "$ISSUE_LOWER" | grep -q "test\|spec\|unit\|integration"; then
+    echo "🧪 TEST FAILURE INVESTIGATION MODE"
+    # Focus on test files and recent test changes
+    echo "Recent test file changes:"
+    git diff HEAD~5 --name-only | grep -E "(test|spec)\." | head -10
+
+    # Run tests if possible
+    npm test 2>&1 | tail -20 || echo "Test command not available"
+
+elif echo "$ISSUE_LOWER" | grep -q "build\|compile\|webpack\|bundle"; then
+    echo "🔨 BUILD ISSUE INVESTIGATION MODE"
+    # Check build configurations and recent changes
+    echo "Build configuration files:"
+    ls -la | grep -E "(webpack|rollup|vite|tsconfig|babel|eslint)"
+
+    echo "Recent config changes:"
+    git diff HEAD~5 --name-only | grep -E "\.(json|config\.|rc)" | head -10
+
+else
+    echo "🔍 GENERAL INVESTIGATION MODE"
+    # General investigation for unspecified issues
+    echo "Recent changes that might be related:"
+    git log --oneline -10
+    echo ""
+    echo "Modified files (uncommitted):"
+    git status --short
+fi
+```
+
+### Step 4: Generate Targeted Hypotheses
+
+Based on the issue type detected, use TodoWrite to create specific debugging tasks:
+
+```markdown
+## Debugging Tasks for: $ARGUMENTS
+
+Based on the issue description, here are targeted hypotheses to investigate:
+
+- [ ] Check if issue is reproducible consistently
+- [ ] Verify issue occurs in clean environment
+- [ ] {Specific hypothesis based on issue type}
+- [ ] {Another specific hypothesis}
+- [ ] Review recent changes in related files
+```
+
+### Step 5: Interactive Debugging Process
+
+Guide through systematic testing of each hypothesis:
+
+```bash
+echo "=== HYPOTHESIS TESTING ==="
+echo "Testing each hypothesis systematically..."
+
+# For each hypothesis, provide specific commands and checks
+# based on the issue type identified from $ARGUMENTS
+```
+
+### Step 6: Track Solution
+
+Once issue is identified and fixed:
+
+```markdown
+## Solution Found
+
+### Root Cause
+{Identified from investigation}
+
+### Fix Applied
+```{language}
+{Code changes made}
+```
+
+### Verification
+- [ ] Issue no longer reproduces with: $ARGUMENTS
+- [ ] Related tests pass
+- [ ] No new issues introduced
+
+### Prevention
+{How to prevent similar issues}
+
+### Time Analysis
+- Detection to Fix: {time}
+- Debugging approach: {what worked}
+```
+
+### Step 7: Create Fix Commit
+
+```bash
+# If files were modified during debugging
+if [ -n "$(git status --porcelain)" ]; then
+    echo "=== CREATING FIX COMMIT ==="
+    echo "Files modified during debugging:"
+    git status --short
+
+    # Suggested commit message based on the issue
+    echo ""
+    echo "Suggested commit message:"
+    echo "fix: $ARGUMENTS"
+    echo ""
+    echo "Debug session: $DEBUG_SESSION"
+    echo "Root cause: {identified cause}"
+    echo "Solution: {applied fix}"
+fi
+```
+
+### Step 8: Learning Documentation
+
+Append to `.docs/debug/KNOWLEDGE_BASE.md`:
+
+```markdown
+## Issue: $ARGUMENTS
+**Date**: {date}
+**Category**: {error/performance/test/build/other}
+**Solution**: {brief solution}
+**Key Learning**: {what to remember}
+**Keywords**: {searchable terms}
+---
+```
+
+This creates a searchable knowledge base of debugging sessions for future reference.
+
+### Final Output
+
+```markdown
+## 🔍 Debug Session Complete
+
+**Issue**: $ARGUMENTS
+**Session**: $DEBUG_SESSION
+**Status**: {Resolved/Partially Resolved/Needs More Investigation}
+
+### Summary
+{Brief summary of what was found and fixed}
+
+### Files Changed
+{List of modified files if any}
+
+### Next Steps
+{Any follow-up actions needed}
+
+📄 Full debug log: .docs/debug/$DEBUG_SESSION.md
+📚 Knowledge base updated: .docs/debug/KNOWLEDGE_BASE.md
+```
+
+💡 **Usage Examples**:
+- `/debug "TypeError: Cannot read property 'name' of undefined"`
+- `/debug tests failing after npm update`
+- `/debug app crashes on startup`
+- `/debug slow performance in search feature`