bobs-workshop 0.3.3 → 3.1.0

package/src/skills/performance/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: performance
+description: Performance analysis, bottleneck identification, and optimization strategies.
+---
+# Performance Analysis Skill
+
+**Skill ID**: performance
+**Category**: Code Quality & Optimization
+**Icon**: 📈
+**Agents**: bob-eng, bob-fix
+
+## Overview
+
+This skill provides performance analysis capabilities for identifying bottlenecks, anti-patterns, and optimization opportunities in code. Use this skill during implementation to avoid performance issues, and during debugging to identify root causes.
+
+## When to Use
+
+Use the `performance` skill when:
+
+- Writing or reviewing loops and iterations
+- Working with data structures and algorithms
+- Analyzing I/O operations (file, network, database)
+- Reviewing caching strategies
+- Identifying memory allocation patterns
+- Analyzing async/await usage
+- Reviewing dependency usage patterns
+
+## Analysis Patterns
+
+### 1. Loop Optimization
+
+**Check for**:
+- Nested loops with high complexity
+- Repeated calculations in loops
+- Inefficient data structure access patterns
+- Missing break/continue conditions
+
+### 2. Memory Allocation
+
+**Check for**:
+- Unnecessary object/array creation in hot paths
+- String concatenation in loops
+- Missing cleanup/disposal patterns
+- Closure captures that prevent garbage collection
+
+### 3. Async Operations
+
+**Check for**:
+- Sequential awaits that could be parallel
+- Missing error handling in async flows
+- Uncontrolled concurrency
+- Memory leaks in async patterns
+
+### 4. Data Structure Selection
+
+**Check for**:
+- Array operations that should use Set/Map
+- Linear searches that could use indexing
+- Object property access that could use Map
+- Repeated sorting of same data
+
+## Common Performance Anti-Patterns
+
+### Anti-Pattern 1: Fetch Loops
+```typescript
+// BAD: N+1 queries
+for (const order of orders) {
+  const items = await db.query('SELECT * FROM items WHERE order_id = ?', order.id);
+  order.items = items;
+}
+
+// GOOD: Single query with JOIN
+const orders = await db.query(`
+  SELECT o.*, i.* FROM orders o
+  LEFT JOIN items i ON i.order_id = o.id
+`);
+```
+
+### Anti-Pattern 2: In-Memory Filtering
+```typescript
+// BAD: Brings all data, filters in memory
+const allUsers = await db.query('SELECT * FROM users');
+const active = allUsers.filter(u => u.active);
+
+// GOOD: Filters at database
+const active = await db.query('SELECT * FROM users WHERE active = true');
+```
+
+## Performance Checklist
+
+When analyzing code, check for:
+
+- [ ] **Complexity**: Are there O(n²) or worse patterns?
+- [ ] **Memory**: Are objects being created unnecessarily?
+- [ ] **I/O**: Are operations blocking or synchronous?
+- [ ] **Concurrency**: Are async operations parallelized when possible?
+- [ ] **Data Structures**: Is the right structure being used?
+- [ ] **Caching**: Can results be cached or memoized?
+- [ ] **Batching**: Can operations be batched?
+- [ ] **Lazy Loading**: Can expensive operations be deferred?
+
+## Optimization Strategies
+
+### Strategy 1: Lazy Evaluation
+```typescript
+// Eager: Always computes
+const fullName = `${user.firstName} ${user.lastName}`;
+
+// Lazy: Computes only when needed
+const getFullName = () => `${user.firstName} ${user.lastName}`;
+```
+
+### Strategy 2: Memoization
+```typescript
+function memoize<T, R>(fn: (arg: T) => R): (arg: T) => R {
+  const cache = new Map<T, R>();
+  return (arg: T): R => {
+    if (cache.has(arg)) return cache.get(arg)!;
+    const result = fn(arg);
+    cache.set(arg, result);
+    return result;
+  };
+}
+```
+
+### Strategy 3: Batch Processing
+```typescript
+async function processItems(items: Item[]): Promise<void> {
+  const CHUNK_SIZE = 100;
+  for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+    const chunk = items.slice(i, i + CHUNK_SIZE);
+    await processChunk(chunk);
+  }
+}
+```
+
+## Integration with Other Skills
+
+| Skill | Use Case |
+|-------|----------|
+| `exploration` | Identify hot paths in codebase |
+| `quality` | Combined quality + performance review |
+| `design` | Performance-aware architecture decisions |
+| `verification` | Validate performance improvements |

package/src/skills/performance/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#10b981" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M22 12h-4l-3 9L9 3l-3 9H2"/>
+</svg>

