Solvdex

An index of solved problems. A Claude Code plugin that auto-captures and retrieves knowledge across any domain.

Quick Install:

/plugin marketplace add https://raw.githubusercontent.com/ducdmdev/solvdex/main/.claude-plugin/marketplace.json
/plugin install solvdex

+-------------------------------------------------------------+
|  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 | | 3 Folders | Organized knowledge: problems, solutions, references | | 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 3.0 uses a pure agent-based architecture. All logic is implemented in agent markdown files - no TypeScript compilation needed. Fixed templates per folder ensure consistency. See docs/templates/.

View Architecture Diagram

| Layer | Components | |-------|------------| | Skills (12) | /wiki search, /wiki add, /wiki health, etc. | | Hooks | SessionStart → entry count, PreToolUse → context hints, Stop → capture prompt | | Agents (8) | searcher, capture, scanner, validator, stats, health, graph, duplicate-checker | | Storage | .wiki/ with 3 universal folders |

Project Structure

solvdex/
├── agents/           # 8 specialized agents as flat .md files
│   ├── searcher.md
│   ├── capture.md
│   ├── scanner.md
│   ├── validator.md
│   ├── stats.md
│   ├── duplicate-checker.md
│   ├── health.md
│   └── graph.md
├── skills/           # 12 Claude Code skills (thin wrappers)
├── hooks/            # hooks.json (prompt-based hints)
├── docs/             # Documentation
│   ├── schema.md     # Entry schema & constants (source of truth)
│   └── templates/    # Fixed templates per folder
└── tests/            # Validation tests

Folders

.wiki/
├── problems/      # What went wrong - bugs, errors, gotchas
├── solutions/     # How to fix/do things - patterns, recipes
└── references/    # Things to remember - docs, configs

Quick Start

# Initialize wiki
/wiki init

# Search for solutions
/wiki search "database timeout"

# Add current solution
/wiki add --folder=problems

# Browse all entries
/wiki search

Commands

Core Commands

| Command | Description | |---------|-------------| | /wiki init | Create .wiki/ structure | | /wiki add | Capture knowledge from conversation | | /wiki search [query] | Search or browse entries (no query = list all) |

Analysis Commands

| Command | Description | |---------|-------------| | /wiki stats [--quick] | Statistics and health score | | /wiki health [--validate] | Health analysis with validation | | /wiki scan | Generate stubs from project | | /wiki graph | Relationship diagrams |

Entry Management

| Command | Description | |---------|-------------| | /wiki flag <entry> | Mark for review | | /wiki fix <entry> | Update flagged entry | | /wiki export [file] | Export to JSON | | /wiki import <file> | Import from JSON |

Agents

All logic is implemented by specialized agents:

| Agent | Commands | Description | |-------|----------|-------------| | searcher | /wiki search | Search + browse | | capture | /wiki add, /wiki fix | Knowledge extraction | | scanner | /wiki scan | Project scanning | | validator | /wiki flag | Quality checks | | stats | /wiki stats | Analytics + maturity | | health | /wiki health | Coverage gaps + validation | | graph | /wiki graph | Relationship diagrams | | duplicate-checker | (internal) | Prevent duplicates |

How It Works

Automatic Knowledge Capture

+--------------+     +--------------+     +--------------+
|  You solve   |---->|   Solvdex    |---->|   .wiki/     |
|  an error    |     |   detects    |     |   saved!     |
+--------------+     +--------------+     +--------------+

Signals detected:
- error_resolved  -> problems/
- workaround      -> solutions/
- user confirms   -> auto-detect folder
- explicit save   -> "remember this"

Automatic Knowledge Retrieval

+--------------+     +--------------+     +--------------+
|  Error       |---->|   Solvdex    |---->|   Solution   |
|  occurs      |     |   matches    |     |   displayed  |
+--------------+     +--------------+     +--------------+

Lookup triggers:
- Session start   -> relevant context
- Error match     -> trigger patterns
- Prompt keywords -> folder detection

Entry Format

---
title: Database Connection Timeout
created: 2025-01-20
updated: 2025-01-20
status: active
confidence: 85
maturity: verified
tags: [database, timeout, postgres]
trigger: "ETIMEDOUT.*postgres"
use_count: 5
last_used: 2025-01-20
related_entries:
  - .wiki/solutions/connection-pool-config.md
audit:
  - date: 2025-01-20
    action: created
    by: user
---

## Problem
Connection times out after 30 seconds...

## Solution
Increase timeout and add connection pool...

## Related
- [[solutions/connection-pool-config]]
- `src/db/config.ts:45`

Note: For complete schema details including all fields, maturity levels, and constants, see docs/schema.md. For entry templates, see docs/templates/.

Entry Maturity System

Solvdex automatically tracks and promotes entries through maturity phases based on usage:

| Maturity | Criteria | Confidence | Meaning | |----------|----------|------------|---------| | captured | 0-2 uses | 40 | Newly documented, unverified | | verified | 3+ uses | 70 | Proven to work multiple times | | validated | 10+ uses, 30+ days old | 90 | Battle-tested over time |

Automatic Promotion:

• Entries start as captured when created
• 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:

• Flagged entries freeze maturity progression
• Manual maturity overrides are respected
• Maturity only goes up (no demotion)
• All promotions logged in audit trail

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 |

Confidence auto-decays for entries unused for 90+ days.

Hooks (Prompt-Based)

Real-time integration with Claude Code via contextual prompts:

| Hook | When | Purpose | |------|------|---------| | SessionStart | New conversation | Shows entry count, hints to use /wiki search | | PreToolUse | Before Edit/Write | Shows problems/solutions count for context | | Stop | Task completes | Hint to capture valuable knowledge |

Hooks are configured in hooks/hooks.json and provide prompt-based guidance to use wiki agents.

Installation

Option 1: Via Marketplace (Recommended)

Add the Solvdex marketplace to Claude Code, then install:

# Step 1: Add marketplace
/plugin marketplace add https://raw.githubusercontent.com/ducdmdev/solvdex/main/.claude-plugin/marketplace.json

# Step 2: Install plugin
/plugin install solvdex

Option 2: Load Directly from GitHub

Clone and load the plugin directly:

# Clone the repository
git clone https://github.com/ducdmdev/solvdex.git

# Start Claude Code with the plugin
claude --plugin-dir ./solvdex

Option 3: Add to Project Settings

For team projects, add to .claude/settings.json:

{
  "plugins": {
    "solvdex": {
      "source": "https://github.com/ducdmdev/solvdex.git"
    }
  }
}

After Installation

# Initialize your wiki
/wiki init

# Scan your project for existing knowledge
/wiki scan

# Start using!
/wiki search "your query"

Development

npm install      # Install dependencies (for tests only)
npm test         # Run validation tests
npm run test:watch   # Watch mode

Documentation

| Document | Description | |----------|-------------| | Schema Reference | Entry schema & constants (source of truth) | | Entry Templates | Fixed templates per folder | | Getting Started | Quick setup guide | | Architecture | System design | | Workflows | Hook and skill flows | | Use Cases | Common scenarios |

License

MIT (c) duc.do