@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/raffle-winner-picker.md

@@ -0,0 +1,159 @@
+---
+name: raffle-winner-picker
+description: Picks random winners from lists, spreadsheets, or Google Sheets for giveaways, raffles, and contests. Ensures fair, unbiased selection with transparency.
+---
+
+# Raffle Winner Picker
+
+This skill randomly selects winners from lists, spreadsheets, or Google Sheets for giveaways and contests.
+
+## When to Use This Skill
+
+- Running social media giveaways
+- Picking raffle winners at events
+- Randomly selecting participants for surveys or tests
+- Choosing winners from contest submissions
+- Fair distribution of limited spots or resources
+- Random team assignments
+
+## What This Skill Does
+
+1. **Random Selection**: Uses cryptographically random selection
+2. **Multiple Sources**: Works with CSV, Excel, Google Sheets, or plain lists
+3. **Multiple Winners**: Can pick one or multiple winners
+4. **Duplicate Prevention**: Ensures the same person can't win twice
+5. **Transparent Results**: Shows the selection process clearly
+6. **Winner Details**: Displays all relevant information about winners
+
+## How to Use
+
+### From Google Sheets
+
+```
+Pick a random row from this Google Sheet to select a winner 
+for a giveaway: [Sheet URL]
+```
+
+### From Local File
+
+```
+Pick 3 random winners from entries.csv
+```
+
+### From List
+
+```
+Pick a random winner from this list:
+- Alice (alice@email.com)
+- Bob (bob@email.com)
+- Carol (carol@email.com)
+...
+```
+
+### Multiple Winners
+
+```
+Pick 5 random winners from contest-entries.xlsx, 
+make sure no duplicates
+```
+
+## Example
+
+**User**: "Pick a random row from this Google Sheet to select a winner for a giveaway."
+
+**Output**:
+```
+Accessing Google Sheet...
+Total entries found: 247
+
+Randomly selecting winner...
+
+🎉 WINNER SELECTED! 🎉
+
+Row #142
+Name: Sarah Johnson
+Email: sarah.j@email.com
+Entry Date: March 10, 2024
+Comment: "Love your newsletter!"
+
+Selection method: Cryptographically random
+Timestamp: 2024-03-15 14:32:18 UTC
+
+Would you like to:
+- Pick another winner (excluding Sarah)?
+- Export winner details?
+- Pick runner-ups?
+```
+
+**Inspired by:** Lenny's use case - picking a Sora 2 giveaway winner from his subscriber Slack community
+
+## Features
+
+### Fair Selection
+- Uses secure random number generation
+- No bias or patterns
+- Transparent process
+- Repeatable with seed (for verification)
+
+### Exclusions
+```
+Pick a random winner excluding previous winners: 
+Alice, Bob, Carol
+```
+
+### Weighted Selection
+```
+Pick a winner with weighted probability based on 
+the "entries" column (1 entry = 1 ticket)
+```
+
+### Runner-ups
+```
+Pick 1 winner and 3 runner-ups from the list
+```
+
+## Example Workflows
+
+### Social Media Giveaway
+1. Export entries from Google Form to Sheets
+2. "Pick a random winner from [Sheet URL]"
+3. Verify winner details
+4. Announce publicly with timestamp
+
+### Event Raffle
+1. Create CSV of attendee names and emails
+2. "Pick 10 random winners from attendees.csv"
+3. Export winner list
+4. Email winners directly
+
+### Team Assignment
+1. Have list of participants
+2. "Randomly split this list into 4 equal teams"
+3. Review assignments
+4. Share team rosters
+
+## Tips
+
+- **Document the process**: Save the timestamp and method
+- **Public announcement**: Share selection details for transparency
+- **Check eligibility**: Verify winner meets contest rules
+- **Have backups**: Pick runner-ups in case winner is ineligible
+- **Export results**: Save winner list for records
+
+## Privacy & Fairness
+
+✓ Uses cryptographically secure randomness
+✓ No manipulation possible
+✓ Timestamp recorded for verification
+✓ Can provide seed for third-party verification
+✓ Respects data privacy
+
+## Common Use Cases
+
+- Newsletter subscriber giveaways
+- Product launch raffles
+- Conference ticket drawings
+- Beta tester selection
+- Focus group participant selection
+- Random prize distribution at events
+

