@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/refactoring-specialist/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: refactoring-specialist
+description: Code refactoring expert for improving code structure, readability, and maintainability. Use when user asks to refactor, clean up, or improve code quality.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Refactoring Specialist
+
+Expert guidance on refactoring code to improve structure, readability, and maintainability while preserving functionality.
+
+## When This Skill Activates
+
+Activates when you:
+- Ask to refactor code
+- Request cleanup or improvement
+- Mention "technical debt" or "code smell"
+- Want to improve code quality
+
+## Refactoring Principles
+
+1. **Preserve Behavior**: Refactoring must not change external behavior
+2. **Small Steps**: Make small, incremental changes
+3. **Test Coverage**: Ensure tests pass before and after
+4. **Commit Often**: Commit after each successful refactoring
+
+## Code Smells to Address
+
+### 1. Long Method
+**Symptom:** Function > 20-30 lines
+
+**Refactoring:** Extract Method
+```typescript
+// Before:
+function processOrder(order) {
+  // 50 lines of code
+}
+
+// After:
+function processOrder(order) {
+  validateOrder(order);
+  calculateTotals(order);
+  saveOrder(order);
+  sendConfirmation(order);
+}
+```
+
+### 2. Duplicate Code
+**Symptom:** Similar code in multiple places
+
+**Refactoring:** Extract Method / Template Method
+```typescript
+// Before:
+class UserService {
+  async validateEmail(email) {
+    if (!email || !email.includes('@')) return false;
+    const domain = email.split('@')[1];
+    return domain.length > 0;
+  }
+}
+class AdminService {
+  async validateEmail(email) {
+    if (!email || !email.includes('@')) return false;
+    const domain = email.split('@')[1];
+    return domain.length > 0;
+  }
+}
+
+// After:
+class EmailValidator {
+  async validate(email) {
+    if (!email || !email.includes('@')) return false;
+    return email.split('@')[1].length > 0;
+  }
+}
+```
+
+### 3. Large Class
+**Symptom:** Class doing too many things
+
+**Refactoring:** Extract Class
+```typescript
+// Before:
+class User {
+  // Authentication
+  // Profile management
+  // Notifications
+  // Reporting
+}
+
+// After:
+class User { /* Core user data */ }
+class UserAuth { /* Authentication */ }
+class UserProfile { /* Profile management */ }
+class UserNotifier { /* Notifications */ }
+```
+
+### 4. Long Parameter List
+**Symptom:** Function with 4+ parameters
+
+**Refactoring:** Introduce Parameter Object
+```typescript
+// Before:
+function createUser(name, email, age, address, phone, role) { ... }
+
+// After:
+function createUser(user: UserData) { ... }
+
+interface UserData {
+  name: string;
+  email: string;
+  age: number;
+  address: string;
+  phone: string;
+  role: string;
+}
+```
+
+### 5. Feature Envy
+**Symptom:** Method uses more data from other classes
+
+**Refactoring:** Move Method
+```typescript
+// Before:
+class Order {
+  calculatePrice(customer) {
+    const discount = customer.getDiscountLevel();
+    // ...
+  }
+}
+
+// After:
+class Customer {
+  calculatePriceForOrder(order) {
+    const discount = this.discountLevel;
+    // ...
+  }
+}
+```
+
+### 6. Data Clumps
+**Symptom**: Same data appearing together
+
+**Refactoring**: Extract Value Object
+```typescript
+// Before:
+function drawShape(x, y, width, height) { ... }
+function moveShape(x, y, width, height, dx, dy) { ... }
+
+// After:
+class Rectangle {
+  constructor(x, y, width, height) { ... }
+}
+function drawShape(rect: Rectangle) { ... }
+```
+
+### 7. Primitive Obsession
+**Symptom**: Using primitives instead of small objects
+
+**Refactoring**: Replace Primitive with Object
+```typescript
+// Before:
+function createUser(name, email, phone) { ... }
+
+// After:
+class Email {
+  constructor(value) {
+    if (!this.isValid(value)) throw new Error('Invalid email');
+    this.value = value;
+  }
+  // ...
+}
+```
+
+### 8. Switch Statements
+**Symptom**: Large switch on type
+
+**Refactoring**: Replace Conditional with Polymorphism
+```typescript
+// Before:
+function calculatePay(employee) {
+  switch (employee.type) {
+    case 'engineer': return employee.salary * 1.2;
+    case 'manager': return employee.salary * 1.5;
+    case 'sales': return employee.salary * 1.1;
+  }
+}
+
+// After:
+interface Employee {
+  calculatePay(): number;
+}
+class Engineer implements Employee {
+  calculatePay() { return this.salary * 1.2; }
+}
+```
+
+### 9. Temporary Field
+**Symptom**: Variables only used in certain scenarios
+
+**Refactoring**: Extract Class
+```typescript
+// Before:
+class User {
+  calculateRefund() {
+    this.tempRefundAmount = 0;
+    // complex calculation
+    return this.tempRefundAmount;
+  }
+}
+
+// After:
+class RefundCalculator {
+  calculate(user) {
+    // ...
+  }
+}
+```
+
+### 10. Comments
+**Symptom**: Code needs extensive comments
+
+**Refactoring**: Extract Method with clear name
+```typescript
+// Before:
+// Calculate the total price including discounts
+// and tax based on user location
+function calc(u, i) {
+  let t = 0;
+  // discount logic
+  if (u.vip) t *= 0.9;
+  // tax logic
+  if (u.state === 'CA') t *= 1.08;
+  return t;
+}
+
+// After:
+function calculateTotalPrice(user: User, items: Item[]): number {
+  let total = items.sum(i => i.price);
+  if (user.isVIP) {
+    total = applyVIPDiscount(total);
+  }
+  return applyTax(total, user.state);
+}
+```
+
+## Refactoring Steps
+
+1. **Identify the smell** - What makes this code hard to work with?
+2. **Determine the refactoring** - Which technique applies?
+3. **Ensure tests pass** - Green before starting
+4. **Apply the refactoring** - Make the change
+5. **Run tests** - Verify behavior unchanged
+6. **Commit** - Small, atomic commits
+
+## Safe Refactoring Practices
+
+- Use your IDE's refactoring tools (Rename, Extract, Move)
+- Run tests frequently (after each change)
+- Keep commits small and focused
+- Write a descriptive commit message
+- Consider code reviews for complex refactorings
+
+## Before Refactoring
+
+- [ ] Tests are passing
+- [ ] I understand what the code does
+- [ ] I have identified the specific code smell
+- [ ] I know which refactoring to apply
+- [ ] I have a rollback plan
+
+## After Refactoring
+
+- [ ] Tests still pass
+- [ ] Code is more readable
+- [ ] Code is easier to maintain
+- [ ] No new code smells introduced
+- [ ] Documentation updated if needed
+
+## References
+
+- `references/smells.md` - Complete code smell catalog
+- `references/techniques.md` - Refactoring techniques
+- `references/checklist.md` - Refactoring checklist

