devflow-kit 0.1.2 → 0.2.0

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

@@ -77,12 +77,36 @@ For each found status document:
 # Check if "completed" features actually work
 echo "=== VALIDATING STATUS CLAIMS ==="
 
-# Test basic functionality - adapt these commands to your project
-echo "Testing basic commands/functionality..."
-# Try common test commands - adapt based on project
-(npm test 2>/dev/null || pytest 2>/dev/null || cargo test 2>/dev/null || mvn test 2>/dev/null || go test 2>/dev/null) || echo "⚠️ Could not run tests (verify test command for your stack)"
-# Try common build commands - adapt based on project
-(npm run build 2>/dev/null || cargo build 2>/dev/null || mvn package 2>/dev/null || make 2>/dev/null) || echo "⚠️ Could not run build (verify build command for your stack)"
+# Detect and run project's test command
+echo "Attempting to run tests..."
+TEST_CMD=""
+BUILD_CMD=""
+
+# Auto-detect test command from common manifest files
+if [ -f "package.json" ]; then
+    TEST_CMD=$(command -v jq >/dev/null && jq -r '.scripts.test // empty' package.json 2>/dev/null || grep -o '"test"[^"]*"[^"]*"' package.json | cut -d'"' -f4)
+    BUILD_CMD=$(command -v jq >/dev/null && jq -r '.scripts.build // empty' package.json 2>/dev/null || grep -o '"build"[^"]*"[^"]*"' package.json | cut -d'"' -f4)
+elif [ -f "Makefile" ]; then
+    grep -q "^test:" Makefile && TEST_CMD="make test"
+    grep -q "^build:" Makefile && BUILD_CMD="make build"
+fi
+
+# Run tests if detected
+if [ -n "$TEST_CMD" ]; then
+    echo "Running: $TEST_CMD"
+    eval $TEST_CMD 2>&1 | head -20 || echo "⚠️ Tests failed - verify 'all tests passing' claims"
+else
+    echo "ℹ️  No test command auto-detected. Manually verify test claims."
+    echo "   Try common commands: npm test, pytest, cargo test, go test, mvn test, etc."
+fi
+
+# Run build if detected
+if [ -n "$BUILD_CMD" ]; then
+    echo "Running: $BUILD_CMD"
+    eval $BUILD_CMD 2>&1 | head -20 || echo "⚠️ Build failed - verify 'build successful' claims"
+else
+    echo "ℹ️  No build command auto-detected. Manually verify build claims."
+fi
 
 # Check for claimed files/features
 echo "Verifying claimed file changes..."
@@ -90,21 +114,23 @@ git status --porcelain | head -10
 
 # Look for obvious broken states
 echo "Checking for red flags..."
