RAG extension for Context-Driven Development
npm install @emb715/cdd-rag> Transform your CDD workspace into a searchable knowledge base with AI-powered context retrieval
Status: Pre-release (active development)
Author: EMB (Ezequiel M. Benitez) @emb715
License: MIT
---
CDD-RAG is a template-based extension for Context-Driven Development that adds:
š Semantic Search - Find relevant decisions, patterns, and solutions across all work items
š¤ AI-Powered Answers - Get contextual answers from your CDD documentation
š Knowledge Discovery - Discover how similar problems were solved before
š Smart Integration - Enhances existing CDD commands with relevant context
š° Cost-Effective - Local indexing + optional cloud AI (~$0.0006/query)
š Privacy-First - All data stays local, cloud only for optional AI answers
---
Both AI assistants and humans face the same challenge with CDD projects:
- ā Limited Context: Can't remember every decision made months ago
- ā Manual Search: Have to grep through files to find relevant patterns
- ā Lost Knowledge: Valuable decisions buried in completed work items
- ā Inconsistency: Hard to maintain consistency across many work items
CDD-RAG creates a living knowledge base that:
- ā
Indexes all your CDD documentation automatically
- ā
Searches semantically (finds meaning, not just keywords)
- ā
Returns relevant chunks with citations
- ā
Enhances AI responses with past context
- ā
Works 100% offline for search (AI answers optional)
---
- Python 3.9+
- Existing CDD project
- 2GB free disk space
``bash`From your CDD project root
cp -r path/to/packages/rag/cdd/.rag ./cdd/.rag
This creates:
``
your-project/
āāā cdd/
āāā .rag/ # RAG extension (like .meta)
āāā core/ # RAG implementation
āāā hooks/ # CDD integration hooks
āāā docs/ # Documentation
āāā config.yaml # Configuration
āāā requirements.txt
`bash`Copy the /cdd:query command
cp path/to/packages/rag/.claude/commands/cdd:query.md ./.claude/commands/
`bash`
cd cdd/.rag
pip install -r requirements.txt
Installed:
- chromadb - Local vector databasesentence-transformers
- - Local embeddingsopenai
- - OpenAI-compatible client (works with OpenAI, Fuelix AI, etc.)
- Other utilities
`bashCopy example config
cp .env.example .env
$3
`bash
Index your CDD workspace
python -m core.cli index
`Done! RAG is now integrated with your CDD project.
---
Usage
$3
`bash
Search across all CDD docs
/cdd:query "authentication patterns"With filters
/cdd:query "database migrations" --type feature --status completedLimit results
/cdd:query "testing strategies" --limit 10
`Result:
`
š Found 5 results:1. cdd/0001-user-auth/DECISIONS.md (score: 0.94)
Work ID: 0001 | Type: feature | Status: completed
Technical Decision: JWT Authentication
We chose JWT-based authentication...
2. cdd/0005-api-security/DECISIONS.md (score: 0.87)
...
`$3
`bash
Get AI answer with citations
/cdd:query "How did we implement authentication?" --ai
`Result:
`
š¤ AI Answer:Based on your CDD documentation:
1. JWT Tokens (Work Item 0001)
- Stateless authentication
- 24-hour expiration
- Refresh tokens in Redis
2. Middleware Protection (Work Item 0005)
- Centralized validation
- Auto user attachment
Sources:
- cdd/0001-user-auth/DECISIONS.md
- cdd/0005-api-security/SESSION_NOTES.md
š Cost: $0.0006
`$3
CDD-RAG can be integrated with existing CDD commands through optional hooks.
Currently supported (manual setup required):
-
/cdd:complete-work - Auto-index completed work items
- /cdd:query - Semantic search across all workPlanned for future releases:
-
/cdd:create-work - Suggest similar work items
- /cdd:plan-work - Inject relevant context
- /cdd:list-work - Similarity filteringSee
docs/CDD_INTEGRATION.md (coming soon) for integration setup.---
How It Works
$3
`
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā CDD Workspace (Your Docs) ā
ā ā
ā ⢠DECISIONS.md files ā
ā ⢠SESSION_NOTES.md files ā
ā ⢠IMPLEMENTATION_PLAN.md files ā
ā ⢠etc. ā
āāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā RAG Indexing (100% Local) ā
ā ā
ā 1. Parse markdown + extract metadata ā
ā 2. Chunk into semantic pieces ā
ā 3. Generate embeddings (local model) ā
ā 4. Store in ChromaDB (local SQLite) ā
āāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Query Processing ā
ā ā
ā User: /cdd:query "auth patterns" ā
ā 1. Embed query (local, fast) ā
ā 2. Search vectors (similarity) ā
ā 3. Return top K results ā
āāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Optional: AI Enhancement ā
ā ā
ā 1. Assemble context from results ā
ā 2. Send to OpenAI-compatible API ā
ā 3. Generate answer with citations ā
ā 4. Track cost (~$0.0006/query) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
`$3
- All markdown files in
cdd/ workspace
- Frontmatter metadata (work ID, type, status, priority)
- Section structure (preserves context)
- Git metadata (author, commit, date)$3
- Template files in
cdd/.meta/templates/
- Hidden files and directories
- Files matching exclude patterns (.env, secrets, etc.)---
Integration Levels
Choose your level of automation:
$3
- You manually run /cdd:query when needed
- Simple, full control
- Best for: Trying RAG, occasional use$3
- Use /cdd:query command regularly
- Auto-index on work completion
- Best for: Regular use, balanced approach$3
- Smart auto-enhancement of all commands
- Auto-indexing on completion
- Auto-suggest similar work items
- Best for: Power users, large projectsConfigure in:
cdd/.rag/config.yaml---
Configuration
$3
`yaml
RAG Mode: local, hybrid, or cloud
mode: hybridSmart Enhancement
smart_enhancement:
enabled: true
enhance_create_work: true
enhance_plan_work: true
enhance_complete_work: true # Just for auto-indexingAuto-Indexing
auto_index:
on_complete: true
async: true
notify: trueQuery Defaults
query:
default_results: 5
min_similarity: 0.3
enable_reranking: trueCost Management
cost:
enable_tracking: true
monthly_budget: 10.00
warning_threshold: 0.01
`$3
`bash
OpenAI-compatible API (optional, for AI answers - works with OpenAI, Fuelix AI, etc.)
OPENAI_API_KEY=your_key_here
OPENAI_DEFAULT_MODEL=gpt-4o-miniOr use local LLM
USE_LOCAL_LLM=true
LOCAL_MODEL=llama3
`---
Documentation
Full documentation in
cdd/.rag/docs/:- CDD_INTEGRATION.md - Complete integration guide
- INTEGRATION_PATTERNS.md - Common workflows
- CONFIGURATION.md - All config options
- TROUBLESHOOTING.md - Common issues & solutions
---
Performance & Cost
$3
- 100 files: ~30 seconds (first run)
- 100 files: ~5 seconds (re-index)
- Cost: $0 (100% local)$3
- Query time: ~50-100ms
- Cost: $0 (100% local, offline)$3
| Model | Time | Cost/Query |
|-------|------|------------|
| GPT-4o-mini | ~1s | ~$0.0006 |
| Claude-3-Haiku | ~1.5s | ~$0.0011 |
| Llama-3-8B | ~1s | ~$0.0003 |$3
- 100 work items: ~10 MB
- 1,000 work items: ~100 MB---
Requirements
System:
- Python 3.9+
- 2GB RAM (for embeddings)
- 2GB free disk space
Optional (for AI answers):
- OpenAI-compatible API key (OpenAI, Fuelix AI, etc.)
- OR Ollama installed for local LLM
---
FAQ
$3
No! Search works 100% offline. API key only needed for AI-generated answers.$3
- Search: Free (local)
- AI answers: ~$0.0006 per query (GPT-4o-mini)
- Monthly (moderate use): <$0.50$3
Yes! Indexing is 100% local. Only queries (if using AI) go to cloud.$3
Yes! Search works 100% offline. AI answers need internet.$3
Auto-updates when you complete work items, or run: python -m core.cli index$3
Yes! Just delete cdd/.rag/ folder and the /cdd:query command. CDD continues to work normally.---
Troubleshooting
$3
- Run python -m core.cli stats to check if indexed
- Try broader search terms
- Lower min_similarity in config.yaml$3
- Verify .claude/commands/cdd:query.md exists
- Check command file has correct format$3
- Re-run: pip install -r cdd/.rag/requirements.txt
- Verify Python 3.9+More: See
cdd/.rag/docs/TROUBLESHOOTING.md---
Support
- Documentation:
cdd/.rag/docs/`---
MIT License - Same as CDD methodology
---
- CDD Methodology by EMB
- ChromaDB for local vector database
- Sentence-Transformers for embeddings
- OpenAI-compatible APIs (OpenAI, Fuelix AI, etc.) for multi-model access
---
Transform your CDD workspace into an intelligent, searchable knowledge base! š