ima-claude 2.18.0 → 2.25.0

package/plugins/ima-claude/skills/mcp-qdrant/SKILL.md

@@ -3,58 +3,48 @@ name: mcp-qdrant
 description: "Qdrant MCP — the permanent library. Unlike Vestige (neural memory that fades), nothing stored here is ever forgotten. Use for all reference material: wiki articles, coding standards, architecture docs, code samples, PRDs, plans, meeting notes, research findings. Triggers on: 'store this', 'what do we know about', 'search knowledge', 'add to library', 'find in docs'. Triggers proactively when reference material is created, discussed, or finalized — feed the library without being asked. Search the library before starting any new work."
 ---
 
-# Qdrant MCP - The Permanent Library
+# Qdrant MCP — Permanent Library
 
-Our permanent reference library. Unlike Vestige (neural memory that fades if unused), nothing stored here is ever forgotten. This is where we feed our entire universe — wiki articles, coding standards, architecture docs, code samples, PRDs, plans, and research findings.
+| System | Role | Lifecycle |
+|--------|------|-----------|
+| **Qdrant** | Permanent library — standards, PRDs, architecture, code samples | Persistent forever |
+| **Vestige** | Neural memory — decisions, preferences, learnings | Fades if unused (FSRS-6) |
+| **Serena Memory** | Project workbench — session state, task progress | Project-scoped |
 
-## Architecture: How This Fits
-
-| System | Role | Lifecycle | Example |
-|--------|------|-----------|---------|
-| **Qdrant** | Permanent library — reference material, standards, PRDs, architecture docs, code samples | Persistent forever | "Our payment system uses Accept.js with ARB" |
-| **Vestige** | Neural memory — decisions, preferences, patterns, bugs, learnings | Fades if unused (FSRS-6 decay) | "We chose JWT over sessions because..." |
-| **Serena Memory** | Project workbench — session state, task progress | Project-scoped, survives git ops | "Currently on task 3/5" |
-
-**Will it fade if we stop referencing it?** If no → Qdrant (permanent). If yes → Vestige (neural decay).
+**Decision rule**: Will it fade if unused? No → Qdrant. Yes → Vestige.
 
 ## Embedding Stack
 
-Two embedding providers are supported. Ollama is the default; fastembed is a CPU-only alternative for machines where Ollama has performance issues.
-
 | Component | Ollama (default) | fastembed |
-|---|---|---|
-| MCP server | `qdrant-mcp` (custom, at `~/dev/qdrant-mcp-server`) | same |
+|-----------|-----------------|-----------|
 | Embedding model | `nomic-embed-text` | `BAAI/bge-small-en-v1.5` |
 | Vector dimensions | 768 | 384 |
 | Distance metric | Cosine | Cosine |
 | Dependency | Ollama running locally | `pip install qdrant-mcp[fastembed]` |
 | Default collection | `ima-knowledge` | `ima-knowledge` |
 
-**Warning**: Collections can't be shared across providers (different vector dimensions). Switching providers requires a collection rebuild.
+Collections can't be shared across providers (different vector dimensions). Switching providers requires collection rebuild.
 
 ## Per-Project Collection
 
-Projects can specify their Qdrant collection via a `.qdrant` file in the project root (YAML format, like `.serena`):
+Add `.qdrant` to project root (YAML):
 
 ```yaml
-# .qdrant — project-level config
 collection: my-project-knowledge
 ```
 
-**At session start**, check for a `.qdrant` file in the working directory. If found, read its `collection` value and pass it as `collection_name` on every `qdrant_store` and `qdrant_find` call for that session.
-
-If no `.qdrant` file is found, omit `collection_name` — the server defaults to `ima-knowledge` (from the `COLLECTION_NAME` env var).
+At session start, check for `.qdrant`. If found, pass `collection_name` on every `qdrant_store` and `qdrant_find` call. If absent, omit `collection_name` — server defaults to `ima-knowledge`.
 
 ## MCP Tools
 
