vibe-and-thrive 1.0.0

package/.claude/commands/fix-types.md

@@ -0,0 +1,238 @@
+# Fix Types
+
+Fix TypeScript type errors without using `any`. Create proper interfaces and types.
+
+## Instructions
+
+When asked to fix TypeScript types:
+
+### Step 1: Understand the Error
+
+Read the TypeScript error message carefully:
+- What type is expected?
+- What type is being provided?
+- Where is the mismatch?
+
+### Step 2: Investigate the Data
+
+Before creating types:
+1. Check if types already exist elsewhere in the codebase
+2. Look at the API response or data source
+3. Understand the shape of the data
+
+### Step 3: Create Proper Types
+
+Instead of using `any`, create specific interfaces:
+
+```typescript
+// DON'T do this
+const data: any = await fetchUser();
+
+// DO this
+interface User {
+  id: number;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+
+const data: User = await fetchUser();
+```
+
+### Step 4: Handle Uncertainty
+
+When you don't know the exact type:
+
+**Option 1: Use `unknown` and narrow**
+```typescript
+function processData(data: unknown) {
+  if (isUser(data)) {
+    // TypeScript now knows data is User
+    console.log(data.email);
+  }
+}
+
+function isUser(data: unknown): data is User {
+  return (
+    typeof data === 'object' &&
+    data !== null &&
+    'email' in data &&
+    'id' in data
+  );
+}
+```
+
+**Option 2: Use generics**
+```typescript
+async function fetchData<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+  return response.json();
+}
+
+const user = await fetchData<User>('/api/user');
+```
+
+**Option 3: Use partial types for incomplete data**
+```typescript
+interface UserInput {
+  email: string;
+  name?: string;  // Optional during creation
+}
+
+interface User extends UserInput {
+  id: number;
+  createdAt: string;
+}
+```
+
+## Common Type Fixes
+
+### API Response Types
+```typescript
+// Instead of: const response: any = await api.get('/users')
+
+interface ApiResponse<T> {
+  data: T;
+  status: number;
+  message?: string;
+}
+
+interface User {
+  id: number;
+  email: string;
+  name: string;
+}
+
+const response: ApiResponse<User[]> = await api.get('/users');
+```
+
+### Event Handler Types
+```typescript
+// Instead of: const handleChange = (e: any) => {}
+
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  setValue(e.target.value);
+};
+
+const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+  e.preventDefault();
+};
+```
+
+### Object with Dynamic Keys
+```typescript
+// Instead of: const cache: any = {}
+
+const cache: Record<string, User> = {};
+// or
+const cache: { [key: string]: User } = {};
+```
+
+### Union Types for Multiple Possibilities
+```typescript
+// Instead of: function process(input: any)
+
+type ProcessInput = string | number | Buffer;
+
+function process(input: ProcessInput) {
+  if (typeof input === 'string') {
+    // TypeScript knows input is string here
+  }
+}
+```
+
+### Third-Party Library Types
+```typescript
+// If library lacks types, create a declaration file
+
+// types/some-library.d.ts
+declare module 'some-library' {
+  export function doThing(input: string): Promise<Result>;
+
+  export interface Result {
+    success: boolean;
+    data: unknown;
+  }
+}
+```
+
+## Output Format
+
+```markdown
+## Type Fix: [filename]
+
+### The Error
+```
+[Original TypeScript error message]
+```
+
+### Analysis
+[What's causing the error and why]
+
+### Solution
+
+**Step 1: Create interfaces**
+```typescript
+[New interface definitions]
+```
+
+**Step 2: Apply types**
+
+Before:
+```typescript
+[Original code with any/type errors]
+```
+
+After:
+```typescript
+[Fixed code with proper types]
+```
+
+### Why This Is Better
+- [Benefit 1: e.g., "IDE autocomplete now works"]
+- [Benefit 2: e.g., "Catches typos at compile time"]
+- [Benefit 3: e.g., "Documents the data shape"]
+```
+
+## Never Use These (Without Good Reason)
+
+| Avoid | Use Instead |
+|-------|-------------|
+| `any` | Specific type, `unknown`, or generic |
+| `@ts-ignore` | Fix the actual type error |
+| `as any` | Proper type assertion or type guard |
+| `// @ts-nocheck` | Fix file's type errors |
+
+## When `any` Might Be Acceptable
+
+Rare cases where `any` is okay (document why!):
+
+```typescript
+// Working with truly dynamic data that can't be typed
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function logAnything(data: any): void {
+  console.log(JSON.stringify(data));
+}
+
+// Interfacing with untyped third-party library
+// TODO: Create proper types when time permits
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const result: any = legacyLibrary.doThing();
+```
+
+## Type Inference Tips
+
+Let TypeScript infer when it can:
+
+```typescript
+// Unnecessary explicit type
+const name: string = 'Alice';  // TypeScript already knows this is string
+
+// Let it infer
+const name = 'Alice';
+
+// But DO be explicit for function return types
+function getUser(id: number): User | null {
+  // ...
+}
+```

