claude-code-workflow 6.3.17 → 6.3.19

package/.claude/skills/code-reviewer/phases/03-best-practices-review.md

@@ -0,0 +1,36 @@
+# Phase 3: Best Practices Review
+
+## Objective
+
+Analyze code for best practices violations including code quality, performance issues, and maintainability concerns.
+
+## Input
+
+- **File Inventory**: From Phase 1 (`.code-review/inventory.json`)
+- **Security Findings**: From Phase 2 (`.code-review/security-findings.json`)
+- **User Arguments**:
+  - `--focus best-practices`: Best practices only mode
+  - `--check quality,performance,maintainability`: Specific areas to check
+
+## Process
+
+### Step 1: Code Quality Analysis
+
+Check naming conventions, function complexity, code duplication, and dead code detection.
+
+### Step 2: Performance Analysis
+
+Detect N+1 queries, inefficient algorithms, and memory leaks.
+
+### Step 3: Maintainability Analysis
+
+Check documentation coverage, test coverage, and dependency management.
+
+## Output
+
+- best-practices-findings.json
+- Markdown report with recommendations
+
+## Next Phase
+
+**Phase 4: Report Generation**

package/.claude/skills/code-reviewer/phases/04-report-generation.md

@@ -0,0 +1,278 @@
+# Phase 4: Report Generation
+
+## Objective
+
+Consolidate security and best practices findings into a comprehensive, actionable code review report.
+
+## Input
+
+- **Security Findings**: `.code-review/security-findings.json`
+- **Best Practices Findings**: `.code-review/best-practices-findings.json`
+- **File Inventory**: `.code-review/inventory.json`
+
+## Process
+
+### Step 1: Load All Findings
+
+```javascript
+const securityFindings = JSON.parse(
+  await Read({ file_path: '.code-review/security-findings.json' })
+);
+const bestPracticesFindings = JSON.parse(
+  await Read({ file_path: '.code-review/best-practices-findings.json' })
+);
+const inventory = JSON.parse(
+  await Read({ file_path: '.code-review/inventory.json' })
+);
+```
+
+### Step 2: Aggregate Statistics
+
+```javascript
+const stats = {
+  total_files_reviewed: inventory.total_files,
+  total_findings: securityFindings.total_findings + bestPracticesFindings.total_findings,
+  by_severity: {
+    critical: securityFindings.by_severity.critical,
+    high: securityFindings.by_severity.high + bestPracticesFindings.by_severity.high,
+    medium: securityFindings.by_severity.medium + bestPracticesFindings.by_severity.medium,
+    low: securityFindings.by_severity.low + bestPracticesFindings.by_severity.low,
+  },
+  by_category: {
+    security: securityFindings.total_findings,
+    code_quality: bestPracticesFindings.by_category.code_quality,
+    performance: bestPracticesFindings.by_category.performance,
+    maintainability: bestPracticesFindings.by_category.maintainability,
+  }
+};
+```
+
+### Step 3: Generate Comprehensive Report
+
+```markdown
+# Comprehensive Code Review Report
+
+**Generated**: {timestamp}
+**Scope**: {scope}
+**Files Reviewed**: {total_files}
+**Total Findings**: {total_findings}
+
+## Executive Summary
+
+{Provide high-level overview of code health}
+
+### Risk Assessment
+
+{Calculate risk score based on findings}
+
+### Compliance Status
+
+{Map findings to compliance requirements}
+
+## Detailed Findings
+
+{Merge and organize security + best practices findings}
+
+## Action Plan
+
+{Prioritized list of fixes with effort estimates}
+
+## Appendix
+
+{Technical details, references, configuration}
+```
+
+### Step 4: Generate Fix Tracking Checklist
+
+Create actionable checklist for developers:
+
+```markdown
+# Code Review Fix Checklist
+
+## Critical Issues (Fix Immediately)
+
+- [ ] [SEC-001] SQL Injection in src/auth/user-service.ts:145
+- [ ] [SEC-002] Hardcoded JWT Secret in src/auth/jwt.ts:23
+- [ ] [SEC-003] XSS Vulnerability in src/api/comments.ts:89
+
+## High Priority Issues (Fix This Week)
+
+- [ ] [SEC-004] Missing Authorization Check in src/api/admin.ts:34
+- [ ] [BP-001] N+1 Query Pattern in src/api/orders.ts:45
+...
+```
+
+### Step 5: Generate Metrics Dashboard
+
+```markdown
+## Code Health Metrics
+
+### Security Score: 68/100
+- Critical Issues: 3 (-30 points)
+- High Issues: 8 (-2 points each)
+
+### Code Quality Score: 75/100
+- High Complexity Functions: 2
+- Code Duplication: 5%
+- Dead Code: 3 instances
+
+### Performance Score: 82/100
+- N+1 Queries: 3
+- Inefficient Algorithms: 2
+
+### Maintainability Score: 70/100
+- Documentation Coverage: 65%
+- Test Coverage: 72%
+- Missing Tests: 5 files
+```
+
+## Output
+
+### Main Report
+
+Save to `.code-review/REPORT.md`:
+
+- Executive summary
+- Detailed findings (security + best practices)
+- Action plan with priorities
+- Metrics and scores
+- References and compliance mapping
+
+### Fix Checklist
+
+Save to `.code-review/FIX-CHECKLIST.md`:
+
+- Organized by severity
+- Checkboxes for tracking
+- File:line references
+- Effort estimates
+
+### JSON Summary
+
+Save to `.code-review/summary.json`:
+
+```json
+{
+  "report_date": "2024-01-15T12:00:00Z",
+  "scope": "src/**/*",
+  "statistics": {
+    "total_files": 247,
+    "total_findings": 69,
+    "by_severity": { "critical": 3, "high": 13, "medium": 30, "low": 23 },
+    "by_category": {
+      "security": 24,
+      "code_quality": 18,
+      "performance": 12,
+      "maintainability": 15
+    }
+  },
+  "scores": {
+    "security": 68,
+    "code_quality": 75,
+    "performance": 82,
+    "maintainability": 70,
+    "overall": 74
+  },
+  "risk_level": "MEDIUM",
+  "action_required": true
+}
+```
+
+## Report Template
+
+Full report includes:
+
+1. **Executive Summary**
+   - Overall code health
+   - Risk assessment
+   - Key recommendations
+
+2. **Security Findings** (from Phase 2)
+   - Critical/High/Medium/Low
+   - OWASP/CWE mappings
+   - Fix recommendations with code examples
+
+3. **Best Practices Findings** (from Phase 3)
+   - Code quality issues
+   - Performance concerns
+   - Maintainability gaps
+
+4. **Metrics Dashboard**
+   - Security score
+   - Code quality score
+   - Performance score
+   - Maintainability score
+
+5. **Action Plan**
+   - Immediate actions (critical)
+   - Short-term (1 week)
+   - Medium-term (1 month)
+   - Long-term (3 months)
+
+6. **Compliance Impact**
+   - PCI DSS findings
+   - HIPAA findings
+   - GDPR findings
+   - SOC 2 findings
+
+7. **Appendix**
+   - Full findings list
+   - Configuration used
+   - Tools and versions
+   - References
+
+## State Management
+
+```json
+{
+  "phase": "04-report-generation",
+  "status": "completed",
+  "timestamp": "2024-01-15T12:00:00Z",
+  "input": {
+    "security_findings": ".code-review/security-findings.json",
+    "best_practices_findings": ".code-review/best-practices-findings.json"
+  },
+  "output": {
+    "report": ".code-review/REPORT.md",
+    "checklist": ".code-review/FIX-CHECKLIST.md",
+    "summary": ".code-review/summary.json"
+  }
+}
+```
+
+## Agent Instructions
+
+```markdown
+You are in Phase 4 (FINAL) of the Code Review workflow. Generate comprehensive report.
+
+**Instructions**:
+1. Load security findings from Phase 2
+2. Load best practices findings from Phase 3
+3. Aggregate statistics and calculate scores
+4. Generate comprehensive markdown report
+5. Create fix tracking checklist
+6. Generate JSON summary
+7. Inform user of completion and output locations
+
+**Tools Available**:
+- Read (load findings)
+- Write (save reports)
+
+**Output Requirements**:
+- REPORT.md (comprehensive markdown report)
+- FIX-CHECKLIST.md (actionable checklist)
+- summary.json (machine-readable summary)
+- All files in .code-review/ directory
+```
+
+## Validation
+
+- ✅ All findings consolidated
+- ✅ Scores calculated
+- ✅ Action plan generated
+- ✅ Reports saved to .code-review/
+- ✅ User notified of completion
+
+## Completion
+
+Code review complete! Outputs available in `.code-review/` directory.