package/skills/refactoring-specialist/references/checklist.md

@@ -0,0 +1,6 @@
+# Refactoring Checklist
+
+- [ ] Behavior preserved
+- [ ] Tests pass
+- [ ] Complexity reduced
+- [ ] Naming improved

package/skills/refactoring-specialist/references/smells.md

@@ -0,0 +1,6 @@
+# Code Smells
+
+- Long methods
+- Large classes
+- Duplicate logic
+- Feature envy

package/skills/refactoring-specialist/references/techniques.md

@@ -0,0 +1,6 @@
+# Refactoring Techniques
+
+- Extract function
+- Extract class
+- Inline variable
+- Replace conditional with polymorphism

package/skills/security-auditor/README.md

@@ -0,0 +1,48 @@
+# Security Auditor
+
+> A Claude Code skill for security audits and vulnerability assessment.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Audit this code for security issues
+You: Check for vulnerabilities
+You: Is this code secure?
+```
+
+## OWASP Top 10 Coverage
+
+| Category | Checks |
+|----------|--------|
+| **A01** | Access Control |
+| **A02** | Cryptographic Failures |
+| **A03** | Injection |
+| **A04** | Insecure Design |
+| **A05** | Security Misconfiguration |
+| **A06** | Vulnerable Components |
+| **A07** | Authentication Failures |
+| **A08** | Data Integrity |
+| **A09** | Logging Failures |
+| **A10** | SSRF |
+
+## Scripts
+
+Run security audit:
+```bash
+python scripts/security_audit.py
+```
+
+Find secrets:
+```bash
+python scripts/find_secrets.py
+```
+
+## Resources
+
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)
+- [CWE Top 25](https://cwe.mitre.org/top25/)

package/skills/security-auditor/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: security-auditor
+description: Security vulnerability expert covering OWASP Top 10 and common security issues. Use when conducting security audits or reviewing code for vulnerabilities.
+allowed-tools: Read, Grep, Glob, Bash, WebSearch
+---
+
+# Security Auditor
+
+Expert in identifying security vulnerabilities following OWASP Top 10 and security best practices.
+
+## When This Skill Activates
+
+Activates when you:
+- Request a security audit
+- Mention "security" or "vulnerability"
+- Need security review
+- Ask about OWASP
+
+## OWASP Top 10 Coverage
+
+### A01: Broken Access Control
+
+**Checks:**
+```bash
+# Check for missing auth on protected routes
+grep -r "@RequireAuth\|@Protected" src/
+
+# Check for IDOR vulnerabilities
+grep -r "req.params.id\|req.query.id" src/
+
+# Check for role-based access
+grep -r "if.*role.*===" src/
+```
+
+**Common Issues:**
+- Missing authentication on sensitive endpoints
+- IDOR: Users can access other users' data
+- Missing authorization checks
+- API keys in URL
+
+### A02: Cryptographic Failures
+
+**Checks:**
+```bash
+# Check for hardcoded secrets
+grep -ri "password.*=.*['\"]" src/
+grep -ri "api_key.*=.*['\"]" src/
+grep -ri "secret.*=.*['\"]" src/
+
+# Check for weak hashing
+grep -r "md5\|sha1" src/
+
+# Check for http URLs
+grep -r "http:\/\/" src/
+```
+
+**Common Issues:**
+- Hardcoded credentials
+- Weak hashing algorithms (MD5, SHA1)
+- Unencrypted sensitive data
+- HTTP instead of HTTPS
+
+### A03: Injection
+
+**Checks:**
+```bash
+# SQL injection patterns
+grep -r "\".*SELECT.*+.*\"" src/
+grep -r "\".*UPDATE.*SET.*+.*\"" src/
+
+# Command injection
+grep -r "exec(\|system(\|spawn(" src/
+grep -r "child_process.exec" src/
+
+# Template injection
+grep -r "render.*req\." src/
+```
+
+**Common Issues:**
+- SQL injection
+- NoSQL injection
+- Command injection
+- XSS (Cross-Site Scripting)
+- Template injection
+
+### A04: Insecure Design
+
+**Checks:**
+```bash
+# Check for rate limiting
+grep -r "rateLimit\|rate-limit\|throttle" src/
+
+# Check for 2FA
+grep -r "twoFactor\|2fa\|mfa" src/
+
+# Check for session timeout
+grep -r "maxAge\|expires\|timeout" src/
+```
+
+**Common Issues:**
+- No rate limiting on auth endpoints
+- Missing 2FA for sensitive operations
+- Session timeout too long
+- No account lockout after failed attempts
+
+### A05: Security Misconfiguration
+
+**Checks:**
+```bash
+# Check for debug mode
+grep -r "DEBUG.*=.*True\|debug.*=.*true" src/
+
+# Check for CORS configuration
+grep -r "origin.*\*" src/
+
+# Check for error messages
+grep -r "console\.log.*error\|console\.error" src/
+```
+
+**Common Issues:**
+- Debug mode enabled in production
+- Overly permissive CORS
+- Verbose error messages
+- Default credentials not changed
+
+### A06: Vulnerable Components
+
+**Checks:**
+```bash
+# Check package files
+cat package.json | grep -E "\"dependencies\"|\"devDependencies\""
+cat requirements.txt
+cat go.mod
+
+# Run vulnerability scanner
+npm audit
+pip-audit
+```
+
+**Common Issues:**
+- Outdated dependencies
+- Known vulnerabilities in dependencies
+- Unused dependencies
+- Unmaintained packages
+
+### A07: Authentication Failures
+
+**Checks:**
+```bash
+# Check password hashing
+grep -r "bcrypt\|argon2\|scrypt" src/
+
+# Check password requirements
+grep -r "password.*length\|password.*complex" src/
+
+# Check for password in URL
+grep -r "password.*req\." src/
+```
+
+**Common Issues:**
+- Weak password hashing
+- No password complexity requirements
+- Password in URL
+- Session fixation
+
+### A08: Software/Data Integrity
+
+**Checks:**
+```bash
+# Check for subresource integrity
+grep -r "integrity\|crossorigin" src/
+
+# Check for signature verification
+grep -r "verify.*signature\|validate.*token" src/
+```
+
+**Common Issues:**
+- No integrity checks
+- Unsigned updates
+- Unverified dependencies
+
+### A09: Logging Failures
+
+**Checks:**
+```bash
+# Check for sensitive data in logs
+grep -r "log.*password\|log.*token\|log.*secret" src/
+
+# Check for audit trail
+grep -r "audit\|activity.*log" src/
+```
+
+**Common Issues:**
+- Sensitive data in logs
+- No audit trail for critical operations
+- Logs not protected
+- No log tampering detection
+
+### A10: SSRF (Server-Side Request Forgery)
+
+**Checks:**
+```bash
+# Check for arbitrary URL fetching
+grep -r "fetch(\|axios(\|request(\|http\\.get" src/
+
+# Check for webhook URLs
+grep -r "webhook.*url\|callback.*url" src/
+```
+
+**Common Issues:**
+- No URL validation
+- Fetching user-supplied URLs
+- No allowlist for external calls
+
+## Security Audit Checklist
+
+### Code Review
+- [ ] No hardcoded secrets
+- [ ] Input validation on all inputs
+- [ ] Output encoding for XSS prevention
+- [ ] Parameterized queries for SQL
+- [ ] Proper error handling
+- [ ] Authentication on protected routes
+- [ ] Authorization checks
+- [ ] Rate limiting on public APIs
+
+### Configuration
+- [ ] Debug mode off
+- [ ) HTTPS enforced
+- [ ] CORS configured correctly
+- [ ] Security headers set
+- [ ] Environment variables for secrets
+- [ ] Database not exposed
+
+### Dependencies
+- [ ] No known vulnerabilities
+- [ ] Dependencies up to date
+- [ ] Unused dependencies removed
+
+## Scripts
+
+Run security audit:
+```bash
+python scripts/security_audit.py
+```
+
+Check for secrets:
+```bash
+python scripts/find_secrets.py
+```
+
+## References
+
+- `references/owasp.md` - OWASP Top 10 details
+- `references/checklist.md` - Security audit checklist
+- `references/remediation.md` - Vulnerability remediation guide

package/skills/security-auditor/references/checklist.md

@@ -0,0 +1,7 @@
+# Security Review Checklist
+
+- [ ] Input validation
+- [ ] Auth and authz checks
+- [ ] Secrets management
+- [ ] Dependency vulnerability scan
+- [ ] Logging and monitoring

package/skills/security-auditor/references/owasp.md

@@ -0,0 +1,12 @@
+# OWASP Top 10 (2021)
+
+1. Broken Access Control
+2. Cryptographic Failures
+3. Injection
+4. Insecure Design
+5. Security Misconfiguration
+6. Vulnerable and Outdated Components
+7. Identification and Authentication Failures
+8. Software and Data Integrity Failures
+9. Security Logging and Monitoring Failures
+10. Server-Side Request Forgery

package/skills/security-auditor/references/remediation.md

@@ -0,0 +1,7 @@
+# Remediation Notes
+
+## Steps
+1. Reproduce the issue
+2. Identify impacted components
+3. Patch and add tests
+4. Document the change

package/skills/security-auditor/scripts/find_secrets.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+# Lightweight secret scanner for common patterns.
+
+from pathlib import Path
+import argparse
+import re
+
+PATTERNS = [
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    re.compile(r"AIza[0-9A-Za-z_-]{35}"),
+    re.compile(r"sk-[0-9A-Za-z]{20,}"),
+]
+
+
+def is_text_file(path: Path) -> bool:
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return False
+    return b"\x00" not in data
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Scan for common secret patterns.")
+    parser.add_argument("path", nargs="?", default=".", help="Path to scan")
+    args = parser.parse_args()
+
+    root = Path(args.path)
+    if not root.exists():
+        print("Path not found: " + str(root))
+        return 1
+
+    matches = []
+    for file_path in root.rglob("*"):
+        if not file_path.is_file():
+            continue
+        if file_path.suffix in {".png", ".jpg", ".jpeg", ".gif", ".pdf"}:
+            continue
+        if not is_text_file(file_path):
+            continue
+        text = file_path.read_text(encoding="utf-8", errors="ignore")
+        for pattern in PATTERNS:
+            if pattern.search(text):
+                matches.append(str(file_path))
+                break
+
+    if matches:
+        print("Potential secrets found:")
+        for match in matches:
+            print("- " + match)
+        return 1
+
+    print("No secrets found.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())