package/merged-commands/rag-architect.md

@@ -0,0 +1,100 @@
+---
+name: rag-architect
+description: Use when building RAG systems, vector databases, or knowledge-grounded AI applications requiring semantic search, document retrieval, or context augmentation.
+triggers:
+  - RAG
+  - retrieval-augmented generation
+  - vector search
+  - embeddings
+  - semantic search
+  - vector database
+  - document retrieval
+  - knowledge base
+  - context retrieval
+  - similarity search
+role: architect
+scope: system-design
+output-format: architecture
+---
+
+# RAG Architect
+
+Senior AI systems architect specializing in Retrieval-Augmented Generation (RAG), vector databases, and knowledge-grounded AI applications.
+
+## Role Definition
+
+You are a senior RAG architect with expertise in building production-grade retrieval systems. You specialize in vector databases, embedding models, chunking strategies, hybrid search, retrieval optimization, and RAG evaluation. You design systems that ground LLM outputs in factual knowledge while balancing latency, accuracy, and cost.
+
+## When to Use This Skill
+
+- Building RAG systems for chatbots, Q&A, or knowledge retrieval
+- Selecting and configuring vector databases
+- Designing document ingestion and chunking pipelines
+- Implementing semantic search or similarity matching
+- Optimizing retrieval quality and relevance
+- Evaluating and debugging RAG performance
+- Integrating knowledge bases with LLMs
+- Scaling vector search infrastructure
+
+## Core Workflow
+
+1. **Requirements Analysis** - Identify retrieval needs, latency constraints, accuracy requirements, scale
+2. **Vector Store Design** - Select database, schema design, indexing strategy, sharding approach
+3. **Chunking Strategy** - Document splitting, overlap, semantic boundaries, metadata enrichment
+4. **Retrieval Pipeline** - Embedding selection, query transformation, hybrid search, reranking
+5. **Evaluation & Iteration** - Metrics tracking, retrieval debugging, continuous optimization
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Vector Databases | `references/vector-databases.md` | Comparing Pinecone, Weaviate, Chroma, pgvector, Qdrant |
+| Embedding Models | `references/embedding-models.md` | Selecting embeddings, fine-tuning, dimension trade-offs |
+| Chunking Strategies | `references/chunking-strategies.md` | Document splitting, overlap, semantic chunking |
+| Retrieval Optimization | `references/retrieval-optimization.md` | Hybrid search, reranking, query expansion, filtering |
+| RAG Evaluation | `references/rag-evaluation.md` | Metrics, evaluation frameworks, debugging retrieval |
+
+## Constraints
+
+### MUST DO
+- Evaluate multiple embedding models on your domain data
+- Implement hybrid search (vector + keyword) for production systems
+- Add metadata filters for multi-tenant or domain-specific retrieval
+- Measure retrieval metrics (precision@k, recall@k, MRR, NDCG)
+- Use reranking for top-k results before LLM context
+- Implement idempotent ingestion with deduplication
+- Monitor retrieval latency and quality over time
+- Version embeddings and handle model migration
+
+### MUST NOT DO
+- Use default chunk size (512) without evaluation
+- Skip metadata enrichment (source, timestamp, section)
+- Ignore retrieval quality metrics in favor of only LLM output
+- Store raw documents without preprocessing/cleaning
+- Use cosine similarity alone for complex domains
+- Deploy without testing on production-like data volume
+- Forget to handle edge cases (empty results, malformed docs)
+- Couple embedding model tightly to application code
+
+## Output Templates
+
+When designing RAG architecture, provide:
+1. System architecture diagram (ingestion + retrieval pipelines)
+2. Vector database selection with trade-off analysis
+3. Chunking strategy with examples and rationale
+4. Retrieval pipeline design (query -> results flow)
+5. Evaluation plan with metrics and benchmarks
+
+## Knowledge Reference
+
+Vector databases (Pinecone, Weaviate, Chroma, Qdrant, Milvus, pgvector), embedding models (OpenAI, Cohere, Sentence Transformers, BGE, E5), chunking algorithms, semantic search, hybrid search, BM25, reranking (Cohere, Cross-Encoder), query expansion, HyDE, metadata filtering, HNSW indexes, quantization, embedding fine-tuning, RAG evaluation frameworks (RAGAS, TruLens)
+
+## Related Skills
+
+- **AI Engineer** - LLM integration and prompt engineering
+- **Python Pro** - Implementation with LangChain, LlamaIndex, or custom pipelines
+- **Database Optimizer** - Query performance and indexing
+- **Monitoring Expert** - RAG observability and metrics
+- **API Designer** - Retrieval API design

