@codeharbor/agent-playbook 0.1.0 → 0.1.1

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.

package/skills/commit-helper/scripts/validate_commit.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+Validate commit message format against Conventional Commits specification.
+"""
+
+import re
+import sys
+
+
+def validate_commit_message(message: str) -> tuple[bool, str]:
+    """
+    Validate a commit message against Conventional Commits format.
+
+    Args:
+        message: The commit message to validate
+
+    Returns:
+        (is_valid, error_message)
+    """
+    if not message:
+        return False, "Commit message is empty"
+
+    lines = message.split('\n')
+    subject = lines[0]
+
+    # Validate subject line format: type(scope): subject
+    pattern = r'^(feat|fix|docs|style|refactor|perf|test|chore|ci|build)(\(.+\))?: .{1,50}$'
+    if not re.match(pattern, subject):
+        return False, (
+            "Invalid format. Expected: type(scope): subject\n"
+            "- Type must be one of: feat, fix, docs, style, refactor, perf, test, chore, ci, build\n"
+            "- Subject must be 1-50 characters\n"
+            "- Use imperative mood (e.g., 'add feature' not 'added feature')"
+        )
+
+    # Check for period at end of subject
+    if subject.endswith('.'):
+        return False, "Subject line should not end with a period"
+
+    # Check subject uses imperative mood (basic check)
+    words = subject.split(': ', 1)[1].split() if ': ' in subject else []
+    if words:
+        first_word = words[0].lower()
+        # Common past tense indicators
+        if first_word.endswith(('ed', 'ing')) and first_word not in ['added', 'building']:
+            return False, f"Subject should use imperative mood ('{first_word}' → '{first_word.rstrip('ed')}')"
+
+    # Validate body format (if present)
+    if len(lines) > 1:
+        if lines[1].strip():  # No blank line after subject
+            return False, "Separate subject from body with a blank line"
+
+        body = '\n'.join(lines[2:])
+        for line in body.split('\n'):
+            if len(line) > 72:
+                return False, f"Body lines should wrap at 72 characters (found {len(line)})"
+
+    return True, "Valid commit message format"
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python validate_commit.py \"commit message\"")
+        sys.exit(1)
+
+    message = sys.argv[1]
+    is_valid, result = validate_commit_message(message)
+
+    print(result)
+    sys.exit(0 if is_valid else 1)

package/skills/create-pr/README.md

@@ -0,0 +1,182 @@
+# Create PR
+
+A Claude Code skill for creating pull requests with automatic bilingual documentation updates.
+
+## Overview
+
+This skill streamlines the PR creation process for the agent-playbook repository. It ensures that both English and Chinese documentation remain synchronized whenever code changes are submitted.
+
+## Features
+
+- **Automatic Change Analysis**: Examines git diff to understand what changed
+- **Documentation Sync**: Updates both README.md and README.zh-CN.md
+- **Bilingual Support**: Maintains parity between English and Chinese docs
+- **PR Template**: Provides consistent PR description format
+- **Verification Checklist**: Ensures nothing is missed before submission
+
+## Installation
+
+```bash
+# Create symbolic link to global skills directory
+ln -s ~/Documents/code/GitHub/agent-playbook/skills/create-pr/SKILL.md ~/.claude/skills/create-pr.md
+```
+
+## Workflow
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Analyze       │ -> │   Determine     │ -> │   Update Docs   │
+│   Changes       │    │   Updates       │    │   (Both EN/CN)  │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                                                           │
+                                                           v
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Create PR     │ <- │   Commit &      │ <- │   Verify        │
+│                 │    │   Push          │    │   Checklist     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Simply ask Claude to create a PR
+"Please create a PR for my changes"
+```
+
+The skill will:
+1. Analyze all changes
+2. Determine if documentation updates are needed
+3. Update both README files
+4. Commit and push
+5. Create the PR
+
+### With Specific Focus
+
+```bash
+"Create a PR for the new skill router"
+```
+
+The skill will focus on the skill-router changes and update documentation accordingly.
+
+## Documentation Update Rules
+
+| Change Type | Update Required |
+|-------------|-----------------|
+| New skill added | ✅ Yes - Add to both READMEs |
+| Skill removed | ✅ Yes - Remove from both READMEs |
+| Skill description changed | ✅ Yes - Update both READMEs |
+ | Bug fix | ❌ No - Unless user-facing |
+ | Internal refactor | ❌ No - Documentation unchanged |
+
+## PR Description Template
+
+```markdown
+## Summary
+
+<Brief description of the changes>
+
+## Changes
+
+- [ ] New skill added
+- [ ] Existing skill modified
+- [ ] Documentation updated
+
+## Documentation
+
+- [x] README.md updated
+- [x] README.zh-CN.md updated
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+## Bilingual Documentation
+
+### Adding a New Skill
+
+**README.md (English):**
+```markdown
+| **[skill-name](./skills/skill-name/)** | Skill description |
+```
+
+**README.zh-CN.md (Chinese):**
+```markdown
+| **[skill-name](./skills/skill-name/)** | 技能描述 |
+```
+
+### Language Switch Links
+
+Both files must have the switch link at the top:
+
+**README.md:**
+```markdown
+English | [简体中文](./README.zh-CN.md)
+```
+
+**README.zh-CN.md:**
+```markdown
+[English](./README.md) | 简体中文
+```
+
+## Examples
+
+### Example 1: Adding a New Skill
+
+**Input:**
+```
+"I've created a new skill called skill-router. Please create a PR."
+```
+
+**Skill Actions:**
+1. Analyzes the skill-router directory
+2. Adds skill-router to Meta Skills table in README.md
+3. Adds skill-router to 元技能 table in README.zh-CN.md
+4. Commits all changes
+5. Pushes to remote branch
+6. Creates PR with description
+
+### Example 2: Bug Fix
+
+**Input:**
+```
+"I fixed a typo in debugger skill. Create a PR."
+```
+
+**Skill Actions:**
+1. Analyzes the change (typo fix only)
+2. Determines no documentation update needed
+3. Commits and pushes
+4. Creates PR with simple description
+
+## Verification Checklist
+
+Before creating PR, the skill verifies:
+
+- [ ] All changes are committed
+- [ ] Branch is pushed to remote
+- [ ] Commit messages follow Conventional Commits
+- [ ] README.md updated (if needed)
+- [ ] README.zh-CN.md updated (if needed)
+- [ ] Language switch links present
+- [ ] New skills have symlinks created
+- [ ] PR title is clear and descriptive
+
+## File Structure
+
+```
+skills/create-pr/
+├── SKILL.md     # Main skill file
+└── README.md    # This file
+```
+
+## Contributing
+
+When contributing to this skill:
+1. Update both SKILL.md and README.md
+2. Test with real PR creation scenarios
+3. Ensure bilingual documentation stays in sync
+
+## License
+
+MIT