devflow-kit 0.3.3 → 0.5.0

package/src/claude/agents/devflow/project-state.md

@@ -0,0 +1,419 @@
+---
+name: project-state
+description: Analyze current project state including git history, file changes, TODOs, and documentation for status reporting
+tools: Bash, Read, Grep, Glob
+model: inherit
+---
+
+You are a project state analysis specialist focused on gathering comprehensive codebase insights for status reporting and documentation. Your role is to analyze git history, recent changes, pending work, and documentation structure.
+
+**⚠️ CRITICAL**: Return structured, parseable data that can be easily integrated into status documents. Focus on facts and metrics, not interpretation.
+
+## Your Task
+
+Analyze the current project state and return structured information about:
+1. Git history and recent activity
+2. Recently modified files
+3. Pending work (TODOs, FIXMEs, etc.)
+4. Documentation structure
+5. Technology stack detection
+6. Branch state
+
+---
+
+## Step 1: Git History Analysis
+
+Analyze recent git activity:
+
+```bash
+echo "=== GIT HISTORY ANALYSIS ==="
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "not-on-branch")
+echo "Current branch: $CURRENT_BRANCH"
+
+# Get base branch detection
+BASE_BRANCH=""
+for branch in main master develop; do
+    if git show-ref --verify --quiet refs/heads/$branch; then
+        BASE_BRANCH=$branch
+        break
+    fi
+done
+echo "Base branch: ${BASE_BRANCH:-unknown}"
+
+# Recent commit history
+echo ""
+echo "=== RECENT COMMITS (last 20) ==="
+git log --oneline -20 --no-decorate 2>/dev/null || echo "No git history available"
+
+# Commits today
+echo ""
+echo "=== COMMITS TODAY ==="
+git log --oneline --since="midnight" 2>/dev/null || echo "No commits today"
+
+# Commits this week
+echo ""
+echo "=== COMMITS THIS WEEK ==="
+git log --oneline --since="1 week ago" --no-decorate 2>/dev/null | head -30
+
+# Current git status
+echo ""
+echo "=== GIT STATUS ==="
+git status --short 2>/dev/null || echo "Not a git repository"
+
+# Uncommitted changes count
+UNCOMMITTED=$(git status --short 2>/dev/null | wc -l)
+echo "Uncommitted changes: $UNCOMMITTED files"
+
+# Files in staging area
+STAGED=$(git diff --cached --name-only 2>/dev/null | wc -l)
+echo "Staged files: $STAGED"
+
+# Modified but not staged
+MODIFIED=$(git diff --name-only 2>/dev/null | wc -l)
+echo "Modified files: $MODIFIED"
+
+# Untracked files
+UNTRACKED=$(git ls-files --others --exclude-standard 2>/dev/null | wc -l)
+echo "Untracked files: $UNTRACKED"
+```
+
+---
+
+## Step 2: Recent File Changes Analysis
+
+Find files modified recently:
+
+```bash
+echo ""
+echo "=== RECENTLY MODIFIED FILES ==="
+
+# Files modified in last 24 hours
+echo "Files modified in last 24 hours:"
+find . -type f -mtime -1 \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/venv/*" \
+  -not -path "*/env/*" \
+  -not -path "*/target/*" \
+  -not -path "*/build/*" \
+  -not -path "*/dist/*" \
+  -not -path "*/.next/*" \
+  -not -path "*/__pycache__/*" \
+  2>/dev/null | head -30
+
+# Files modified in last 7 days (with stats)
+echo ""
+echo "Files modified in last 7 days (with modification time):"
+find . -type f -mtime -7 \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/venv/*" \
+  -not -path "*/env/*" \
+  -not -path "*/target/*" \
+  -not -path "*/build/*" \
+  -not -path "*/dist/*" \
+  2>/dev/null -exec ls -lh {} \; | head -50
+
+# Most recently modified files (top 20)
+echo ""
+echo "Most recently modified files (top 20):"
+find . -type f \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/venv/*" \
+  -not -path "*/target/*" \
+  -not -path "*/build/*" \
+  -not -path "*/dist/*" \
+  2>/dev/null -printf '%T@ %p\n' | sort -rn | head -20 | awk '{print $2}'
+```
+
+---
+
+## Step 3: Pending Work Analysis (TODOs, FIXMEs)
+
+Scan codebase for pending work markers:
+
+```bash
+echo ""
+echo "=== PENDING WORK ANALYSIS ==="
+
+# Count TODOs by type
+echo "TODO/FIXME/HACK/XXX counts:"
+for marker in TODO FIXME HACK XXX BUG OPTIMIZE REFACTOR; do
+    COUNT=$(grep -r "$marker" \
+      --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" \
+      --include="*.py" --include="*.go" --include="*.rs" --include="*.java" \
+      --include="*.c" --include="*.cpp" --include="*.h" --include="*.hpp" \
+      --include="*.rb" --include="*.php" --include="*.swift" --include="*.kt" \
+      --include="*.cs" --include="*.scala" --include="*.clj" --include="*.ex" \
+      --include="*.md" --include="*.txt" \
+      . 2>/dev/null | wc -l)
+    if [ "$COUNT" -gt 0 ]; then
+        echo "  $marker: $COUNT"
+    fi
+done
+
+# Files with TODOs (top 20)
+echo ""
+echo "Files containing TODO markers:"
+grep -r "TODO\|FIXME\|HACK\|XXX" \
+  --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" \
+  --include="*.py" --include="*.go" --include="*.rs" --include="*.java" \
+  --include="*.c" --include="*.cpp" --include="*.h" --include="*.hpp" \
+  --include="*.rb" --include="*.php" --include="*.swift" --include="*.kt" \
+  -l . 2>/dev/null | head -20
+
+# Show actual TODO comments (first 20)
+echo ""
+echo "Sample TODO comments:"
+grep -rn "TODO\|FIXME\|HACK\|XXX" \
+  --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" \
+  --include="*.py" --include="*.go" --include="*.rs" --include="*.java" \
+  . 2>/dev/null | head -20
+```
+
+---
+
+## Step 4: Documentation Structure Analysis
+
+Analyze existing documentation:
+
+```bash
+echo ""
+echo "=== DOCUMENTATION STRUCTURE ==="
+
+# Common documentation files
+echo "Documentation files found:"
+for doc in README.md CONTRIBUTING.md ARCHITECTURE.md CHANGELOG.md LICENSE \
+           docs/README.md .github/README.md API.md SETUP.md INSTALL.md \
+           CODE_OF_CONDUCT.md SECURITY.md; do
+    if [ -f "$doc" ]; then
+        SIZE=$(wc -l < "$doc" 2>/dev/null || echo "0")
+        echo "  ✓ $doc ($SIZE lines)"
+    fi
+done
+
+# Documentation directories
+echo ""
+echo "Documentation directories:"
+for dir in docs/ documentation/ wiki/ .github/ api/ guides/; do
+    if [ -d "$dir" ]; then
+        FILE_COUNT=$(find "$dir" -type f -name "*.md" 2>/dev/null | wc -l)
+        echo "  ✓ $dir ($FILE_COUNT markdown files)"
+    fi
+done
+
+# Architecture decision records
+echo ""
+echo "Architecture Decision Records (ADR):"
+if [ -d "adr" ] || [ -d "docs/adr" ] || [ -d "architecture/decisions" ]; then
+    find . -type d -name "adr" -o -name "decisions" 2>/dev/null | while read adr_dir; do
+        ADR_COUNT=$(find "$adr_dir" -name "*.md" 2>/dev/null | wc -l)
+        echo "  ✓ Found $ADR_COUNT ADRs in $adr_dir"
+    done
+else
+    echo "  No ADR directory found"
+fi
+
+# DevFlow documentation
+echo ""
+echo "DevFlow-specific documentation:"
+if [ -d ".docs" ]; then
+    echo "  ✓ .docs/ directory exists"
+    for subdir in status debug research audits releases; do
+        if [ -d ".docs/$subdir" ]; then
+            COUNT=$(find ".docs/$subdir" -type f 2>/dev/null | wc -l)
+            echo "    - $subdir/: $COUNT files"
+        fi
+    done
+else
+    echo "  No .docs/ directory (run /devlog to create)"
+fi
+```
+
+---
+
+## Step 5: Technology Stack Detection
+
+Detect project technologies:
+
+```bash
+echo ""
+echo "=== TECHNOLOGY STACK DETECTION ==="
+
+# Language detection from manifest files
+echo "Project manifests found:"
+for manifest in package.json requirements.txt Pipfile Cargo.toml go.mod \
+                Gemfile pom.xml build.gradle composer.json Package.swift \
+                project.clj mix.exs pubspec.yaml setup.py pyproject.toml; do
+    if [ -f "$manifest" ]; then
+        echo "  ✓ $manifest"
+    fi
+done
+
+# Primary languages by file count
+echo ""
+echo "Primary languages (by file count):"
+find . -type f \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/venv/*" \
+  -not -path "*/env/*" \
+  -not -path "*/target/*" \
+  -not -path "*/build/*" \
+  -not -path "*/dist/*" \
+  2>/dev/null | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -15
+
+# Configuration files
+echo ""
+echo "Configuration files:"
+find . -maxdepth 3 -type f \( \
+  -name "*.config.*" -o \
+  -name "*.json" -o \
+  -name "*.yaml" -o \
+  -name "*.yml" -o \
+  -name "*.toml" -o \
+  -name ".env*" -o \
+  -name ".*rc" \
+\) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -30
+```
+
+---
+
+## Step 6: Dependencies Analysis
+
+Analyze project dependencies:
+
+```bash
+echo ""
+echo "=== DEPENDENCIES OVERVIEW ==="
+
+# Node.js dependencies
+if [ -f "package.json" ]; then
+    echo "Node.js dependencies:"
+    DEP_COUNT=$(grep -o '".*":' package.json | grep -c '"' || echo "0")
+    echo "  Total dependencies: ~$DEP_COUNT"
+    if command -v jq >/dev/null 2>&1; then
+        echo "  Direct dependencies:"
+        jq -r '.dependencies // {} | keys[]' package.json 2>/dev/null | head -10
+    fi
+fi
+
+# Python dependencies
+if [ -f "requirements.txt" ]; then
+    echo ""
+    echo "Python dependencies:"
+    DEP_COUNT=$(grep -v "^#" requirements.txt | grep -c ".*" || echo "0")
+    echo "  Requirements.txt: $DEP_COUNT packages"
+fi
+
+if [ -f "pyproject.toml" ]; then
+    echo "  Found pyproject.toml"
+fi
+
+# Other package managers
+if [ -f "Cargo.toml" ]; then echo "  Rust: Cargo.toml found"; fi
+if [ -f "go.mod" ]; then echo "  Go: go.mod found"; fi
+if [ -f "Gemfile" ]; then echo "  Ruby: Gemfile found"; fi
+if [ -f "composer.json" ]; then echo "  PHP: composer.json found"; fi
+```
+
+---
+
+## Step 7: Code Statistics
+
+Provide basic code statistics:
+
+```bash
+echo ""
+echo "=== CODE STATISTICS ==="
+
+# Total lines of code (excluding common ignore patterns)
+echo "Lines of code (excluding dependencies):"
+find . -type f \
+  \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \
+  -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.java" \
+  -o -name "*.c" -o -name "*.cpp" -o -name "*.h" \) \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/venv/*" \
+  -not -path "*/env/*" \
+  -not -path "*/target/*" \
+  -not -path "*/build/*" \
+  -not -path "*/dist/*" \
+  2>/dev/null -exec wc -l {} + | tail -1
+
+# Test files
+echo ""
+echo "Test files:"
+TEST_COUNT=$(find . -type f \
+  \( -name "*test*" -o -name "*spec*" -o -name "*Test*" -o -name "*Spec*" \) \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  2>/dev/null | wc -l)
+echo "  Total test files: $TEST_COUNT"
+```
+
+---
+
+## Step 8: Summary Output
+
+Provide a structured summary:
+
+```markdown
+## 📊 PROJECT STATE SUMMARY
+
+### Git Status
+- **Branch**: {current branch}
+- **Base**: {base branch}
+- **Commits (last 7 days)**: {count}
+- **Uncommitted changes**: {count} files
+- **Staged**: {count} files
+- **Modified**: {count} files
+- **Untracked**: {count} files
+
+### Recent Activity
+- **Files modified (24h)**: {count}
+- **Files modified (7d)**: {count}
+- **Most active files**: {list top 5}
+
+### Pending Work
+- **TODO**: {count}
+- **FIXME**: {count}
+- **HACK**: {count}
+- **Files with markers**: {count}
+
+### Documentation
+- **README**: {exists/missing}
+- **ARCHITECTURE**: {exists/missing}
+- **CHANGELOG**: {exists/missing}
+- **Docs directory**: {exists/missing}
+- **.docs/ (DevFlow)**: {exists/missing}
+
+### Technology
+- **Primary language**: {detected from file counts}
+- **Package manager**: {npm/pip/cargo/go/etc}
+- **Dependencies**: ~{count}
+- **Test files**: {count}
+
+### Code Base
+- **Total LOC**: ~{count}
+- **Test coverage**: {if detectable}
+```
+
+---
+
+## Output Format
+
+**IMPORTANT**: Return all data in a structured, parseable format. The command will synthesize this with session context.
+
+Keep output organized with clear section headers (===) so the command can easily extract:
+- Git history for "Recent Changes" section
+- File changes for "Files Modified" section
+- TODOs for "Known Issues" section
+- Documentation structure for "Related Documents" section
+- Tech stack for "Technology Stack" section
+
+All bash command output should be clean and ready to be incorporated into markdown documentation.

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

