@codeharbor/agent-playbook 0.1.0 → 0.1.1

package/skills/code-reviewer/references/patterns.md

@@ -0,0 +1,226 @@
+# Common Patterns and Anti-Patterns
+
+## Patterns to Encourage
+
+### Error Handling
+
+**Good:**
+```typescript
+async function getUser(id: string) {
+  const user = await db.users.findById(id);
+  if (!user) {
+    throw new NotFoundError(`User ${id} not found`);
+  }
+  return user;
+}
+```
+
+**Bad:**
+```typescript
+async function getUser(id: string) {
+  return await db.users.findById(id); // Returns null, not handled
+}
+```
+
+### Async/Await
+
+**Good:**
+```typescript
+const result = await fetch(url);
+const data = await result.json();
+```
+
+**Bad:**
+```typescript
+fetch(url).then(r => r.json()).then(data => {
+  // Nested callbacks
+});
+```
+
+### Early Returns
+
+**Good:**
+```typescript
+function process(user) {
+  if (!user) return null;
+  if (!user.active) return null;
+  return user.data;
+}
+```
+
+**Bad:**
+```typescript
+function process(user) {
+  if (user) {
+    if (user.active) {
+      return user.data;
+    }
+  }
+  return null;
+}
+```
+
+### Destructuring
+
+**Good:**
+```typescript
+const { name, email } = user;
+```
+
+**Bad:**
+```typescript
+const name = user.name;
+const email = user.email;
+```
+
+## Anti-Patterns to Catch
+
+### Magic Numbers
+
+**Bad:**
+```typescript
+if (user.role === 5) { ... }
+```
+
+**Good:**
+```typescript
+const Role = { ADMIN: 5, USER: 1 };
+if (user.role === Role.ADMIN) { ... }
+```
+
+### Neglected Promise Rejection
+
+**Bad:**
+```typescript
+fetch(url).then(data => processData(data));
+```
+
+**Good:**
+```typescript
+fetch(url)
+  .then(data => processData(data))
+  .catch(error => logError(error));
+```
+
+### Any Type
+
+**Bad:**
+```typescript
+function parse(data: any) { ... }
+```
+
+**Good:**
+```typescript
+function parse(data: unknown): Result { ... }
+```
+
+### Deep Nesting
+
+**Bad:**
+```typescript
+if (a) {
+  if (b) {
+    if (c) {
+      doSomething();
+    }
+  }
+}
+```
+
+**Good:**
+```typescript
+if (!a) return;
+if (!b) return;
+if (!c) return;
+doSomething();
+```
+
+### Large Functions
+
+**Bad:** Functions > 50 lines
+
+**Good:** Split into smaller, focused functions
+
+### God Objects
+
+**Bad:** Classes/methods that do everything
+
+**Good:** Single Responsibility Principle
+
+### Shotgun Surgery
+
+**Bad:** Adding a feature requires changing many files
+
+**Good:** Good separation of concerns
+
+## React Specific
+
+### Hooks Dependencies
+
+**Bad:**
+```typescript
+useEffect(() => {
+  fetchData(userId);
+}, []); // Missing userId dependency
+```
+
+**Good:**
+```typescript
+useEffect(() => {
+  fetchData(userId);
+}, [userId]);
+```
+
+### State Updates
+
+**Bad:**
+```typescript
+setCount(count + 1);
+setCount(count + 1);
+```
+
+**Good:**
+```typescript
+setCount(c => c + 2);
+```
+
+### Key Props
+
+**Bad:**
+```typescript
+items.map((item, i) => <Item key={i} />)
+```
+
+**Good:**
+```typescript
+items.map(item => <Item key={item.id} />)
+```
+
+## Backend Specific
+
+### N+1 Query
+
+**Bad:**
+```python
+for user in users:
+  posts = db.query("SELECT * FROM posts WHERE user_id = ?", user.id)
+```
+
+**Good:**
+```python
+user_ids = [u.id for u in users]
+posts = db.query("SELECT * FROM posts WHERE user_id IN ?", user_ids)
+```
+
+### Transaction Handling
+
+**Bad:**
+```python
+db.transfer(a, b, amount)  # No transaction
+```
+
+**Good:**
+```python
+with db.transaction():
+  db.transfer(a, b, amount)
+```

package/skills/code-reviewer/references/security.md

