cursor-ai-toolkit 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# 🧠 Cursor AI Toolkit
+
+> AI Self-Improvement Commands for Cursor IDE - Learning, Rules & Context Management
+
+[![npm version](https://badge.fury.io/js/cursor-ai-toolkit.svg)](https://www.npmjs.com/package/cursor-ai-toolkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Quick Install
+
+```bash
+npx cursor-ai-toolkit
+```
+
+One command installs 8 AI self-improvement commands for Cursor.
+
+## What is AI Toolkit?
+
+AI Toolkit enhances Cursor's AI capabilities with:
+
+- **Pattern Learning** - Extract patterns from your codebase and create persistent memories
+- **Rule Generation** - Auto-generate .mdc rules from established patterns
+- **Self-Healing** - Fix bugs and proactively find similar issues
+- **Context Management** - Prevent context drift in long conversations
+
+## 📦 Command Bundles
+
+| Bundle | Commands | Use Case |
+|--------|----------|----------|
+| **Minimal** | 4 | Core learning only |
+| **Standard** | 8 | + Context management |
+
+## 🔧 Commands Reference
+
+### 🧠 Learning
+
+| Command | Description |
+|---------|-------------|
+| `/generate-memories` | Create persistent memories from session patterns |
+| `/generate-rules` | Auto-generate .mdc rules from codebase analysis |
+| `/self-heal` | Fix a bug and find/fix similar antipatterns |
+| `/self-improve` | Learn from user patterns, evolve behavior |
+
+### 📊 Context Management
+
+| Command | Description |
+|---------|-------------|
+| `/context-prune` | Summarize progress, prevent context drift |
+| `/orchestrate` | Multi-agent coordination for complex tasks |
+| `/ask-clarification` | Request missing information before proceeding |
+| `/smart-detection` | Auto-detect changes and make smart decisions |
+
+## 💡 Example Usage
+
+### Generate Memories from Session
+
+```
+/generate-memories
+
+════════════════════════════════════════════════════════════════
+  MEMORY GENERATION
+════════════════════════════════════════════════════════════════
+
+📊 SESSION ANALYSIS
+
+Patterns detected:
+  1. Used useWatch 5 times (consistent)
+  2. Applied AbortController pattern 3 times
+  3. Skipped optional docs
+
+📝 PROPOSED MEMORIES
+
+1. [Preference] React Hook Form
+   "Use useWatch hook instead of methods.watch()"
+   Create? (y/n)
+```
+
+### Auto-Generate Rules
+
+```
+/generate-rules src/components
+
+════════════════════════════════════════════════════════════════
+  PATTERN ANALYSIS RESULTS
+════════════════════════════════════════════════════════════════
+
+## Detected Patterns (423 files analyzed)
+
+✅ Styled component namespace: 98% use `* as S`
+✅ Feature folder structure: 87% follow standard
+⚠️ Barrel files: 23% still use index.ts
+
+📁 Created: .cursor/rules/component-patterns.mdc
+```
+
+### Self-Healing Bug Fix
+
+```
+/self-heal "TypeError: Cannot read property 'data' of null"
+
+Root Cause: Race condition - component unmounted before async resolved
+
+✅ Fixed: useBookingData.ts:45
+✅ Found 5 similar patterns
+✅ Applied fix to all occurrences
+✅ Added to .cursor/rules/web-standards.mdc
+```
+
+## 🛠️ CLI Commands
+
+```bash
+npx cursor-ai-toolkit              # Interactive install
+npx cursor-ai-toolkit --bundle standard -y  # Non-interactive
+npx cursor-ai-toolkit status       # Check installation
+npx cursor-ai-toolkit list         # List all commands
+npx cursor-ai-toolkit help         # Show help
+```
+
+## 📂 Installation Structure
+
+After installation:
+
+```
+.cursor/
+└── commands/
+    ├── generate-memories.md
+    ├── generate-rules.md
+    ├── self-heal.md
+    ├── self-improve.md
+    ├── context-prune.md
+    ├── orchestrate.md
+    ├── ask-clarification.md
+    └── smart-detection.md
+```
+
+## 🤝 Works With
+
+- [Buddy OS](https://github.com/sharath317/buddy-os) - Role-aware autonomous agent
+- [Cursor Full-Flow](https://github.com/sharath317/cursor-full-flow) - Jira to PR automation
+- [Cursor Quality Suite](https://github.com/sharath317/cursor-quality-suite) - Testing & quality
+
+## 📄 License
+
+MIT © Sharath Chandra
+
+---
+
+**Make your AI smarter with every interaction.**
+

package/bin/cli.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+/**
+ * cursor-ai-toolkit CLI
+ * AI Self-Improvement Commands for Cursor IDE
+ * Learning, Rules, and Context Management
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const VERSION = '1.0.0';
+const CURSOR_DIR = '.cursor';
+const COMMANDS_DIR = 'commands';
+
+const colors = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+};
+
+const log = {
+    info: (msg) => console.log(`${colors.cyan}ℹ${colors.reset} ${msg}`),
+    success: (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`),
+    warn: (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`),
+    error: (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`),
+    step: (msg) => console.log(`  ${colors.dim}→${colors.reset} ${msg}`),
+    header: (msg) => console.log(`\n${colors.bold}${colors.cyan}${msg}${colors.reset}\n`),
+};
+
+const BUNDLES = {
+    minimal: {
+        name: 'Minimal (Core Learning)',
+        description: 'Essential self-improvement commands',
+        commands: ['learning'],
+        count: 4,
+    },
+    standard: {
+        name: 'Standard (Learning + Context)',
+        description: 'Learning with context management',
+        commands: ['learning', 'context'],
+        count: 8,
+    },
+};
+
+function prompt(question, defaultValue = '') {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    const defaultText = defaultValue ? ` (${defaultValue})` : '';
+
+    return new Promise((resolve) => {
+        rl.question(`${question}${defaultText}: `, (answer) => {
+            rl.close();
+            resolve(answer || defaultValue);
+        });
+    });
+}
+
+function ensureDir(dir) {
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+
+function copyCommands(sourceDir, targetDir, categories) {
+    let copiedCount = 0;
+
+    categories.forEach((category) => {
+        const srcCategoryDir = path.join(sourceDir, category);
+
+        if (fs.existsSync(srcCategoryDir)) {
+            const files = fs.readdirSync(srcCategoryDir).filter((f) => f.endsWith('.md'));
+
+            files.forEach((file) => {
+                const srcFile = path.join(srcCategoryDir, file);
+                const tgtFile = path.join(targetDir, file);
+
+                if (!fs.existsSync(tgtFile)) {
+                    fs.copyFileSync(srcFile, tgtFile);
+                    log.step(`Installed: ${file}`);
+                    copiedCount++;
+                } else {
+                    log.step(`Exists: ${file} (skipped)`);
+                }
+            });
+        }
+    });
+
+    return copiedCount;
+}
+
+async function init(flags = {}) {
+    console.log(`
+${colors.bold}${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 CURSOR AI TOOLKIT v${VERSION}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}
+AI Self-Improvement: Learning, Rules & Context Management
+
+`);
+
+    const projectDir = process.cwd();
+    const cursorDir = path.join(projectDir, CURSOR_DIR);
+    const commandsDir = path.join(cursorDir, COMMANDS_DIR);
+
+    log.header('📦 Select Command Bundle');
+
+    Object.entries(BUNDLES).forEach(([key, bundle], idx) => {
+        console.log(`  ${idx + 1}. ${colors.bold}${bundle.name}${colors.reset}`);
+        console.log(`     ${bundle.description} (${bundle.count} commands)\n`);
+    });
+
+    let selectedBundle = 'standard';
+    if (!flags.bundle && !flags.yes) {
+        const bundleAnswer = await prompt('Select bundle (1-2)', '2');
+        selectedBundle = Object.keys(BUNDLES)[parseInt(bundleAnswer, 10) - 1] || 'standard';
+    } else if (flags.bundle) {
+        selectedBundle = flags.bundle;
+    }
+
+    const bundle = BUNDLES[selectedBundle];
+    log.success(`Selected: ${bundle.name}`);
+
+    log.header('📥 Installing Commands');
+
+    ensureDir(commandsDir);
+
+    const packageDir = path.dirname(__dirname);
+    const packageCommandsDir = path.join(packageDir, 'commands');
+
+    const copiedCount = copyCommands(packageCommandsDir, commandsDir, bundle.commands);
+
+    console.log(`
+${colors.bold}${colors.green}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✓ INSTALLATION COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}
+
+${colors.cyan}Commands installed:${colors.reset} ${copiedCount}
+${colors.cyan}Location:${colors.reset}          ${commandsDir}
+
+${colors.bold}Commands Reference:${colors.reset}
+
+  ${colors.cyan}🧠 Learning${colors.reset}
+  /generate-memories     Create persistent memories from patterns
+  /generate-rules        Auto-generate .mdc rules from codebase
+  /self-heal             Fix bugs and prevent similar issues
+  /self-improve          Learn and evolve from user patterns
+
+  ${colors.cyan}📊 Context${colors.reset}
+  /context-prune         Manage context window, prevent drift
+  /orchestrate           Multi-agent coordination
+  /ask-clarification     Request missing information
+  /smart-detection       Auto-detect changes and decisions
+
+${colors.dim}Documentation: https://github.com/sharath317/cursor-ai-toolkit${colors.reset}
+`);
+}
+
+async function status() {
+    const projectDir = process.cwd();
+    const commandsDir = path.join(projectDir, CURSOR_DIR, COMMANDS_DIR);
+
+    if (!fs.existsSync(commandsDir)) {
+        log.warn('AI Toolkit not installed. Run: npx cursor-ai-toolkit');
+        process.exit(0);
+    }
+
+    const commands = fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md'));
+
+    console.log(`
+${colors.bold}${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 AI TOOLKIT STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}
+
+${colors.cyan}Version:${colors.reset}  ${VERSION}
+${colors.cyan}Commands:${colors.reset} ${commands.length} installed
+${colors.cyan}Location:${colors.reset} ${commandsDir}
+
+${colors.bold}Installed Commands:${colors.reset}`);
+
+    commands.forEach((cmd) => {
+        console.log(`  - /${cmd.replace('.md', '')}`);
+    });
+
+    console.log('');
+}
+
+async function listCommands() {
+    const packageDir = path.dirname(__dirname);
+    const packageCommandsDir = path.join(packageDir, 'commands');
+
+    console.log(`
+${colors.bold}${colors.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 AVAILABLE COMMANDS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${colors.reset}
+`);
+
+    const categories = ['learning', 'context'];
+    const icons = { learning: '🧠', context: '📊' };
+
+    categories.forEach((cat) => {
+        const catDir = path.join(packageCommandsDir, cat);
+        if (fs.existsSync(catDir)) {
+            console.log(`\n${icons[cat]} ${colors.bold}${cat.toUpperCase()}${colors.reset}`);
+
+            const files = fs.readdirSync(catDir).filter((f) => f.endsWith('.md'));
+            files.forEach((file) => {
+                const name = file.replace('.md', '');
+                console.log(`  /${name}`);
+            });
+        }
+    });
+
+    console.log('');
+}
+
+function showHelp() {
+    console.log(`
+${colors.bold}cursor-ai-toolkit v${VERSION}${colors.reset}
+
+AI Self-Improvement Commands for Cursor IDE
+
+${colors.bold}Usage:${colors.reset}
+  npx cursor-ai-toolkit [command] [options]
+
+${colors.bold}Commands:${colors.reset}
+  init          Install commands (default)
+  status        Show current configuration
+  list          List all available commands
+  help          Show this help
+
+${colors.bold}Options:${colors.reset}
+  --bundle      Select bundle (minimal, standard)
+  -y, --yes     Non-interactive mode
+
+${colors.bold}Examples:${colors.reset}
+  npx cursor-ai-toolkit                   Interactive install
+  npx cursor-ai-toolkit --bundle standard Install all commands
+  npx cursor-ai-toolkit status            Check installation
+
+${colors.bold}After Installation:${colors.reset}
+  /generate-memories    Create persistent memories
+  /generate-rules       Auto-generate .mdc rules
+  /self-heal            Fix bugs proactively
+  /context-prune        Manage context window
+
+${colors.dim}https://github.com/sharath317/cursor-ai-toolkit${colors.reset}
+`);
+}
+
+const args = process.argv.slice(2);
+const flags = {};
+let command = null;
+const skipNextArg = new Set();
+
+args.forEach((arg, idx) => {
+    if (arg === '--bundle' && args[idx + 1]) {
+        skipNextArg.add(idx + 1);
+    }
+});
+
+args.forEach((arg, idx) => {
+    if (skipNextArg.has(idx)) {
+        return;
+    } else if (arg === '-y' || arg === '--yes') {
+        flags.yes = true;
+    } else if (arg === '--bundle' && args[idx + 1]) {
+        flags.bundle = args[idx + 1];
+    } else if (!arg.startsWith('-') && command === null) {
+        command = arg;
+    }
+});
+
+switch (command) {
+    case 'init':
+    case null:
+        init(flags);
+        break;
+    case 'status':
+        status();
+        break;
+    case 'list':
+        listCommands();
+        break;
+    case 'help':
+    case '-h':
+    case '--help':
+        showHelp();
+        break;
+    default:
+        log.error(`Unknown command: ${command}`);
+        console.log('Run "npx cursor-ai-toolkit help" for usage');
+        process.exit(1);
+}
+

package/commands/context/ask-clarification.md

@@ -0,0 +1,215 @@
+---
+description: Guidelines for when to ask for clarification vs proceed with assumptions
+category: Reference
+aliases: [clarify, ask, question]
+---
+
+# Ask Clarification - Request Missing Information
+
+Guidelines for when and how to ask for more information during workflows.
+
+## When to Ask for Clarification
+
+### 🔴 Must Ask (Blocking)
+
+| Situation                    | Example Question                                                   |
+| ---------------------------- | ------------------------------------------------------------------ |
+| Acceptance criteria is vague | "AC says 'improve tooltip' - what specific improvement is needed?" |
+| Multiple valid approaches    | "Should I use existing pattern A or pattern B for this?"           |
+| Breaking change potential    | "This changes public API - is that acceptable?"                    |
+| Missing design               | "No Figma link found - can you share the design?"                  |
+| Conflicting requirements     | "AC #2 conflicts with AC #4 - which takes priority?"               |
+| Security/data handling       | "This touches user data - any specific handling needed?"           |
+
+### 🟡 Should Ask (Important)
+
+| Situation                  | Example Question                                                         |
+| -------------------------- | ------------------------------------------------------------------------ |
+| Edge cases not specified   | "What should happen when display_name is empty string vs undefined?"     |
+| Performance considerations | "This could impact bundle size - is that acceptable?"                    |
+| Scope creep risk           | "Should I also update the related component, or create separate ticket?" |
+| Test coverage unclear      | "Should I add unit tests, integration tests, or both?"                   |
+
+### 🟢 Can Proceed (Minor)
+
+| Situation                     | What I Do                            |
+| ----------------------------- | ------------------------------------ |
+| Styling details not specified | Follow design system defaults        |
+| Naming conventions            | Follow existing patterns in codebase |
+| File organization             | Follow project structure rules       |
+| Error message wording         | Use existing patterns                |
+
+## Clarification Request Format
+
+```markdown
+## ❓ Clarification Needed
+
+Before proceeding, I need some information:
+
+### 1. [Category]: [Question]
+
+**Context:** [Why I'm asking]
+**Options:**
+
+-   A) [Option 1]
+-   B) [Option 2]
+    **My recommendation:** [If I have one]
+
+### 2. [Category]: [Question]
+
+...
+
+---
+
+Please provide answers, or say "proceed with recommendations" to use my suggested approach.
+```
+
+## Example Clarification Request
+
+```markdown
+## ❓ Clarification Needed
+
+Before implementing TICKET-123, I need some information:
+
+### 1. Edge Case Handling
+
+**Context:** The AC says "use display_name when available"
+**Question:** What should happen when display_name is an empty string ""?
+**Options:**
+
+-   A) Treat empty string as "not available", use original name
+-   B) Show empty string (might look broken)
+    **My recommendation:** Option A (treat empty as missing)
+
+### 2. Scope Confirmation
+
+**Context:** I found similar code in PackagesV2.tsx that could benefit from this change
+**Question:** Should I update PackagesV2.tsx in this ticket, or create a follow-up?
+**Options:**
+
+-   A) Include in this ticket (more complete, slightly larger PR)
+-   B) Separate ticket (smaller PR, but temporary inconsistency)
+    **My recommendation:** Option A (avoid code duplication)
+
+### 3. Test Coverage
+
+**Context:** helpers.ts doesn't have existing tests
+**Question:** Should I add unit tests for getModifiedLineItems?
+**Options:**
+
+-   A) Yes, add comprehensive tests
+-   B) Skip tests (matches current state)
+    **My recommendation:** Option A if time permits
+
+---
+
+Please provide answers, or say "proceed with recommendations".
+```
+
+## Information Sufficiency Checklist
+
+Before implementation, verify:
+
+### Requirements
+
+-   [ ] Clear acceptance criteria (actionable, measurable)
+-   [ ] Edge cases defined (or I can make reasonable assumptions)
+-   [ ] Design available (Figma link or clear description)
+-   [ ] Backend contract clear (API response structure)
+
+### Technical
+
+-   [ ] Know which files to modify
+-   [ ] Found existing patterns to follow
+-   [ ] Understand dependencies
+-   [ ] No blocking conflicts with open PRs
+
+### Scope
+
+-   [ ] Clear boundaries (what's in/out of scope)
+-   [ ] Estimate is reasonable
+-   [ ] No hidden complexity discovered
+
+## AI Execution
+
+### At Start of /gather-context or /full-flow:
+
+1. **Fetch all available information** (Jira, Figma, codebase)
+
+2. **Run sufficiency check:**
+
+    ```
+    For each checklist item:
+      - If info available → ✅
+      - If info missing but can assume → ⚠️ (note assumption)
+      - If info missing and blocking → ❓ (must ask)
+    ```
+
+3. **If any ❓ items exist:**
+
+    - Generate clarification request
+    - Wait for user response
+    - Do NOT proceed until answered
+
+4. **If only ⚠️ items:**
+
+    - List assumptions being made
+    - Ask: "Proceed with these assumptions? (y/n)"
+
+5. **If all ✅:**
+    - Proceed with implementation
+
+### Example Flow:
+
+```
+📋 Gathering context for TICKET-123...
+
+[... gather info ...]
+
+════════════════════════════════════════════════════════════════
+  INFORMATION CHECK
+════════════════════════════════════════════════════════════════
+
+✅ Requirements
+  ✅ Acceptance criteria: Clear (3 items)
+  ⚠️ Edge cases: Assuming empty string = missing
+  ✅ Design: Found Figma link
+  ✅ Backend: BE-789 defines display_name field
+
+✅ Technical
+  ✅ Files to modify: 4 identified
+  ✅ Patterns found: getModifiedLineItems, TooltipTitle
+  ✅ Dependencies: None blocking
+  ✅ Conflicts: No open PRs in same files
+
+✅ Scope
+  ⚠️ Boundaries: PackagesV2 also needs update (including)
+  ✅ Estimate: Small (2-3 hours)
+  ✅ Complexity: Low
+
+════════════════════════════════════════════════════════════════
+
+⚠️ Proceeding with assumptions:
+1. Empty string display_name treated as missing (fallback to name)
+2. PackagesV2.tsx included in scope (avoid duplication)
+
+Proceed with these assumptions? (y/n)
+```
+
+## Handling Responses
+
+### User says "y" or "proceed":
+
+→ Continue with stated assumptions
+
+### User says "n":
+
+→ Ask which assumption is wrong
+→ Get correct approach
+→ Update plan and re-confirm
+
+### User provides additional context:
+
+→ Incorporate into understanding
+→ Update plan
+→ Re-run sufficiency check