-MCP server name: `qdrant-memory`. Tool prefix: `mcp__qdrant-memory__`.
+Server: `qdrant-memory`. Prefix: `mcp__qdrant-memory__`.
 
 | Tool | Purpose | Parameters |
 |------|---------|------------|
 | `qdrant_store` | Store text with auto-embedding | `information` (required), `collection_name`, `metadata` |
-| `qdrant_find` | Semantic search across stored knowledge | `query` (required), `collection_name`, `limit` |
+| `qdrant_find` | Semantic search | `query` (required), `collection_name`, `limit` |
 
-## Storing Knowledge
+## Storing
 
 ```
 mcp__qdrant-memory__qdrant_store
@@ -63,112 +53,81 @@ mcp__qdrant-memory__qdrant_store
   metadata: {"source": "donation-system-prd", "type": "architecture", "date": "2026-02-21"}
 ```
 
-To target a specific collection explicitly:
-
-```
-mcp__qdrant-memory__qdrant_store
-  collection_name: "other-project-knowledge"
-  information: "..."
-```
-
 ### What to Store
 
-Anything that should never be forgotten — reference material for our permanent library.
-
-| Content Type | Metadata `type` |
+| Content Type | `type` metadata |
 |---|---|
 | PRDs / Feature Specs | `prd` |
-| Architecture decisions & diagrams | `architecture` |
+| Architecture decisions | `architecture` |
 | Integration guides | `integration` |
 | Domain knowledge | `domain` |
 | Requirements / meeting notes | `requirements` |
-| Coding standards & conventions | `standard` |
-| Useful code samples | `sample` |
+| Coding standards | `standard` |
+| Code samples | `sample` |
 
-### Chunking Large Documents
+### Chunking (docs >2000 words)
 
-For documents over ~2000 words, store by section:
+Store by section; include document title in each chunk:
 
 ```
 Store: "Donation System PRD - Overview: [content]"
   metadata: {"source": "donation-prd", "type": "prd", "section": "overview"}
-
-Store: "Donation System PRD - Payment Flow: [content]"
-  metadata: {"source": "donation-prd", "type": "prd", "section": "payment-flow"}
 ```
 
-Include the document title in each chunk so search results have context.
-
-## Searching Knowledge
+## Searching
 
 ```
 mcp__qdrant-memory__qdrant_find
   query: "how does guest recurring donation work"
 ```
 
-**Broad**: `"payment processing"` — discover what's available
-**Specific**: `"Authorize.net ARB guest checkout"` — find exact knowledge
-**Problem-oriented**: `"SSO authentication between WordPress and Discourse"` — find solutions
+- Broad: `"payment processing"` — discover available knowledge
+- Specific: `"Authorize.net ARB guest checkout"` — targeted lookup
+- Problem-oriented: `"SSO between WordPress and Discourse"` — find solutions
 
 ## Proactive Behavior
 
-### Feed the Library When:
-
-- A wiki article, PRD, or spec is created or discussed → store it
-- Architecture is documented or diagrammed → store it
-- A coding standard or convention is established → store it
-- A useful code sample is written → store it
-- Research is completed on a topic → store the findings
-- A Compound Engineering solution is finalized → store it
-- Integration is documented → store it
-- Meeting notes capture decisions or context → store them
-- User says "add this to knowledge base" or "store this"
-
-### Search the Library When:
-
-- Starting implementation of any feature → check if prior art exists
-- Debugging an integration → search for architecture context
-- User asks "how does X work" → check library before guessing
-- Planning new work → search for related PRDs or standards
-- Before making architectural decisions → search for existing conventions
-
-## Ingestion: Claude Web → Qdrant
-
-When user shares content from Claude Web Projects:
-
-1. User pastes document content
-2. For short docs (<2000 words): store as single entry
-3. For long docs: chunk by section with shared `source` metadata
-4. Confirm: "Stored [title] in knowledge base ([N] chunks)"
+**Feed library when:**
+- Wiki article, PRD, or spec created/discussed
+- Architecture documented or diagrammed
+- Coding standard established
+- Useful code sample written
+- Research completed
+- Integration documented
+- Meeting notes capture decisions
+- User says "store this" or "add to knowledge base"
+
+**Search library when:**
+- Starting any feature implementation
+- Debugging an integration
+- User asks "how does X work"
+- Planning new work or making architectural decisions
 
 ## Decision Logic
 
