solvdex 1.0.5 → 2.0.0-alpha.3

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Knowledge management plugins for Claude Code",
-    "version": "1.0.5"
+    "version": "2.0.0-alpha.3"
   },
   "plugins": [
     {
@@ -16,7 +16,7 @@
         "url": "https://github.com/ducdmdev/solvdex.git"
       },
       "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
-      "version": "1.0.5"
+      "version": "2.0.0-alpha.3"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "solvdex",
   "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
-  "version": "1.0.5",
+  "version": "2.0.0-alpha.3",
   "author": {
     "name": "duc.do",
     "email": "ducdm.dev.work@gmail.com"

package/README.md

@@ -1,34 +1,61 @@
 # Solvdex
 
-[![Tests](https://img.shields.io/badge/tests-204%20passed-brightgreen)](./tests)
-[![Version](https://img.shields.io/badge/version-0.3.0-blue)](./package.json)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](./tests)
+[![Version](https://img.shields.io/badge/version-2.0.0--alpha.3-blue)](./package.json)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+[![Architecture](https://img.shields.io/badge/architecture-pure%20agent-purple)](./docs/schema.md)
 
 > **An index of solved problems.** A Claude Code plugin that auto-captures and retrieves project knowledge.
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  Error: ETIMEDOUT connecting to database                    │
-├─────────────────────────────────────────────────────────────┤
-│  📚 Solvdex found a solution:                               │
-│     "Database Connection Timeout"                           │
-│     Confidence: 85                                          │
-│                                                             │
-│     Solution: Increase pool timeout in config...            │
-└─────────────────────────────────────────────────────────────┘
++-------------------------------------------------------------+
+|  Error: ETIMEDOUT connecting to database                    |
++-------------------------------------------------------------+
+|  Solvdex found a solution:                                  |
+|     "Database Connection Timeout"                           |
+|     Confidence: 85                                          |
+|                                                             |
+|     Solution: Increase pool timeout in config...            |
++-------------------------------------------------------------+
 ```
 
 ## Features
 
 | Feature | Description |
 |---------|-------------|
-| 🔄 **Auto-Capture** | Saves solutions when errors are resolved |
-| 🔍 **Auto-Lookup** | Surfaces relevant knowledge on errors |
-| 📊 **7 Categories** | Organized knowledge across development domains |
-| 🎯 **Trigger Patterns** | Regex matching for automatic error detection |
-| 📈 **Confidence Tracking** | Trust scores with decay over time |
-| 🔗 **Cross-References** | Link related entries and source files |
+| **Auto-Capture** | Saves solutions when errors are resolved |
+| **Auto-Lookup** | Surfaces relevant knowledge on errors |
+| **7 Categories** | Organized knowledge across development domains |
+| **Trigger Patterns** | Regex matching for automatic error detection |
+| **Confidence Tracking** | Trust scores with decay over time |
+| **Cross-References** | Link related entries and source files |
+
+## Architecture
+
+**Pure Agent Plugin - No Code Required**
+
+Solvdex 2.0 uses a pure agent-based architecture. All logic is implemented in agent markdown files - no TypeScript compilation needed.
+
+> **[View Architecture Diagram](./docs/diagrams/architecture-overview.md)**
+
+| Layer | Components |
+|-------|------------|
+| **Skills (18)** | `/wiki search`, `/wiki add`, `/wiki health`, etc. |
+| **Hooks** | SessionStart → wiki-advisor prompt, Stop → wiki-capture prompt |
+| **Agents (8)** | wiki-searcher, wiki-capture, wiki-scanner, wiki-validator, wiki-stats, wiki-health, wiki-graph, wiki-duplicate |
+| **Storage** | `.wiki/` with 7 categories |
+
+## Project Structure
+
+```
+solvdex/
+├── agents/      # 8 specialized agents (ALL logic)
+├── skills/      # 18 Claude Code skills (thin wrappers)
+├── hooks/       # hooks.json (prompt-based hints)
+├── docs/        # Documentation
+│   └── schema.md  # Entry schema & constants (source of truth)
+└── tests/       # Validation tests
+```
 
 ## Categories
 
@@ -80,6 +107,8 @@
 | `/wiki scan` | Generate stubs from project |
 | `/wiki flag <entry>` | Mark for review |
 | `/wiki fix <entry>` | Update flagged entry |
+| `/wiki health` | Coverage gaps and health analysis |
+| `/wiki graph` | Relationship diagrams |
 
 ### Transfer Commands
 
@@ -91,40 +120,48 @@
 
 ### Agents
 
-| Command | Description |
-|---------|-------------|
-| `/wiki explore <query>` | Deep multi-strategy search |
-| `/wiki capture` | Extract knowledge from conversation |
+All logic is implemented by specialized agents:
+
+| Agent | Commands | Description |
+|-------|----------|-------------|
+| `wiki-searcher` | `/wiki search`, `/wiki explore` | Search + recommendations |
+| `wiki-capture` | `/wiki add`, `/wiki capture` | Knowledge extraction |
+| `wiki-scanner` | `/wiki scan` | Project scanning |
+| `wiki-validator` | `/wiki validate` | Quality checks |
+| `wiki-stats` | `/wiki stats` | Analytics + maturity |
+| `wiki-duplicate-checker` | (internal) | Prevent duplicates |
+| `wiki-health` | `/wiki health` | Coverage gaps |
+| `wiki-graph` | `/wiki graph` | Relationship diagrams |
 
 ## How It Works
 
 ### Automatic Knowledge Capture
 
 ```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│  You solve   │────▶│   Solvdex    │────▶│   .wiki/     │
-│  an error    │     │   detects    │     │   saved!     │
-└──────────────┘     └──────────────┘     └──────────────┘
++--------------+     +--------------+     +--------------+
+|  You solve   |---->|   Solvdex    |---->|   .wiki/     |
+|  an error    |     |   detects    |     |   saved!     |
++--------------+     +--------------+     +--------------+
 
 Signals detected:
-• error_resolved  → issues/
-• workaround      → gotchas/
-• user confirms   → auto-detect category
-• explicit save   → "remember this"
+- error_resolved  -> issues/
+- workaround      -> gotchas/
+- user confirms   -> auto-detect category
+- explicit save   -> "remember this"
 ```
 
 ### Automatic Knowledge Retrieval
 
 ```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│  Error       │────▶│   Solvdex    │────▶│   Solution   │
-│  occurs      │     │   matches    │     │   displayed  │
-└──────────────┘     └──────────────┘     └──────────────┘
++--------------+     +--------------+     +--------------+
+|  Error       |---->|   Solvdex    |---->|   Solution   |
+|  occurs      |     |   matches    |     |   displayed  |
++--------------+     +--------------+     +--------------+
 
 Lookup triggers:
-• Session start   → relevant context
-• Error match     → trigger patterns
-• Prompt keywords → category detection
+- Session start   -> relevant context
+- Error match     -> trigger patterns
+- Prompt keywords -> category detection
 ```
 
 ## Entry Format
@@ -150,7 +187,7 @@ Increase timeout and add connection pool...
 - `src/db/config.ts:45`
 ```
 
-> **Note:** Entries also include maturity tracking fields (`maturity`, `use_count`, `last_used`). See [Entry Maturity System](#entry-maturity-system) below.
+> **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md).
 
 ### Entry Maturity System
 
@@ -164,9 +201,9 @@ Solvdex automatically tracks and promotes entries through maturity phases based
 
 **Automatic Promotion:**
 - Entries start as `captured` when created
-- Maturity is evaluated automatically each time `recordEntryUsage()` is called
-- After 3 successful uses → promoted to `verified`
-- After 10 uses AND 30+ days → promoted to `validated`
+- Maturity is evaluated automatically on each use
+- After 3 successful uses: promoted to `verified`
+- After 10 uses AND 30+ days: promoted to `validated`
 - Confidence scores update automatically with maturity
 
 **Safety Features:**
@@ -175,45 +212,26 @@ Solvdex automatically tracks and promotes entries through maturity phases based
 - Maturity only goes up (no demotion)
 - All promotions logged in audit trail
 
-**Example Entry:**
-```yaml
----
-title: Fix Redis Connection Timeout
-maturity: verified
-confidence: 70
-use_count: 5
-last_used: 2025-01-23
-audit:
-  - date: 2025-01-20
-    action: created
-    by: user
-  - date: 2025-01-22
-    action: maturity_promoted
-    by: system
-    context: "Auto-promoted: captured → verified (3 uses)"
----
-```
-
 ## Confidence Scale
 
 | Score | Level | Meaning |
 |-------|-------|---------|
-| 90-100 | 🟢 High | Typically validated entries |
-| 60-89 | 🟡 Medium | Typically verified entries or manually set |
-| 0-59 | 🔴 Low | Typically captured entries or stubs |
+| 90-100 | High | Typically validated entries |
+| 60-89 | Medium | Typically verified entries or manually set |
+| 0-59 | Low | Typically captured entries or stubs |
 
 Confidence auto-decays for entries unused for 90+ days.
 
-## Hooks
+## Hooks (Prompt-Based)
+
+Real-time integration with Claude Code via contextual prompts:
 
-Real-time integration with Claude Code:
+| Hook | Suggests | When | Purpose |
+|------|----------|------|---------|
+| `SessionStart` | `wiki-advisor` | New conversation | Hint to check for relevant entries |
+| `Stop` | `wiki-capture` | Task completes | Hint to capture valuable knowledge |
 
-| Hook | When | Action |
-|------|------|--------|
-| `SessionStart` | New conversation | Surface relevant entries |
-| `UserPromptSubmit` | Each prompt | Enrich with context |
-| `PostToolUseFailure` | Error occurs | Show matching solutions |
-| `Stop` | Task completes | Offer to capture knowledge |
+Hooks are configured in `hooks/hooks.json` and provide prompt-based guidance to use wiki agents.
 
 ## Installation
 
@@ -222,8 +240,7 @@ Real-time integration with Claude Code:
 ```bash
 git clone https://github.com/ducdmdev/solvdex.git
 cd solvdex
-npm install
-npm run build
+npm install   # For running tests only
 ```
 
 ### Via Claude Code Marketplace
@@ -233,38 +250,27 @@ npm run build
 /plugin install solvdex
 ```
 
+## Development
+
+```bash
+npm install      # Install dependencies (for tests only)
+npm test         # Run validation tests
+npm run test:watch   # Watch mode
+```
+
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
+| [Schema Reference](./docs/schema.md) | Entry schema & constants (source of truth) |
 | [Getting Started](./docs/getting-started.md) | Quick setup guide |
 | [Architecture](./docs/architecture.md) | System design |
 | [Workflows](./docs/workflows.md) | Hook and skill flows |
 | [Use Cases](./docs/use-cases.md) | Common scenarios |
 
-## Development
-
-```bash
-npm install      # Install dependencies
-npm run build    # Compile TypeScript
-npm test         # Run 204 tests
-npm run lint     # Check code style
-```
-
-## Project Structure
-
-```
-solvdex/
-├── src/         # Core TypeScript library
-├── skills/      # 16 Claude Code skills
-├── hooks/       # 4 automated hooks
-├── docs/        # Documentation
-└── tests/       # Test suite (204 tests)
-```
-
 ## License
 
-MIT © [duc.do](https://github.com/ducdmdev)
+MIT (c) [duc.do](https://github.com/ducdmdev)
 
 ---
 

package/agents/wiki-capture/AGENT.md

@@ -0,0 +1,182 @@
+---
+description: Extract problem/solution from conversation context and create wiki entry.
+  Smart categorization, duplicate checking, tag suggestions.
+tools:
+  - Glob
+  - Read
+  - Write
+---
+
+# Wiki Capture Agent
+
+## Schema Reference
+
+For entry structure, validation rules, and constants, see: `docs/schema.md`
+
+Key references:
+- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Maturity rules: `docs/schema.md#maturity-rules`
+- Confidence levels: `docs/schema.md#confidence-levels`
+- Categories: `docs/schema.md#default-categories`
+
+Intelligently extract problem and solution from conversation context to create a wiki entry.
+
+## Input
+
+You will receive conversation context containing:
+- Error messages or problem descriptions
+- Solution steps or code fixes
+- Verification that solution worked
+
+Optional parameters:
+- `mode: "auto-capture"` - Auto-capture from conversation (hook)
+- `category: "<category>"` - Force specific category
+- `title: "<title>"` - Force specific title
+
+## Process
+
+### Step 1: Extract Problem
+
+Look for:
+- Error messages: `Error:`, `Exception:`, `failed`, `timeout`
+- Problem statements: "I'm trying to...", "It doesn't work when..."
+- Stack traces or logs
+
+Summarize in 1-3 sentences.
+
+### Step 2: Extract Solution
+
+Look for:
+- Code changes or fixes
+- Configuration updates
+- Commands that resolved the issue
+- Explanation of what worked
+
+Include relevant code snippets (max 20 lines).
+
+### Step 3: Check for Duplicates
+
+**IMPORTANT: Always check before creating!**
+
+1. Search existing entries in detected category:
+   ```
+   Glob .wiki/<category>/*.md
+   ```
+
+2. Compare semantically:
+   - Title similarity (exact, partial, synonym)
+   - Tag overlap
+   - Content similarity
+
+3. If >80% similarity found:
+   ```
+   Similar entry exists: category/existing-entry.md
+   Consider updating it instead: /wiki fix category/existing-entry.md
+   ```
+   Do NOT create new entry.
+
+4. If 50-79% similarity:
+   ```
+   Related entry found: category/related-entry.md
+   Creating new entry and linking to related.
+   ```
+   Create entry with `related_entries` field.
+
+### Step 4: Determine Category
+
+| Keywords/Context | Category |
+|------------------|----------|
+| Error, Exception, bug, fix, crash | issues |
+| Pattern, approach, template, design | patterns |
+| Warning, pitfall, gotcha, careful, avoid | gotchas |
+| Test, mock, assert, spec, fixture | testing |
+| Auth, permission, token, secret, security | security |
+| Slow, optimize, cache, memory, performance | performance |
+| Doc, readme, guide, documentation | docs |
+
+### Step 5: Generate Tags
+
+**Reuse existing tags when possible!**
+
+1. Read existing tags from wiki:
+   ```
+   Grep "tags:" .wiki/**/*.md
+   ```
+
+2. Extract candidates from content:
+   - Technology names (go, typescript, postgres)
+   - Concepts (auth, api, database)
+   - Error types (timeout, null, parse)
+
+3. Prefer existing tags over new ones
+4. Limit to 3-5 most relevant
+
+### Step 6: Generate Title
+
+Create a concise, descriptive title:
+- Start with action verb if fix: "Fix Database Timeout"
+- Be specific: "Redis Connection Pool Exhaustion" not "Database Error"
+- Include technology: "TypeScript Generic Constraint Issue"
+- Max 60 characters
+
+### Step 7: Create Entry
+
+Write to `.wiki/<category>/<slug>.md`:
+
+```yaml
+---
+title: Descriptive Title
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+status: active
+confidence: 40
+maturity: captured
+tags: [tag1, tag2, tag3]
+trigger: "error pattern regex"  # For issues category
+use_count: 0
+related_entries:  # If found related entries
+  - category/related-entry.md
+audit:
+  - date: YYYY-MM-DD
+    action: created
+    by: capture-agent
+    context: Auto-captured from conversation
+---
+
+# Problem
+
+<extracted problem description>
+
+# Solution
+
+<extracted solution with code>
+
+# Verification
+
+<how to verify it works, or "Verified in conversation">
+
+# Related
+
+- [[category/related-entry]]  # If applicable
+```
+
+### Step 8: Return Confirmation
+
+```
+Captured: category/entry-name.md
+   Title: Entry Title
+   Tags: tag1, tag2, tag3
+   Confidence: 40 (captured)
+
+   Edit: /wiki fix category/entry-name.md
+```
+
+## Important Rules
+
+1. **Always check duplicates first** - don't create redundant entries
+2. **Reuse existing tags** - maintain consistent tagging
+3. **Include code** - solutions need concrete examples
+4. **Keep it concise** - problem/solution should be scannable
+5. **Set confidence 40** - captured entries start at maturity baseline
+6. **Add trigger patterns** - for issues category, extract regex
+7. **Link related entries** - build the knowledge graph

package/agents/wiki-duplicate-checker/AGENT.md

@@ -0,0 +1,98 @@
+---
+description: Check if a new entry would duplicate existing knowledge.
+  Uses semantic similarity, not just title matching.
+tools:
+  - Glob
+  - Read
+---
+
+# Wiki Duplicate Checker Agent
+
+## Schema Reference
+
+For entry structure, validation rules, and constants, see: `docs/schema.md`
+
+Key references:
+- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Maturity rules: `docs/schema.md#maturity-rules`
+- Confidence levels: `docs/schema.md#confidence-levels`
+- Categories: `docs/schema.md#default-categories`
+
+Detect potential duplicate entries before creation.
+
+## Input
+
+```json
+{
+  "title": "Database Connection Timeout",
+  "tags": ["database", "timeout", "postgres"],
+  "category": "issues",
+  "contentSummary": "Fix for connection pool exhaustion..."
+}
+```
+
+## Process
+
+1. Load existing entries in same category
+2. Compare semantically:
+   - Title similarity (exact, partial, synonym)
+   - Tag overlap (Jaccard similarity)
+   - Content overlap (key phrases)
+3. Calculate overall similarity score
+4. Determine if duplicate
+
+## Output Format
+
+### Duplicate Found
+```json
+{
+  "isDuplicate": true,
+  "similarity": 85,
+  "matchedEntry": "issues/db-timeout.md",
+  "matchedTitle": "Database Timeout Fix",
+  "reason": "Very similar title and tags",
+  "suggestion": "Consider updating existing entry instead"
+}
+```
+
+### No Duplicate
+```json
+{
+  "isDuplicate": false,
+  "similarity": 20,
+  "closestMatch": "issues/connection-error.md",
+  "suggestion": "Safe to create new entry"
+}
+```
+
+## Similarity Thresholds
+
+| Score | Meaning | Action |
+|-------|---------|--------|
+| 80-100 | Likely duplicate | Block creation, suggest merge |
+| 50-79 | Possibly related | Warn, suggest linking |
+| 0-49 | Distinct | Allow creation |
+
+## Similarity Calculation
+
+### Title Similarity (40% weight)
+- Exact match: 100
+- Contains same words: 80
+- Synonyms/related: 60
+- Partial match: 40
+
+### Tag Overlap (30% weight)
+- Jaccard index: |intersection| / |union|
+- Score = Jaccard * 100
+
+### Content Overlap (30% weight)
+- Key phrase matching
+- Problem/solution similarity
+- Technology overlap
+
+## Important Rules
+
+1. Be conservative - prefer false positives over duplicates
+2. Consider synonyms (e.g., "timeout" ≈ "connection timeout")
+3. Same category increases likelihood
+4. Different maturity levels can coexist (stub vs detailed)