cursor-ai-toolkit 1.0.0

package/commands/learning/generate-rules.md

@@ -0,0 +1,175 @@
+---
+description: Analyze codebase patterns and auto-generate .mdc rules for enforcement
+category: AI Self-Improvement
+aliases: [gen-rules, create-rules, extract-patterns]
+---
+
+# Generate Rules - Auto-create .mdc Rules from Patterns
+
+Analyze codebase patterns and generate specialized `.mdc` rule files for real-time enforcement.
+
+## Usage
+
+```
+/generate-rules                     # Analyze entire codebase
+/generate-rules {PATH}              # Analyze specific directory
+/generate-rules --domain auth       # Focus on specific domain
+```
+
+## What This Does
+
+1. **Analyzes codebase patterns** - Scans for conventions, antipatterns, and styles
+2. **Extracts implicit rules** - Identifies what makes "good" code in your repo
+3. **Generates .mdc files** - Creates Cursor rules for real-time enforcement
+4. **Validates existing rules** - Checks if current rules match actual patterns
+
+## Generated Rule Types
+
+| Rule File                | Purpose             | Auto-detects              |
+| ------------------------ | ------------------- | ------------------------- |
+| `component-patterns.mdc` | Component structure | File organization, naming |
+| `hook-patterns.mdc`      | Hook conventions    | Custom hook patterns      |
+| `api-patterns.mdc`       | API client patterns | Error handling, types     |
+| `testing-patterns.mdc`   | Test conventions    | AAA pattern, mocks        |
+| `domain-{name}.mdc`      | Domain-specific     | Business logic patterns   |
+
+## Analysis Process
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 1: Pattern Extraction                                 │
+├─────────────────────────────────────────────────────────────┤
+│  • Scan files by type (.tsx, .ts, .styled.ts)               │
+│  • Extract import patterns                                  │
+│  • Identify naming conventions                              │
+│  • Detect hook usage patterns                               │
+│  • Find error handling patterns                             │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 2: Frequency Analysis                                 │
+├─────────────────────────────────────────────────────────────┤
+│  • Count pattern occurrences                                │
+│  • Identify dominant patterns (>70% usage)                  │
+│  • Flag antipatterns (patterns in high-churn files)         │
+│  • Correlate with git history (stable vs unstable)          │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 3: Rule Generation                                    │
+├─────────────────────────────────────────────────────────────┤
+│  • Create .mdc file with frontmatter                        │
+│  • Define glob patterns for application                     │
+│  • Write enforcement rules with examples                    │
+│  • Add good/bad pattern comparisons                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Example Output
+
+```
+📋 Analyzing codebase patterns...
+
+════════════════════════════════════════════════════════════════
+  PATTERN ANALYSIS RESULTS
+════════════════════════════════════════════════════════════════
+
+## Detected Patterns
+
+### Component Patterns (423 files analyzed)
+✅ Styled component namespace: 98% use `* as S`
+✅ Feature folder structure: 87% follow standard
+⚠️ Barrel files: 23% still use index.ts (antipattern)
+✅ Type separation: 92% use .types.ts files
+
+### Hook Patterns (918 hooks analyzed)
+✅ AbortController cleanup: 76% compliance
+⚠️ watch() usage: 12% still use (should be useWatch)
+✅ Single responsibility: 89% focused hooks
+⚠️ God hooks (>15 returns): 8% of hooks
+
+### API Patterns (55 clients analyzed)
+✅ ApiError type: 94% usage
+✅ Generic response types: 91% typed
+⚠️ Retry logic: Only 34% implement
+
+## Generated Rules
+
+📁 Created: .cursor/rules/component-patterns.mdc
+   - Styled component namespace enforcement
+   - Feature folder structure requirement
+   - No barrel files in components
+
+📁 Created: .cursor/rules/hook-patterns.mdc
+   - AbortController requirement
+   - useWatch over watch()
+   - Single responsibility enforcement
+
+📁 Created: .cursor/rules/api-patterns.mdc
+   - ApiError typing requirement
+   - Response type generics
+
+════════════════════════════════════════════════════════════════
+  3 rule files created in .cursor/rules/
+════════════════════════════════════════════════════════════════
+```
+
+## Commands Used
+
+```bash
+# Find dominant patterns
+grep -rh "import \* as S" --include="*.tsx" apps/ libraries/ | wc -l
+
+# Find antipatterns
+grep -rl "methods\.watch()" --include="*.tsx" apps/ | wc -l
+
+# Check hook returns
+grep -A 50 "^export const use" --include="*.ts" apps/*/src/hooks/ | \
+  grep -c "return {"
+
+# Correlate with churn
+git log --oneline --after="2024-01-01" --name-only | \
+  grep "\.tsx$" | sort | uniq -c | sort -rn | head -20
+```
+
+## Rule File Format
+
+Generated `.mdc` files follow this structure:
+
+```markdown
+---
+description: { Description }
+globs: ['{glob patterns}']
+alwaysApply: { true/false }
+---
+
+# {Rule Name}
+
+## Enforced Patterns
+
+### ✅ REQUIRED: {Pattern Name}
+
+\`\`\`typescript
+// Good example
+\`\`\`
+
+### ❌ FORBIDDEN: {Antipattern Name}
+
+\`\`\`typescript
+// Bad example - never generate
+\`\`\`
+
+## Rationale
+
+{Why this pattern matters, backed by data}
+```
+
+## AI Execution
+
+When user runs `/generate-rules`:
+
+1. **Scan codebase** for file types and patterns
+2. **Extract conventions** using regex and AST analysis
+3. **Correlate with history** to identify stable vs unstable patterns
+4. **Generate .mdc files** with proper frontmatter
+5. **Report coverage** and any gaps detected