-**Will it fade if we stop referencing it?** If no → store here. Qdrant is the permanent library.
-
 ```
 IF reference material that should never be forgotten
-   (wiki, standards, PRDs, architecture docs, code samples, plans):
-    → Qdrant qdrant_store (permanent library)
-ELSE IF knowledge that should strengthen with use, fade if unused
-   (preferences, decisions, patterns, bugs):
-    → Vestige smart_ingest (neural memory)
+   (wiki, standards, PRDs, architecture, code samples):
+    → qdrant_store (permanent)
+ELSE IF knowledge that strengthens with use, fades if unused:
+    → Vestige smart_ingest
 ELSE IF session state or project progress:
-    → Serena write_memory (project workbench)
+    → Serena write_memory
 
 Searching:
 IF need reference docs, architecture context, prior art:
-    → Qdrant qdrant_find
-IF need user preferences or past decisions:
+    → qdrant_find
+IF need preferences or past decisions:
     → Vestige search
-IF starting any new work:
-    → Search BOTH Qdrant and Vestige
+IF starting new work:
+    → Search BOTH
 ```
 
 ## Metadata Conventions
 
 | Key | Values | Purpose |
 |-----|--------|---------|
-| `source` | Document name (kebab-case) | Group chunks from same doc |
+| `source` | kebab-case document name | Group chunks from same doc |
 | `type` | `prd`, `architecture`, `integration`, `domain`, `requirements`, `standard`, `sample` | Categorize |
 | `date` | `YYYY-MM-DD` | When stored |
 
@@ -179,15 +138,15 @@ IF starting any new work:
 | No results | Broaden query terms |
 | Irrelevant results | Use more specific key terms |
 | Qdrant not responding | `docker ps \| grep qdrant` — restart if needed |
-| Ollama not responding | `ollama list` — ensure it's running with `nomic-embed-text` |
+| Ollama not responding | `ollama list` — ensure running with `nomic-embed-text` |
 | fastembed not installed | `pip install qdrant-mcp[fastembed]` |
-| Switched providers, bad results | Different vector dimensions — rebuild the collection |
+| Switched providers, bad results | Different vector dimensions — rebuild collection |
 | Duplicate content | Search before storing to verify novelty |
 
 ## When NOT to Use
 
-- Knowledge that should fade if unused (preferences, decisions, patterns) → Vestige (neural memory)
-- Session state or task progress → Serena memory (project workbench)
+- Fading knowledge (preferences, decisions) → Vestige
+- Session state / task progress → Serena memory
 - Code symbol search → Serena or Grep
 - Current web info → Tavily
 - Library API docs → Context7
@@ -195,26 +154,25 @@ IF starting any new work:
 ## Setup
 
 ```bash
-# 1. Start Qdrant with persistent storage
+# 1. Start Qdrant
 docker run -d --name qdrant \
   -p 6333:6333 \
   -v qdrant_storage:/qdrant/storage \
   qdrant/qdrant:latest
 
-# 2a. Option A: Ollama (default)
+# 2a. Ollama (default)
 ollama pull nomic-embed-text
 
-# 2b. Option B: fastembed (CPU-only, no Ollama needed)
+# 2b. fastembed (CPU-only)
 # pip install qdrant-mcp[fastembed]
 
-# 3. Install custom MCP server
+# 3. Install MCP server
 cd ~/dev/qdrant-mcp-server && pip install -e .
 
-# 4. Add to Claude Code (in ~/.claude.json mcpServers)
+# 4. Add to ~/.claude.json mcpServers:
 # "qdrant-memory": {
 #   "type": "stdio",
 #   "command": "qdrant-mcp",
-#   "args": [],
 #   "env": {
 #     "QDRANT_URL": "http://localhost:6333",
 #     "COLLECTION_NAME": "ima-knowledge",
@@ -223,22 +181,7 @@ cd ~/dev/qdrant-mcp-server && pip install -e .
 #     "EMBEDDING_MODEL": "nomic-embed-text"
 #   }
 # }
-# For fastembed, set EMBEDDING_PROVIDER=fastembed (OLLAMA_URL not needed)
 
 # 5. Verify
 curl http://localhost:6333/health
 ```
