claude-code-workflow 6.3.18 → 6.3.19

package/.claude/skills/code-reviewer/specs/quality-standards.md

@@ -0,0 +1,252 @@
+# Quality Standards
+
+## Overall Quality Metrics
+
+### Quality Score Formula
+
+```
+Overall Quality = (
+  Correctness × 0.30 +
+  Security × 0.25 +
+  Maintainability × 0.20 +
+  Performance × 0.15 +
+  Documentation × 0.10
+)
+```
+
+### Score Ranges
+
+| Range | Grade | Description |
+|-------|-------|-------------|
+| 90-100 | A | Excellent - Production ready |
+| 80-89 | B | Good - Minor improvements needed |
+| 70-79 | C | Acceptable - Some issues to address |
+| 60-69 | D | Poor - Significant improvements required |
+| 0-59 | F | Failing - Major issues, not production ready |
+
+## Review Completeness
+
+### Mandatory Checks
+
+**Security**:
+- ✅ OWASP Top 10 coverage
+- ✅ CWE Top 25 coverage
+- ✅ Language-specific security patterns
+- ✅ Dependency vulnerability scan
+
+**Code Quality**:
+- ✅ Naming convention compliance
+- ✅ Complexity analysis
+- ✅ Code duplication detection
+- ✅ Dead code identification
+
+**Performance**:
+- ✅ N+1 query detection
+- ✅ Algorithm efficiency check
+- ✅ Memory leak detection
+- ✅ Resource cleanup verification
+
+**Maintainability**:
+- ✅ Documentation coverage
+- ✅ Test coverage analysis
+- ✅ Dependency health check
+- ✅ Error handling review
+
+## Reporting Standards
+
+### Finding Requirements
+
+Each finding must include:
+- **Unique ID**: SEC-001, BP-001, etc.
+- **Type**: Specific issue type (sql-injection, high-complexity, etc.)
+- **Severity**: Critical, High, Medium, Low
+- **Location**: File path and line number
+- **Code Snippet**: Vulnerable/problematic code
+- **Message**: Clear description of the issue
+- **Recommendation**: Specific fix guidance
+- **Example**: Before/after code example
+
+### Report Structure
+
+**Executive Summary**:
+- High-level overview
+- Risk assessment
+- Key statistics
+- Compliance status
+
+**Detailed Findings**:
+- Organized by severity
+- Grouped by category
+- Full details for each finding
+
+**Action Plan**:
+- Prioritized fix list
+- Effort estimates
+- Timeline recommendations
+
+**Metrics Dashboard**:
+- Quality scores
+- Trend analysis (if historical data)
+- Compliance status
+
+**Appendix**:
+- Full findings list
+- Configuration details
+- Tool versions
+- References
+
+## Output File Standards
+
+### File Naming
+
+```
+.code-review/
+├── inventory.json              # File inventory
+├── security-findings.json      # Security findings
+├── best-practices-findings.json # Best practices findings
+├── summary.json                # Summary statistics
+├── REPORT.md                   # Main report
+├── FIX-CHECKLIST.md           # Action checklist
+└── state.json                  # Session state
+```
+
+### JSON Schema
+
+**Finding Schema**:
+```json
+{
+  "id": "string",
+  "type": "string",
+  "category": "security|code_quality|performance|maintainability",
+  "severity": "critical|high|medium|low",
+  "file": "string",
+  "line": "number",
+  "column": "number",
+  "code": "string",
+  "message": "string",
+  "recommendation": {
+    "description": "string",
+    "fix_example": "string"
+  },
+  "references": ["string"],
+  "cwe": "string (optional)",
+  "owasp": "string (optional)"
+}
+```
+
+## Validation Requirements
+
+### Phase Completion Criteria
+
+**Phase 1 (Code Discovery)**:
+- ✅ At least 1 file discovered
+- ✅ Files categorized by priority
+- ✅ Metadata extracted
+- ✅ Inventory JSON created
+
+**Phase 2 (Security Analysis)**:
+- ✅ All critical/high priority files analyzed
+- ✅ Findings have severity classification
+- ✅ CWE/OWASP mappings included
+- ✅ Fix recommendations provided
+
+**Phase 3 (Best Practices)**:
+- ✅ Code quality checks completed
+- ✅ Performance analysis done
+- ✅ Maintainability assessed
+- ✅ Recommendations provided
+
+**Phase 4 (Report Generation)**:
+- ✅ All findings consolidated
+- ✅ Scores calculated
+- ✅ Reports generated
+- ✅ Checklist created
+
+## Skill Execution Standards
+
+### Performance Targets
+
+- **Phase 1**: < 30 seconds per 1000 files
+- **Phase 2**: < 60 seconds per 100 files (security)
+- **Phase 3**: < 60 seconds per 100 files (best practices)
+- **Phase 4**: < 10 seconds (report generation)
+
+### Resource Limits
+
+- **Memory**: < 2GB for projects with 1000+ files
+- **CPU**: Efficient pattern matching (minimize regex complexity)
+- **Disk**: Use streaming for large files (> 10MB)
+
+### Error Handling
+
+**Graceful Degradation**:
+- If tool unavailable: Skip check, note in report
+- If file unreadable: Log warning, continue with others
+- If analysis fails: Report error, continue with next file
+
+**User Notification**:
+- Progress updates every 10% completion
+- Clear error messages with troubleshooting steps
+- Final summary with metrics and file locations
+
+## Integration Standards
+
+### Git Integration
+
+**Pre-commit Hook**:
+```bash
+#!/bin/bash
+ccw run code-reviewer --scope staged --severity critical,high
+exit $?  # Block commit if critical/high issues found
+```
+
+**PR Comments**:
+- Automatic review comments on changed lines
+- Summary comment with overall findings
+- Status check (pass/fail based on threshold)
+
+### CI/CD Integration
+
+**Requirements**:
+- Exit code 0 if no critical/high issues
+- Exit code 1 if blocking issues found
+- JSON output for parsing
+- Configurable severity threshold
+
+### IDE Integration
+
+**LSP Support** (future):
+- Real-time security/quality feedback
+- Inline fix suggestions
+- Quick actions for common fixes
+
+## Compliance Mapping
+
+### Supported Standards
+
+**PCI DSS**:
+- Requirement 6.5: Common coding vulnerabilities
+- Map findings to specific requirements
+
+**HIPAA**:
+- Technical safeguards
+- Map data exposure findings
+
+**GDPR**:
+- Data protection by design
+- Map sensitive data handling
+
+**SOC 2**:
+- Security controls
+- Map access control findings
+
+### Compliance Reports
+
+Generate compliance-specific reports:
+```
+.code-review/compliance/
+├── pci-dss-report.md
+├── hipaa-report.md
+├── gdpr-report.md
+└── soc2-report.md
+```