package/commands/learning/self-heal.md

@@ -0,0 +1,233 @@
+---
+description: Fix a bug and proactively find/fix similar antipatterns across the codebase
+category: AI Self-Improvement
+aliases: [heal, fix-pattern, fix-all]
+---
+
+# Self-Heal - Proactive Pattern Fixing
+
+Fix a bug and proactively find/fix similar patterns across the codebase.
+
+## Usage
+
+```
+/self-heal {ERROR_LOG}
+/self-heal {FILE:LINE} "Description of issue"
+/self-heal --pattern "watch()" --fix "useWatch()"
+/self-heal --sentry {ISSUE_ID}
+```
+
+## What This Does
+
+1. **Analyzes error** - Understands root cause
+2. **Fixes immediate issue** - Applies fix to reported location
+3. **Finds similar patterns** - Searches codebase for same antipattern
+4. **Proactively fixes** - Applies fix to all occurrences
+5. **Prevents future** - Adds to .mdc rules if pattern is common
+
+## Self-Healing Process
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 1: Analyze Error                                      │
+├─────────────────────────────────────────────────────────────┤
+│  • Parse error message and stack trace                      │
+│  • Identify root cause pattern                              │
+│  • Classify error type                                      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 2: Fix Immediate Issue                                │
+├─────────────────────────────────────────────────────────────┤
+│  • Apply targeted fix                                       │
+│  • Verify fix compiles                                      │
+│  • Run related tests                                        │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 3: Find Similar Patterns                              │
+├─────────────────────────────────────────────────────────────┤
+│  • Search codebase for same pattern                         │
+│  • Filter by risk (same conditions apply)                   │
+│  • Rank by likelihood of failure                            │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 4: Proactive Healing                                  │
+├─────────────────────────────────────────────────────────────┤
+│  • Apply same fix to all occurrences                        │
+│  • Create separate PR or same PR                            │
+│  • Document in commit message                               │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│  STEP 5: Prevent Recurrence                                 │
+├─────────────────────────────────────────────────────────────┤
+│  • Add pattern to .cursor/rules/ if common                  │
+│  • Create ESLint rule if applicable                         │
+│  • Update /code-standards                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Example: Race Condition Fix
+
+````
+/self-heal "TypeError: Cannot read property 'data' of null"
+
+────────────────────────────────────────────────────────────────
+  ERROR ANALYSIS
+────────────────────────────────────────────────────────────────
+
+Error: TypeError: Cannot read property 'data' of null
+File: src/features/checkout/src/hooks/useBookingData.ts:45
+Stack: useBookingData → useEffect → fetchData → setData
+
+Root Cause: Race condition - component unmounted before async resolved
+
+Pattern Detected:
+```typescript
+// ❌ Antipattern: No cleanup, state update on unmounted component
+useEffect(() => {
+    fetchData().then(result => {
+        setData(result.data);  // May run after unmount
+    });
+}, [id]);
+````
+
+────────────────────────────────────────────────────────────────
+IMMEDIATE FIX
+────────────────────────────────────────────────────────────────
+
+Applied to: useBookingData.ts:45
+
+```typescript
+// ✅ Fixed: AbortController prevents race condition
+useEffect(() => {
+    const controller = new AbortController();
+
+    const fetchData = async () => {
+        try {
+            const result = await api.getData(id, { signal: controller.signal });
+            setData(result.data);
+        } catch (err) {
+            if (!controller.signal.aborted) {
+                setError(err as ApiError);
+            }
+        }
+    };
+
+    fetchData();
+    return () => controller.abort();
+}, [id]);
+```
+
+────────────────────────────────────────────────────────────────
+SIMILAR PATTERNS FOUND
+────────────────────────────────────────────────────────────────
+
+Searching for: `useEffect.*fetchData.*then.*set[A-Z]` without AbortController
+
+| File                 | Line | Risk      | Status          |
+| -------------------- | ---- | --------- | --------------- |
+| useOfferData.ts      | 23   | 🔴 HIGH   | Same pattern    |
+| useUserProfile.ts    | 56   | 🔴 HIGH   | Same pattern    |
+| usePaymentMethods.ts | 34   | 🔴 HIGH   | Same pattern    |
+| useBranches.ts       | 89   | 🟠 MEDIUM | Similar pattern |
+| useVehicles.ts       | 12   | 🟠 MEDIUM | Similar pattern |
+
+Total: 5 files with same antipattern
+
+────────────────────────────────────────────────────────────────
+PROACTIVE HEALING
+────────────────────────────────────────────────────────────────
+
+Applying fix to 5 additional files...
+
+✅ useOfferData.ts:23 - Fixed
+✅ useUserProfile.ts:56 - Fixed
+✅ usePaymentMethods.ts:34 - Fixed
+✅ useBranches.ts:89 - Fixed
+✅ useVehicles.ts:12 - Fixed
+
+All files compile successfully.
+
+────────────────────────────────────────────────────────────────
+PREVENTION
+────────────────────────────────────────────────────────────────
+
+## Rule Added to .cursor/rules/web-standards.mdc
+
+```markdown
+### ✅ REQUIRED: AbortController for async useEffect
+
+All useEffect hooks with async operations MUST include:
+
+1. AbortController setup
+2. Signal passed to fetch/API calls
+3. Cleanup function returning controller.abort()
+4. Aborted check before setState
+```
+
+## ESLint Rule Suggestion
+
+Consider adding `eslint-plugin-react-hooks` rule:
+`exhaustive-deps` with custom cleanup checker
+
+────────────────────────────────────────────────────────────────
+SUMMARY
+────────────────────────────────────────────────────────────────
+
+| Action         | Count        |
+| -------------- | ------------ |
+| Files fixed    | 6            |
+| Bugs prevented | ~5 potential |
+| Rule added     | 1            |
+
+Commit message:
+"Fix race condition in async useEffect across 6 hooks
+
+Applied AbortController pattern to prevent state updates
+on unmounted components. Fixes TypeError in useBookingData
+and proactively prevents same issue in 5 other hooks."
+
+````
+
+## Pattern Library
+
+| Pattern | Search Regex | Fix Template |
+|---------|--------------|--------------|
+| Race condition | `useEffect.*then.*set[A-Z]` | AbortController |
+| watch() usage | `methods\.watch\(\)` | useWatch |
+| Missing memoization | `yup\.object\(` not in useMemo | useMemo wrapper |
+| Any type | `: any` | Specific type |
+| Console.log | `console\.log` | Remove or debug util |
+| Hardcoded pixels | `[0-9]+px` in styled | spacing() token |
+
+## Commands Used
+
+```bash
+# Find similar patterns
+grep -rn "useEffect.*then.*setState" --include="*.ts" apps/ libraries/
+
+# Check which files lack AbortController
+for f in $(grep -rl "useEffect.*fetch" --include="*.ts" apps/); do
+    if ! grep -q "AbortController" "$f"; then
+        echo "$f"
+    fi
+done
+
+# Verify fixes compile
+pnpm compile
+````
+
+## AI Execution
+
+When user runs `/self-heal {ERROR}`:
+
+1. **Parse error** - Extract file, line, message
+2. **Identify pattern** - Match to known antipatterns
+3. **Apply fix** - To immediate location
+4. **Search codebase** - Find similar patterns
+5. **Batch fix** - Apply to all occurrences
+6. **Update rules** - Add to .mdc if common
+7. **Report** - Summary of all changes

package/commands/learning/self-improve.md

@@ -0,0 +1,229 @@
+---
+description: Learn from user patterns, suggest command improvements, evolve automation
+category: AI Self-Improvement
+aliases: [improve, evolve, learn]
+---
+
+# Self-Improve - Learn and Evolve Commands
+
+Automatically learn from user patterns, suggest improvements, and evolve commands.
+
+## How Self-Learning Works
+
+### 1. Pattern Recognition
+
+I observe and learn from:
+
+| What I Observe              | What I Learn                      |
+| --------------------------- | --------------------------------- |
+| Commands you run frequently | Create shortcuts or combine steps |
+| Steps you always skip       | Add to auto-skip list             |
+| Clarifications you give     | Update defaults and assumptions   |
+| Corrections you make        | Update rules and patterns         |
+| Preferences you express     | Store in memory                   |
+
+### 2. Trigger Phrases
+
+When you say:
+
+-   "always do X" → I create a memory and update commands
+-   "never do Y" → I add to skip list
+-   "remember that..." → I store as preference
+-   "this is wrong because..." → I learn the correction
+-   "better way is..." → I update the approach
+
+### 3. Auto-Suggestions
+
+After each workflow, I may suggest:
+
+```
+════════════════════════════════════════════════════════════════
+  💡 IMPROVEMENT SUGGESTIONS
+════════════════════════════════════════════════════════════════
+
+Based on this session, I noticed:
+
+1. **Frequent Pattern**: You always add "How to Test" after PR creation
+   → Suggestion: Make this automatic (no confirmation)
+   → Accept? (y/n)
+
+2. **Repeated Clarification**: You always want empty string = missing
+   → Suggestion: Add as default assumption
+   → Accept? (y/n)
+
+3. **Skipped Step**: You skipped Confluence docs in last 5 runs
+   → Suggestion: Remove from default flow, make on-demand
+   → Accept? (y/n)
+
+4. **New Pattern Detected**: You often run /pr-review after /full-flow
+   → Suggestion: Create /full-flow-with-review command
+   → Accept? (y/n)
+════════════════════════════════════════════════════════════════
+```
+
+## Memory Updates
+
+When I learn something, I update my memory:
+
+```bash
+# Example: User says "always skip Confluence docs"
+# I will:
+1. Create memory: "Skip Confluence docs in default full-flow"
+2. Update full-flow.md behavior
+3. Confirm: "Got it! Confluence docs now on-demand only."
+```
+
+## Command Evolution
+
+### How Commands Self-Evolve
+
+1. **Usage Tracking** (mental model):
+
+    - Which commands run most
+    - Which steps get skipped
+    - Which clarifications repeat
+
+2. **Feedback Loop**:
+
+    ```
+    User runs command
+         ↓
+    I observe outcome
+         ↓
+    Note any corrections/preferences
+         ↓
+    Suggest improvements
+         ↓
+    User accepts/rejects
+         ↓
+    Update command behavior
+    ```
+
+3. **Periodic Review**:
+
+    ```
+    Every few sessions, I'll ask:
+
+    "I've noticed some patterns in how you work.
+    Would you like me to suggest optimizations to the workflow?"
+    ```
+
+## Evolution Examples
+
+### Example 1: Learned Skip
+
+```
+Before: Always ask "Add How to Test? (y/n)"
+Observed: User says "y" 100% of time
+After: Auto-add, just confirm "✅ How to Test added"
+```
+
+### Example 2: Learned Default
+
+```
+Before: Ask "Empty string = missing or show empty?"
+Observed: User always picks "missing"
+After: Default to "missing", mention assumption
+```
+
+### Example 3: New Shortcut
+
+```
+Observed: User often runs /jira-fetch then /jira-branch
+Created: /jira-start (combines both)
+```
+
+### Example 4: Critical Focus
+
+```
+Observed: User says "skip minor issues" frequently
+Updated: /pr-review now defaults to critical-only mode
+```
+
+## Suggesting New Commands
+
+When I notice a gap, I'll propose:
+
+```
+💡 COMMAND SUGGESTION
+
+I noticed you often:
+1. Fetch ticket
+2. Check if branch exists
+3. Create branch if not
+4. Start implementation
+
+This could be a single command: /jira-quick-start
+
+Would you like me to create it? (y/n)
+```
+
+## Updating Existing Commands
+
+When I learn a better approach:
+
+```
+💡 COMMAND UPDATE SUGGESTION
+
+Current: /pr-review posts all issues as comments
+Learned: You prefer critical issues only, minor as summary
+
+Proposed change to /pr-review:
+- Default: Post only critical/high-impact issues
+- Summary: Mention minor issues in summary comment
+- Flag: --all to include everything
+
+Apply this update? (y/n)
+```
+
+## What I Track (Mentally)
+
+| Category        | Examples                                 |
+| --------------- | ---------------------------------------- |
+| **Preferences** | Skip confirmations, auto-add docs        |
+| **Defaults**    | Empty string handling, test coverage     |
+| **Patterns**    | Command sequences, common clarifications |
+| **Corrections** | Wrong assumptions I made                 |
+| **Skips**       | Steps user never wants                   |
+
+## AI Execution
+
+### During Every Command Run:
+
+1. **Observe**: What did user do differently than expected?
+2. **Note**: Any corrections, skips, or preferences expressed?
+3. **Learn**: Update mental model
+4. **Suggest**: If pattern is strong, propose improvement
+
+### After Multiple Runs:
+
+```
+I've worked with you on 5 tickets this week. I noticed:
+
+1. You always use Tampa Airport for testing
+   → Should I default to Tampa in test instructions?
+
+2. You prefer smaller PRs (< 200 lines)
+   → Should I warn when PR exceeds this?
+
+3. You always add @team-lead as reviewer
+   → Should I auto-add as default reviewer?
+
+Update preferences? (y/n for each)
+```
+
+## Manual Triggers
+
+```bash
+# Ask for suggestions
+/self-improve suggest
+
+# Show what I've learned
+/self-improve show-learnings
+
+# Reset a specific learning
+/self-improve reset "skip confluence"
+
+# Force update a command
+/self-improve update pr-review "focus on critical only"
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cursor-ai-toolkit",
+  "version": "1.0.0",
+  "description": "AI Self-Improvement Commands for Cursor IDE - Learning, Rules, and Context Management",
+  "bin": {
+    "cursor-ai-toolkit": "./bin/cli.js",
+    "ai-toolkit": "./bin/cli.js"
+  },
+  "main": "./bin/cli.js",
+  "keywords": [
+    "cursor",
+    "cursor-rules",
+    "cursor-commands",
+    "ai-learning",
+    "self-improvement",
+    "context-management",
+    "dev-productivity",
+    "ai-coding"
+  ],
+  "author": "Sharath Chandra",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sharath317/cursor-ai-toolkit"
+  },
+  "homepage": "https://github.com/sharath317/cursor-ai-toolkit#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "commands/"
+  ]
+}
+