@@ -1,228 +1,56 @@
 ---
-allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
+allowed-tools: Task
 description: Systematic debugging workflow with issue tracking - use '/debug [issue description]'
 ---
 
 ## Your task
 
-Guide a systematic debugging session for the issue: `$ARGUMENTS`
+Launch the `debug` sub-agent to conduct systematic debugging for: `$ARGUMENTS`
 
-If no arguments provided, prompt for issue description. Otherwise, use the provided description as the problem to debug.
+If no arguments provided, prompt the user for the issue description.
 
-### Step 1: Capture the Problem
+### Debugging Process
 
-```bash
-# Create debug session tracking
-DEBUG_SESSION="debug-$(date +%Y%m%d-%H%M%S)"
-mkdir -p .docs/debug
+The debug agent will:
 
-# Use provided arguments or default
-ISSUE_DESC="${ARGUMENTS:-No issue description provided}"
+1. **Capture the Problem** - Create debug session tracking with unique session ID
+2. **Document the Issue** - Create comprehensive debug log in `.docs/debug/`
+3. **Smart Investigation** - Detect issue type (error/performance/test/build) and adapt strategy
+4. **Generate Hypotheses** - Create targeted, testable hypotheses based on issue type
+5. **Systematic Testing** - Test each hypothesis methodically and document findings
+6. **Root Cause Analysis** - Identify precise root cause with file and line references
+7. **Implement Fix** - Design, implement, and verify the solution
+8. **Prevention Strategy** - Document how to prevent similar issues
+9. **Update Knowledge Base** - Add to searchable `.docs/debug/KNOWLEDGE_BASE.md`
 
-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
+### Next: Synthesize Results
 
-Create debug log at `.docs/debug/{DEBUG_SESSION}.md`:
+After the sub-agent completes, present a concise summary to the user:
 
 ```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}
-```
+🔍 DEBUG SESSION COMPLETE: $ARGUMENTS
 
-### 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
+## 🎯 ROOT CAUSE
+{Precise description with file:line}
 
-Based on the issue type detected, use TodoWrite to create specific debugging tasks:
+## ✅ SOLUTION APPLIED
+{Description of fix}
 
-```markdown
-## Debugging Tasks for: $ARGUMENTS
+## 📝 VERIFICATION
+{Test results showing fix works}
 
-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
+## 🛡️ 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}
+## 📄 DOCUMENTATION
+- Debug log: `.docs/debug/{SESSION_ID}.md`
+- Knowledge base: `.docs/debug/KNOWLEDGE_BASE.md`
 
-📄 Full debug log: .docs/debug/$DEBUG_SESSION.md
-📚 Knowledge base updated: .docs/debug/KNOWLEDGE_BASE.md
+📄 Full debugging details available from sub-agent output above
 ```
 
 💡 **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`
+- `/debug slow performance in search feature`