package/.claude/skills/code-reviewer/specs/security-requirements.md

@@ -0,0 +1,243 @@
+# Security Requirements Specification
+
+## OWASP Top 10 Coverage
+
+### A01:2021 - Broken Access Control
+
+**Checks**:
+- Missing authorization checks on protected routes
+- Insecure direct object references (IDOR)
+- Path traversal vulnerabilities
+- Missing CSRF protection
+- Elevation of privilege
+
+**Patterns**:
+```javascript
+// Missing auth middleware
+router.get('/admin/*', handler);  // ❌ No auth check
+
+// Insecure direct object reference
+router.get('/user/:id', async (req, res) => {
+  const user = await User.findById(req.params.id);  // ❌ No ownership check
+  res.json(user);
+});
+```
+
+### A02:2021 - Cryptographic Failures
+
+**Checks**:
+- Sensitive data transmitted without encryption
+- Weak cryptographic algorithms (MD5, SHA1)
+- Hardcoded secrets/keys
+- Insecure random number generation
+
+**Patterns**:
+```javascript
+// Weak hashing
+const hash = crypto.createHash('md5').update(password);  // ❌ MD5 is weak
+
+// Hardcoded secret
+const token = jwt.sign(payload, 'secret123');  // ❌ Hardcoded secret
+```
+
+### A03:2021 - Injection
+
+**Checks**:
+- SQL injection
+- NoSQL injection
+- Command injection
+- LDAP injection
+- XPath injection
+
+**Patterns**:
+```javascript
+// SQL injection
+const query = `SELECT * FROM users WHERE id = ${userId}`;  // ❌
+
+// Command injection
+exec(`git clone ${userRepo}`);  // ❌
+```
+
+### A04:2021 - Insecure Design
+
+**Checks**:
+- Missing rate limiting
+- Lack of input validation
+- Business logic flaws
+- Missing security requirements
+
+### A05:2021 - Security Misconfiguration
+
+**Checks**:
+- Default credentials
+- Overly permissive CORS
+- Verbose error messages
+- Unnecessary features enabled
+- Missing security headers
+
+**Patterns**:
+```javascript
+// Overly permissive CORS
+app.use(cors({ origin: '*' }));  // ❌
+
+// Verbose error
+res.status(500).json({ error: err.stack });  // ❌
+```
+
+### A06:2021 - Vulnerable and Outdated Components
+
+**Checks**:
+- Dependencies with known vulnerabilities
+- Unmaintained dependencies
+- Using deprecated APIs
+
+### A07:2021 - Identification and Authentication Failures
+
+**Checks**:
+- Weak password requirements
+- Permits brute force attacks
+- Exposed session IDs
+- Weak JWT implementation
+
+**Patterns**:
+```javascript
+// Weak bcrypt rounds
+bcrypt.hash(password, 4);  // ❌ Too low (min: 10)
+
+// Session ID in URL
+res.redirect(`/dashboard?sessionId=${sessionId}`);  // ❌
+```
+
+### A08:2021 - Software and Data Integrity Failures
+
+**Checks**:
+- Insecure deserialization
+- Unsigned/unverified updates
+- CI/CD pipeline vulnerabilities
+
+**Patterns**:
+```javascript
+// Insecure deserialization
+const obj = eval(userInput);  // ❌
+
+// Pickle vulnerability (Python)
+data = pickle.loads(untrusted_data)  # ❌
+```
+
+### A09:2021 - Security Logging and Monitoring Failures
+
+**Checks**:
+- Missing audit logs
+- Sensitive data in logs
+- Insufficient monitoring
+
+**Patterns**:
+```javascript
+// Password in logs
+console.log(`Login attempt: ${username}:${password}`);  // ❌
+```
+
+### A10:2021 - Server-Side Request Forgery (SSRF)
+
+**Checks**:
+- Unvalidated URLs in requests
+- Internal network access
+- Cloud metadata exposure
+
+**Patterns**:
+```javascript
+// SSRF vulnerability
+const response = await fetch(userProvidedUrl);  // ❌
+```
+
+## CWE Top 25 Coverage
+
+### CWE-79: Cross-site Scripting (XSS)
+
+**Patterns**:
+```javascript
+element.innerHTML = userInput;  // ❌
+document.write(userInput);  // ❌
+```
+
+### CWE-89: SQL Injection
+
+**Patterns**:
+```javascript
+query = `SELECT * FROM users WHERE name = '${name}'`;  // ❌
+```
+
+### CWE-20: Improper Input Validation
+
+**Checks**:
+- Missing input sanitization
+- No input length limits
+- Unvalidated file uploads
+
+### CWE-78: OS Command Injection
+
+**Patterns**:
+```javascript
+exec(`ping ${userInput}`);  // ❌
+```
+
+### CWE-190: Integer Overflow
+
+**Checks**:
+- Large number operations without bounds checking
+- Array allocation with user-controlled size
+
+## Language-Specific Security Rules
+
+### TypeScript/JavaScript
+
+- Prototype pollution
+- eval() usage
+- Unsafe regex (ReDoS)
+- require() with dynamic input
+
+### Python
+
+- pickle vulnerabilities
+- yaml.unsafe_load()
+- SQL injection in SQLAlchemy
+- Command injection in subprocess
+
+### Java
+
+- Deserialization vulnerabilities
+- XXE in XML parsers
+- Path traversal
+- SQL injection in JDBC
+
+### Go
+
+- Race conditions
+- SQL injection
+- Path traversal
+- Weak cryptography
+
+## Severity Classification
+
+### Critical
+- Remote code execution
+- SQL injection with write access
+- Authentication bypass
+- Hardcoded credentials in production
+
+### High
+- XSS in sensitive contexts
+- Missing authorization checks
+- Sensitive data exposure
+- Insecure cryptography
+
+### Medium
+- Missing rate limiting
+- Weak password policy
+- Security misconfiguration
+- Information disclosure
+
+### Low
+- Missing security headers
+- Verbose error messages
+- Outdated dependencies (no known exploits)

