@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/skill-router/README.md

@@ -0,0 +1,155 @@
+# Skill Router
+
+An intelligent routing layer for Claude Code skills that helps users find the right skill for their task.
+
+## Overview
+
+The Skill Router analyzes user requests and intelligently recommends the most appropriate skill from the available catalog. It uses intent classification, semantic matching, and interactive clarification to ensure users get the help they need.
+
+## Installation
+
+```bash
+# Create symbolic link to global skills directory
+ln -s ~/Documents/code/GitHub/agent-playbook/skills/skill-router/SKILL.md ~/.claude/skills/skill-router.md
+```
+
+## How It Works
+
+```
+User Request → Intent Analysis → Skill Matching → Recommendation
+                                    ↓
+                         Interactive Clarification (if needed)
+```
+
+### Routing Process
+
+1. **Intent Analysis**: Parse user request to identify task type, context, and complexity
+2. **Skill Matching**: Match intent against available skills using keywords and semantics
+3. **Interactive Clarification**: Ask targeted questions if request is ambiguous
+4. **Recommendation**: Present the best matching skill with reasoning
+
+## Usage Examples
+
+### Direct Skill Match
+
+```
+You: "I need to review this pull request"
+
+Skill Router: Recommended Skill: code-reviewer
+This skill is designed for reviewing PRs and code changes for quality,
+security, and best practices.
+
+Would you like me to activate this skill?
+```
+
+### Ambiguous Request
+
+```
+You: "Use a skill to help with my project"
+
+Skill Router: I'd like to understand your needs better:
+- What type of task are you working on?
+- Are you designing, coding, testing, or documenting?
+- What's the primary goal?
+
+[Based on your answers, I'll recommend the right skill]
+```
+
+### Multi-Skill Workflow
+
+```
+You: "I'm building a new API from scratch"
+
+Skill Router: For a complete API project, I recommend using multiple skills:
+
+1. api-designer - Design your API structure and endpoints
+2. api-documenter - Create OpenAPI/Swagger documentation
+3. test-automator - Set up automated API testing
+4. code-reviewer - Review your implementation
+
+Shall we start with api-designer?
+```
+
+## Supported Skills
+
+| Category | Skills |
+|----------|--------|
+| **Core Development** | commit-helper, code-reviewer, debugger, refactoring-specialist |
+| **Documentation & Testing** | documentation-engineer, api-documenter, test-automator, qa-expert |
+| **Architecture & DevOps** | api-designer, security-auditor, performance-engineer, deployment-engineer |
+| **Planning & Analysis** | architecting-solutions, planning-with-files, self-improving-agent |
+
+## Features
+
+- **Intent Classification**: Understands what the user wants to accomplish
+- **Semantic Matching**: Finds relevant skills even with different wording
+- **Interactive Guidance**: Asks clarifying questions when needed
+- **Multi-Skill Orchestrations**: Suggests skill combinations for complex tasks
+- **Confidence Indicators**: Shows how confident the recommendation is
+
+## Best Practices
+
+### For Users
+
+1. **Be specific**: "I need to write tests for my API" vs "Help with tests"
+2. **Provide context**: Mention your project type and stage
+3. **Answer clarification questions**: Helps the router find the best match
+4. **Request alternatives**: Ask "What are my options?" for multiple choices
+
+### For Maintainers
+
+1. **Update skill catalog**: Add new skills to the catalog table
+2. **Refine routing logic**: Add new patterns and keywords
+3. **Track edge cases**: Note requests that don't fit existing skills
+4. **Improve questions**: Refine clarification templates based on usage
+
+## Routing Patterns
+
+| User Says | Routes To |
+|-----------|-----------|
+| "review my code" | code-reviewer |
+| "fix this bug" | debugger |
+| "write tests" | test-automator |
+| "create documentation" | documentation-engineer |
+| "design an API" | api-designer |
+| "deploy to production" | deployment-engineer |
+| "improve performance" | performance-engineer |
+| "check security" | security-auditor |
+| "refactor code" | refactoring-specialist |
+| "commit these changes" | commit-helper |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Skill Router                        │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+│  │ Intent       │  │ Skill        │  │ Interactive  │ │
+│  │ Analyzer     │→ │ Matcher      │→ │ Clarifier    │ │
+│  └──────────────┘  └──────────────┘  └──────────────┘ │
+│                          ↓                              │
+│                   ┌──────────────┐                      │
+│                   │ Recommended  │                      │
+│                   │ Skill        │                      │
+│                   └──────────────┘                      │
+└─────────────────────────────────────────────────────────┘
+                           │
+                           ↓
+        ┌──────────────────┼──────────────────┐
+        │                  │                  │
+    ┌───▼────┐      ┌─────▼────┐     ┌──────▼───┐
+    │ Skill 1│      │  Skill 2 │     │  Skill N │
+    └────────┘      └──────────┘     └──────────┘
+```
+
+## References
+
+- [AI Agent Routing: Tutorial & Best Practices](https://www.patronus.ai/ai-agent-development/ai-agent-routing)
+- [Intent Recognition in Multi-Agent Systems](https://gist.github.com/mkbctrl/a35764e99fe0c8e8c00b2358f55cd7fa)
+- [Multi-LLM Routing Strategies - AWS](https://aws.amazon.com/blogs/machine-learning/multi-llm-routing-strategies-for-generative-ai-applications-on-aws/)
+
+## License
+
+MIT

package/skills/skill-router/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: skill-router
+description: Intelligently routes user requests to the most appropriate Claude Code skill. ALWAYS use this skill FIRST when user asks for help, mentions "skill", "which", "how to", or seems unsure about which approach to take. This is the default entry point for all skill-related requests.
+allowed-tools: Read, AskUserQuestion, WebSearch, Grep
+---
+
+# Skill Router
+
+An intelligent router that analyzes user requests and recommends the most appropriate Claude Code skill for the task.
+
+## When This Skill Activates
+
+This skill activates when you:
+- Ask "which skill should I use?" or "what skill can help with...?"
+- Say "use a skill" without specifying which one
+- Express a need but aren't sure which skill fits
+- Mention "skill router" or "help me find a skill"
+
+## Available Skills Catalog
+
+### Core Development
+
+| Skill | Best For |
+|-------|----------|
+| `commit-helper` | Writing Git commit messages, formatting commits |
+| `code-reviewer` | Reviewing PRs, code changes, quality checks |
+| `debugger` | Diagnosing bugs, errors, unexpected behavior |
+| `refactoring-specialist` | Improving code structure, reducing technical debt |
+
+### Design & UX
+
+| Skill | Best For |
+|-------|----------|
+| `figma-designer` | Analyzing Figma designs and producing implementation-ready visual specs/PRDs |
+
+### Documentation & Testing
+
+| Skill | Best For |
+|-------|----------|
+| `documentation-engineer` | Writing README, technical docs, code documentation |
+| `api-documenter` | Creating OpenAPI/Swagger specifications |
+| `test-automator` | Writing tests, setting up test frameworks |
+| `qa-expert` | Test strategy, quality gates, QA processes |
+
+### Architecture & DevOps
+
+| Skill | Best For |
+|-------|----------|
+| `api-designer` | Designing REST/GraphQL APIs, API architecture |
+| `security-auditor` | Security audits, vulnerability reviews, OWASP Top 10 |
+| `performance-engineer` | Performance optimization, speed analysis |
+| `deployment-engineer` | CI/CD pipelines, deployment automation |
+
+### Planning & Analysis
+
+| Skill | Best For |
+|-------|----------|
+| `architecting-solutions` | Creating PRDs, solution design, requirements analysis |
+| `planning-with-files` | Multi-step task planning, persistent file-based organization |
+| `self-improving-agent` | Universal self-improvement that learns from all skill experiences |
+
+## Routing Process
+
+### Step 1: Intent Analysis
+
+Analyze the user's request to identify:
+- **Task Type**: What does the user want to accomplish?
+- **Context**: What is the working domain (web, mobile, data, etc.)?
+- **Complexity**: Is this a simple task or complex workflow?
+
+### Step 2: Skill Matching
+
+Match the identified intent to the most relevant skill(s) using:
+- **Keyword matching**: Compare request keywords with skill descriptions
+- **Semantic similarity**: Understand the meaning behind the request
+- **Context awareness**: Consider project state and previous actions
+
+### Step 3: Interactive Clarification
+
+If the request is ambiguous, guide the user with targeted questions:
+- What is the primary goal?
+- What type of output is expected?
+- Are there specific constraints or preferences?
+
+### Step 4: Recommendation & Execution
+
+Present the recommended skill with:
+- Skill name and brief description
+- Why it fits the current request
+- Option to proceed or ask for alternatives
+
+## Routing Examples
+
+### Example 1: Clear Intent
+
+**User:** "I need to review this pull request"
+
+**Router Analysis:**
+- Keywords: "review", "pull request"
+- Intent: Code review
+- **Recommendation:** `code-reviewer`
+
+### Example 2: Ambiguous Intent
+
+**User:** "Use a skill to help with my project"
+
+**Router Questions:**
+1. What type of task are you working on?
+2. Are you designing, coding, testing, or documenting?
+
+Based on answers → Recommend appropriate skill
+
+### Example 3: Multi-Skill Scenario
+
+**User:** "I'm building a new API and need help with the full workflow"
+
+**Router Recommendation:**
+Consider using multiple skills in sequence:
+1. `api-designer` - Design the API structure
+2. `api-documenter` - Document endpoints with OpenAPI
+3. `test-automator` - Set up API tests
+4. `code-reviewer` - Review implementation
+
+## Interactive Question Templates
+
+When user intent is unclear, use these question patterns:
+
+### Goal Clarification
+- "What are you trying to accomplish with this task?"
+- "What would the ideal outcome look like?"
+
+### Domain Identification
+- "What area does this relate to: development, testing, documentation, or deployment?"
+- "Are you working on code, APIs, infrastructure, or something else?"
+
+### Stage Assessment
+- "What stage are you at: planning, implementing, testing, or maintaining?"
+
+### Preference Confirmation
+- "Do you want a quick solution or a comprehensive approach?"
+- "Are there specific tools or frameworks you're using?"
+
+## Best Practices
+
+### 1. Start Broad, Then Narrow
+- Begin with general category questions
+- Drill down into specifics based on responses
+
+### 2. Explain Your Reasoning
+- Tell the user why a particular skill is recommended
+- Build trust through transparency
+
+### 3. Offer Alternatives
+- Present the top recommendation
+- Mention 1-2 alternatives if applicable
+
+### 4. Handle Edge Cases
+- If no skill fits perfectly, suggest the closest match
+- Offer to help without a specific skill if better
+
+### 5. Learn from Context
+- Consider previous interactions
+- Remember user preferences for future routing
+
+## Advanced Routing Patterns
+
+### Semantic Routing
+Use semantic similarity when keywords don't match directly:
+- "clean up my code" → `refactoring-specialist`
+- "make my app faster" → `performance-engineer`
+- "check for security issues" → `security-auditor`
+
+### Multi-Skill Orchestrations
+Suggest skill combinations for complex workflows:
+- **New Feature**: `architecting-solutions` → `debugger` → `code-reviewer`
+- **API Project**: `api-designer` → `api-documenter` → `test-automator`
+- **Production Readiness**: `security-auditor` → `performance-engineer` → `deployment-engineer`
+
+### Confidence Levels
+Indicate confidence in recommendations:
+- **High**: Direct keyword match, clear intent
+- **Medium**: Semantic similarity, reasonable inference
+- **Low**: Ambiguous request, clarification needed
+
+## Error Recovery
+
+If the recommended skill doesn't fit:
+1. Acknowledge the mismatch
+2. Ask follow-up questions to refine understanding
+3. Provide alternative recommendations
+4. Fall back to general assistance if needed
+
+## Output Format
+
+When recommending a skill, use this format:
+
+```markdown
+## Recommended Skill: {skill-name}
+
+{brief description of why this skill fits}
+
+**What it does:** {one-sentence skill description}
+
+**Best for:** {specific use cases}
+
+---
+
+Would you like me to activate this skill, or would you prefer to see other options?
+```
+
+## References
+
+- [AI Agent Routing: Tutorial & Best Practices](https://www.patronus.ai/ai-agent-development/ai-agent-routing)
+- [Intent Recognition and Auto-Routing in Multi-Agent Systems](https://gist.github.com/mkbctrl/a35764e99fe0c8e8c00b2358f55cd7fa)
+- [Multi-LLM Routing Strategies (AWS)](https://aws.amazon.com/blogs/machine-learning/multi-llm-routing-strategies-for-generative-ai-applications-on-aws/)

package/skills/test-automator/README.md

@@ -0,0 +1,41 @@
+# Test Automator
+
+> A Claude Code skill for creating and maintaining automated tests.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Write tests for this function
+You: Create test cases
+You: Improve test coverage
+```
+
+## Testing Frameworks
+
+| Language | Framework |
+|----------|-----------|
+| TypeScript/JS | Jest, Vitest, Mocha |
+| Python | pytest, unittest |
+| Go | testing package |
+| Java | JUnit |
+
+## Scripts
+
+Generate test boilerplate:
+```bash
+python scripts/generate_test.py <filename>
+```
+
+Check test coverage:
+```bash
+python scripts/coverage_report.py
+```
+
+## Resources
+
+- [Testing Best Practices](https://google.github.io/eng-practices/review/developer/tests.html)
+- [Test Driven Development](https://www.amazon.com/Test-Driven-Development-Kent-Beck/dp/0321146530)

package/skills/test-automator/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: test-automator
+description: Test automation framework expert for creating and maintaining automated tests. Use when user asks to write tests, automate testing, or improve test coverage.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Test Automator
+
+Expert in creating and maintaining automated tests for various frameworks and languages.
+
+## When This Skill Activates
+
+Activates when you:
+- Ask to write tests
+- Mention test automation
+- Request test coverage improvement
+- Need to set up testing framework
+
+## Testing Pyramid
+
+```
+        /\
+       /E2E\      - Few, expensive, slow
+      /------\
+     /  Integration \ - Moderate number
+    /--------------\
+   /     Unit Tests  \ - Many, cheap, fast
+  /------------------\
+```
+
+## Unit Testing
+
+### Principles
+1. **Test behavior, not implementation**
+2. **One assertion per test** (generally)
+3. **Arrange-Act-Assert** pattern
+4. **Descriptive test names**
+
+### Example (Jest)
+
+```typescript
+describe('UserService', () => {
+  describe('createUser', () => {
+    it('should create a user with valid data', async () => {
+      // Arrange
+      const userData = {
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+
+      // Act
+      const user = await userService.create(userData);
+
+      // Assert
+      expect(user.id).toBeDefined();
+      expect(user.email).toBe(userData.email);
+    });
+
+    it('should throw error for invalid email', async () => {
+      // Arrange
+      const userData = { email: 'invalid' };
+
+      // Act & Assert
+      await expect(userService.create(userData))
+        .rejects.toThrow('Invalid email');
+    });
+  });
+});
+```
+
+## Integration Testing
+
+### Principles
+1. **Test component interactions**
+2. **Use test doubles for external services**
+3. **Clean up test data**
+4. **Run in isolation**
+
+### Example (Supertest)
+
+```typescript
+describe('POST /api/users', () => {
+  it('should create a user', async () => {
+    const response = await request(app)
+      .post('/api/users')
+      .send({
+        name: 'John Doe',
+        email: 'john@example.com'
+      })
+      .expect(201)
+      .expect((res) => {
+        expect(res.body.id).toBeDefined();
+        expect(res.body.email).toBe('john@example.com');
+      });
+  });
+});
+```
+
+## E2E Testing
+
+### Principles
+1. **Test critical user flows**
+2. **Use realistic test data**
+3. **Handle async operations properly**
+4. **Clean up after tests**
+
+### Example (Playwright)
+
+```typescript
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[name="email"]', 'user@example.com');
+  await page.fill('[name="password"]', 'password123');
+  await page.click('button[type="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+  await expect(page.locator('h1')).toContainText('Welcome');
+});
+```
+
+## Test Coverage
+
+### Coverage Goals
+
+| Type | Target |
+|------|--------|
+| Lines | > 80% |
+| Branches | > 75% |
+| Functions | > 80% |
+| Statements | > 80% |
+
+### Coverage Reports
+
+```bash
+# Jest
+npm test -- --coverage
+
+# Python (pytest-cov)
+pytest --cov=src --cov-report=html
+
+# Go
+go test -coverprofile=coverage.out
+go tool cover -html=coverage.out
+```
+
+## Testing Best Practices
+
+### DO's
+- Write tests before fixing bugs (TDD)
+- Test edge cases
+- Keep tests independent
+- Use descriptive test names
+- Mock external dependencies
+- Clean up test data
+
+### DON'Ts
+- Don't test implementation details
+- Don't write brittle tests
+- Don't skip tests without a reason
+- Don't commit commented-out tests
+- Don't test third-party libraries
+
+## Test Naming Conventions
+
+```typescript
+// Good: Describes what is being tested
+it('should reject invalid email addresses')
+
+// Good: Describes the scenario and outcome
+it('returns 401 when user provides invalid credentials')
+
+// Bad: Vague
+it('works correctly')
+```
+
+## Common Testing Frameworks
+
+| Language | Framework | Command |
+|----------|-----------|---------|
+| TypeScript/JS | Jest, Vitest | `npm test` |
+| Python | pytest | `pytest` |
+| Go | testing | `go test` |
+| Java | JUnit | `mvn test` |
+| Rust | built-in | `cargo test` |
+
+## Scripts
+
+Generate test boilerplate:
+```bash
+python scripts/generate_test.py <filename>
+```
+
+Check test coverage:
+```bash
+python scripts/coverage_report.py
+```
+
+## References
+
+- `references/best-practices.md` - Testing best practices
+- `references/examples/` - Framework-specific examples
+- `references/mocking.md` - Mocking guidelines

package/skills/test-automator/references/best-practices.md

@@ -0,0 +1,6 @@
+# Test Automation Best Practices
+
+- Keep tests deterministic
+- Avoid test order dependencies
+- Prefer explicit fixtures
+- Run tests in CI on every change

package/skills/test-automator/references/examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+This directory contains small, focused test automation examples.

package/skills/test-automator/references/examples/unit-test-example.md

@@ -0,0 +1,8 @@
+# Unit Test Example
+
+```python
+from my_module import add
+
+def test_add():
+    assert add(2, 3) == 5
+```

package/skills/test-automator/references/mocking.md

@@ -0,0 +1,5 @@
+# Mocking Guide
+
+- Mock external services
+- Avoid mocking internal logic
+- Use realistic data shapes

package/skills/test-automator/scripts/coverage_report.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# Template generator for coverage report.
+
+from pathlib import Path
+import argparse
+import textwrap
+
+
+def write_output(path: Path, content: str, force: bool) -> bool:
+    if path.exists() and not force:
+        print(f"{path} already exists (use --force to overwrite)")
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return True
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a coverage report.")
+    parser.add_argument("--output", default="coverage-report.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Component or repo name")
+    parser.add_argument("--owner", default="team", help="Owning team")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    content = textwrap.dedent(
+        f"""\
+        # Coverage Report
+
+        ## Summary
+        Coverage for {args.name}
+
+        ## Ownership
+        - Owner: {args.owner}
+
+        ## Coverage Breakdown
+        - Lines:
+        - Branches:
+        - Functions:
+
+        ## Low Coverage Areas
+        - Module:
+        - Module:
+
+        ## Action Items
+        - Add missing tests
+        - Track progress
+        """
+    ).strip() + "\n"
+
+    output = Path(args.output)
+    if not write_output(output, content, args.force):
+        return 1
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())