@codeharbor/agent-playbook 0.1.0 → 0.1.1

package/skills/prd-planner/references/edge-case-analysis.md

@@ -0,0 +1,111 @@
+# Edge Case Analysis Reference
+
+This document provides detailed guidance for Step 2.5: Context-Aware Edge Case Analysis.
+
+## Codebase Pattern Scanning Commands
+
+Run these searches to understand how the project handles common scenarios:
+
+```bash
+# Delete strategy (soft delete vs hard delete)
+grep -r "softDelete\|isDeleted\|deletedAt\|removed" src/ --include="*.ts" --include="*.tsx"
+
+# Error handling patterns
+grep -r "toast\|notification\|alert\|snackbar\|message\." src/ --include="*.tsx"
+
+# Empty state handling
+grep -r "empty\|noData\|EmptyState\|placeholder" src/ --include="*.tsx"
+
+# Pagination patterns
+grep -r "pageSize\|limit\|offset\|pagination\|perPage" src/ --include="*.ts"
+
+# Loading state patterns
+grep -r "loading\|isLoading\|pending\|Skeleton" src/ --include="*.tsx"
+
+# Validation patterns
+grep -r "validate\|validator\|yup\|zod\|schema" src/ --include="*.ts"
+```
+
+## Requirement Type Classification
+
+| Requirement Type | Keywords | Key Edge Cases |
+|-----------------|----------|----------------|
+| CRUD Operations | create, edit, delete, list | Concurrent edits, cascade delete, validation |
+| State Workflow | status, approval, flow | Invalid transitions, rollback, concurrent state |
+| Async Operations | submit, load, sync | Timeout, retry, race conditions |
+| Data Display | list, report, dashboard | Empty data, pagination, sorting, filtering |
+| Form Input | form, input, submit | Validation, required fields, format |
+| File Operations | upload, download, export | Size limits, format validation, progress |
+
+## Smart Assumptions Output Format
+
+Record inferred patterns in `{scope}-prd-notes.md`:
+
+```markdown
+## Inferred Patterns (from codebase)
+
+| Edge Case | Source | Pattern Applied |
+|-----------|--------|-----------------|
+| Delete strategy | `src/models/User.ts:45` uses `deletedAt` | Soft delete |
+| Error display | `src/utils/toast.ts` global Toast | Toast notification |
+| Empty state | `src/components/EmptyState.tsx` exists | Reuse EmptyState component |
+| Pagination | `src/hooks/usePagination.ts:12` default 20 | 20 items per page |
+| Loading | `src/components/Skeleton.tsx` exists | Use Skeleton component |
+```
+
+## When to Ask Users
+
+Only ask about edge cases when:
+
+1. **No precedent in codebase** - First time the project encounters this scenario
+2. **Multiple patterns exist** - Codebase has inconsistent approaches
+3. **Business decision required** - Technical analysis cannot determine the answer
+
+### Question Categories
+
+| Category | Example Question | When to Ask |
+|----------|-----------------|-------------|
+| Data lifecycle | "Should deleted items be recoverable?" | No existing delete pattern found |
+| Conflict resolution | "When two users edit simultaneously, who wins?" | Feature involves concurrent access |
+| Failure handling | "If partial data saves, show error or partial success?" | Complex multi-step operation |
+| Business rules | "Can users edit after submission?" | State machine not defined |
+
+## User Confirmation Format
+
+```markdown
+## Edge Cases Requiring Confirmation
+
+Based on the feature requirements, these edge cases need your input:
+
+### 1. Concurrent Edit Handling
+When two users edit the same record simultaneously:
+- [ ] A: Last write wins (simpler, may lose data)
+- [ ] B: Show conflict dialog (better UX, more complex)
+- [ ] C: Lock record during edit (prevents conflicts, may block users)
+
+### 2. Cascade Delete Behavior
+When deleting a parent record with children:
+- [ ] A: Block deletion, show warning
+- [ ] B: Cascade delete all children
+- [ ] C: Orphan children (set parent_id to null)
+
+**Note**: Questions not listed above will follow existing codebase patterns.
+```
+
+## Edge Cases Section in Notes File
+
+```markdown
+## Edge Cases
+
+### Auto-handled (following codebase patterns)
+- Empty list → Use existing `EmptyState` component
+- Network error → Retry 3 times (from `src/utils/api.ts:23`)
+- Form validation → Real-time with inline errors (from `src/hooks/useForm.ts`)
+
+### Confirmed by User
+- Concurrent edit: Last write wins (confirmed {date})
+- Cascade delete: Block and warn (confirmed {date})
+
+### Open Questions
+- (List any remaining questions)
+```

package/skills/qa-expert/README.md