package/.claude/commands/refactor.md

@@ -0,0 +1,184 @@
+# Refactor Code
+
+Guided refactoring with explanations of why each change improves the code.
+
+## Instructions
+
+When asked to refactor code:
+
+### Step 1: Understand Current State
+
+Before changing anything:
+1. Read and understand the existing code
+2. Identify what it's supposed to do
+3. Check for existing tests
+4. Note the current patterns in use
+
+### Step 2: Identify Refactoring Opportunities
+
+Look for:
+
+**Structural Issues**
+- Functions doing too many things
+- Deep nesting
+- Long parameter lists
+- Feature envy (method uses another class's data more than its own)
+
+**Duplication**
+- Copy-pasted code
+- Similar functions that could be generalized
+- Repeated patterns
+
+**Naming**
+- Unclear variable/function names
+- Inconsistent naming conventions
+- Names that don't match behavior
+
+**Complexity**
+- Overly clever code
+- Unnecessary abstractions
+- Missing abstractions
+
+### Step 3: Plan the Refactoring
+
+Before making changes, explain:
+1. What you're going to change
+2. Why each change improves the code
+3. What risks to watch for
+
+### Step 4: Make Changes Incrementally
+
+For each change:
+1. Show the before state
+2. Show the after state
+3. Explain the improvement
+4. Verify behavior is preserved
+
+### Step 5: Verify
+
+After refactoring:
+1. Run existing tests (if any)
+2. Manually verify the code still works
+3. Check that the refactoring achieved its goals
+
+## Output Format
+
+```markdown
+## Refactoring: [filename or description]
+
+### Current State
+[Brief description of current code and its issues]
+
+### Refactoring Plan
+1. [Change 1] - [Why]
+2. [Change 2] - [Why]
+3. [Change 3] - [Why]
+
+### Change 1: [Description]
+
+**Before:**
+```[language]
+[original code]
+```
+
+**After:**
+```[language]
+[refactored code]
+```
+
+**Why this is better:**
+- [Benefit 1]
+- [Benefit 2]
+
+### Change 2: [Description]
+[... repeat pattern ...]
+
+### Final Result
+
+**Before (complete):**
+```[language]
+[all original code]
+```
+
+**After (complete):**
+```[language]
+[all refactored code]
+```
+
+### Summary of Improvements
+- [Improvement 1]
+- [Improvement 2]
+- [Improvement 3]
+
+### Verification
+- [ ] Existing tests pass
+- [ ] Behavior unchanged
+- [ ] Code is cleaner/simpler
+```
+
+## Common Refactorings
+
+### Extract Function
+**When:** Code does multiple things or is deeply nested
+```python
+# Before
+def process_order(order):
+    # validate
+    if not order.items:
+        raise Error("No items")
+    if not order.customer:
+        raise Error("No customer")
+    # calculate
+    total = sum(item.price for item in order.items)
+    # save
+    db.save(order)
+
+# After
+def process_order(order):
+    validate_order(order)
+    order.total = calculate_total(order)
+    save_order(order)
+
+def validate_order(order):
+    if not order.items:
+        raise Error("No items")
+    if not order.customer:
+        raise Error("No customer")
+```
+
+### Replace Conditionals with Polymorphism
+**When:** Multiple if/else checking type
+
+### Introduce Parameter Object
+**When:** Function has many related parameters
+
+### Replace Magic Numbers with Constants
+**When:** Hardcoded numbers with unclear meaning
+
+### Simplify Conditionals
+**When:** Complex boolean expressions
+
+### Remove Dead Code
+**When:** Code that's never executed
+
+## Refactoring Modes
+
+### Safe Refactoring
+Only make changes that clearly preserve behavior:
+> "Safely refactor this without changing behavior"
+
+### Aggressive Refactoring
+Restructure more significantly:
+> "Refactor this to follow clean code principles"
+
+### Targeted Refactoring
+Fix a specific issue:
+> "Refactor to reduce the nesting in this function"
+
+## Important Rules
+
+1. **Never change behavior** while refactoring
+2. **Make small changes** - one refactoring at a time
+3. **Test after each change** if possible
+4. **Explain every change** - this is a teaching tool
+5. **Keep it simple** - don't over-engineer

package/.claude/commands/review.md

@@ -0,0 +1,136 @@
+# Code Review
+
+Review code for issues, improvements, and best practices.
+
+## Instructions
+
+When asked to review code, perform a thorough analysis looking for:
+
+### 1. Security Issues (Critical)
+
+- [ ] SQL injection vulnerabilities
+- [ ] XSS (cross-site scripting) risks
+- [ ] Hardcoded secrets or credentials
+- [ ] Unsafe data handling
+- [ ] Missing authentication/authorization checks
+- [ ] Insecure dependencies
+
+### 2. Error Handling (High)
+
+- [ ] Empty catch blocks
+- [ ] Missing error boundaries
+- [ ] Unhandled promise rejections
+- [ ] Missing null/undefined checks
+- [ ] Silent failures
+
+### 3. Type Safety (High for TypeScript)
+
+- [ ] Usage of `any` type
+- [ ] Missing type annotations
+- [ ] Type assertions that could fail
+- [ ] Inconsistent types
+
+### 4. Code Quality (Medium)
+
+- [ ] Functions over 50 lines
+- [ ] Deep nesting (4+ levels)
+- [ ] Code duplication
+- [ ] Magic numbers
+- [ ] Unclear variable names
+- [ ] Missing or outdated comments
+
+### 5. Performance (Medium)
+
+- [ ] N+1 query patterns
+- [ ] Missing memoization for expensive operations
+- [ ] Unnecessary re-renders (React)
+- [ ] Large bundle imports
+- [ ] Missing pagination
+
+### 6. Maintainability (Low)
+
+- [ ] Dead code
+- [ ] Commented-out code
+- [ ] TODOs that should be addressed
+- [ ] Inconsistent patterns
+- [ ] Missing tests
+
+## Output Format
+
+Structure your review like this:
+
+```markdown
+## Code Review: [filename or description]
+
+### Summary
+[1-2 sentence overview of the code quality]
+
+### Critical Issues
+These must be fixed before merging:
+
+1. **[Issue Title]** (Line X)
+   - Problem: [What's wrong]
+   - Risk: [What could happen]
+   - Fix: [How to fix it]
+   ```
+   [Code suggestion if applicable]
+   ```
+
+### Improvements
+These should be addressed:
+
+1. **[Issue Title]** (Line X)
+   - Current: [What it does now]
+   - Better: [What it should do]
+   - Why: [Benefit of changing]
+
+### Minor Suggestions
+Nice to have, low priority:
+
+1. **[Suggestion]** (Line X)
+   - [Brief explanation]
+
+### What's Good
+[Acknowledge good patterns and practices in the code]
+
+### Verdict
+[ ] Ready to merge
+[ ] Needs minor changes
+[ ] Needs significant changes
+[ ] Needs rewrite
+```
+
+## Severity Guide
+
+| Severity | Block Merge? | Examples |
+|----------|--------------|----------|
+| Critical | Yes | Security vulnerabilities, data loss risks |
+| High | Yes | Missing error handling, type safety issues |
+| Medium | Review | Performance issues, code quality |
+| Low | No | Style preferences, minor improvements |
+
+## Review Modes
+
+### Quick Review
+Focus only on critical and high-severity issues:
+> "Quick review of this code"
+
+### Full Review
+Check everything:
+> "Full review of src/api/users.ts"
+
+### Security Review
+Focus on security concerns:
+> "Security review of the authentication flow"
+
+### Performance Review
+Focus on performance:
+> "Performance review of the dashboard page"
+
+## Be Constructive
+
+- Explain **why** something is an issue, not just that it is
+- Provide **specific** suggestions for fixes
+- Acknowledge what's **done well**
+- Be **respectful** - we all make mistakes
+- Focus on the **code**, not the coder