-
-**Persistence**: `-v qdrant_storage:/qdrant/storage` preserves data across restarts.
-**Embeddings**: Ollama with `nomic-embed-text` (768d) or fastembed with `bge-small-en-v1.5` (384d). All data stays on your machine.
-
-### Per-Project Setup
-
-Add a `.qdrant` file to any project root to use a project-specific collection:
-
-```yaml
-# .qdrant
-collection: my-project-knowledge
-```
-
-This keeps project knowledge isolated from the global `ima-knowledge` collection. The collection is created automatically on first store.

package/plugins/ima-claude/skills/mcp-sequential/SKILL.md

@@ -5,70 +5,53 @@ description: "Sequential Thinking MCP — use for debugging, root cause analysis
 
 # Sequential Thinking MCP - Structured Reasoning
 
-Use Sequential Thinking for complex problems that benefit from structured, revisable analysis.
+Use for: debugging, root cause analysis, trade-off evaluation, architectural decisions, multi-step problems requiring mid-stream revision.
 
-## Available Tool
+Skip for: simple tasks, obvious answers, single-step operations.
+
+## Tool
 
 | Tool | Purpose |
 |------|---------|
-| `mcp__sequential-thinking__sequentialThinking` | Execute a thought in a reasoning chain |
-
-## When to Use
-
-**Use Sequential Thinking for:**
-- Breaking down complex problems into steps
-- Debugging issues where the cause isn't obvious
-- Architectural/design decisions with trade-offs
-- Problems where you might need to revise your approach
-- Multi-step analysis that needs context maintained
-- Filtering irrelevant information from complex scenarios
-- Hypothesis generation and verification
+| `mcp__sequential-thinking__sequentialThinking` | Execute one thought in a reasoning chain |
 
-**Don't use for:**
-- Simple, straightforward tasks
-- Questions with obvious answers
-- Tasks that don't require multi-step reasoning
+## Parameters
 
-## Basic Usage
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `thought` | Yes | Current thinking step |
+| `nextThoughtNeeded` | Yes | `true` to continue, `false` when done |
+| `thoughtNumber` | Yes | Current step (1, 2, 3...) |
+| `totalThoughts` | Yes | Estimated total — adjust freely |
+| `isRevision` | No | `true` if revising a previous thought |
+| `revisesThought` | No | Which thought number being revised |
+| `branchFromThought` | No | Branch point thought number |
+| `branchId` | No | Branch identifier |
 
-Each call represents one thought in your reasoning chain.
+## Usage Patterns
 
+### Start chain
 ```
 mcp__sequential-thinking__sequentialThinking
-  thought: "First, let me understand the problem. We have X happening when Y..."
+  thought: "The bug report says form submits but data isn't saved. Failure points: frontend validation, AJAX request, backend handler, DB write."
   nextThoughtNeeded: true
   thoughtNumber: 1
   totalThoughts: 5
 ```
 
-## Parameters
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `thought` | Yes | Current thinking step content |
-| `nextThoughtNeeded` | Yes | `true` to continue, `false` when done |
-| `thoughtNumber` | Yes | Current step number (1, 2, 3...) |
-| `totalThoughts` | Yes | Estimated total (can adjust up/down) |
-| `isRevision` | No | `true` if revising previous thought |
-| `revisesThought` | No | Which thought number being revised |
-| `branchFromThought` | No | Thought number to branch from |
-| `branchId` | No | Identifier for the branch |
-
-## Continue Chain
-
+### Continue
 ```
 mcp__sequential-thinking__sequentialThinking
-  thought: "Based on step 1, the likely cause is Z because..."
+  thought: "Based on step 1, checking AJAX request first..."
   nextThoughtNeeded: true
   thoughtNumber: 2
   totalThoughts: 5
 ```
 