package/src/skills/plan-writing/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: plan-writing
+description: Structured task planning with clear breakdowns, dependencies, and verification criteria.
+metadata:
+  recommended_for: alice
+  category: planning
+---
+
+# Plan Writing
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
+
+## Task Breakdown Principles
+
+### 1. Small, Focused Tasks
+- Each task should take 2-5 minutes
+- One clear outcome per task
+- Independently verifiable
+
+### 2. Clear Verification
+- How do you know it's done?
+- What can you check/test?
+- What's the expected output?
+
+### 3. Logical Ordering
+- Dependencies identified
+- Parallel work where possible
+- Critical path highlighted
+- **Phase X: Verification is always LAST**
+
+### 4. Dynamic Naming in Project Root
+- Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
+- Name derived from task (e.g., "add auth" → `auth-feature.md`)
+- **NEVER** inside `.claude/`, `docs/`, or temp folders
+
+## Planning Principles (NOT Templates!)
+
+> 🔴 **NO fixed templates. Each plan is UNIQUE to the task.**
+
+### Principle 1: Keep It SHORT
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
+| Every micro-step listed | Only actionable items |
+| Verbose descriptions | One-line per task |
+
+> **Rule:** If plan is longer than 1 page, it's too long. Simplify.
+
+---
+
+### Principle 2: Be SPECIFIC, Not Generic
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Set up project" | "Run `npx create-next-app`" |
+| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
+| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
+
+> **Rule:** Each task should have a clear, verifiable outcome.
+
+---
+
+### Principle 3: Dynamic Content Based on Project Type
+
+**For NEW PROJECT:**
+- What tech stack? (decide first)
+- What's the MVP? (minimal features)
+- What's the file structure?
+
+**For FEATURE ADDITION:**
+- Which files are affected?
+- What dependencies needed?
+- How to verify it works?
+
+**For BUG FIX:**
+- What's the root cause?
+- What file/line to change?
+- How to test the fix?
+
+---
+
+### Principle 4: Scripts Are Project-Specific
+
+> 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
+
+| Project Type | Relevant Scripts |
+|--------------|------------------|
+| Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
+| Backend/API | `api_validator.py`, `security_scan.py` |
+| Mobile | `mobile_audit.py` |
+| Database | `schema_validator.py` |
+| Full-stack | Mix of above based on what you touched |
+
+**Wrong:** Adding all scripts to every plan
+**Right:** Only scripts relevant to THIS task
+
+---
+
+### Principle 5: Verification is Simple
+
+| ❌ Wrong | ✅ Right |
+|----------|----------|
+| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
+| "Test the API" | "curl localhost:3000/api/users returns 200" |
+| "Check styles" | "Open browser, verify dark mode toggle works" |
+
+---
+
+## Plan Structure (Flexible, Not Fixed!)
+
+```
+# [Task Name]
+
+## Goal
+One sentence: What are we building/fixing?
+
+## Tasks
+- [ ] Task 1: [Specific action] → Verify: [How to check]
+- [ ] Task 2: [Specific action] → Verify: [How to check]
+- [ ] Task 3: [Specific action] → Verify: [How to check]
+
+## Done When
+- [ ] [Main success criteria]
+```
+
+> **That's it.** No phases, no sub-sections unless truly needed.
+> Keep it minimal. Add complexity only when required.
+
+## Notes
+[Any important considerations]
+```
+
+---
+
+## Best Practices (Quick Reference)
+
+1. **Start with goal** - What are we building/fixing?
+2. **Max 10 tasks** - If more, break into multiple plans
+3. **Each task verifiable** - Clear "done" criteria
+4. **Project-specific** - No copy-paste templates
+5. **Update as you go** - Mark `[x]` when complete
+
+---
+
+## When to Use
+
+- New project from scratch
+- Adding a feature
+- Fixing a bug (if complex)
+- Refactoring multiple files
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **alice (architect)** agent during the PLAN phase.
+
+### MANUAL Integration
+
+Add implementation plan to MANUAL:
+```markdown
+## 🚀 Implementation Plan
+
+### Layered Tasks
+
+#### DB-001: Database Schema
+- [ ] Create `users` table → Verify: Schema matches design doc
+- [ ] Add indexes → Verify: Queries run efficiently
+- [ ] Write migration → Verify: `npm run migrate` succeeds
+
+#### BE-001: Backend API
+- [ ] Create `/api/users` endpoint → Verify: Returns 200
+- [ ] Add auth middleware → Verify: Protects routes
+- [ ] Write unit tests → Verify: All tests pass
+
+#### FE-001: Frontend Components
+- [ ] Create UserList component → Verify: Renders users
+- [ ] Add edit button → Verify: Opens modal
+- [ ] Style with Tailwind → Verify: Matches design
+
+#### TEST-001: Integration Tests
+- [ ] Add E2E test for user flow → Verify: Playwright passes
+- [ ] Add API integration test → Verify: All endpoints tested
+
+### Dependencies
+- DB-001 must complete before BE-001
+- BE-001 must complete before TEST-001
+- FE-001 and BE-001 can run in parallel
+```
+
+### Task Size Guidelines
+
+Each task should be:
+- **2-5 minutes** to implement
+- **1 file or small set of files** to edit
+- **1 clear outcome** to verify
+- **Independently testable** when possible
+
+### Verification Criteria Format
+
+For each task, include:
+```markdown
+- [ ] [Task description] → Verify: [Specific check]
+```
+
+Examples:
+```markdown
+- [ ] Create UserList component → Verify: Renders in browser at `/users`
+- [ ] Add delete function → Verify: Clicking delete removes user from list
+- [ ] Add error handling → Verify: Error shows toast notification
+```
+
+### Handoff Format
+
+When plan is complete:
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 alice: Implementation plan complete - 12 tasks across 4 layers
+🤝 alice → bob-eng: MANUAL ready - proceeding to BUILD phase
+```