@@ -0,0 +1,88 @@
+# Security Review Guidelines
+
+## OWASP Top 10 Coverage
+
+### A01:2021 – Broken Access Control
+- [ ] Users can only access their own data
+- [ ] API endpoints have proper authentication
+- [ ] Admin actions require admin role
+- [ ] No IDOR (Insecure Direct Object References)
+- [ ] Proper authorization checks on all endpoints
+
+### A02:2021 – Cryptographic Failures
+- [ ] Passwords are hashed (bcrypt/argon2)
+- [ ] HTTPS is enforced
+- [ ] Sensitive data is encrypted at rest
+- [ ] No weak cipher suites
+- [ ] Proper key management
+
+### A03:2021 – Injection
+- [ ] Parameterized queries for SQL
+- [ ] Input validation and sanitization
+- [ ] ORM used safely
+- [ ] No command injection from user input
+- [ ] No LDAP injection
+
+### A04:2021 – Insecure Design
+- [ ] Rate limiting on auth endpoints
+- [ ] Proper logout functionality
+- [ ] Session timeout is reasonable
+- [ ] No security through obscurity
+
+### A05:2021 – Security Misconfiguration
+- [ ] Debug mode off in production
+- [ ] Error messages don't leak information
+- [ ] Default credentials changed
+- [ ] Security headers configured
+- [ ] CORS configured correctly
+
+### A06:2021 – Vulnerable Components
+- [ ] Dependencies up to date
+- [ ] No known vulnerabilities in deps
+- [ ] Unused dependencies removed
+
+### A07:2021 – Auth Failures
+- [ ] Strong password policy
+- [ ] No brute force protection needed (rate limiting)
+- [ ] MFA implemented for sensitive operations
+- [ ] Session IDs are random
+
+### A08:2021 – Software/Data Integrity
+- [ ] Dependencies from trusted sources
+- [ ] CI/CD has integrity checks
+- [ ] Verify data integrity
+
+### A09:2021 – Logging Failures
+- [ ] Security events logged
+- [ ] Logs don't contain sensitive data
+- [ ] Log tampering protection
+- [ ] Audit trail for critical operations
+
+### A10:2021 – SSRF
+- [ ] No arbitrary URL fetching from user input
+- [ ] Allowlist for external calls
+- [ ] Network segmentation
+
+## Frontend Security
+
+- [ ] XSS prevention
+- [ ] CSRF tokens
+- [ ] Content Security Policy
+- [ ] Subresource Integrity
+- [ ] No `dangerouslySetInnerHTML` with user content
+
+## Backend Security
+
+- [ ] Input validation on all endpoints
+- [ ] Output encoding
+- [ ] Prepared statements
+- [ ] Principle of least privilege
+- [ ] Secure file upload handling
+
+## Infrastructure Security
+
+- [ ] Secrets in environment variables
+- [ ] No secrets in code
+- [ ] Proper RBAC
+- [ ] Network security rules
+- [ ] Regular security updates