@@ -0,0 +1,37 @@
+# QA Expert
+
+> A Claude Code skill for quality assurance strategy and quality gates.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Create a QA plan
+You: Set up quality gates
+You: What tests should I write?
+```
+
+## Quality Gates
+
+| Gate | Purpose |
+|------|---------|
+| **Lint** | Code style and formatting |
+| **Type Check** | Type safety |
+| **Unit Tests** | Functionality correctness |
+| **Integration Tests** | Component interaction |
+| **E2E Tests** | User workflows |
+
+## Scripts
+
+Generate test plan:
+```bash
+python scripts/generate_test_plan.py <feature>
+```
+
+## Resources
+
+- [Google Testing Blog](https://testing.google.com/)
+- [Ministry of Testing](https://www.ministryoftesting.com/)

package/skills/qa-expert/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: qa-expert
+description: Quality assurance expert for testing strategies and quality gates. Use when planning test coverage, setting up QA processes, or improving quality standards.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch
+---
+
+# QA Expert
+
+Quality assurance specialist for developing comprehensive testing strategies and quality gates.
+
+## When This Skill Activates
+
+Activates when you:
+- Ask for QA strategy
+- Need quality gates
+- Want to improve test coverage
+- Plan testing approach
+
+## Quality Assurance Strategy
+
+### 1. Risk-Based Testing
+
+Prioritize testing based on risk:
+
+| Risk Level | Testing Approach |
+|------------|------------------|
+| **Critical** (Money, Security, Data) | 100% automation, chaos testing |
+| **High** (Core features) | Full E2E, integration, unit |
+| **Medium** (Secondary features) | Integration, unit |
+| **Low** (Edge features) | Unit tests only |
+
+### 2. Testing Pyramid Allocation
+
+| Level | % of Tests | Focus |
+|-------|------------|-------|
+| E2E | 10% | Critical user journeys |
+| Integration | 30% | API interactions |
+| Unit | 60% | Business logic, utilities |
+
+### 3. Quality Gates
+
+#### Pre-Commit
+```bash
+- Lint: npm run lint
+- Format check: npm run format:check
+- Type check: npm run type-check
+- Unit tests: npm run test:unit
+```
+
+#### Pre-Merge
+```bash
+- All tests: npm test
+- Coverage threshold: > 80%
+- Security scan: npm audit
+- License check: npm run check:licenses
+```
+
+#### Pre-Production
+```bash
+- Full test suite: npm run test:all
+- E2E tests: npm run test:e2e
+- Performance tests: npm run test:perf
+- Security audit: npm audit --audit-level high
+```
+
+## Test Categories
+
+### Functional Testing
+
+**Purpose**: Verify features work as specified
+
+- Happy path testing
+- Edge case testing
+- Boundary value analysis
+- Error handling
+
+### Non-Functional Testing
+
+**Performance**
+- Response time < 200ms (p95)
+- Throughput > 1000 req/s
+- Memory usage stable
+- No memory leaks
+
+**Security**
+- OWASP Top 10 coverage
+- Penetration testing
+- Dependency vulnerability scan
+- Secrets detection
+
+**Compatibility**
+- Browser testing (Chrome, Firefox, Safari, Edge)
+- Device testing (Mobile, Desktop, Tablet)
+- OS testing (Windows, macOS, Linux)
+- Version testing (N-1 browser versions)
+
+### Regression Testing
+
+- Previous bugs don't reappear
+- New features don't break existing features
+- Performance doesn't degrade
+
+### Exploratory Testing
+
+- Find unexpected issues
+- Test edge cases
+- User experience issues
+
+## Test Planning
+
+### Test Plan Template
+
+```markdown
+# Test Plan: [Feature Name]
+
+## Overview
+[Feature description]
+
+## Scope
+[In scope / Out of scope]
+
+## Test Cases
+
+### Functional
+- [ ] TC001: [Description]
+- [ ] TC002: [Description]
+
+### Integration
+- [ ] TC101: [Description]
+
+### E2E
+- [ ] TC201: [Description]
+
+## Test Data
+[Required test data]
+
+## Environment
+[Test environment setup]
+
+## Schedule
+[Testing timeline]
+
+## Exit Criteria
+[Definition of done]
+```
+
+## Quality Metrics
+
+### Code Quality
+- **Test Coverage**: > 80%
+- **Cyclomatic Complexity**: < 10 per function
+- **Code Duplication**: < 5%
+- **Technical Debt Ratio**: < 5%
+
+### Defect Metrics
+- **Defect Density**: < 1 defect per 1000 LOC
+- **Critical Defects**: 0
+- **High Defects**: 0
+- **Medium Defects**: < 3
+
+### Test Metrics
+- **Test Pass Rate**: > 95%
+- **Flaky Tests**: 0
+- **Test Execution Time**: < 10 minutes
+
+## Automation Strategy
+
+### Automate When
+- Test is run frequently
+- Test has deterministic results
+- Test is stable
+- ROI justifies automation cost
+
+### Don't Automate When
+- Test requires human judgment
+- Test is exploratory
+- Test is one-time only
+- Test changes frequently
+
+## Bug Report Template
+
+```markdown
+## Bug Summary
+[One-line summary]
+
+## Severity
+Critical / High / Medium / Low
+
+## Steps to Reproduce
+1.
+2.
+3.
+
+## Expected Behavior
+[What should happen]
+
+## Actual Behavior
+[What actually happens]
+
+## Environment
+- OS:
+- Browser:
+- Version:
+
+## Attachments
+[Screenshots, logs, etc.]
+```
+
+## Scripts
+
+Generate test plan:
+```bash
+python scripts/generate_test_plan.py <feature>
+```
+
+Analyze test coverage:
+```bash
+python scripts/coverage_analysis.py
+```
+
+## References
+
+- `references/strategy.md` - Testing strategies
+- `references/gates.md` - Quality gate definitions
+- `references/metrics.md` - QA metrics and KPIs

package/skills/qa-expert/references/gates.md

@@ -0,0 +1,11 @@
+# Quality Gates
+
+## Required Checks
+- Lint passes
+- Unit tests pass
+- Coverage threshold met
+- Security scan clean
+
+## Release Criteria
+- No high severity defects
+- Performance within target thresholds

package/skills/qa-expert/references/metrics.md

@@ -0,0 +1,6 @@
+# QA Metrics
+
+- Defect escape rate
+- Test coverage by module
+- Mean time to detect (MTTD)
+- Mean time to resolve (MTTR)

package/skills/qa-expert/references/strategy.md

@@ -0,0 +1,11 @@
+# QA Strategy
+
+## Objectives
+- Validate critical user flows
+- Detect regressions early
+- Ensure performance and security baselines
+
+## Scope
+- Unit tests
+- Integration tests
+- End-to-end tests

package/skills/qa-expert/scripts/coverage_analysis.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# Template generator for coverage analysis.
+
+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 analysis.")
+    parser.add_argument("--output", default="coverage-analysis.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 Analysis
+
+        ## Summary
+        Coverage summary for {args.name}.
+
+        ## Ownership
+        - Owner: {args.owner}
+
+        ## Coverage Gaps
+        - Missing unit tests
+        - Missing integration tests
+
+        ## Risk Areas
+        - Critical paths with low coverage
+        - Recently changed modules
+
+        ## Recommendations
+        - Add tests for gaps
+        - Improve data-driven coverage
+
+        ## Next Steps
+        - Owners and deadlines
+        """
+    ).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())

package/skills/qa-expert/scripts/generate_test_plan.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+# Template generator for QA test plan.
+
+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 QA test plan.")
+    parser.add_argument("--output", default="docs/test-plan.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="Feature or release 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"""\
+        # QA Test Plan
+
+        ## Scope
+        {args.name}
+
+        ## Ownership
+        - Owner: {args.owner}
+        - QA lead: TBD
+
+        ## Risks
+        - High impact areas
+        - Known regressions
+
+        ## Test Matrix
+        - Platforms
+        - Browsers
+        - Locales
+
+        ## Environments
+        - Staging
+        - Production
+
+        ## Test Data
+        - Seed data requirements
+        - Edge-case fixtures
+
+        ## Exit Criteria
+        - Critical tests passing
+        - No unresolved P0/P1 issues
+        """
+    ).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())

package/skills/refactoring-specialist/README.md

@@ -0,0 +1,37 @@
+# Refactoring Specialist
+
+> A Claude Code skill for code refactoring and technical debt reduction.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Refactor this code
+You: Clean up this function
+You: This code is messy, help me improve it
+```
+
+## Common Refactorings
+
+| Code Smell | Refactoring |
+|------------|-------------|
+| Long Method | Extract Method |
+| Duplicate Code | Extract Method |
+| Large Class | Extract Class |
+| Long Parameter List | Introduce Parameter Object |
+| Switch Statement | Replace with Polymorphism |
+
+## Principles
+
+1. **Behavior Preservation**: Refactoring must not change external behavior
+2. **Small Steps**: Make incremental changes
+3. **Test Coverage**: Ensure tests pass before and after
+4. **Commit Often**: Commit after each successful refactoring
+
+## Resources
+
+- [Refactoring.com](https://refactoring.com/)
+- [Clean Code](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)