solvdex 2.0.0-alpha.8 → 3.1.0-alpha.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Knowledge management plugins for Claude Code",
-    "version": "2.0.0-alpha.8"
+    "version": "3.1.0-alpha.1"
   },
   "plugins": [
     {
@@ -15,8 +15,8 @@
         "source": "url",
         "url": "https://github.com/ducdmdev/solvdex.git"
       },
-      "description": "Auto-capture and retrieve project knowledge - solutions, patterns, gotchas, testing, docs, security, performance",
-      "version": "2.0.0-alpha.8"
+      "description": "Universal problem-solving journal - auto-capture and retrieve knowledge (problems, solutions, references)",
+      "version": "3.1.0-alpha.1"
     }
   ]
 }

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": "2.0.0-alpha.8",
+  "description": "Universal problem-solving journal - auto-captures and retrieves knowledge across problems, solutions, and references",
+  "version": "3.1.0-alpha.1",
   "author": {
     "name": "duc.do",
     "email": "ducdm.dev.work@gmail.com"

package/README.md

@@ -1,11 +1,17 @@
 # Solvdex
 
+[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://github.com/ducdmdev/solvdex)
+[![Version](https://img.shields.io/badge/version-3.1.0--alpha.1-blue)](./package.json)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](./tests)
-[![Version](https://img.shields.io/badge/version-2.0.0--alpha.8-blue)](./package.json)
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
-[![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.
+> **An index of solved problems.** A Claude Code plugin that auto-captures and retrieves knowledge across any domain.
+
+**Quick Install:**
+```bash
+/plugin marketplace add https://raw.githubusercontent.com/ducdmdev/solvdex/main/.claude-plugin/marketplace.json
+/plugin install solvdex
+```
 
 ```
 +-------------------------------------------------------------+
@@ -25,7 +31,7 @@
 |---------|-------------|
 | **Auto-Capture** | Saves solutions when errors are resolved |
 | **Auto-Lookup** | Surfaces relevant knowledge on errors |
-| **7 Categories** | Organized knowledge across development domains |
+| **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 |
@@ -34,16 +40,16 @@
 
 **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.
+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/](./docs/templates/).
 
 > **[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 → capture prompt |
+| **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 7 categories |
+| **Storage** | `.wiki/` with 3 universal folders |
 
 ## Project Structure
 
@@ -57,26 +63,22 @@ solvdex/
 │   ├── stats.md
 │   ├── duplicate-checker.md
 │   ├── health.md
-│   ├── graph.md
-│   └── templates/    # Category templates
-├── skills/           # 18 Claude Code skills (thin wrappers)
+│   └── 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)
+│   ├── schema.md     # Entry schema & constants (source of truth)
+│   └── templates/    # Fixed templates per folder
 └── tests/            # Validation tests
 ```
 
-## Categories
+## Folders
 
 ```
 .wiki/
-├── issues/        # Bug fixes, error solutions
-├── patterns/      # Reusable code patterns
-├── gotchas/       # Pitfalls to avoid
-├── testing/       # Test strategies, mocks
-├── docs/          # Documentation guides
-├── security/      # Auth, vulnerabilities
-└── performance/   # Optimizations, benchmarks
+├── problems/      # What went wrong - bugs, errors, gotchas
+├── solutions/     # How to fix/do things - patterns, recipes
+└── references/    # Things to remember - docs, configs
 ```
 
 ## Quick Start
@@ -89,10 +91,10 @@ solvdex/
 /wiki search "database timeout"
 
 # Add current solution
-/wiki add --category=issues
+/wiki add --folder=problems
 
-# Browse entries
-/wiki browse
+# Browse all entries
+/wiki search
 ```
 
 ## Commands
@@ -102,30 +104,26 @@ solvdex/
 | Command | Description |
 |---------|-------------|
 | `/wiki init` | Create `.wiki/` structure |
-| `/wiki add` | Save current solution |
-| `/wiki search <query>` | Full-text search |
-| `/wiki browse` | List entries with filters |
+| `/wiki add` | Capture knowledge from conversation |
+| `/wiki search [query]` | Search or browse entries (no query = list all) |
 
-### Management Commands
+### Analysis Commands
 
 | Command | Description |
 |---------|-------------|
-| `/wiki status` | Quick health overview |
-| `/wiki stats` | Detailed analytics |
-| `/wiki validate` | Check for issues |
+| `/wiki stats [--quick]` | Statistics and health score |
+| `/wiki health [--validate]` | Health analysis with validation |
 | `/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
+### 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 |
-| `/wiki test-trigger` | Test regex patterns |
 
 ### Agents
 
@@ -133,14 +131,14 @@ All logic is implemented by specialized agents:
 
 | Agent | Commands | Description |
 |-------|----------|-------------|
-| `searcher` | `/wiki search`, `/wiki explore` | Search + recommendations |
-| `capture` | `/wiki add`, `/wiki capture` | Knowledge extraction |
+| `searcher` | `/wiki search` | Search + browse |
+| `capture` | `/wiki add`, `/wiki fix` | Knowledge extraction |
 | `scanner` | `/wiki scan` | Project scanning |
-| `validator` | `/wiki validate` | Quality checks |
+| `validator` | `/wiki flag` | Quality checks |
 | `stats` | `/wiki stats` | Analytics + maturity |
-| `duplicate-checker` | (internal) | Prevent duplicates |
-| `health` | `/wiki health` | Coverage gaps |
+| `health` | `/wiki health` | Coverage gaps + validation |
 | `graph` | `/wiki graph` | Relationship diagrams |
+| `duplicate-checker` | (internal) | Prevent duplicates |
 
 ## How It Works
 
@@ -153,9 +151,9 @@ All logic is implemented by specialized agents:
 +--------------+     +--------------+     +--------------+
 
 Signals detected:
-- error_resolved  -> issues/
-- workaround      -> gotchas/
-- user confirms   -> auto-detect category
+- error_resolved  -> problems/
+- workaround      -> solutions/
+- user confirms   -> auto-detect folder
 - explicit save   -> "remember this"
 ```
 
@@ -170,7 +168,7 @@ Signals detected:
 Lookup triggers:
 - Session start   -> relevant context
 - Error match     -> trigger patterns
-- Prompt keywords -> category detection
+- Prompt keywords -> folder detection
 ```
 
 ## Entry Format
@@ -179,10 +177,20 @@ Lookup triggers:
 ---
 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
@@ -192,11 +200,11 @@ Connection times out after 30 seconds...
 Increase timeout and add connection pool...
 
 ## Related
-- [[issues/connection-pool]]
+- [[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](./docs/schema.md).
+> **Note:** For complete schema details including all fields, maturity levels, and constants, see [docs/schema.md](./docs/schema.md). For entry templates, see [docs/templates/](./docs/templates/).
 
 ### Entry Maturity System
 
@@ -235,28 +243,65 @@ Confidence auto-decays for entries unused for 90+ days.
 
 Real-time integration with Claude Code via contextual prompts:
 
-| Hook | Suggests | When | Purpose |
-|------|----------|------|---------|
-| `SessionStart` | `wiki-advisor` | New conversation | Hint to check for relevant entries |
-| `Stop` | `capture` | Task completes | Hint to capture valuable knowledge |
+| 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
 
-### From Source
+### Option 1: Via Marketplace (Recommended)
+
+Add the Solvdex marketplace to Claude Code, then install:
 
 ```bash
+# 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:
+
+```bash
+# Clone the repository
 git clone https://github.com/ducdmdev/solvdex.git
-cd solvdex
-npm install   # For running tests only
+
+# Start Claude Code with the plugin
+claude --plugin-dir ./solvdex
 ```
 
-### Via Claude Code Marketplace
+### Option 3: Add to Project Settings
+
+For team projects, add to `.claude/settings.json`:
+
+```json
+{
+  "plugins": {
+    "solvdex": {
+      "source": "https://github.com/ducdmdev/solvdex.git"
+    }
+  }
+}
+```
+
+### After Installation
 
 ```bash
-# Coming soon
-/plugin install solvdex
+# Initialize your wiki
+/wiki init
+
+# Scan your project for existing knowledge
+/wiki scan
+
+# Start using!
+/wiki search "your query"
 ```
 
 ## Development
@@ -272,6 +317,7 @@ npm run test:watch   # Watch mode
 | Document | Description |
 |----------|-------------|
 | [Schema Reference](./docs/schema.md) | Entry schema & constants (source of truth) |
+| [Entry Templates](./docs/templates/) | Fixed templates per folder |
 | [Getting Started](./docs/getting-started.md) | Quick setup guide |
 | [Architecture](./docs/architecture.md) | System design |
 | [Workflows](./docs/workflows.md) | Hook and skill flows |

package/agents/capture.md

@@ -1,10 +1,7 @@
 ---
-description: Extract problem/solution from conversation context and create wiki entry.
-  Smart categorization, duplicate checking, tag suggestions.
-tools:
-  - Glob
-  - Read
-  - Write
+name: capture
+description: Extract problem/solution from conversation context and create wiki entry. Smart categorization, duplicate checking, tag suggestions.
+tools: Glob, Read, Write
 ---
 
 # Wiki Capture Agent
@@ -14,10 +11,11 @@ tools:
 For entry structure, validation rules, and constants, see: `docs/schema.md`
 
 Key references:
-- Entry frontmatter fields: `docs/schema.md#entry-frontmatter`
+- Entry frontmatter fields: `docs/schema.md#entryfrontmatter`
 - Maturity rules: `docs/schema.md#maturity-rules`
-- Confidence levels: `docs/schema.md#confidence-levels`
-- Categories: `docs/schema.md#default-categories`
+- Confidence levels: `docs/schema.md#confidence-constants`
+- Folders: `docs/schema.md#default-folders`
+- Entry Templates: `docs/templates/` (problems.md, solutions.md, references.md)
 
 Intelligently extract problem and solution from conversation context to create a wiki entry.
 
@@ -30,7 +28,7 @@ You will receive conversation context containing:
 
 Optional parameters:
 - `mode: "auto-capture"` - Auto-capture from conversation (hook)
-- `category: "<category>"` - Force specific category
+- `folder: "<folder>"` - Force specific folder (problems, solutions, references)
 - `title: "<title>"` - Force specific title
 
 ## Process
@@ -58,9 +56,9 @@ Include relevant code snippets (max 20 lines).
 
 **IMPORTANT: Always check before creating!**
 
-1. Search existing entries in detected category:
+1. Search existing entries in detected folder:
    ```
-   Glob .wiki/<category>/*.md
+   Glob .wiki/<folder>/*.md
    ```
 
 2. Compare semantically:
@@ -70,29 +68,29 @@ Include relevant code snippets (max 20 lines).
 
 3. If >80% similarity found:
    ```
-   Similar entry exists: category/existing-entry.md
-   Consider updating it instead: /wiki fix category/existing-entry.md
+   Similar entry exists: folder/existing-entry.md
+   Consider updating it instead: /wiki fix folder/existing-entry.md
    ```
    Do NOT create new entry.
 
 4. If 50-79% similarity:
    ```
-   Related entry found: category/related-entry.md
+   Related entry found: folder/related-entry.md
    Creating new entry and linking to related.
    ```
    Create entry with `related_entries` field.
 
-### Step 4: Determine Category
+### Step 4: Determine Folder
 
-| 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 |
+Analyze content to determine the appropriate folder:
+
+| Content Analysis | Folder |
+|------------------|--------|
+| Problem encountered, error, failure, blocker, bug, crash, exception, pitfall, gotcha, warning, careful, avoid, security issue | problems/ |
+| How-to, procedure, recipe, pattern, template, approach, optimization, test strategy, workflow, steps to do something | solutions/ |
+| Documentation, reference, config, link, guide, API docs, notes, information to remember | references/ |
+
+**AI decides automatically.** If genuinely uncertain (>30% confidence in multiple folders), default to `problems/` for issues or `references/` for informational content.
 
 ### Step 5: Generate Tags
 
@@ -119,36 +117,117 @@ Create a concise, descriptive title:
 - Include technology: "TypeScript Generic Constraint Issue"
 - Max 60 characters
 
-### Step 7: Create Entry Using Template
+### Step 7: Create Entry Using Fixed Template
 
-1. Read template for detected category:
-   ```
-   Read agents/templates/<category>.md
-   ```
+**Use the fixed template for the target folder.** See `docs/templates/` for full templates.
+
+1. **Select template** based on folder:
+
+| Folder | Template Sections |
+|--------|-------------------|
+| `problems/` | Problem, Cause, Solution, Prevention, Related |
+| `solutions/` | Overview, Prerequisites, Steps, Example, Related |
+| `references/` | Summary, Details, Links, Related |
+
+2. **Fill frontmatter**:
+
+```yaml
+---
+title: {{generated_title}}
+created: {{today YYYY-MM-DD}}
+updated: {{today YYYY-MM-DD}}
+status: active
+confidence: 40
+maturity: captured
+tags: [{{extracted_tags}}]
+trigger: "{{error_regex}}"  # problems/ only
+source: capture-agent
+use_count: 0
+audit:
+  - date: {{today YYYY-MM-DD}}
+    action: created
+    by: capture-agent
+---
+```
+
+3. **Fill template sections** with extracted content:
 
-2. Replace placeholders with extracted values:
-   - `{{title}}` → generated title
-   - `{{created}}` → today's date (YYYY-MM-DD)
-   - `{{updated}}` → today's date (YYYY-MM-DD)
-   - `{{tags}}` → comma-separated tags
-   - `{{trigger}}` → error regex pattern (issues/security/performance only)
-   - `{{source}}` → "conversation" or "capture-agent"
-   - `{{created_by}}` → "capture-agent"
-   - Section placeholders → extracted content
+**For problems/**:
+- Problem: The error or issue encountered
+- Cause: Root cause analysis
+- Solution: Fix steps or code
+- Prevention: How to avoid in future
 
-3. Write filled template to `.wiki/<category>/<slug>.md`
+**For solutions/**:
+- Overview: What this does and when to use
+- Prerequisites: What's needed first
+- Steps: Numbered procedure
+- Example: Code or config sample
+
+**For references/**:
+- Summary: Brief description
+- Details: Information to remember
+- Links: External resources
+
+4. **Add Related section** with relative paths (NOT absolute):
+
+```markdown
+## Related
+
+- `internal/auth/handler.go`     ✅ Relative from project root
+- `docs/api.md`                  ✅ Relative from project root
+- [Other Entry](../problems/x.md) ✅ Wiki cross-link
+- `/Users/foo/project/file.go`   ❌ Never use absolute paths
+```
+
+5. **Write to** `.wiki/<folder>/<slug>.md`
 
 ### Step 8: Return Confirmation
 
 ```
-Captured: category/entry-name.md
+Captured: folder/entry-name.md
    Title: Entry Title
+   Folder: problems | solutions | references
    Tags: tag1, tag2, tag3
    Confidence: 40 (captured)
 
-   Edit: /wiki fix category/entry-name.md
+   Edit: /wiki fix folder/entry-name.md
 ```
 
+### Step 9: Update Index
+
+After creating the entry file, update the index:
+
+1. **Read index**: Try Read `.wiki/index.json`
+   - If missing: create new index with this entry only
+   - If exists: parse JSON
+
+2. **Add entry to index**:
+   ```json
+   {
+     "path": "<folder>/<slug>.md",
+     "title": "<generated_title>",
+     "folder": "<folder>",
+     "tags": ["<tags>"],
+     "trigger": "<regex>",
+     "confidence": 40,
+     "maturity": "captured",
+     "status": "active",
+     "use_count": 0
+   }
+   ```
+
+3. **Update stats**:
+   - Increment `stats.total`
+   - Increment `stats.by_folder[folder]`
+   - Increment `stats.by_maturity.captured`
+
+4. **Update timestamp**: Set `updated` to current ISO timestamp
+
+5. **Write index**: Write `.wiki/index.json`
+
+**If index write fails**: Log warning but don't fail entry creation. Index can be rebuilt with `/wiki health --reindex`.
+
 ## Important Rules
 
 1. **Always check duplicates first** - don't create redundant entries
@@ -156,5 +235,5 @@ Captured: category/entry-name.md
 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
+6. **Add trigger patterns** - for problems folder, extract regex
 7. **Link related entries** - build the knowledge graph

package/agents/duplicate-checker.md

@@ -1,9 +1,7 @@
 ---
-description: Check if a new entry would duplicate existing knowledge.
-  Uses semantic similarity, not just title matching.
-tools:
-  - Glob
-  - Read
+name: duplicate-checker
+description: Check if a new entry would duplicate existing knowledge. Uses semantic similarity, not just title matching.
+tools: Glob, Read
 ---
 
 # Wiki Duplicate Checker Agent
@@ -16,7 +14,7 @@ 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`
+- Folders: `docs/schema.md#default-folders`
 
 Detect potential duplicate entries before creation.
 
@@ -26,14 +24,14 @@ Detect potential duplicate entries before creation.
 {
   "title": "Database Connection Timeout",
   "tags": ["database", "timeout", "postgres"],
-  "category": "issues",
+  "folder": "problems",
   "contentSummary": "Fix for connection pool exhaustion..."
 }
 ```
 
 ## Process
 
-1. Load existing entries in same category
+1. Load existing entries in same folder
 2. Compare semantically:
    - Title similarity (exact, partial, synonym)
    - Tag overlap (Jaccard similarity)
@@ -48,7 +46,7 @@ Detect potential duplicate entries before creation.
 {
   "isDuplicate": true,
   "similarity": 85,
-  "matchedEntry": "issues/db-timeout.md",
+  "matchedEntry": "problems/db-timeout.md",
   "matchedTitle": "Database Timeout Fix",
   "reason": "Very similar title and tags",
   "suggestion": "Consider updating existing entry instead"
@@ -60,7 +58,7 @@ Detect potential duplicate entries before creation.
 {
   "isDuplicate": false,
   "similarity": 20,
-  "closestMatch": "issues/connection-error.md",
+  "closestMatch": "problems/connection-error.md",
   "suggestion": "Safe to create new entry"
 }
 ```
@@ -94,5 +92,5 @@ Detect potential duplicate entries before creation.
 
 1. Be conservative - prefer false positives over duplicates
 2. Consider synonyms (e.g., "timeout" ≈ "connection timeout")
-3. Same category increases likelihood
+3. Same folder increases likelihood
 4. Different maturity levels can coexist (stub vs detailed)