package/skills/code-reviewer/scripts/review_checklist.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+Code Review Checklist Generator
+Generates a structured review checklist for a given PR or diff.
+"""
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def get_changed_files(base_branch: str = "main") -> list[str]:
+    """Get list of changed files."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", f"{base_branch}...HEAD", "--name-only"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return [f.strip() for f in result.stdout.strip().split('\n') if f.strip()]
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_commit_messages(base_branch: str = "main") -> list[str]:
+    """Get commit messages in the PR."""
+    try:
+        result = subprocess.run(
+            ["git", "log", f"{base_branch}...HEAD", "--oneline"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return [line.strip() for line in result.stdout.strip().split('\n') if line.strip()]
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_diff(base_branch: str = "main") -> str:
+    """Get the full diff."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", f"{base_branch}...HEAD"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout
+    except subprocess.CalledProcessError:
+        return ""
+
+
+def categorize_file(filename: str) -> str:
+    """Categorize file by extension for targeted checks."""
+    ext = Path(filename).suffix.lower()
+    if ext in {'.ts', '.tsx', '.js', '.jsx'}:
+        return 'javascript'
+    if ext in {'.py'}:
+        return 'python'
+    if ext in {'.go'}:
+        return 'go'
+    if ext in {'.rs'}:
+        return 'rust'
+    if ext in {'.java', '.kt'}:
+        return 'jvm'
+    if ext in {'.sql'}:
+        return 'sql'
+    if ext in {'.yml', '.yaml'}:
+        return 'yaml'
+    if ext in {'.md', '.rst'}:
+        return 'docs'
+    return 'general'
+
+
+def generate_review_checklist(base_branch: str = "main") -> str:
+    """Generate a structured review checklist."""
+    files = get_changed_files(base_branch)
+    commits = get_commit_messages(base_branch)
+    diff = get_diff(base_branch)
+
+    if not files:
+        return "# No changes found\n\nNo files changed compared to " + base_branch
+
+    lines = ["# Code Review Checklist\n"]
+
+    # Overview
+    lines.append("## Overview\n")
+    lines.append(f"- **Branch**: {base_branch} → HEAD")
+    lines.append(f"- **Files changed**: {len(files)}")
+    lines.append(f"- **Commits**: {len(commits)}\n")
+
+    # Commits
+    lines.append("### Commits\n")
+    for commit in commits:
+        lines.append(f"- {commit}")
+    lines.append("")
+
+    # Files by category
+    categories = {}
+    for f in files:
+        cat = categorize_file(f)
+        categories.setdefault(cat, []).append(f)
+
+    lines.append("## Files to Review\n")
+    for cat, cat_files in categories.items():
+        lines.append(f"\n### {cat.title()}\n")
+        for f in cat_files:
+            lines.append(f"- [{f}]")
+
+    # Diff snippet (first 100 lines)
+    lines.append("\n## Diff Preview\n")
+    lines.append("```diff")
+    for line in diff.split('\n')[:100]:
+        lines.append(line)
+    if len(diff.split('\n')) > 100:
+        lines.append("\n... (diff truncated)")
+    lines.append("```\n")
+
+    # Review sections
+    lines.append("## Review Sections\n")
+
+    # Security check
+    lines.append("### 🔒 Security\n")
+    if any('secret' in f.lower() or 'config' in f.lower() or 'env' in f.lower() for f in files):
+        lines.append("- [ ] **Secrets check**: No hardcoded credentials in config/env files\n")
+    lines.append("- [ ] **Input validation**: User input is validated and sanitized\n")
+    lines.append("- [ ] **Injection**: No SQL/command injection vulnerabilities\n")
+    lines.append("- [ ] **Auth**: Proper authentication/authorization on new endpoints\n")
+
+    # Code quality
+    lines.append("\n### 📝 Code Quality\n")
+    lines.append("- [ ] **Readability**: Code is clear and understandable\n")
+    lines.append("- [ ] **Naming**: Variables/functions are well named\n")
+    lines.append("- [ ] **DRY**: No duplicate code\n")
+    lines.append("- [ ] **Comments**: Complex logic is explained\n")
+
+    # Testing
+    test_files = [f for f in files if 'test' in f.lower() or 'spec' in f.lower()]
+    if test_files:
+        lines.append(f"\n### 🧪 Testing ({len(test_files)} test files)\n")
+    else:
+        lines.append("\n### 🧪 Testing\n")
+        lines.append("- [ ] **Tests added**: New functionality has tests\n")
+    lines.append("- [ ] **Coverage**: Test coverage not decreased\n")
+    lines.append("- [ ] **Edge cases**: Edge cases are tested\n")
+
+    # Performance
+    lines.append("\n### ⚡ Performance\n")
+    lines.append("- [ ] **N+1 queries**: No database queries in loops\n")
+    lines.append("- [ ] **Caching**: Appropriate caching where needed\n")
+    lines.append("- [ ] **Efficiency**: Efficient algorithms/data structures\n")
+
+    # Documentation
+    lines.append("\n### 📚 Documentation\n")
+    lines.append("- [ ] **API docs**: Public APIs are documented\n")
+    lines.append("- [ ] **README**: README updated if needed\n")
+    lines.append("- [ ] **Comments**: Complex logic has comments\n")
+
+    # Breaking changes
+    lines.append("\n### ⚠️ Breaking Changes\n")
+    lines.append("- [ ] **Documented**: Breaking changes are documented\n")
+    lines.append("- [ ] **Migration**: Migration guide provided if needed\n")
+
+    # Approval
+    lines.append("\n## Approval\n")
+    lines.append("- [ ] **Critical issues**: None\n")
+    lines.append("- [ ] **Tests pass**: All tests pass locally\n")
+    lines.append("- [ ] **Ready to merge**: No blocking issues\n")
+
+    return '\n'.join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate code review checklist")
+    parser.add_argument("--base", default="main", help="Base branch to compare against")
+    parser.add_argument("--output", "-o", help="Output file (default: stdout)")
+    args = parser.parse_args()
+
+    checklist = generate_review_checklist(args.base)
+
+    if args.output:
+        Path(args.output).write_text(checklist)
+        print(f"Checklist written to {args.output}")
+    else:
+        print(checklist)
+
+
+if __name__ == "__main__":
+    main()

package/skills/commit-helper/README.md

@@ -0,0 +1,58 @@
+# Commit Helper
+
+> A Claude Code skill for writing Git commit messages following the Conventional Commits specification.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+When working with Git, simply ask Claude to commit your changes:
+
+```
+You: commit my changes
+```
+
+The skill will automatically:
+1. Review your changes with `git diff`
+2. Generate a properly formatted commit message
+3. Present it for your approval
+4. Execute the commit when confirmed
+
+## Examples
+
+### Simple Feature
+```
+You: Commit the new user authentication feature
+
+Claude generates:
+feat(auth): add OAuth2 login support
+
+Implement OAuth2 authentication flow for Google and GitHub.
+Users can now link multiple social accounts to their profile.
+```
+
+### Bug Fix
+```
+You: Commit the API timeout fix
+
+Claude generates:
+fix(api): resolve timeout in user endpoint
+
+Added 30-second timeout to database query to prevent slow queries
+from causing request timeouts.
+```
+
+## Validation
+
+The skill includes a validation script to check commit message format:
+
+```bash
+python scripts/validate_commit.py "feat(api): add user endpoint"
+```
+
+## References
+
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [Angular Commit Guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit)

package/skills/commit-helper/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: commit-helper
+description: Helps write Git commit messages following the Conventional Commits specification. Use this skill when the user asks to commit changes, write commit messages, format commits, or mentions git commits.
+allowed-tools: Read, Write, Edit, Bash, Grep
+---
+
+# Commit Message Helper
+
+A skill for creating properly formatted Git commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+## When This Skill Activates
+
+This skill activates when you:
+- Ask to commit changes
+- Mention commit messages
+- Request git commit formatting
+- Say "commit" or "git commit"
+
+## Commit Message Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | A new feature |
+| `fix` | A bug fix |
+| `docs` | Documentation only changes |
+| `style` | Changes that do not affect the meaning of the code (formatting, etc.) |
+| `refactor` | A code change that neither fixes a bug nor adds a feature |
+| `perf` | A code change that improves performance |
+| `test` | Adding missing tests or correcting existing tests |
+| `chore` | Changes to the build process or auxiliary tools |
+| `ci` | Changes to CI configuration files and scripts |
+| `build` | Changes that affect the build system or external dependencies |
+
+## Scope
+
+The scope should indicate the area of the codebase affected:
+- For frontend: `components`, `hooks`, `store`, `styles`, `utils`
+- For backend: `api`, `models`, `services`, `database`, `auth`
+- For devops: `ci`, `deploy`, `docker`
+- Project-specific scopes are also acceptable
+
+## Guidelines
+
+### Subject Line
+- Use imperative mood ("add feature" not "added feature" or "adds feature")
+- No period at the end
+- Maximum 50 characters
+- Be specific and concise
+
+### Body
+- Separate subject from body with a blank line
+- Use the body to explain **what** and **why**, not **how**
+- Wrap at 72 characters per line
+- Mention any breaking changes
+
+### Footer
+- Reference issues: `Closes #123`, `Fixes #456`, `Refs #789`
+- Multiple issues: `Closes #123, #456, #789`
+- Breaking changes: Start with `BREAKING CHANGE:` followed by description
+
+## Examples
+
+### Good Examples
+
+```
+feat(auth): add OAuth2 login support
+
+Implement OAuth2 authentication flow to allow users to log in
+with their Google or GitHub accounts.
+
+This change adds:
+- New OAuth2 middleware for handling callbacks
+- Updated login UI with social login buttons
+- User profile synchronization
+
+Closes #123
+```
+
+```
+fix(api): resolve race condition in user creation
+
+The concurrent user creation requests could result in duplicate
+email entries. Added unique constraint and proper error handling.
+
+Fixes #456
+```
+
+```
+refactor(user): simplify profile update logic
+
+Extracted common validation logic into a reusable function
+to reduce code duplication across profile update endpoints.
+```
+
+```
+docs: update API documentation with new endpoints
+
+Added documentation for the v2 user management endpoints
+including request/response examples and error codes.
+```
+
+### Bad Examples
+
+```
+updated stuff                    # Too vague, no type/scope
+fixed bug                        # No context about which bug
+feat: added feature              # Redundant ("feat" means new feature)
+Feat(User): Add Login            # Incorrect capitalization
+feat: A really really really long subject line that exceeds the recommended limit  # Too long
+```
+
+## Breaking Changes
+
+When introducing breaking changes, add `BREAKING CHANGE:` to the footer:
+
+```
+feat(api): migrate to REST v2
+
+The API endpoints have been restructured for better consistency.
+Old endpoints are deprecated and will be removed in v3.0.
+
+BREAKING CHANGE: `/api/v1/users` is now `/api/v2/users`.
+All consumers must update their integration by 2025-03-01.
+```
+
+## Workflow
+
+When writing a commit message:
+
+1. **Review changes** - Run `git diff` to understand what changed
+2. **Identify type** - Determine the type of change
+3. **Identify scope** - Determine which area is affected
+4. **Write subject** - Create a clear, concise subject line
+5. **Write body** - Explain what and why (if needed)
+6. **Add footer** - Reference issues or note breaking changes
+
+## Validation
+
+Use the validation script to check commit message format:
+
+```bash
+python scripts/validate_commit.py "your commit message"
+```
+
+## Reference Documents
+
+- See `references/conventional-commits.md` for full specification
+- See `references/examples.md` for more examples
+- See `references/scopes.md` for recommended scope naming