ai-qakit 1.0.0

package/templates/.claude/skills/sequential-thinking/references/examples-architecture.md

@@ -0,0 +1,94 @@
+# Example: Architecture Decision with Sequential Thinking
+
+**Problem**: Choose state management for growing React app.
+
+## Sequential Thinking Approach
+
+```
+Thought 1/4: Initial assessment
+
+React app growing complex. useState scattered across components.
+Need centralized state management.
+Options: Redux, MobX, Zustand, Context API, Jotai.
+
+Next: Define requirements
+
+Thought 2/5: Requirements (adjusted up)
+
+App needs:
+- Real-time updates (WebSocket)
+- Offline support
+- Complex nested state
+- Multiple devs (maintainability)
+- TypeScript (type safety)
+
+These eliminate simpler solutions.
+Next: Evaluate remaining options
+
+Thought 3/5 [REVISION of Thought 1]: Scope refinement
+
+Original assumption: Need global state management.
+Realization: Not all state needs centralization.
+
+Better breakdown:
+- Server state (API data): React Query
+- UI state (modals, forms): Local useState
+- Auth state: Context API
+- App-wide settings: Simple global store
+
+This reduces problem scope significantly.
+Changes evaluation criteria.
+Next: Re-evaluate with refined scope
+
+Thought 4/6: Re-evaluation (adjusted)
+
+Only need lightweight store for app-wide settings.
+Zustand fits:
+- Minimal boilerplate
+- Excellent TypeScript support
+- No provider wrapper
+- ~1KB size
+
+React Query handles server state (caching, refetch, offline).
+Most state stays local.
+
+Next: Verify this handles all requirements
+
+Thought 5/6 [HYPOTHESIS]: Hybrid approach
+
+Hypothesis: Zustand + React Query + local state solves needs.
+
+- Zustand: Theme, user prefs, global UI flags
+- React Query: All server data, caching, sync
+- useState: Component-local UI
+
+Benefits: Simple, performant, maintainable.
+Uncertainty: Real-time updates?
+
+Thought 6/6 [FINAL]: Verified solution
+
+React Query supports WebSocket via custom hooks.
+Zustand handles global UI simply.
+Local state for component-specific needs.
+
+Architecture decision:
+- Zustand for global UI state
+- React Query for all server interactions
+- Local useState for component state
+
+Confidence: High
+Assumptions: Team comfortable with React Query patterns
+Benefits: Simpler than Redux, more powerful than Context
+Trade-offs: Learning curve for React Query (but worthwhile)
+```
+
+## Key Insights
+
+1. **Scope revision crucial**: Original "need global state" reframed to specific state categories
+2. **Separation of concerns**: Different state types need different solutions
+3. **Hypothesis verification**: Confirmed WebSocket support before finalizing
+4. **Simpler is better**: Avoided over-engineering with heavy Redux solution
+
+## Impact of Revision
+
+Without Thought 3 revision, might have chosen Redux for all state—significant over-engineering. Revision led to more appropriate, simpler solution.

package/templates/.claude/skills/sequential-thinking/references/examples-debug.md

@@ -0,0 +1,90 @@
+# Example: Performance Debugging with Sequential Thinking
+
+**Problem**: API endpoint slow (2-3s instead of <200ms).
+
+## Sequential Thinking Approach
+
+```
+Thought 1/5: Initial investigation
+
+Endpoint: GET /api/users/{id}/dashboard
+Expected: <200ms
+Actual: 2-3s
+
+Need to identify bottleneck.
+Next: Analyze endpoint logic
+
+Thought 2/5: Endpoint analysis
+
+Dashboard fetches:
+- User profile
+- Recent activities (last 50)
+- Notifications (unread)
+- Analytics summary
+
+Each is separate DB query. Could be N+1 problem.
+Next: Profile actual execution
+
+Thought 3/6: Profiling results (adjusted up—more complex)
+
+Profiling:
+- User profile: 20ms
+- Activities: 1800ms (!!)
+- Notifications: 100ms
+- Analytics: 80ms
+
+Activities query is bottleneck (90% of time).
+Need to examine that query.
+Next: Investigate activities query
+
+Thought 4/6 [BRANCH A]: Hypothesis - N+1 query
+
+Activities table has user_id FK to users.
+Query might fetch activities, then user for each (N+1).
+Verification: Check if uses joins or loops.
+
+Thought 4/6 [BRANCH B]: Hypothesis - Missing index
+
+Activities table might lack index on user_id + created_at.
+Without index, full table scan for user's activities.
+Verification: Check table indexes.
+
+Thought 5/6 [VERIFICATION]: Testing hypotheses
+
+Query examination: Uses proper joins (not N+1).
+Index check: user_id indexed, NOT created_at.
+Query filters by user_id AND sorts by created_at.
+
+Branch B confirmed: Missing composite index causes slow sort.
+Branch A eliminated: No N+1 issue.
+
+Root cause identified.
+Next: Implement solution
+
+Thought 6/6 [FINAL]: Solution and verification
+
+Create composite index:
+```sql
+CREATE INDEX idx_activities_user_created
+ON activities(user_id, created_at DESC);
+```
+
+Tested: Response time now 120ms (target met).
+
+Confidence: High (verified with profiling)
+Result: 95% performance improvement
+```
+
+## Key Techniques Demonstrated
+
+1. **Branching for hypothesis testing**: Explored N+1 vs index hypotheses in parallel
+2. **Verification before solution**: Tested both hypotheses systematically
+3. **Data-driven decisions**: Used profiling data to guide investigation
+4. **Dynamic adjustment**: Expanded thought count when complexity emerged
+5. **Elimination method**: Ruled out N+1, confirmed index issue
+
+## Comparison
+
+**Without sequential thinking**: Might jump to N+1 conclusion (common issue), waste time optimizing wrong thing.
+
+**With sequential thinking**: Systematically tested hypotheses, identified actual root cause, implemented correct fix.

package/templates/.claude/skills/sequential-thinking/scripts/format-thought.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+/**
+ * Sequential Thinking Thought Formatter
+ *
+ * Formats thoughts for display with visual indicators for type (regular/revision/branch).
+ * Provides consistent, readable output for thought sequences.
+ *
+ * Usage:
+ *   node format-thought.js --thought "Analysis" --number 1 --total 5
+ *   node format-thought.js --thought "Revision" --number 2 --total 5 --revision 1
+ *   node format-thought.js --thought "Branch A" --number 3 --total 5 --branch 2 --branchId "a"
+ */
+
+class ThoughtFormatter {
+  static format(thoughtData) {
+    const { thoughtNumber, totalThoughts, thought, isRevision, revisesThought, branchFromThought, branchId } = thoughtData;
+
+    let prefix = '';
+    let context = '';
+    let emoji = '';
+
+    if (isRevision && revisesThought) {
+      emoji = '🔄';
+      prefix = 'REVISION';
+      context = ` (revising thought ${revisesThought})`;
+    } else if (branchFromThought) {
+      emoji = '🌿';
+      prefix = 'BRANCH';
+      context = branchId ? ` (from thought ${branchFromThought}, ID: ${branchId})` : ` (from thought ${branchFromThought})`;
+    } else {
+      emoji = '💭';
+      prefix = 'Thought';
+      context = '';
+    }
+
+    const header = `${emoji} ${prefix} ${thoughtNumber}/${totalThoughts}${context}`;
+    const maxLength = Math.max(header.length, thought.length);
+    const border = '─'.repeat(maxLength + 4);
+
+    // Wrap long thoughts
+    const wrappedThought = this.wrapText(thought, maxLength);
+    const thoughtLines = wrappedThought.map(line => `│ ${line.padEnd(maxLength + 2)} │`).join('\n');
+
+    return `
+┌${border}┐
+│ ${header.padEnd(maxLength + 2)} │
+├${border}┤
+${thoughtLines}
+└${border}┘`;
+  }
+
+  static wrapText(text, maxWidth) {
+    if (text.length <= maxWidth) {
+      return [text];
+    }
+
+    const words = text.split(' ');
+    const lines = [];
+    let currentLine = '';
+
+    for (const word of words) {
+      if ((currentLine + ' ' + word).trim().length <= maxWidth) {
+        currentLine = currentLine ? currentLine + ' ' + word : word;
+      } else {
+        if (currentLine) lines.push(currentLine);
+        currentLine = word;
+      }
+    }
+
+    if (currentLine) lines.push(currentLine);
+    return lines;
+  }
+
+  static formatSimple(thoughtData) {
+    const { thoughtNumber, totalThoughts, thought, isRevision, revisesThought, branchFromThought, branchId } = thoughtData;
+
+    let marker = '';
+    if (isRevision && revisesThought) {
+      marker = ` [REVISION of Thought ${revisesThought}]`;
+    } else if (branchFromThought) {
+      marker = branchId ? ` [BRANCH ${branchId.toUpperCase()} from Thought ${branchFromThought}]` : ` [BRANCH from Thought ${branchFromThought}]`;
+    }
+
+    return `Thought ${thoughtNumber}/${totalThoughts}${marker}: ${thought}`;
+  }
+
+  static formatMarkdown(thoughtData) {
+    const { thoughtNumber, totalThoughts, thought, isRevision, revisesThought, branchFromThought, branchId } = thoughtData;
+
+    let marker = '';
+    if (isRevision && revisesThought) {
+      marker = ` **[REVISION of Thought ${revisesThought}]**`;
+    } else if (branchFromThought) {
+      marker = branchId ? ` **[BRANCH ${branchId.toUpperCase()} from Thought ${branchFromThought}]**` : ` **[BRANCH from Thought ${branchFromThought}]**`;
+    }
+
+    return `**Thought ${thoughtNumber}/${totalThoughts}**${marker}\n\n${thought}\n`;
+  }
+}
+
+// CLI Interface
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  const parseArgs = (args) => {
+    const parsed = {};
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg.startsWith('--')) {
+        const key = arg.slice(2);
+        const value = args[i + 1];
+
+        if (value && !value.startsWith('--')) {
+          // Parse boolean
+          if (value === 'true') parsed[key] = true;
+          else if (value === 'false') parsed[key] = false;
+          // Parse number
+          else if (!isNaN(value)) parsed[key] = parseFloat(value);
+          // String
+          else parsed[key] = value;
+          i++;
+        }
+      }
+    }
+    return parsed;
+  };
+
+  const input = parseArgs(args);
+
+  const thoughtData = {
+    thought: input.thought || 'No thought provided',
+    thoughtNumber: input.number || 1,
+    totalThoughts: input.total || 1,
+    isRevision: input.revision !== undefined,
+    revisesThought: input.revision,
+    branchFromThought: input.branch,
+    branchId: input.branchId
+  };
+
+  const format = input.format || 'box';
+
+  let output;
+  switch (format) {
+    case 'simple':
+      output = ThoughtFormatter.formatSimple(thoughtData);
+      break;
+    case 'markdown':
+      output = ThoughtFormatter.formatMarkdown(thoughtData);
+      break;
+    case 'box':
+    default:
+      output = ThoughtFormatter.format(thoughtData);
+  }
+
+  console.log(output);
+}
+
+module.exports = { ThoughtFormatter };

package/templates/.claude/skills/sequential-thinking/scripts/process-thought.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * Sequential Thinking Thought Processor
+ *
+ * Validates and tracks sequential thoughts with revision and branching support.
+ * Provides deterministic validation and context management.
+ *
+ * Usage:
+ *   node process-thought.js --thought "Analysis text" --number 1 --total 5 --next true
+ *   node process-thought.js --thought "Revision" --number 2 --total 5 --next true --revision 1
+ *   node process-thought.js --reset  # Reset thought history
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration
+const HISTORY_FILE = path.join(__dirname, '.thought-history.json');
+const DISABLE_LOGGING = process.env.DISABLE_THOUGHT_LOGGING?.toLowerCase() === 'true';
+
+class ThoughtProcessor {
+  constructor() {
+    this.loadHistory();
+  }
+
+  loadHistory() {
+    try {
+      if (fs.existsSync(HISTORY_FILE)) {
+        const data = JSON.parse(fs.readFileSync(HISTORY_FILE, 'utf8'));
+        this.thoughtHistory = data.thoughtHistory || [];
+        this.branches = data.branches || {};
+      } else {
+        this.thoughtHistory = [];
+        this.branches = {};
+      }
+    } catch (error) {
+      this.thoughtHistory = [];
+      this.branches = {};
+    }
+  }
+
+  saveHistory() {
+    fs.writeFileSync(
+      HISTORY_FILE,
+      JSON.stringify({
+        thoughtHistory: this.thoughtHistory,
+        branches: this.branches
+      }, null, 2)
+    );
+  }
+
+  resetHistory() {
+    this.thoughtHistory = [];
+    this.branches = {};
+    if (fs.existsSync(HISTORY_FILE)) {
+      fs.unlinkSync(HISTORY_FILE);
+    }
+  }
+
+  validateThought(input) {
+    const errors = [];
+
+    if (!input.thought || typeof input.thought !== 'string' || input.thought.trim() === '') {
+      errors.push('Invalid thought: must be a non-empty string');
+    }
+
+    if (!input.thoughtNumber || typeof input.thoughtNumber !== 'number' || input.thoughtNumber < 1) {
+      errors.push('Invalid thoughtNumber: must be a positive number');
+    }
+
+    if (!input.totalThoughts || typeof input.totalThoughts !== 'number' || input.totalThoughts < 1) {
+      errors.push('Invalid totalThoughts: must be a positive number');
+    }
+
+    if (typeof input.nextThoughtNeeded !== 'boolean') {
+      errors.push('Invalid nextThoughtNeeded: must be a boolean');
+    }
+
+    // Optional field validations
+    if (input.isRevision !== undefined && typeof input.isRevision !== 'boolean') {
+      errors.push('Invalid isRevision: must be a boolean');
+    }
+
+    if (input.revisesThought !== undefined && (typeof input.revisesThought !== 'number' || input.revisesThought < 1)) {
+      errors.push('Invalid revisesThought: must be a positive number');
+    }
+
+    if (input.branchFromThought !== undefined && (typeof input.branchFromThought !== 'number' || input.branchFromThought < 1)) {
+      errors.push('Invalid branchFromThought: must be a positive number');
+    }
+
+    if (input.branchId !== undefined && typeof input.branchId !== 'string') {
+      errors.push('Invalid branchId: must be a string');
+    }
+
+    if (input.needsMoreThoughts !== undefined && typeof input.needsMoreThoughts !== 'boolean') {
+      errors.push('Invalid needsMoreThoughts: must be a boolean');
+    }
+
+    return errors;
+  }
+
+  processThought(input) {
+    const errors = this.validateThought(input);
+
+    if (errors.length > 0) {
+      return {
+        success: false,
+        errors,
+        status: 'failed'
+      };
+    }
+
+    // Auto-adjust totalThoughts if thoughtNumber exceeds it
+    if (input.thoughtNumber > input.totalThoughts) {
+      input.totalThoughts = input.thoughtNumber;
+    }
+
+    // Create thought data
+    const thoughtData = {
+      thought: input.thought,
+      thoughtNumber: input.thoughtNumber,
+      totalThoughts: input.totalThoughts,
+      nextThoughtNeeded: input.nextThoughtNeeded,
+      isRevision: input.isRevision,
+      revisesThought: input.revisesThought,
+      branchFromThought: input.branchFromThought,
+      branchId: input.branchId,
+      needsMoreThoughts: input.needsMoreThoughts,
+      timestamp: new Date().toISOString()
+    };
+
+    // Add to history
+    this.thoughtHistory.push(thoughtData);
+
+    // Track branches
+    if (thoughtData.branchFromThought && thoughtData.branchId) {
+      if (!this.branches[thoughtData.branchId]) {
+        this.branches[thoughtData.branchId] = [];
+      }
+      this.branches[thoughtData.branchId].push(thoughtData);
+    }
+
+    // Save history
+    this.saveHistory();
+
+    return {
+      success: true,
+      thoughtNumber: thoughtData.thoughtNumber,
+      totalThoughts: thoughtData.totalThoughts,
+      nextThoughtNeeded: thoughtData.nextThoughtNeeded,
+      branches: Object.keys(this.branches),
+      thoughtHistoryLength: this.thoughtHistory.length,
+      timestamp: thoughtData.timestamp
+    };
+  }
+
+  getHistory() {
+    return {
+      thoughts: this.thoughtHistory,
+      branches: this.branches,
+      totalThoughts: this.thoughtHistory.length
+    };
+  }
+}
+
+// CLI Interface
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const processor = new ThoughtProcessor();
+
+  // Parse arguments
+  const parseArgs = (args) => {
+    const parsed = {};
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg.startsWith('--')) {
+        const key = arg.slice(2);
+        const value = args[i + 1];
+
+        if (key === 'reset') {
+          return { reset: true };
+        }
+
+        if (key === 'history') {
+          return { history: true };
+        }
+
+        if (value && !value.startsWith('--')) {
+          // Parse boolean
+          if (value === 'true') parsed[key] = true;
+          else if (value === 'false') parsed[key] = false;
+          // Parse number
+          else if (!isNaN(value)) parsed[key] = parseFloat(value);
+          // String
+          else parsed[key] = value;
+          i++;
+        }
+      }
+    }
+    return parsed;
+  };
+
+  const input = parseArgs(args);
+
+  if (input.reset) {
+    processor.resetHistory();
+    console.log(JSON.stringify({ success: true, message: 'History reset' }, null, 2));
+    process.exit(0);
+  }
+
+  if (input.history) {
+    console.log(JSON.stringify(processor.getHistory(), null, 2));
+    process.exit(0);
+  }
+
+  // Map CLI args to expected field names
+  const thoughtInput = {
+    thought: input.thought,
+    thoughtNumber: input.number,
+    totalThoughts: input.total,
+    nextThoughtNeeded: input.next,
+    isRevision: input.revision !== undefined ? true : input.isRevision,
+    revisesThought: input.revision,
+    branchFromThought: input.branch,
+    branchId: input.branchId,
+    needsMoreThoughts: input.needsMore
+  };
+
+  const result = processor.processThought(thoughtInput);
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.success ? 0 : 1);
+}
+
+module.exports = { ThoughtProcessor };