package/.claude/skills/code-reviewer/templates/best-practice-finding.md

@@ -0,0 +1,234 @@
+# Best Practice Finding Template
+
+Use this template for documenting code quality, performance, and maintainability issues.
+
+## Finding Structure
+
+```json
+{
+  "id": "BP-{number}",
+  "type": "{issue-type}",
+  "category": "{code_quality|performance|maintainability}",
+  "severity": "{high|medium|low}",
+  "file": "{file-path}",
+  "line": {line-number},
+  "function": "{function-name}",
+  "message": "{clear-description}",
+  "recommendation": {
+    "description": "{how-to-fix}",
+    "example": "{corrected-code}"
+  }
+}
+```
+
+## Markdown Template
+
+```markdown
+### 🟠 [BP-{number}] {Issue Title}
+
+**File**: `{file-path}:{line}`
+**Category**: {Code Quality|Performance|Maintainability}
+
+**Issue**: {Detailed explanation of the problem}
+
+**Current Code**:
+\`\`\`{language}
+{problematic-code}
+\`\`\`
+
+**Recommended Fix**:
+\`\`\`{language}
+{improved-code-with-comments}
+\`\`\`
+
+**Impact**: {Why this matters - readability, performance, maintainability}
+
+---
+```
+
+## Example: High Complexity
+
+```markdown
+### 🟠 [BP-001] High Cyclomatic Complexity
+
+**File**: `src/utils/validator.ts:78`
+**Category**: Code Quality
+**Function**: `validateUserInput`
+**Complexity**: 15 (threshold: 10)
+
+**Issue**: Function has 15 decision points, making it difficult to test and maintain.
+
+**Current Code**:
+\`\`\`typescript
+function validateUserInput(input) {
+  if (!input) return false;
+  if (!input.email) return false;
+  if (!input.email.includes('@')) return false;
+  if (input.email.length > 255) return false;
+  // ... 11 more conditions
+}
+\`\`\`
+
+**Recommended Fix**:
+\`\`\`typescript
+// Extract validation rules
+const validationRules = {
+  email: (email) => email && email.includes('@') && email.length <= 255,
+  password: (pwd) => pwd && pwd.length >= 8 && /[A-Z]/.test(pwd),
+  username: (name) => name && /^[a-zA-Z0-9_]+$/.test(name),
+};
+
+// Simplified validator
+function validateUserInput(input) {
+  return Object.entries(validationRules).every(([field, validate]) =>
+    validate(input[field])
+  );
+}
+\`\`\`
+
+**Impact**: Reduces complexity from 15 to 3, improves testability, and makes validation rules reusable.
+
+---
+```
+
+## Example: N+1 Query
+
+```markdown
+### 🟠 [BP-002] N+1 Query Pattern
+
+**File**: `src/api/orders.ts:45`
+**Category**: Performance
+
+**Issue**: Database query executed inside loop, causing N+1 queries problem. For 100 orders, this creates 101 database queries instead of 2.
+
+**Current Code**:
+\`\`\`typescript
+const orders = await Order.findAll();
+for (const order of orders) {
+  const user = await User.findById(order.userId);
+  order.userName = user.name;
+}
+\`\`\`
+
+**Recommended Fix**:
+\`\`\`typescript
+// Batch query all users at once
+const orders = await Order.findAll();
+const userIds = orders.map(o => o.userId);
+const users = await User.findByIds(userIds);
+
+// Create lookup map for O(1) access
+const userMap = new Map(users.map(u => [u.id, u]));
+
+// Enrich orders with user data
+for (const order of orders) {
+  order.userName = userMap.get(order.userId)?.name;
+}
+\`\`\`
+
+**Impact**: Reduces database queries from O(n) to O(1), significantly improving performance for large datasets.
+
+---
+```
+
+## Example: Missing Documentation
+
+```markdown
+### 🟡 [BP-003] Missing Documentation
+
+**File**: `src/services/PaymentService.ts:23`
+**Category**: Maintainability
+
+**Issue**: Exported class lacks documentation, making it difficult for other developers to understand its purpose and usage.
+
+**Current Code**:
+\`\`\`typescript
+export class PaymentService {
+  async processPayment(orderId: string, amount: number) {
+    // implementation
+  }
+}
+\`\`\`
+
+**Recommended Fix**:
+\`\`\`typescript
+/**
+ * Service for processing payment transactions
+ * 
+ * Handles payment processing, refunds, and transaction logging.
+ * Integrates with Stripe payment gateway.
+ * 
+ * @example
+ * const paymentService = new PaymentService();
+ * const result = await paymentService.processPayment('order-123', 99.99);
+ */
+export class PaymentService {
+  /**
+   * Process a payment for an order
+   * 
+   * @param orderId - Unique order identifier
+   * @param amount - Payment amount in USD
+   * @returns Payment confirmation with transaction ID
+   * @throws {PaymentError} If payment processing fails
+   */
+  async processPayment(orderId: string, amount: number) {
+    // implementation
+  }
+}
+\`\`\`
+
+**Impact**: Improves code discoverability and reduces onboarding time for new developers.
+
+---
+```
+
+## Example: Memory Leak
+
+```markdown
+### 🟠 [BP-004] Potential Memory Leak
+
+**File**: `src/components/Chat.tsx:56`
+**Category**: Performance
+
+**Issue**: WebSocket event listener added without cleanup, causing memory leaks when component unmounts.
+
+**Current Code**:
+\`\`\`tsx
+useEffect(() => {
+  socket.on('message', handleMessage);
+}, []);
+\`\`\`
+
+**Recommended Fix**:
+\`\`\`tsx
+useEffect(() => {
+  socket.on('message', handleMessage);
+  
+  // Cleanup on unmount
+  return () => {
+    socket.off('message', handleMessage);
+  };
+}, []);
+\`\`\`
+
+**Impact**: Prevents memory leaks and improves application stability in long-running sessions.
+
+---
+```
+
+## Severity Guidelines
+
+### High
+- Major performance impact (N+1 queries, O(n²) algorithms)
+- Critical maintainability issues (complexity > 15)
+- Missing error handling in critical paths
+
+### Medium
+- Moderate performance impact
+- Code quality issues (complexity 11-15, duplication)
+- Missing tests for important features
+
+### Low
+- Minor style violations
+- Missing documentation
+- Low-impact dead code