-## Revise if Needed
-
+### Revise
 ```
 mcp__sequential-thinking__sequentialThinking
-  thought: "Actually, my assumption in thought 2 was wrong. Let me reconsider..."
+  thought: "My assumption in thought 2 was wrong. Reconsidering..."
   nextThoughtNeeded: true
   thoughtNumber: 3
   totalThoughts: 6
@@ -76,11 +59,10 @@ mcp__sequential-thinking__sequentialThinking
   revisesThought: 2
 ```
 
-## Branch for Alternatives
-
+### Branch for alternatives
 ```
 mcp__sequential-thinking__sequentialThinking
-  thought: "Let me explore an alternative approach from step 2..."
+  thought: "Exploring alternative approach from step 2..."
   nextThoughtNeeded: true
   thoughtNumber: 4
   totalThoughts: 7
@@ -88,11 +70,10 @@ mcp__sequential-thinking__sequentialThinking
   branchId: "alternative-approach"
 ```
 
-## Conclude
-
+### Conclude
 ```
 mcp__sequential-thinking__sequentialThinking
-  thought: "Based on my analysis, the solution is X because of Y and Z."
+  thought: "Root cause: field name mismatch — frontend sends 'user_email', backend expects 'email'."
   nextThoughtNeeded: false
   thoughtNumber: 5
   totalThoughts: 5
@@ -100,50 +81,14 @@ mcp__sequential-thinking__sequentialThinking
 
 ## Best Practices
 
-1. **Start with estimate, adjust as needed** - `totalThoughts` is flexible
-2. **Express uncertainty** - It's OK to say "I'm not sure, but..."
-3. **Revise freely** - Use `isRevision` when your understanding changes
-4. **Branch for alternatives** - Explore multiple approaches
-5. **Verify hypotheses** - Don't just guess, test your reasoning
-6. **Filter noise** - Focus on relevant information per step
-7. **Only conclude when confident** - Keep `nextThoughtNeeded: true` until satisfied
-
-## Example: Debugging a Bug
-
-```
-Thought 1: "The bug report says the form submits but data isn't saved. Let me identify possible failure points: 1) Frontend validation, 2) AJAX request, 3) Backend handler, 4) Database write."
-
-Thought 2: "Starting with the AJAX request - I should check if the request is being sent and what response comes back."
-
-Thought 3: "The request is sent but returns 500. So the issue is backend. Let me check the error logs."
-
-Thought 4: "Error log shows 'undefined index: email'. The frontend is sending 'user_email' but backend expects 'email'. This is a field name mismatch."
-
-Thought 5 (conclusion): "Root cause: Field name mismatch between frontend ('user_email') and backend ('email'). Solution: Update frontend to use 'email' or backend to accept 'user_email'."
-```
-
-## Example: Architecture Decision
-
-```
-Thought 1: "Need to decide between REST API and GraphQL for this project. Let me list the requirements: multiple clients, varying data needs, team experience."
-
-Thought 2: "REST pros: Team knows it well, simple caching, established patterns. Cons: Over-fetching for mobile, multiple endpoints."
-
-Thought 3: "GraphQL pros: Single endpoint, client specifies data needs, good for mobile. Cons: Learning curve, caching complexity."
-
-Thought 4 (revision): "Wait, I should also consider that we're using WordPress backend. REST is native to WordPress, GraphQL would need WPGraphQL plugin."
-
-Thought 5 (conclusion): "Recommendation: REST API. Reasons: 1) Native WordPress support, 2) Team expertise, 3) Simpler caching. The over-fetching concern can be mitigated with sparse fieldsets."
-```
+- Adjust `totalThoughts` freely — it's an estimate
+- Express uncertainty inline: "I'm not sure, but..."
+- Revise with `isRevision` when understanding changes
+- Keep `nextThoughtNeeded: true` until confident
+- Branch to compare approaches, not just to explore
 
 ## Setup
 
-No API key required. Install with:
-```bash
-bun run scripts/setup-mcp.ts
-```
-
-Or manually:
 ```bash
 claude mcp add --scope user sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking@latest
 ```