package/.claude/skills/code-reviewer/specs/best-practices-requirements.md

@@ -0,0 +1,346 @@
+# Best Practices Requirements Specification
+
+## Code Quality Standards
+
+### Naming Conventions
+
+**TypeScript/JavaScript**:
+- Classes/Interfaces: PascalCase (`UserService`, `IUserRepository`)
+- Functions/Methods: camelCase (`getUserById`, `validateEmail`)
+- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`, `API_BASE_URL`)
+- Private properties: prefix with `_` or `#` (`_cache`, `#secretKey`)
+
+**Python**:
+- Classes: PascalCase (`UserService`, `DatabaseConnection`)
+- Functions: snake_case (`get_user_by_id`, `validate_email`)
+- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
+- Private: prefix with `_` (`_internal_cache`)
+
+**Java**:
+- Classes/Interfaces: PascalCase (`UserService`, `IUserRepository`)
+- Methods: camelCase (`getUserById`, `validateEmail`)
+- Constants: UPPER_SNAKE_CASE (`MAX_RETRY_COUNT`)
+- Packages: lowercase (`com.example.service`)
+
+### Function Complexity
+
+**Cyclomatic Complexity Thresholds**:
+- **Low**: 1-5 (simple functions, easy to test)
+- **Medium**: 6-10 (acceptable, well-structured)
+- **High**: 11-20 (needs refactoring)
+- **Very High**: 21+ (critical, must refactor)
+
+**Calculation**:
+```
+Complexity = 1 (base) 
+  + count(if)
+  + count(else if)
+  + count(while)
+  + count(for)
+  + count(case)
+  + count(catch)
+  + count(&&)
+  + count(||)
+  + count(? :)
+```
+
+### Code Duplication
+
+**Thresholds**:
+- **Acceptable**: < 3% duplication
+- **Warning**: 3-5% duplication
+- **Critical**: > 5% duplication
+
+**Detection**:
+- Minimum block size: 5 lines
+- Similarity threshold: 85%
+- Ignore: Comments, imports, trivial getters/setters
+
+### Dead Code Detection
+
+**Targets**:
+- Unused imports
+- Unused variables/functions (not exported)
+- Unreachable code (after return/throw)
+- Commented-out code blocks (> 5 lines)
+
+## Performance Standards
+
+### N+1 Query Prevention
+
+**Anti-patterns**:
+```javascript
+// ❌ N+1 Query
+for (const order of orders) {
+  const user = await User.findById(order.userId);
+}
+
+// ✅ Batch Query
+const userIds = orders.map(o => o.userId);
+const users = await User.findByIds(userIds);
+```
+
+### Algorithm Efficiency
+
+**Common Issues**:
+- Nested loops (O(n²)) when O(n) possible
+- Array.indexOf in loop → use Set.has()
+- Array.filter().length → use Array.some()
+- Multiple array iterations → combine into one pass
+
+**Acceptable Complexity**:
+- **O(1)**: Ideal for lookups
+- **O(log n)**: Good for search
+- **O(n)**: Acceptable for linear scan
+- **O(n log n)**: Acceptable for sorting
+- **O(n²)**: Avoid if possible, document if necessary
+
+### Memory Leak Prevention
+
+**Common Issues**:
+- Event listeners without cleanup
+- setInterval without clearInterval
+- Global variable accumulation
+- Circular references
+- Large array/object allocations
+
+**Patterns**:
+```javascript
+// ❌ Memory Leak
+element.addEventListener('click', handler);
+// No cleanup
+
+// ✅ Proper Cleanup
+useEffect(() => {
+  element.addEventListener('click', handler);
+  return () => element.removeEventListener('click', handler);
+}, []);
+```
+
+### Resource Cleanup
+
+**Required Cleanup**:
+- Database connections
+- File handles
+- Network sockets
+- Timers (setTimeout, setInterval)
+- Event listeners
+
+## Maintainability Standards
+
+### Documentation Requirements
+
+**Required for**:
+- All exported functions/classes
+- Public APIs
+- Complex algorithms
+- Non-obvious business logic
+
+**JSDoc Format**:
+```javascript
+/**
+ * Validates user credentials and generates JWT token
+ * 
+ * @param {string} username - User's username or email
+ * @param {string} password - Plain text password
+ * @returns {Promise<{token: string, expiresAt: Date}>} JWT token and expiration
+ * @throws {AuthenticationError} If credentials are invalid
+ * 
+ * @example
+ * const {token} = await authenticateUser('john@example.com', 'secret123');
+ */
+async function authenticateUser(username, password) {
+  // ...
+}
+```
+
+**Coverage Targets**:
+- Critical modules: 100%
+- High priority: 90%
+- Medium priority: 70%
+- Low priority: 50%
+
+### Test Coverage Requirements
+
+**Coverage Targets**:
+- Unit tests: 80% line coverage
+- Integration tests: Key workflows covered
+- E2E tests: Critical user paths covered
+
+**Required Tests**:
+- All exported functions
+- All public methods
+- Error handling paths
+- Edge cases
+
+**Test File Convention**:
+```
+src/auth/login.ts
+  → src/auth/login.test.ts (unit)
+  → src/auth/login.integration.test.ts (integration)
+```
+
+### Dependency Management
+
+**Best Practices**:
+- Pin major versions (`"^1.2.3"` not `"*"`)
+- Avoid 0.x versions in production
+- Regular security audits (npm audit, snyk)
+- Keep dependencies up-to-date
+- Minimize dependency count
+
+**Version Pinning**:
+```json
+{
+  "dependencies": {
+    "express": "^4.18.0",    // ✅ Pinned major version
+    "lodash": "*",            // ❌ Wildcard
+    "legacy-lib": "^0.5.0"   // ⚠️ Unstable 0.x
+  }
+}
+```
+
+### Magic Numbers
+
+**Definition**: Numeric literals without clear meaning
+
+**Anti-patterns**:
+```javascript
+// ❌ Magic numbers
+if (user.age > 18) { }
+setTimeout(() => {}, 5000);
+buffer = new Array(1048576);
+
+// ✅ Named constants
+const LEGAL_AGE = 18;
+const RETRY_DELAY_MS = 5000;
+const BUFFER_SIZE_1MB = 1024 * 1024;
+
+if (user.age > LEGAL_AGE) { }
+setTimeout(() => {}, RETRY_DELAY_MS);
+buffer = new Array(BUFFER_SIZE_1MB);
+```
+
+**Exceptions** (acceptable magic numbers):
+- 0, 1, -1 (common values)
+- 100, 1000 (obvious scaling factors in context)
+- HTTP status codes (200, 404, 500)
+
+## Error Handling Standards
+
+### Required Error Handling
+
+**Categories**:
+- Network errors (timeout, connection failure)
+- Database errors (query failure, constraint violation)
+- Validation errors (invalid input)
+- Authentication/Authorization errors
+
+**Anti-patterns**:
+```javascript
+// ❌ Silent failure
+try {
+  await saveUser(user);
+} catch (err) {
+  // Empty catch
+}
+
+// ❌ Generic catch
+try {
+  await processPayment(order);
+} catch (err) {
+  console.log('Error');  // No details
+}
+
+// ✅ Proper handling
+try {
+  await processPayment(order);
+} catch (err) {
+  logger.error('Payment processing failed', { orderId: order.id, error: err });
+  throw new PaymentError('Failed to process payment', { cause: err });
+}
+```
+
+### Logging Standards
+
+**Required Logs**:
+- Authentication attempts (success/failure)
+- Authorization failures
+- Data modifications (create/update/delete)
+- External API calls
+- Errors and exceptions
+
+**Log Levels**:
+- **ERROR**: System errors, exceptions
+- **WARN**: Recoverable issues, deprecations
+- **INFO**: Business events, state changes
+- **DEBUG**: Detailed troubleshooting info
+
+**Sensitive Data**:
+- Never log: passwords, tokens, credit cards, SSNs
+- Hash/mask: emails, IPs, usernames (in production)
+
+## Code Structure Standards
+
+### File Organization
+
+**Max File Size**: 300 lines (excluding tests)
+**Max Function Size**: 50 lines
+
+**Module Structure**:
+```
+module/
+  ├── index.ts          # Public exports
+  ├── types.ts          # Type definitions
+  ├── constants.ts      # Constants
+  ├── utils.ts          # Utilities
+  ├── service.ts        # Business logic
+  └── service.test.ts   # Tests
+```
+
+### Import Organization
+
+**Order**:
+1. External dependencies
+2. Internal modules (absolute imports)
+3. Relative imports
+4. Type imports (TypeScript)
+
+```typescript
+// ✅ Organized imports
+import express from 'express';
+import { Logger } from 'winston';
+
+import { UserService } from '@/services/user';
+import { config } from '@/config';
+
+import { validateEmail } from './utils';
+import { UserRepository } from './repository';
+
+import type { User, UserCreateInput } from './types';
+```
+
+## Scoring System
+
+### Overall Score Calculation
+
+```
+Overall Score = (
+  Security Score × 0.4 +
+  Code Quality Score × 0.25 +
+  Performance Score × 0.2 +
+  Maintainability Score × 0.15
+)
+
+Security = 100 - (Critical × 30 + High × 2 + Medium × 0.5)
+Code Quality = 100 - (violations / total_checks × 100)
+Performance = 100 - (issues / potential_issues × 100)
+Maintainability = (doc_coverage × 0.4 + test_coverage × 0.4 + dependency_health × 0.2)
+```
+
+### Risk Levels
+
+- **LOW**: Score 90-100
+- **MEDIUM**: Score 70-89
+- **HIGH**: Score 50-69
+- **CRITICAL**: Score < 50