@codeharbor/agent-playbook 0.1.0 → 0.1.2

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

package/skills/commit-helper/references/conventional-commits.md

@@ -0,0 +1,68 @@
+# Conventional Commits Specification
+
+## Summary
+
+The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history.
+
+## Structure
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Type
+
+Must be one of the following:
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, 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
+- **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
+- **ci**: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
+- **chore**: Other changes that don't modify src or test files
+- **revert**: Reverts a previous commit
+
+## Scope
+
+The scope should be the name of the npm package or module affected.
+
+## Description
+
+The description contains a short description of the change:
+
+- Use imperative, present tense: "change" not "changed" nor "changes"
+- Don't capitalize the first letter
+- No period (.) at the end
+
+## Body
+
+Just as in the subject, use the imperative, present tense: "fix" not "fixed" nor "fixes".
+
+Explain **what** and **why** instead of **how**.
+
+## Footer
+
+The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
+
+## Breaking Changes
+
+A BREAKING CHANGE must be indicated in the footer. A BREAKING CHANGE must be a part of the type/scope or the description.
+
+```
+feat(api): remove deprecated endpoints
+
+BREAKING CHANGE: The /api/v1/users endpoint has been removed.
+```
+
+## References
+
+- https://www.conventionalcommits.org/
+- https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format

package/skills/commit-helper/references/examples.md

@@ -0,0 +1,125 @@
+# Commit Message Examples
+
+## Features
+
+```
+feat(auth): add OAuth2 login support
+
+Implement OAuth2 authentication flow supporting Google and GitHub
+providers. Users can now link multiple social accounts to their profile.
+
+Closes #123
+```
+
+```
+feat(components): add data table component
+
+New reusable table component with built-in sorting, filtering, and
+pagination. Uses TanStack Table for performance.
+```
+
+## Bug Fixes
+
+```
+fix(api): resolve race condition in user creation
+
+Concurrent requests could create duplicate users. Added unique constraint
+on email field with proper error handling.
+
+Fixes #456
+```
+
+```
+fix(auth): prevent session token leakage
+
+Session tokens were being logged in debug output. Removed sensitive
+data from debug logs.
+```
+
+## Refactoring
+
+```
+refactor(user): extract validation logic
+
+Moved user validation logic into a dedicated validator module to
+enable reuse across different parts of the application.
+```
+
+```
+refactor(api): simplify error handling middleware
+
+Unified error response format across all API endpoints.
+```
+
+## Documentation
+
+```
+docs: update installation guide with new requirements
+
+Added Python 3.12 and Node.js 20 to the supported versions list.
+Updated docker-compose examples.
+```
+
+```
+docs(api): add OpenAPI specification for v2 endpoints
+
+Complete API documentation including request/response schemas and
+authentication requirements.
+```
+
+## Performance
+
+```
+perf(api): add database query caching
+
+Implemented Redis caching for frequently accessed data. Reduced
+average response time from 200ms to 50ms.
+```
+
+```
+perf(frontend): lazy load images below fold
+
+Implemented Intersection Observer for lazy loading. Reduced initial
+page load by 40%.
+```
+
+## Breaking Changes
+
+```
+feat(api): migrate to REST v2
+
+API endpoints have been restructured for better consistency.
+Old v1 endpoints are deprecated.
+
+BREAKING CHANGE: All `/api/v1/*` endpoints moved to `/api/v2/*`.
+Migration guide: docs/api-migration-v1-to-v2.md
+
+Closes #789
+```
+
+## Complex Example
+
+```
+feat(payment): integrate Stripe payment processing
+
+Add comprehensive Stripe integration for subscription and one-time payments.
+Includes webhook handling for payment events and automatic invoice generation.
+
+Key features:
+- Support for multiple payment methods (card, Apple Pay, Google Pay)
+- Subscription lifecycle management
+- Payment failure retry logic
+- PCI-compliant card handling via Stripe Elements
+
+Security considerations:
+- All card data is handled directly by Stripe
+- Webhook signatures are verified
+- Sensitive payment data is never stored locally
+
+Migration notes:
+- Existing users need to add payment method
+- Trial period extended by 14 days for existing users
+
+Related tickets: FEAT-123, FEAT-124
+Breaking Change: Old PayPal integration removed
+```

package/skills/commit-helper/references/scopes.md

@@ -0,0 +1,49 @@
+# Recommended Scopes
+
+## Frontend
+
+| Scope | Usage |
+|-------|-------|
+| `components` | UI component changes |
+| `hooks` | Custom React hooks |
+| `store` | State management (Redux, Zustand, etc.) |
+| `styles` | CSS, styled-components, theme |
+| `utils` | Utility functions |
+| `forms` | Form-related changes |
+| `routing` | Route configuration |
+
+## Backend
+
+| Scope | Usage |
+|-------|-------|
+| `api` | API endpoints, controllers |
+| `models` | Data models, schemas |
+| `services` | Business logic services |
+| `database` | Database queries, migrations |
+| `auth` | Authentication, authorization |
+| `middleware` | Express/HTTP middleware |
+| `validators` | Input validation |
+
+## DevOps
+
+| Scope | Usage |
+|-------|-------|
+| `ci` | Continuous Integration (GitHub Actions, Jenkins) |
+| `cd` | Continuous Deployment |
+| `docker` | Dockerfile, docker-compose |
+| `k8s` | Kubernetes manifests |
+| `terraform` | Infrastructure as Code |
+
+## General
+
+| Scope | Usage |
+|-------|-------|
+| `config` | Configuration changes |
+| `deps` | Dependency updates |
+| `tests` | Test files (use `test` type for test code changes) |
+| `types` | TypeScript type definitions |
+| `assets` | Images, fonts, static files |
+
+## Project-Specific
+
+Projects should define their own scopes based on their module structure. Document project-specific scopes in the project's CONTRIBUTING.md.