-find . -name "*.tmp" -o -name "*.bak" -o -name "*~" | head -5
-# Search across common source file extensions
-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="*.rb" --include="*.php" . 2>/dev/null | head -5
-
-# Check if dependencies are actually installed - adapt based on project
-if [ -f "package.json" ]; then
-    echo "Checking Node.js dependencies..."
-    npm ls 2>/dev/null | grep -i "missing\|invalid" || echo "✅ Node dependencies seem consistent"
-elif [ -f "requirements.txt" ] || [ -f "Pipfile" ]; then
-    echo "Checking Python dependencies..."
-    pip list 2>/dev/null >/dev/null || echo "⚠️ Check Python dependencies"
-elif [ -f "Cargo.toml" ]; then
-    echo "Checking Rust dependencies..."
-    cargo check 2>/dev/null || echo "⚠️ Check Rust dependencies"
-fi
+find . -type f \( -name "*.tmp" -o -name "*.bak" -o -name "*~" \) ! -path "*/node_modules/*" ! -path "*/.git/*" | head -5
+
+# Search for TODO/FIXME across all source files (language-agnostic)
+echo "Scanning for TODO/FIXME markers..."
+find . -type f ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" ! -path "*/target/*" ! -path "*/build/*" ! -path "*/dist/*" \
+    \( -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" -o -name "*.rb" -o -name "*.php" \
+    -o -name "*.cs" -o -name "*.swift" -o -name "*.kt" -o -name "*.scala" \) \
+    -exec grep -l "TODO\|FIXME\|HACK\|XXX" {} \; 2>/dev/null | head -5
+
+# Generic dependency check
+echo "Checking dependency health..."
+for manifest in package.json requirements.txt Cargo.toml go.mod Gemfile pom.xml; do
+    if [ -f "$manifest" ]; then
+        echo "Found: $manifest - verify dependencies are installed for your environment"
+    fi
+done
 
 echo "=== END VALIDATION ==="
 ```

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

@@ -10,15 +10,43 @@ You are a commit specialist focused on helping developers create clean, atomic,
 **⚠️ 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
+- ALWAYS check for lock file before operations and wait for release
 - 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
+- Add explicit `wait` after git operations to ensure process completion
+- Use command substitution patterns that force synchronous execution
 
 ## Your Task
 
 Help developers create intelligent, safe, and atomic commits by analyzing changes, detecting issues, grouping related files, and generating clear commit messages.
 
+### Step 0: Wait for Lock Release (CRITICAL)
+
+Before ANY git operation, ensure no lock file exists. If it does, wait for it to be released:
+
+```bash
+# Function to wait for lock file release (prevents zombie process issues)
+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 this before git operations
+wait_for_lock_release || exit 1
+```
+
 ### Step 1: Analyze Uncommitted Changes
 
 First, check what changes are staged and unstaged.
@@ -28,18 +56,18 @@ First, check what changes are staged and unstaged.
 ```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
+# Ensure no lock file, then get uncommitted changes
+wait_for_lock_release && git status --porcelain; wait
 
-# 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)
+# Count files by status (using command substitution for synchronous execution)
+MODIFIED=$(git status --porcelain | grep "^ M" | wc -l); wait
+STAGED=$(git status --porcelain | grep "^M" | wc -l); wait
+UNTRACKED=$(git status --porcelain | grep "^??" | wc -l); wait
 
 echo "Modified: $MODIFIED, Staged: $STAGED, Untracked: $UNTRACKED"
 
-# Show detailed diff
-git diff HEAD --stat
+# Show detailed diff (explicit wait after)
+git diff HEAD --stat; wait
 echo ""
 ```
 
@@ -97,8 +125,8 @@ TEST_PATTERNS=(
 
 DANGEROUS_FILES=""
 
-# Scan uncommitted files against patterns
-for file in $(git diff HEAD --name-only); do
+# Scan uncommitted files against patterns (ensure git completes)
+for file in $(git diff HEAD --name-only; wait); do
   # Check against all patterns
   for pattern in "${SENSITIVE_PATTERNS[@]}" "${TEMP_PATTERNS[@]}" "${TEST_PATTERNS[@]}"; do
     if [[ "$file" == $pattern ]]; then
@@ -135,8 +163,8 @@ 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
+# Get all changed files with their paths (explicit wait for completion)
+git diff HEAD --name-only > /tmp/changed_files.txt; wait
 
 # Analyze files and suggest groupings
 # Group by:
@@ -254,14 +282,16 @@ Message:
 
 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.
+**CRITICAL**: All git commands MUST run sequentially with proper wait handling to prevent `.git/index.lock` conflicts.
 
 ```bash
-# For each commit group, run ALL operations sequentially in a SINGLE command:
+# For each commit group, wait for lock release, then execute sequentially:
+
+# STEP 1: Wait for any existing lock to be released
+wait_for_lock_release || { echo "❌ Lock wait failed"; exit 1; }
 
-# 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 && \
+# STEP 2: Execute commit operations in single chain with explicit waits
+git add file1 file2 file3; wait && \
 git commit -m "$(cat <<'EOF'
 type: short summary
 
@@ -273,22 +303,27 @@ Closes #issue
 
 Co-Authored-By: Claude <noreply@anthropic.com>
 EOF
-)" && \
-git log -1 --oneline && \
+)"; wait && \
+git log -1 --oneline; wait && \
 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
+# STEP 3: Explicit final wait to ensure all git processes complete
+wait
+
+# IMPORTANT: This pattern ensures:
+# 1. Wait for lock release before operations (prevents zombie conflicts)
+# 2. Sequential execution with && chains (no parallel operations)
+# 3. Explicit wait after each git command (ensures process completion)
+# 4. Final wait at end (reaps any remaining child processes)
+# 5. Any failure stops the entire chain immediately
 ```
 
-**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
+**Why This Pattern Prevents Lock Issues**:
+- **Wait for lock release**: Prevents starting operations while lock exists
+- **Explicit `wait` commands**: Ensures git processes fully complete and are reaped
+- **Command substitution**: Forces synchronous execution (parent waits for child)
+- **Sequential chains**: No parallel git operations that could conflict
+- **Timeout handling**: Fails gracefully if lock persists (indicates real problem)
 
 ### Step 7: Post-Commit Summary
 

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

@@ -118,20 +118,20 @@ For each approach, document:
 ```bash
 echo "=== DOCUMENTATION RESEARCH ==="
 
-# Look for package.json or requirements to understand current stack
-if [ -f "package.json" ]; then
-    echo "Node.js project detected"
-    cat package.json | grep -A 20 "dependencies"
-elif [ -f "requirements.txt" ]; then
-    echo "Python project detected"
-    cat requirements.txt
-elif [ -f "Cargo.toml" ]; then
-    echo "Rust project detected"
-    cat Cargo.toml | grep -A 10 "dependencies"
-elif [ -f "go.mod" ]; then
-    echo "Go project detected"
-    cat go.mod
-fi
+# Auto-detect project stack from common manifest files
+echo "Detecting project stack..."
+for manifest in package.json requirements.txt Pipfile Cargo.toml go.mod Gemfile pom.xml build.gradle composer.json Package.swift; do
+    if [ -f "$manifest" ]; then
+        echo "=== Found: $manifest ==="
+        head -30 "$manifest" | grep -i "depend\|version\|name" || head -30 "$manifest"
+        echo ""
+    fi
+done
+
+# Show detected languages from git (file extensions)
+echo "Primary file types in project:"
+find . -type f ! -path "*/.*" ! -path "*/node_modules/*" ! -path "*/vendor/*" ! -path "*/target/*" ! -path "*/build/*" ! -path "*/dist/*" 2>/dev/null \
+    | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
 ```
 
 **For each relevant library/framework**:
@@ -185,17 +185,23 @@ echo "=== CODEBASE PATTERN ANALYSIS ==="
 # Find similar existing implementations
 echo "Searching for similar patterns..."
 
-# Example: If implementing auth, search for existing auth patterns
-# grep -r "auth\|Auth\|authenticate" --include="*.js" --include="*.ts" . | head -20
+# Generic search across all source files (language-agnostic)
+# Example: If implementing auth, adapt the search term below
+# find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \
+#     -o -name "*.java" -o -name "*.rb" -o -name "*.php" -o -name "*.cs" -o -name "*.cpp" \) \
+#     ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" ! -path "*/target/*" \
+#     -exec grep -l "auth\|authenticate" {} \; | head -20
 
 # Find architectural patterns
 echo "Analyzing project structure..."
 ls -la | head -20
-find . -type f -name "*.config.*" -o -name "*.json" | head -10
+find . -type f \( -name "*.config.*" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.toml" \) \
+    ! -path "*/node_modules/*" ! -path "*/.git/*" | head -15
 
-# Look for test patterns
+# Look for test patterns (language-agnostic)
 echo "Checking test patterns..."
-find . -type f -name "*.test.*" -o -name "*.spec.*" | head -10
+find . -type f \( -name "*test*" -o -name "*spec*" -o -name "*Test*" -o -name "*Spec*" \) \
+    ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" | head -15
 ```
 
 **Analysis Areas**:
@@ -217,17 +223,22 @@ find . -type f -name "*.test.*" -o -name "*.spec.*" | head -10
 ### 4.2 Code Style & Conventions
 
 ```bash
-# Check TypeScript/JavaScript patterns
-if [ -f "tsconfig.json" ]; then
-    echo "TypeScript configuration:"
-    cat tsconfig.json | head -30
-fi
-
-# Check linting rules
-if [ -f ".eslintrc.js" ] || [ -f ".eslintrc.json" ]; then
-    echo "ESLint configuration found"
-    cat .eslintrc.* | head -20
-fi
+# Auto-detect language configuration files
+echo "=== DETECTING CODE STYLE & CONVENTIONS ==="
+
+# Check for common configuration files across languages
+for config in tsconfig.json jsconfig.json .eslintrc* .prettierrc* pyproject.toml setup.cfg .pylintrc \
+    .rubocop.yml Cargo.toml rustfmt.toml .editorconfig .clang-format checkstyle.xml; do
+    if [ -f "$config" ] || ls $config 2>/dev/null | grep -q .; then
+        echo "=== Found: $config ==="
+        head -30 "$config" 2>/dev/null
+        echo ""
+    fi
+done
+
+# Look for linter/formatter patterns
+echo "Checking for linting/formatting tools..."
+ls -la | grep -E "lint|format|style" | head -10
 ```
 
 **Document**:
@@ -247,9 +258,17 @@ fi
 # Find similar features already implemented
 echo "Looking for similar existing features..."
 
-# Example searches - adapt to specific research topic
-# grep -r "export.*function" --include="*.ts" --include="*.js" . | head -10
-# grep -r "export.*class" --include="*.ts" --include="*.js" . | head -10
+# Generic pattern search across all source files (adapt search term to research topic)
+# Example: searching for function/class definitions across common languages
+# 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 "*.rb" \
+#     -o -name "*.php" -o -name "*.cs" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" \) \
+#     ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/vendor/*" ! -path "*/target/*" \
+#     -exec grep -H "^export\|^public\|^def\|^func\|^fn\|^function\|^class" {} \; 2>/dev/null | head -20
+
+# Show most commonly edited files (good candidates for similar patterns)
+echo "Frequently modified files (likely contain patterns to follow):"
+git log --pretty=format: --name-only --since="6 months ago" 2>/dev/null | sort | uniq -c | sort -rn | head -15
 ```
 
 **Analyze and document**:

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

@@ -7,6 +7,12 @@ allowed-tools: Task, Bash, Read, Write, Grep, Glob
 
 Perform a comprehensive review of uncommitted changes by orchestrating multiple specialized sub-agents in parallel. This provides quick feedback before committing changes.
 
+**Audit Strategy**:
+- **Always Run** (5 core audits): Security, Performance, Architecture, Tests, Complexity
+- **Available on demand**: Documentation, Dependencies, Database (use `/pre-pr` for full audit)
+
+This lightweight approach provides fast feedback for individual commits. Use `/pre-pr` for comprehensive branch reviews before creating pull requests.
+
 ### Step 1: Analyze Current Changes
 
 First, check what changes are available for review:

package/src/claude/commands/devflow/pre-pr.md

@@ -53,27 +53,51 @@ git log --oneline $BASE_BRANCH..HEAD
 echo ""
 ```
 
-### Step 2: Launch Specialized Sub-Agents in Parallel
+### Step 2: Detect Change Categories
 
-Launch these sub-agents in parallel:
+Analyze what types of changes are in this branch to determine which specialized agents are needed:
 
+```bash
+# Check if database-related files changed
+DB_CHANGES=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E '\.(sql|prisma|migration|knex|sequelize|db)' || true)
+DB_CHANGES+=$(git diff --name-only $BASE_BRANCH...HEAD | grep -iE '(migration|schema|database|models/)' || true)
+
+if [ -n "$DB_CHANGES" ]; then
+    echo "🗄️  Database changes detected - will run database audit"
+    INCLUDE_DB_AUDIT=true
+else
+    echo "ℹ️  No database changes detected - skipping database audit"
+    INCLUDE_DB_AUDIT=false
+fi
+echo ""
+```
+
+### Step 3: Launch Specialized Sub-Agents in Parallel
+
+Launch these sub-agents in parallel based on change detection:
+
+**Core Audits (Always Run)**:
 1. audit-security sub-agent
 2. audit-performance sub-agent
 3. audit-architecture sub-agent
 4. audit-tests sub-agent
 5. audit-complexity sub-agent
 6. audit-dependencies sub-agent
+7. audit-documentation sub-agent
 
-### Step 3: Synthesize Comprehensive Review
+**Conditional Audits**:
+8. audit-database sub-agent (only if database changes detected)
+
+### Step 4: Synthesize Comprehensive Review
 
 After all sub-agents complete their analysis:
 
-1. **Collect Results**: Gather findings from all 6 specialized sub-agents
+1. **Collect Results**: Gather findings from all 7-8 specialized sub-agents (depending on change types)
 2. **Cross-Reference Issues**: Identify overlapping concerns between domains
 3. **Prioritize for PR**: Focus on merge-blocking vs nice-to-have improvements
 4. **Create PR-Ready Review**: Structure for easy consumption by human reviewers
 
-### Step 4: Save Comprehensive Review Document
+### Step 5: Save Comprehensive Review Document
 
 Create a detailed review document at `.docs/reviews/branch-{BRANCH_NAME}-{YYYY-MM-DD_HHMM}.md`:
 
@@ -178,6 +202,25 @@ Create a detailed review document at `.docs/reviews/branch-{BRANCH_NAME}-{YYYY-M
 #### Dependency Recommendations
 {specific dependency management improvements}
 
+### 📚 Documentation Analysis (audit-documentation)
+**Documentation Quality**: {Excellent/Good/Acceptable/Poor}
+
+#### Documentation Issues Found
+{detailed documentation drift, missing docs, stale examples}
+
+#### Documentation Recommendations
+{specific documentation updates needed}
+
+### 🗄️ Database Analysis (audit-database)
+**Database Health**: {Excellent/Good/Acceptable/Poor}
+**Note**: Only included if database changes detected
+
+#### Database Issues Found
+{detailed database design, migration, and query issues}
+
+#### Database Recommendations
+{specific database improvements needed}
+
 ---
 
 ## 🎯 Action Plan
@@ -209,6 +252,8 @@ Create a detailed review document at `.docs/reviews/branch-{BRANCH_NAME}-{YYYY-M
 - Test Coverage: {score}/10
 - Maintainability: {score}/10
 - Dependencies: {score}/10
+- Documentation: {score}/10
+- Database: {score}/10 (if applicable)
 
 ### Comparison to {BASE_BRANCH}
 - Quality Trend: {Improving/Stable/Declining}
@@ -253,7 +298,7 @@ Based on sub-agent analysis, human reviewers should focus on:
 *Next: Address blocking issues, then create PR with this review as reference*
 ```
 
-### Step 5: Provide Executive Summary
+### Step 6: Provide Executive Summary
 
 Give the developer a clear, actionable summary: