solvdex 1.0.0

package/skills/wiki-browse/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: wiki-browse
+description: List and filter Solvdex wiki entries. Use to see all available knowledge organized by category.
+argument-hint: [--category=<cat>] [--status=<status>] [--tag=<tag>]
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Browse Solvdex Entries
+
+List all wiki entries with optional filtering.
+
+## Process
+
+1. Read all entries from `.wiki/`
+2. Apply filters (category, status, tag)
+3. Group by category
+4. Display summary
+
+## Categories
+
+| Category | Purpose |
+|----------|---------|
+| issues | Bug fixes, error solutions |
+| patterns | Reusable code patterns |
+| gotchas | Pitfalls, traps |
+| testing | Test strategies, mocks |
+| docs | Documentation templates |
+| security | Auth, vulnerabilities |
+| performance | Optimizations, profiling |
+
+## Implementation
+
+```typescript
+import { listEntries, wikiExists, DEFAULT_CATEGORIES } from 'solvdex';
+
+const projectRoot = process.cwd();
+
+if (!wikiExists(projectRoot)) {
+  console.log('No wiki found. Run `/wiki init` first.');
+  return;
+}
+
+const entries = listEntries(projectRoot, {
+  category: args.category,
+  status: args.status,
+  tags: args.tag ? [args.tag] : undefined
+});
+
+if (entries.length === 0) {
+  console.log('No entries found.');
+  return;
+}
+
+// Group by category
+const byCategory: Record<string, typeof entries> = {};
+for (const entry of entries) {
+  if (!byCategory[entry.category]) {
+    byCategory[entry.category] = [];
+  }
+  byCategory[entry.category].push(entry);
+}
+
+console.log(`Found ${entries.length} entries:\n`);
+
+for (const category of DEFAULT_CATEGORIES) {
+  const items = byCategory[category];
+  if (!items || items.length === 0) continue;
+
+  console.log(`## ${category}/ (${items.length})`);
+  for (const entry of items) {
+    const status = entry.frontmatter.status === 'active' ? '' : ` [${entry.frontmatter.status}]`;
+    const conf = entry.frontmatter.confidence;
+    console.log(`  - ${entry.frontmatter.title}${status} (${conf})`);
+  }
+  console.log('');
+}
+```
+
+## Output
+
+```
+Found 12 entries:
+
+## issues/ (4)
+  - Auth Token Expiration Fix (80)
+  - Database Connection Timeout (50)
+  - NPM Permission Error [flagged] (60)
+  - Type Casting Bug (20)
+
+## patterns/ (3)
+  - API Retry Pattern (80)
+  - React Hook Pattern (70)
+  - Error Boundary Pattern (50)
+
+## gotchas/ (1)
+  - Environment Variable Gotcha (60)
+
+## testing/ (2)
+  - Mock Database Strategy (70)
+  - E2E Test Setup (50)
+
+## security/ (1)
+  - JWT Token Validation (80)
+
+## performance/ (1)
+  - Query Optimization Pattern (60)
+```

package/skills/wiki-capture/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: wiki-capture
+description: Intelligent agent that analyzes conversation context and extracts knowledge worth capturing as wiki entries.
+argument-hint: [--category=<cat>] [--title=<title>] [--dry-run]
+context: fork
+agent: general-purpose
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: Read, Write, Glob, Grep
+---
+
+# Wiki Capture Agent
+
+An intelligent agent that analyzes the current conversation context, extracts valuable knowledge, and creates well-structured wiki entries.
+
+## When to Use
+
+- After solving a bug or error
+- After implementing a pattern or approach
+- After discovering a gotcha or pitfall
+- After writing tests with useful patterns
+- After configuring security or performance optimizations
+- When user says "save this", "remember this", "document this"
+
+## Agent Behavior
+
+This agent will:
+
+1. **Analyze conversation context** to identify:
+   - Problems encountered and their solutions
+   - Patterns or approaches used
+   - Gotchas discovered
+   - Code changes made
+   - Files modified
+
+2. **Determine the best category** based on content:
+   - `issues` - Bug fixes, error solutions
+   - `patterns` - Reusable approaches
+   - `gotchas` - Pitfalls to avoid
+   - `testing` - Test strategies
+   - `docs` - Documentation guides
+   - `security` - Auth, vulnerabilities
+   - `performance` - Optimizations
+
+3. **Extract structured content**:
+   - Title (concise, searchable)
+   - Tags (for discovery)
+   - Trigger pattern (for errors)
+   - Problem/Solution sections
+   - Related files
+
+4. **Check for duplicates** before creating
+
+5. **Create the entry** with proper confidence level
+
+## Options
+
+- `--category=<cat>` - Override auto-detected category
+- `--title=<title>` - Override auto-generated title
+- `--confidence=<0-100>` - Set confidence level (default: 50)
+- `--dry-run` - Preview without creating
+
+## Implementation
+
+```typescript
+// Agent: wiki-capture
+// Tools: Read, Write, Glob, Grep
+
+import {
+  wikiExists,
+  createEntryWithValidation,
+  checkDuplicate,
+  generateStubContent,
+  CATEGORY_TEMPLATES
+} from 'solvdex';
+
+const projectRoot = process.cwd();
+const args = $ARGUMENTS.split(' ').filter(Boolean);
+
+// Parse options
+const categoryOverride = args.find(a => a.startsWith('--category='))?.split('=')[1];
+const titleOverride = args.find(a => a.startsWith('--title='))?.split('=')[1];
+const confidenceOverride = args.find(a => a.startsWith('--confidence='))?.split('=')[1];
+const dryRun = args.includes('--dry-run');
+
+if (!wikiExists(projectRoot)) {
+  console.log('No wiki found. Run `/wiki init` first.');
+  return;
+}
+
+console.log('# Wiki Capture Agent\n');
+
+// Analyze conversation context (this is provided by Claude Code)
+const context = getConversationContext(); // Context comes from Claude
+
+if (!context || !context.recentMessages) {
+  console.log('No conversation context available.');
+  console.log('');
+  console.log('**Usage:**');
+  console.log('Run this after solving a problem or implementing something worth remembering.');
+  console.log('');
+  console.log('**Manual capture:**');
+  console.log('```');
+  console.log('/wiki add --category=issues --title="My Solution"');
+  console.log('```');
+  return;
+}
+
+console.log('## Analyzing Conversation...\n');
+
+// Extract signals from context
+const signals = analyzeContext(context);
+
+console.log(`**Detected signals:**`);
+for (const signal of signals) {
+  console.log(`- ${signal.type}: ${signal.description}`);
+}
+console.log('');
+
+// Determine category
+const category = categoryOverride || detectCategory(signals, context);
+console.log(`**Category:** ${category}\n`);
+
+// Generate title
+const title = titleOverride || generateTitle(signals, context);
+console.log(`**Title:** ${title}\n`);
+
+// Extract tags
+const tags = extractTags(signals, context);
+console.log(`**Tags:** ${tags.join(', ')}\n`);
+
+// Check for duplicates
+const dupCheck = await checkDuplicate(projectRoot, title, tags, category);
+if (dupCheck.isDuplicate) {
+  console.log(`## Duplicate Detected\n`);
+  console.log(`Similar entry exists: "${dupCheck.matchedEntry.frontmatter.title}"`);
+  console.log(`Path: ${dupCheck.matchedEntry.path}`);
+  console.log(`Similarity: ${Math.round(dupCheck.similarity * 100)}%`);
+  console.log('');
+  console.log('**Options:**');
+  console.log('- Use `/wiki fix <path>` to update the existing entry');
+  console.log('- Use `--title="Different Title"` to create anyway');
+  return;
+}
+
+// Generate content structure
+const content = generateContent(category, signals, context);
+
+console.log('## Generated Content\n');
+console.log('```markdown');
+for (const [section, text] of Object.entries(content)) {
+  console.log(`# ${section}\n`);
+  console.log(text);
+  console.log('');
+}
+console.log('```\n');
+
+// Extract trigger pattern if it's an error fix
+let trigger = undefined;
+if (category === 'issues' && signals.some(s => s.type === 'error')) {
+  trigger = extractTriggerPattern(signals);
+  if (trigger) {
+    console.log(`**Trigger pattern:** \`${trigger}\`\n`);
+  }
+}
+
+// Set confidence
+const confidence = confidenceOverride ? parseInt(confidenceOverride) : 50;
+
+if (dryRun) {
+  console.log('## Dry Run - No Entry Created\n');
+  console.log('Remove `--dry-run` to create the entry.');
+  return;
+}
+
+// Create the entry
+console.log('## Creating Entry...\n');
+
+const result = await createEntryWithValidation(projectRoot, {
+  category,
+  title,
+  tags,
+  content,
+  trigger,
+  confidence,
+  autoCapture: true,
+  context: 'Captured via /wiki capture agent'
+});
+
+console.log(`Entry created: **${result.entry.path}**`);
+console.log(`Confidence: ${confidence}`);
+
+if (result.qualityIssues.length > 0) {
+  console.log('\n**Quality suggestions:**');
+  for (const issue of result.qualityIssues) {
+    console.log(`- ${issue.message}`);
+  }
+}
+
+console.log('\n---');
+console.log('Use `/wiki browse` to see all entries');
+console.log('Use `/wiki fix <path>` to improve it');
+```
+
+## Output Example
+
+```
+# Wiki Capture Agent
+
+## Analyzing Conversation...
+
+**Detected signals:**
+- error_resolved: Fixed: ETIMEDOUT connecting to database...
+- code_changed: Modified 2 files
+- user_confirmed: User confirmed solution works
+
+**Category:** issues
+
+**Title:** Fix: ETIMEDOUT connecting to database
+
+**Tags:** ts, js, auto-captured
+
+## Generated Content
+
+```markdown
+# Problem
+
+ETIMEDOUT connecting to database at 10.0.0.1:5432
+
+# Cause
+
+Connection pool exhausted due to unclosed connections.
+
+# Solution
+
+TODO: Fill in details
+
+# Prevention
+
+TODO: Fill in details
+```
+
+**Trigger pattern:** `ETIMEDOUT.*database`
+
+## Creating Entry...
+
+Entry created: **issues/fix-etimedout-connecting-to-database.md**
+Confidence: 50
+
+**Quality suggestions:**
+- Solution section needs more detail
+- Consider adding code examples
+
+---
+Use `/wiki browse` to see all entries
+Use `/wiki fix <path>` to improve it
+```
+
+## Auto-Capture Integration
+
+This agent is automatically triggered by the `Stop` hook when:
+- An error was resolved during the session
+- User explicitly confirms solution works
+- User says "save to wiki" or "remember this"
+- Workaround/HACK comments are added to code

package/skills/wiki-explorer/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: wiki-explorer
+description: Deep search agent that explores wiki entries to find relevant knowledge for a given context or question.
+argument-hint: <query>
+context: fork
+agent: Explore
+allowed-tools: Read, Glob, Grep
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Wiki Explorer Agent
+
+An intelligent agent that deeply searches the Solvdex wiki to find relevant knowledge entries for a given question or context.
+
+## When to Use
+
+- Before answering questions about the codebase
+- When troubleshooting errors
+- When implementing features that may have existing patterns
+- When uncertain about conventions or gotchas
+
+## Agent Behavior
+
+This agent will:
+
+1. **Analyze the query** to understand intent and extract keywords
+2. **Search across all categories** using multiple strategies:
+   - Full-text search on titles and content
+   - Tag matching
+   - Trigger pattern matching for errors
+   - Related entry discovery
+3. **Rank and filter results** by relevance and confidence
+4. **Present a summary** with actionable information
+
+## Implementation
+
+```typescript
+// Agent: wiki-explorer
+// Tools: Read, Glob, Grep
+
+import { wikiExists, searchWiki, listEntries, matchTrigger, getBestMatch } from 'solvdex';
+
+const projectRoot = process.cwd();
+const query = $ARGUMENTS;
+
+if (!query) {
+  console.log('Usage: /wiki explore <query>');
+  console.log('');
+  console.log('Examples:');
+  console.log('  /wiki explore database connection timeout');
+  console.log('  /wiki explore how to handle authentication');
+  console.log('  /wiki explore Error: ECONNREFUSED');
+  return;
+}
+
+if (!wikiExists(projectRoot)) {
+  console.log('No wiki found. Run `/wiki init` first.');
+  return;
+}
+
+console.log(`# Wiki Explorer\n`);
+console.log(`Query: "${query}"\n`);
+
+// Strategy 1: Full-text search
+const searchResults = await searchWiki(projectRoot, { query });
+
+// Strategy 2: Check if query looks like an error (try trigger matching)
+const isErrorLike = /error|exception|failed|cannot|unable/i.test(query);
+let triggerResults = [];
+if (isErrorLike) {
+  triggerResults = await matchTrigger(projectRoot, query);
+}
+
+// Strategy 3: Search by category keywords
+const categoryKeywords = {
+  issues: ['error', 'fix', 'bug', 'broken', 'fails'],
+  patterns: ['pattern', 'template', 'how to', 'approach'],
+  gotchas: ['careful', 'avoid', 'pitfall', 'watch out'],
+  testing: ['test', 'mock', 'fixture', 'spec'],
+  security: ['auth', 'token', 'permission', 'vulnerability'],
+  performance: ['slow', 'optimize', 'memory', 'latency']
+};
+
+const relevantCategories = [];
+const queryLower = query.toLowerCase();
+for (const [category, keywords] of Object.entries(categoryKeywords)) {
+  if (keywords.some(kw => queryLower.includes(kw))) {
+    relevantCategories.push(category);
+  }
+}
+
+// Combine and deduplicate results
+const seen = new Set();
+const allResults = [];
+
+// Add trigger matches first (highest priority for errors)
+for (const result of triggerResults) {
+  if (!seen.has(result.entry.path)) {
+    seen.add(result.entry.path);
+    allResults.push({ ...result, source: 'trigger' });
+  }
+}
+
+// Add search results
+for (const result of searchResults) {
+  if (!seen.has(result.entry.path)) {
+    seen.add(result.entry.path);
+    allResults.push({ ...result, source: 'search' });
+  }
+}
+
+// Output results
+if (allResults.length === 0) {
+  console.log('## No Results Found\n');
+  console.log('No wiki entries match your query.\n');
+
+  if (relevantCategories.length > 0) {
+    console.log(`**Suggested categories to check:** ${relevantCategories.join(', ')}`);
+  }
+
+  console.log('\n**Tips:**');
+  console.log('- Try different keywords');
+  console.log('- Use `/wiki browse` to see all entries');
+  console.log('- Use `/wiki scan` to generate stubs from your project');
+  return;
+}
+
+console.log(`## Found ${allResults.length} Relevant Entries\n`);
+
+// Show top results with details
+for (const result of allResults.slice(0, 5)) {
+  const entry = result.entry;
+  const fm = entry.frontmatter;
+
+  console.log(`### ${fm.title}`);
+  console.log(`- **Category:** ${entry.category}`);
+  console.log(`- **Confidence:** ${fm.confidence}`);
+  console.log(`- **Tags:** ${fm.tags.join(', ') || 'none'}`);
+  console.log(`- **Path:** ${entry.path}`);
+
+  if (result.source === 'trigger') {
+    console.log(`- **Match:** Trigger pattern matched`);
+  }
+
+  // Extract and show summary (first 150 chars of content after frontmatter)
+  const contentPreview = entry.content
+    .replace(/^#.*$/gm, '')  // Remove headings
+    .trim()
+    .slice(0, 150);
+
+  if (contentPreview) {
+    console.log(`\n> ${contentPreview}...`);
+  }
+
+  console.log('');
+}
+
+// Show additional results count
+if (allResults.length > 5) {
+  console.log(`\n*... and ${allResults.length - 5} more entries*`);
+}
+
+// Suggest related categories
+if (relevantCategories.length > 0) {
+  console.log(`\n## Related Categories`);
+  console.log(`Consider also checking: ${relevantCategories.join(', ')}`);
+}
+
+console.log('\n---');
+console.log('Use `/wiki search <query>` for simple search');
+console.log('Use `/wiki browse` to view entries by category');
+```
+
+## Output Example
+
+```
+# Wiki Explorer
+
+Query: "database connection timeout"
+
+## Found 3 Relevant Entries
+
+### Database Connection Timeout Fix
+- **Category:** issues
+- **Confidence:** 85
+- **Tags:** database, timeout, postgres
+- **Path:** issues/database-connection-timeout.md
+- **Match:** Trigger pattern matched
+
+> When connecting to PostgreSQL, timeouts can occur due to network issues
+> or connection pool exhaustion. The default timeout of 30s may be...
+
+### Connection Pool Best Practices
+- **Category:** patterns
+- **Confidence:** 80
+- **Tags:** database, connection-pool
+- **Path:** patterns/connection-pool-best-practices.md
+
+> Always configure your connection pool size based on your workload...
+
+### Database Configuration Gotchas
+- **Category:** gotchas
+- **Confidence:** 75
+- **Tags:** database, config
+- **Path:** gotchas/database-config-gotchas.md
+
+> Watch out for these common database configuration mistakes...
+
+## Related Categories
+Consider also checking: issues, performance
+
+---
+Use `/wiki search <query>` for simple search
+Use `/wiki browse` to view entries by category
+```
+
+## Integration
+
+This agent is automatically invoked by hooks when:
+- Session starts with relevant task description
+- Errors are encountered (via PostToolUseFailure hook)
+- Prompts contain wiki-related keywords

package/skills/wiki-export/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: wiki-export
+description: Export Solvdex wiki to a portable JSON file for backup or migration.
+argument-hint: [output-file] [--categories=cat1,cat2] [--include-deprecated]
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Solvdex Export
+
+Export wiki entries to a portable JSON format for backup or migration.
+
+## Options
+
+- `output-file`: Output file path (default: `wiki-export.json`)
+- `--categories=cat1,cat2`: Only export specific categories
+- `--include-deprecated`: Include deprecated entries
+
+## Implementation
+
+```typescript
+import { wikiExists, exportWikiToFile } from 'solvdex';
+import * as path from 'path';
+
+const projectRoot = process.cwd();
+const args = $ARGUMENTS.split(' ').filter(Boolean);
+
+if (!wikiExists(projectRoot)) {
+  console.log('No wiki found. Run `/wiki init` first.');
+  return;
+}
+
+// Parse args
+const outputFile = args.find(a => !a.startsWith('--')) || 'wiki-export.json';
+const categoriesArg = args.find(a => a.startsWith('--categories='));
+const includeDeprecated = args.includes('--include-deprecated');
+
+const categories = categoriesArg
+  ? categoriesArg.replace('--categories=', '').split(',')
+  : undefined;
+
+const outputPath = path.isAbsolute(outputFile)
+  ? outputFile
+  : path.join(projectRoot, outputFile);
+
+console.log('# Solvdex Export\n');
+
+try {
+  await exportWikiToFile(projectRoot, outputPath, {
+    categories,
+    includeDeprecated
+  });
+
+  console.log(`Exported to: ${outputPath}`);
+
+  if (categories) {
+    console.log(`Categories: ${categories.join(', ')}`);
+  }
+  console.log(`Include deprecated: ${includeDeprecated}`);
+  console.log('\nExport complete!');
+} catch (error) {
+  console.error(`Export failed: ${error.message}`);
+}
+```
+
+## Output
+
+```
+# Solvdex Export
+
+Exported to: /path/to/project/wiki-export.json
+Categories: all
+Include deprecated: false
+
+Export complete!
+```
+
+## Export Format
+
+```json
+{
+  "version": "1.0.0",
+  "exportedAt": "2025-01-20T10:30:00Z",
+  "projectName": "my-project",
+  "config": { ... },
+  "entries": [
+    {
+      "path": "issues/database-timeout.md",
+      "category": "issues",
+      "frontmatter": {
+        "title": "Database Connection Timeout",
+        "created": "2025-01-15",
+        "status": "active",
+        "confidence": 80,
+        "tags": ["database", "timeout"]
+      },
+      "content": "# Problem\n..."
+    }
+  ]
+}
+```