@codeharbor/agent-playbook 0.1.0 → 0.1.2

package/skills/performance-engineer/README.md

@@ -0,0 +1,42 @@
+# Performance Engineer
+
+> A Claude Code skill for performance optimization and analysis.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Optimize this code
+You: Why is this slow?
+You: Profile this application
+```
+
+## Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| API Response (p50) | < 100ms |
+| API Response (p95) | < 500ms |
+| Database Query | < 50ms |
+| Page Load (FMP) | < 2s |
+| Time to Interactive | < 3s |
+
+## Scripts
+
+Profile application:
+```bash
+python scripts/profile.py
+```
+
+Generate performance report:
+```bash
+python scripts/perf_report.py
+```
+
+## Resources
+
+- [Web.dev Performance](https://web.dev/performance/)
+- [Google Performance](https://developer.chrome.com/docs/lighthouse/performance/)

package/skills/performance-engineer/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: performance-engineer
+description: Performance optimization specialist for improving application speed and efficiency. Use when investigating performance issues or optimizing code.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Performance Engineer
+
+Specialist in analyzing and optimizing application performance, identifying bottlenecks, and implementing efficiency improvements.
+
+## When This Skill Activates
+
+Activates when you:
+- Report performance issues
+- Need performance optimization
+- Mention "slow" or "latency"
+- Want to improve efficiency
+
+## Performance Analysis Process
+
+### Phase 1: Identify the Problem
+
+1. **Define metrics**
+   - What's the baseline?
+   - What's the target?
+   - What's acceptable?
+
+2. **Measure current performance**
+   ```bash
+   # Response time
+   curl -w "@curl-format.txt" -o /dev/null -s https://example.com/users
+
+   # Database query time
+   # Add timing logs to queries
+
+   # Memory usage
+   # Use profiler
+   ```
+
+3. **Profile the application**
+   ```bash
+   # Node.js
+   node --prof app.js
+
+   # Python
+   python -m cProfile app.py
+
+   # Go
+   go test -cpuprofile=cpu.prof
+   ```
+
+### Phase 2: Find the Bottleneck
+
+Common bottleneck locations:
+
+| Layer | Common Issues |
+|-------|---------------|
+| **Database** | N+1 queries, missing indexes, large result sets |
+| **API** | Over-fetching, no caching, serial requests |
+| **Application** | Inefficient algorithms, excessive logging |
+| **Frontend** | Large bundles, re-renders, no lazy loading |
+| **Network** | Too many requests, large payloads, no compression |
+
+### Phase 3: Optimize
+
+#### Database Optimization
+
+**N+1 Queries:**
+```typescript
+// Bad: N+1 queries
+const users = await User.findAll();
+for (const user of users) {
+  user.posts = await Post.findAll({ where: { userId: user.id } });
+}
+
+// Good: Eager loading
+const users = await User.findAll({
+  include: [{ model: Post, as: 'posts' }]
+});
+```
+
+**Missing Indexes:**
+```sql
+-- Add index on frequently queried columns
+CREATE INDEX idx_user_email ON users(email);
+CREATE INDEX idx_post_user_id ON posts(user_id);
+```
+
+#### API Optimization
+
+**Pagination:**
+```typescript
+// Always paginate large result sets
+const users = await User.findAll({
+  limit: 100,
+  offset: page * 100
+});
+```
+
+**Field Selection:**
+```typescript
+// Select only needed fields
+const users = await User.findAll({
+  attributes: ['id', 'name', 'email']
+});
+```
+
+**Compression:**
+```typescript
+// Enable gzip compression
+app.use(compression());
+```
+
+#### Frontend Optimization
+
+**Code Splitting:**
+```typescript
+// Lazy load routes
+const Dashboard = lazy(() => import('./Dashboard'));
+```
+
+**Memoization:**
+```typescript
+// Use useMemo for expensive calculations
+const filtered = useMemo(() =>
+  items.filter(item => item.active),
+  [items]
+);
+```
+
+**Image Optimization:**
+- Use WebP format
+- Lazy load images
+- Use responsive images
+- Compress images
+
+### Phase 4: Verify
+
+1. **Measure again**
+2. **Compare to baseline**
+3. **Ensure no regressions**
+4. **Document the improvement**
+
+## Performance Targets
+
+| Metric | Target | Critical Threshold |
+|--------|--------|-------------------|
+| API Response (p50) | < 100ms | < 500ms |
+| API Response (p95) | < 500ms | < 1s |
+| API Response (p99) | < 1s | < 2s |
+| Database Query | < 50ms | < 200ms |
+| Page Load (FMP) | < 2s | < 3s |
+| Time to Interactive | < 3s | < 5s |
+| Memory Usage | < 512MB | < 1GB |
+
+## Common Optimizations
+
+### Caching Strategy
+
+```typescript
+// Cache expensive computations
+const cache = new Map();
+
+async function getUserStats(userId: string) {
+  if (cache.has(userId)) {
+    return cache.get(userId);
+  }
+
+  const stats = await calculateUserStats(userId);
+  cache.set(userId, stats);
+
+  // Invalidate after 5 minutes
+  setTimeout(() => cache.delete(userId), 5 * 60 * 1000);
+
+  return stats;
+}
+```
+
+### Batch Processing
+
+```typescript
+// Bad: Individual requests
+for (const id of userIds) {
+  await fetchUser(id);
+}
+
+// Good: Batch request
+await fetchUsers(userIds);
+```
+
+### Debouncing/Throttling
+
+```typescript
+// Debounce search input
+const debouncedSearch = debounce(search, 300);
+
+// Throttle scroll events
+const throttledScroll = throttle(handleScroll, 100);
+```
+
+## Performance Monitoring
+
+### Key Metrics
+
+- **Response Time**: Time to process request
+- **Throughput**: Requests per second
+- **Error Rate**: Failed requests percentage
+- **Memory Usage**: Heap/RAM used
+- **CPU Usage**: Processor utilization
+
+### Monitoring Tools
+
+| Tool | Purpose |
+|------|---------|
+| Lighthouse | Frontend performance |
+| New Relic | APM monitoring |
+| Datadog | Infrastructure monitoring |
+| Prometheus | Metrics collection |
+
+## Scripts
+
+Profile application:
+```bash
+python scripts/profile.py
+```
+
+Generate performance report:
+```bash
+python scripts/perf_report.py
+```
+
+## References
+
+- `references/optimization.md` - Optimization techniques
+- `references/monitoring.md` - Monitoring setup
+- `references/checklist.md` - Performance checklist

package/skills/performance-engineer/references/checklist.md

@@ -0,0 +1,6 @@
+# Performance Checklist
+
+- [ ] Baseline metrics recorded
+- [ ] Bottlenecks identified
+- [ ] Fixes verified with benchmarks
+- [ ] Regression tests added

package/skills/performance-engineer/references/monitoring.md

@@ -0,0 +1,5 @@
+# Performance Monitoring
+
+- Track latency percentiles
+- Monitor throughput and error rates
+- Set alerts on regressions

package/skills/performance-engineer/references/optimization.md

@@ -0,0 +1,7 @@
+# Performance Optimization Guide
+
+## Common Levers
+- Cache hot paths
+- Reduce N+1 queries
+- Minimize payload size
+- Batch network calls

package/skills/performance-engineer/scripts/perf_report.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# Template generator for performance 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 performance report.")
+    parser.add_argument("--output", default="perf-report.md", help="Output file path")
+    parser.add_argument("--name", default="example", help="System or endpoint 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"""\
+        # Performance Report
+
+        ## Summary
+        {args.name}
+
+        ## Ownership
+        - Owner: {args.owner}
+
+        ## Baseline Metrics
+        - p50 latency:
+        - p95 latency:
+        - error rate:
+        - throughput:
+
+        ## Findings
+        - Top bottlenecks
+        - Resource saturation
+
+        ## Recommendations
+        - Short-term fixes
+        - Long-term optimizations
+
+        ## Validation
+        - Benchmark commands
+        - Regression checks
+        """
+    ).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/performance-engineer/scripts/profile.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# Template generator for performance profile.
+
+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 performance profile.")
+    parser.add_argument("--output", default="perf-profile.txt", help="Output file path")
+    parser.add_argument("--name", default="example", help="Scenario name")
+    parser.add_argument("--tool", default="perf", help="Profiling tool")
+    parser.add_argument("--command", default="run-benchmark.sh", help="Command profiled")
+    parser.add_argument("--duration", default="60s", help="Profile duration")
+    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
+    args = parser.parse_args()
+
+    content = textwrap.dedent(
+        f"""\
+        Profile: {args.name}
+        Tool: {args.tool}
+        Command: {args.command}
+        Duration: {args.duration}
+
+        Environment:
+          - CPU:
+          - Memory:
+          - OS:
+          - Build:
+
+        Workload:
+          - Input size:
+          - Concurrency:
+          - Dataset:
+
+        Top Hotspots:
+          - function_a: 0.00%
+          - function_b: 0.00%
+
+        Notes:
+          - Findings summary
+        """
+    ).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/planning-with-files/README.md

@@ -0,0 +1,27 @@
+# Planning With Files
+
+> A Claude Code skill for file-based planning and progress tracking.
+
+## Installation
+
+This skill is part of the [agent-playbook](https://github.com/Charon-Fan/agent-playbook) collection.
+
+## Usage
+
+```
+You: Plan a multi-step migration and track progress in files
+You: Create a research plan and save notes and deliverables
+You: Organize this project with persistent task files
+```
+
+## Core Pattern
+
+```
+/task_plan.md  -> Phases and progress
+/notes.md      -> Research and findings
+/output.md     -> Final deliverable
+```
+
+## Notes
+
+If you prefer the original standalone workflow, see the upstream project linked in the skill documentation.

package/skills/planning-with-files/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: planning-with-files
+description: Uses persistent markdown files for general planning, progress tracking, and knowledge storage (Manus-style workflow). Use for multi-step tasks, research projects, or general organization WITHOUT mentioning PRD. For PRD-specific work, use prd-planner skill instead.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Planning with Files
+
+> "Work like Manus" — Uses persistent markdown files for planning, progress tracking, and knowledge storage.
+
+## Description
+
+A Claude Code skill that transforms your workflow to use persistent markdown files for planning and progress tracking — the pattern that made Manus AI worth billions.
+
+## The Problem
+
+Claude Code (and most AI agents) suffer from:
+- **Volatile memory** — TodoWrite tool disappears on context reset
+- **Goal drift** — Original goals get forgotten after many tool calls
+- **Hidden errors** — Failures aren't tracked, mistakes repeat
+- **Context stuffing** — Everything crammed into context instead of stored
+
+## The Solution: 3-File Pattern
+
+For every complex task, create THREE files:
+
+```text
+task_plan.md      → Track phases and progress
+notes.md          → Store research and findings
+[deliverable].md  → Final output
+```
+
+### The Workflow Loop
+
+```text
+1. Create task_plan.md with goal and phases
+2. Research → save to notes.md → update task_plan.md
+3. Read notes.md → create deliverable → update task_plan.md
+4. Deliver final output
+```
+
+## When to Use
+
+**Use this pattern for:**
+- Multi-step tasks (3+ steps)
+- Research tasks
+- Building/creating projects
+- Tasks spanning many tool calls
+- Anything requiring organization
+
+**Skip for:**
+- Simple questions
+- Single-file edits
+- Quick lookups
+
+## Installation
+
+This skill is typically installed globally at `~/.claude/skills/planning-with-files/`.
+
+From this repository:
+
+```bash
+ln -s /path/to/agent-playbook/skills/planning-with-files ~/.claude/skills/planning-with-files
+```
+
+If you prefer the standalone workflow, see the upstream repository in the Links section.
+
+## The Manus Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Filesystem as memory | Store in files, not context |
+| Attention manipulation | Re-read plan before decisions |
+| Error persistence | Log failures in plan file |
+| Goal tracking | Checkboxes show progress |
+| Append-only context | Never modify history |
+
+## Example
+
+**You:** "Research the benefits of TypeScript and write a summary"
+
+**Claude creates:**
+
+```markdown
+# Task Plan: TypeScript Benefits Research
+
+## Goal
+Create a research summary on TypeScript benefits.
+
+## Phases
+- [x] Phase 1: Create plan ✓
+- [ ] Phase 2: Research and gather sources (CURRENT)
+- [ ] Phase 3: Synthesize findings
+- [ ] Phase 4: Deliver summary
+
+## Status
+**Currently in Phase 2** - Searching for sources
+```
+
+## Links
+
+- [GitHub Repository](https://github.com/OthmanAdi/planning-with-files)
+- [Context Engineering for AI Agents](https://manus.im/de/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus)

package/skills/prd-implementation-precheck/README.md

@@ -0,0 +1,97 @@
+# PRD Implementation Precheck
+
+A skill that performs mandatory preflight review before implementing PRDs, ensuring issues are caught before coding begins.
+
+## Overview
+
+Instead of blindly implementing a PRD, this skill:
+1. Reviews the PRD for scope, alignment, dependencies, and risks
+2. Presents findings and questions to the user
+3. Waits for confirmation before proceeding
+4. Implements with minimal, consistent changes
+
+## Installation
+
+```bash
+# Create symbolic link to global skills directory
+ln -s ~/Documents/code/GitHub/agent-playbook/skills/prd-implementation-precheck/SKILL.md ~/.claude/skills/prd-implementation-precheck.md
+```
+
+## Usage
+
+```bash
+# Ask to implement a PRD
+"Implement the PRD at docs/feature-prd.md"
+
+# The skill will:
+# 1. Read and analyze the PRD
+# 2. Present precheck report with questions
+# 3. Wait for your confirmation
+# 4. Implement after approval
+```
+
+## Precheck Checklist
+
+| Category | What's Checked |
+|----------|---------------|
+| **Scope** | Over-broad changes? Suggest targeted approach |
+| **Alignment** | Conflicts with existing patterns? Propose alternatives |
+| **Dependencies** | Missing hooks/providers/data sources? |
+| **Behavior** | Flows and edge cases specified? |
+| **Risks** | Performance, regression, migration issues? |
+| **Testing** | Success criteria and test coverage clear? |
+
+## Workflow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PRD Implementation                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Locate PRD → Read all referenced files                  │
+│  2. Precheck → Run checklist, identify issues              │
+│  3. Present → Show findings, ask questions                  │
+│  4. Confirm → User approves or updates PRD                  │
+│  5. Implement → Minimal, consistent changes                 │
+│  6. Validate → Tests or manual verification                 │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Output Example
+
+```markdown
+## Precheck Report for {PRD}
+
+### Intent
+{1-2 sentence summary}
+
+### Blockers
+- [ ] Blocker 1
+- [ ] Blocker 2
+
+### Questions
+1. Question about scope?
+2. Question about dependencies?
+
+### Risks
+- Risk 1
+- Risk 2
+
+### Recommendation
+Proceed as-is, or update the PRD first?
+```
+
+## Benefits
+
+| Problem | Solution |
+|---------|----------|
+| Implementing unclear PRDs | Precheck catches gaps |
+| Scope creep | Identified early |
+| Breaking existing patterns | Flagged before coding |
+| Missing dependencies | Found before implementation |
+| Unclear success criteria | Clarified upfront |
+
+## License
+
+MIT