package/templates/.claude/skills/sequential-thinking/tests/format-thought.test.js

@@ -0,0 +1,133 @@
+/**
+ * Tests for Sequential Thinking Thought Formatter
+ *
+ * Run with: npm test
+ */
+
+const { ThoughtFormatter } = require('../scripts/format-thought');
+
+describe('ThoughtFormatter', () => {
+  describe('Simple Format', () => {
+    test('formats regular thought', () => {
+      const result = ThoughtFormatter.formatSimple({
+        thought: 'Test thought',
+        thoughtNumber: 1,
+        totalThoughts: 5
+      });
+
+      expect(result).toBe('Thought 1/5: Test thought');
+    });
+
+    test('formats revision thought', () => {
+      const result = ThoughtFormatter.formatSimple({
+        thought: 'Revised thought',
+        thoughtNumber: 2,
+        totalThoughts: 5,
+        isRevision: true,
+        revisesThought: 1
+      });
+
+      expect(result).toContain('[REVISION of Thought 1]');
+      expect(result).toContain('Revised thought');
+    });
+
+    test('formats branch thought', () => {
+      const result = ThoughtFormatter.formatSimple({
+        thought: 'Branch thought',
+        thoughtNumber: 3,
+        totalThoughts: 5,
+        branchFromThought: 2,
+        branchId: 'a'
+      });
+
+      expect(result).toContain('[BRANCH A from Thought 2]');
+      expect(result).toContain('Branch thought');
+    });
+  });
+
+  describe('Markdown Format', () => {
+    test('formats regular thought', () => {
+      const result = ThoughtFormatter.formatMarkdown({
+        thought: 'Test thought',
+        thoughtNumber: 1,
+        totalThoughts: 5
+      });
+
+      expect(result).toContain('**Thought 1/5**');
+      expect(result).toContain('Test thought');
+    });
+
+    test('formats revision thought', () => {
+      const result = ThoughtFormatter.formatMarkdown({
+        thought: 'Revised thought',
+        thoughtNumber: 2,
+        totalThoughts: 5,
+        isRevision: true,
+        revisesThought: 1
+      });
+
+      expect(result).toContain('**[REVISION of Thought 1]**');
+    });
+  });
+
+  describe('Box Format', () => {
+    test('formats with border', () => {
+      const result = ThoughtFormatter.format({
+        thought: 'Test thought',
+        thoughtNumber: 1,
+        totalThoughts: 5
+      });
+
+      expect(result).toContain('┌');
+      expect(result).toContain('└');
+      expect(result).toContain('💭');
+      expect(result).toContain('Test thought');
+    });
+
+    test('formats revision with emoji', () => {
+      const result = ThoughtFormatter.format({
+        thought: 'Revised',
+        thoughtNumber: 2,
+        totalThoughts: 5,
+        isRevision: true,
+        revisesThought: 1
+      });
+
+      expect(result).toContain('🔄');
+      expect(result).toContain('REVISION');
+    });
+
+    test('formats branch with emoji', () => {
+      const result = ThoughtFormatter.format({
+        thought: 'Branch',
+        thoughtNumber: 3,
+        totalThoughts: 5,
+        branchFromThought: 2,
+        branchId: 'a'
+      });
+
+      expect(result).toContain('🌿');
+      expect(result).toContain('BRANCH');
+    });
+  });
+
+  describe('Text Wrapping', () => {
+    test('wraps long text', () => {
+      const longText = 'This is a very long thought that should be wrapped across multiple lines when it exceeds the maximum width specified for the formatter';
+      const wrapped = ThoughtFormatter.wrapText(longText, 50);
+
+      expect(wrapped.length).toBeGreaterThan(1);
+      wrapped.forEach(line => {
+        expect(line.length).toBeLessThanOrEqual(50);
+      });
+    });
+
+    test('does not wrap short text', () => {
+      const shortText = 'Short thought';
+      const wrapped = ThoughtFormatter.wrapText(shortText, 50);
+
+      expect(wrapped.length).toBe(1);
+      expect(wrapped[0]).toBe(shortText);
+    });
+  });
+});