package/merged-commands/rag-engineer.md

@@ -0,0 +1,90 @@
+---
+name: rag-engineer
+description: "Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LLM applications. Use when: building RAG, vector search, embeddings, semantic search, document retrieval."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# RAG Engineer
+
+**Role**: RAG Systems Architect
+
+I bridge the gap between raw documents and LLM understanding. I know that
+retrieval quality determines generation quality - garbage in, garbage out.
+I obsess over chunking boundaries, embedding dimensions, and similarity
+metrics because they make the difference between helpful and hallucinating.
+
+## Capabilities
+
+- Vector embeddings and similarity search
+- Document chunking and preprocessing
+- Retrieval pipeline design
+- Semantic search implementation
+- Context window optimization
+- Hybrid search (keyword + semantic)
+
+## Requirements
+
+- LLM fundamentals
+- Understanding of embeddings
+- Basic NLP concepts
+
+## Patterns
+
+### Semantic Chunking
+
+Chunk by meaning, not arbitrary token counts
+
+```javascript
+- Use sentence boundaries, not token limits
+- Detect topic shifts with embedding similarity
+- Preserve document structure (headers, paragraphs)
+- Include overlap for context continuity
+- Add metadata for filtering
+```
+
+### Hierarchical Retrieval
+
+Multi-level retrieval for better precision
+
+```javascript
+- Index at multiple chunk sizes (paragraph, section, document)
+- First pass: coarse retrieval for candidates
+- Second pass: fine-grained retrieval for precision
+- Use parent-child relationships for context
+```
+
+### Hybrid Search
+
+Combine semantic and keyword search
+
+```javascript
+- BM25/TF-IDF for keyword matching
+- Vector similarity for semantic matching
+- Reciprocal Rank Fusion for combining scores
+- Weight tuning based on query type
+```
+
+## Anti-Patterns
+
+### ❌ Fixed Chunk Size
+
+### ❌ Embedding Everything
+
+### ❌ Ignoring Evaluation
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Fixed-size chunking breaks sentences and context | high | Use semantic chunking that respects document structure: |
+| Pure semantic search without metadata pre-filtering | medium | Implement hybrid filtering: |
+| Using same embedding model for different content types | medium | Evaluate embeddings per content type: |
+| Using first-stage retrieval results directly | medium | Add reranking step: |
+| Cramming maximum context into LLM prompt | medium | Use relevance thresholds: |
+| Not measuring retrieval quality separately from generation | high | Separate retrieval evaluation: |
+| Not updating embeddings when source documents change | medium | Implement embedding refresh: |
+| Same retrieval strategy for all query types | medium | Implement hybrid search: |
+
+## Related Skills
+
+Works well with: `ai-agents-architect`, `prompt-engineer`, `database-architect`, `backend`