agentic-flow 1.8.15 → 1.9.0

package/docs/features/agent-booster/00-INDEX.md

@@ -0,0 +1,230 @@
+# Agent Booster: Complete Planning Documentation
+
+> **Ultra-fast code application engine - 200x faster than Morph LLM at $0 cost**
+
+## 📚 Documentation Index
+
+### Core Planning Documents
+
+1. **[00-OVERVIEW.md](./00-OVERVIEW.md)** - Vision, Objectives & Success Metrics
+   - Project vision and motivation
+   - Core objectives (performance, accuracy, cost, DX)
+   - Key features and capabilities
+   - Development phases (10 weeks)
+   - Success criteria and metrics
+   - Open questions and next steps
+
+2. **[01-ARCHITECTURE.md](./01-ARCHITECTURE.md)** - Technical Architecture & Design
+   - System architecture diagrams
+   - Rust crate structure (core, native, wasm)
+   - Module breakdown (parser, embeddings, vector, merge)
+   - Data flow and algorithms
+   - Performance optimizations
+   - Testing strategy
+   - Error handling
+
+3. **[02-INTEGRATION.md](./02-INTEGRATION.md)** - Integration with Agentic-Flow & MCP
+   - Agentic-flow integration (.env, tools, CLI)
+   - MCP server architecture
+   - Tool implementations
+   - Configuration presets
+   - Metrics & monitoring
+   - Workspace detection
+
+4. **[03-BENCHMARKS.md](./03-BENCHMARKS.md)** - Benchmark Methodology
+   - Test dataset design (100 samples)
+   - Morph LLM baseline (Claude Sonnet/Opus/Haiku)
+   - Agent Booster variants (native/WASM/TypeScript)
+   - Metrics collection (performance, accuracy, cost)
+   - Statistical analysis
+   - Expected results (166x speedup, 100% cost savings)
+
+5. **[04-NPM-SDK.md](./04-NPM-SDK.md)** - NPM SDK & CLI Design
+   - Package structure (agent-booster, agent-booster-cli)
+   - Auto-detection loader (native > WASM)
+   - TypeScript definitions
+   - CLI commands (apply, batch, watch, mcp, dashboard)
+   - Platform-specific packages
+   - Distribution strategy
+
+6. **[README.md](./README.md)** - Main README (for crate/package)
+   - Quick start guide
+   - Performance comparison tables
+   - Feature comparison vs Morph LLM
+   - Usage examples
+   - Installation instructions
+   - Documentation links
+
+7. **[GITHUB-ISSUE.md](./GITHUB-ISSUE.md)** - GitHub Issue Template
+   - Complete feature request
+   - Implementation roadmap (10 weeks)
+   - Task breakdown by phase
+   - Success criteria
+   - Testing checklist
+   - Release plan
+
+## 🎯 Quick Reference
+
+### Key Performance Targets
+
+| Metric | Morph LLM | Agent Booster | Improvement |
+|--------|-----------|---------------|-------------|
+| **Latency (p50)** | 6,000ms | 30ms | **200x faster** ⚡ |
+| **Throughput** | 10,500 tok/s | 1M+ tok/s | **95x faster** ⚡ |
+| **Cost/edit** | $0.01 | $0.00 | **100% savings** 💰 |
+| **Accuracy** | 98% | 97-99% | **Comparable** ✅ |
+| **Privacy** | API | Local | **100% private** 🔒 |
+
+### Technology Stack
+
+```
+Core:
+├── Rust (performance + safety)
+├── Tree-sitter (AST parsing, 40+ languages)
+├── ONNX Runtime (local ML inference)
+└── HNSW (vector similarity)
+
+Bindings:
+├── napi-rs (Node.js native addon)
+├── wasm-bindgen (WebAssembly)
+└── TypeScript (type-safe API)
+
+Models:
+├── jina-embeddings-v2-base-code (768-dim, best)
+└── all-MiniLM-L6-v2 (384-dim, fast)
+```
+
+### Project Structure
+
+```
+agent-booster/
+├── crates/
+│   ├── agent-booster/           # Core Rust library
+│   ├── agent-booster-native/    # napi-rs bindings
+│   └── agent-booster-wasm/      # WASM bindings
+│
+├── npm/
+│   ├── agent-booster/           # Main NPM package
+│   └── agent-booster-cli/       # Standalone CLI
+│
+├── benchmarks/                   # Benchmark suite
+│   ├── datasets/                # Test code samples
+│   ├── baselines/               # Morph LLM baselines
+│   └── results/                 # Benchmark outputs
+│
+└── docs/                        # Documentation
+```
+
+### 10-Week Implementation Roadmap
+
+- **Week 1-2**: Foundation (Rust setup, tree-sitter, benchmarks)
+- **Week 3-4**: Core engine (embeddings, vector search, merge)
+- **Week 5**: Native integration (napi-rs, NPM package)
+- **Week 6**: WASM support (browser compatibility)
+- **Week 7**: Agentic-flow integration (.env, tools)
+- **Week 8**: MCP server (Claude/Cursor/VS Code)
+- **Week 9**: CLI & SDK (npx agent-booster)
+- **Week 10**: Documentation & release
+
+## 🚀 Getting Started
+
+### For Reviewers
+
+1. Read **[00-OVERVIEW.md](./00-OVERVIEW.md)** for high-level vision
+2. Review **[01-ARCHITECTURE.md](./01-ARCHITECTURE.md)** for technical design
+3. Check **[03-BENCHMARKS.md](./03-BENCHMARKS.md)** for validation plan
+4. See **[GITHUB-ISSUE.md](./GITHUB-ISSUE.md)** for complete task breakdown
+
+### For Implementers
+
+1. Start with **[01-ARCHITECTURE.md](./01-ARCHITECTURE.md)** for crate structure
+2. Follow **[GITHUB-ISSUE.md](./GITHUB-ISSUE.md)** roadmap (week by week)
+3. Reference **[02-INTEGRATION.md](./02-INTEGRATION.md)** for agentic-flow integration
+4. Use **[04-NPM-SDK.md](./04-NPM-SDK.md)** for NPM package design
+
+### For Users
+
+1. Start with **[README.md](./README.md)** for quick start
+2. Check **[02-INTEGRATION.md](./02-INTEGRATION.md)** for usage examples
+3. Review **[03-BENCHMARKS.md](./03-BENCHMARKS.md)** for performance data
+
+## 📊 Expected Results
+
+### Performance (100 edits)
+
+```
+Morph LLM baseline:
+├─ Total time: 10 minutes
+├─ Total cost: $1.00
+└─ Method: API calls
+
+Agent Booster:
+├─ Total time: 3.5 seconds    ⚡ 170x faster
+├─ Total cost: $0.00           💰 100% savings
+└─ Method: Local inference
+
+Hybrid (80% Agent Booster, 20% fallback):
+├─ Total time: 1.4 minutes    ⚡ 7x faster
+├─ Total cost: $0.20          💰 80% savings
+└─ Best accuracy + speed
+```
+
+### Accuracy
+
+| Complexity | Morph LLM | Agent Booster | Difference |
+|------------|-----------|---------------|------------|
+| Simple | 99.2% | 98.5% | -0.7% |
+| Medium | 97.8% | 96.2% | -1.6% |
+| Complex | 96.1% | 93.8% | -2.3% |
+| **Overall** | **98.0%** | **96.8%** | **-1.2%** |
+
+## 🎯 Success Metrics
+
+### MVP (v0.1)
+- [x] Complete planning
+- [ ] Core Rust library functional
+- [ ] 100x speedup demonstrated
+- [ ] 95%+ accuracy on simple edits
+- [ ] Agentic-flow integration working
+
+### Production (v1.0)
+- [ ] WASM support
+- [ ] MCP server
+- [ ] 5+ languages
+- [ ] >80% test coverage
+- [ ] Documentation site
+
+### Adoption
+- [ ] 100+ GitHub stars
+- [ ] 1,000+ npm downloads
+- [ ] 10+ production users
+- [ ] 5+ contributors
+
+## 💡 Key Innovations
+
+1. **Vector-Based Semantic Merging** - No LLM needed for code application
+2. **Hybrid Fallback Strategy** - Best of both worlds (speed + accuracy)
+3. **Universal Deployment** - Native, WASM, MCP server from one codebase
+4. **Zero Runtime Cost** - 100% local after model download
+5. **Deterministic Results** - Same input always produces same output
+
+## 🤝 Next Steps
+
+1. **Review Planning** - Get team feedback on architecture
+2. **Finalize Scope** - Confirm MVP features
+3. **Create GitHub Issue** - Use [GITHUB-ISSUE.md](./GITHUB-ISSUE.md) template
+4. **Begin Phase 1** - Setup Rust workspace and benchmarks
+5. **Recruit Contributors** - Find Rust developers interested
+
+## 📝 Questions or Feedback?
+
+- Open an issue on GitHub
+- Comment on the planning documents
+- Join the discussion in Discord
+- DM the project maintainers
+
+---
+
+**Ready to make AI code editing 200x faster! 🚀**
+
+*Last updated: 2025-10-07*

package/docs/features/agent-booster/00-OVERVIEW.md

@@ -0,0 +1,454 @@
+# Agent Booster: Ultra-Fast Code Application Engine
+
+## 🎯 Vision
+
+Replace expensive, slow LLM-based code application APIs (like Morph LLM) with a deterministic, vector-based semantic code merging system that is:
+- **200x faster** (30-50ms vs 6000ms)
+- **100% free** (no API costs after setup)
+- **Deterministic** (same input = same output)
+- **Privacy-first** (fully local, no data leaves machine)
+- **Semantic** (understands code meaning via embeddings)
+
+## 🏗️ Project Structure
+
+```
+agent-booster/
+├── Cargo.toml                    # Rust workspace
+├── README.md                     # Main documentation
+├── LICENSE                       # MIT/Apache dual license
+├── crates/
+│   ├── agent-booster/           # Core Rust library
+│   │   ├── src/
+│   │   │   ├── lib.rs           # Public API
+│   │   │   ├── parser.rs        # Tree-sitter AST parsing
+│   │   │   ├── embeddings.rs    # Code embedding generation
+│   │   │   ├── vector.rs        # Vector similarity search
+│   │   │   ├── merge.rs         # Smart code merging
+│   │   │   └── models.rs        # Data structures
+│   │   └── Cargo.toml
+│   │
+│   ├── agent-booster-native/    # napi-rs Node.js addon
+│   │   ├── src/
+│   │   │   └── lib.rs           # Native bindings
+│   │   └── Cargo.toml
+│   │
+│   └── agent-booster-wasm/      # WebAssembly bindings
+│       ├── src/
+│       │   └── lib.rs           # WASM bindings
+│       └── Cargo.toml
+│
+├── npm/
+│   ├── agent-booster/           # Main NPM package
+│   │   ├── package.json
+│   │   ├── index.js             # Auto-detect native/WASM
+│   │   ├── index.d.ts           # TypeScript definitions
+│   │   └── README.md
+│   │
+│   └── agent-booster-cli/       # Standalone CLI (npx)
+│       ├── package.json
+│       ├── bin/
+│       │   └── agent-booster.js # CLI entry point
+│       └── README.md
+│
+├── benchmarks/
+│   ├── morphllm-baseline.ts     # Morph LLM baseline benchmarks
+│   ├── agent-booster.ts         # Agent Booster benchmarks
+│   ├── anthropic-models.ts      # Claude model comparison
+│   ├── datasets/                # Test code samples
+│   │   ├── javascript/
+│   │   ├── typescript/
+│   │   ├── python/
+│   │   └── rust/
+│   └── results/                 # Benchmark output
+│       ├── baseline.json
+│       └── comparison.json
+│
+├── docs/
+│   ├── architecture.md          # Technical architecture
+│   ├── integration.md           # Agentic-flow integration guide
+│   ├── api.md                   # API documentation
+│   ├── benchmarks.md            # Benchmark methodology
+│   └── comparison.md            # vs Morph LLM comparison
+│
+└── examples/
+    ├── basic-usage.js
+    ├── agentic-flow-integration.js
+    └── cli-usage.sh
+```
+
+## 🎯 Core Objectives
+
+### 1. Performance
+- **Target**: < 50ms per edit (vs Morph's 6000ms)
+- **Method**: Native Rust + WASM + Vector embeddings
+- **Measurement**: Comprehensive benchmarks vs Morph LLM
+
+### 2. Accuracy
+- **Target**: 95-99% accuracy (comparable to Morph's 98%)
+- **Method**: Vector similarity + AST-based merging + heuristics
+- **Validation**: Test suite with real-world code edits
+
+### 3. Developer Experience
+- **Target**: Zero-config for 80% of use cases
+- **Method**: Pre-trained models + auto-detection
+- **Integration**: Drop-in replacement for Morph LLM API
+
+### 4. Cost Efficiency
+- **Target**: $0 runtime cost (vs Morph's $0.01-0.10 per call)
+- **Method**: Local inference, one-time model download
+- **Savings**: 100% cost reduction after initial setup
+
+## 🚀 Key Features
+
+### Core Capabilities
+1. **Semantic Code Understanding** - Vector embeddings capture code meaning
+2. **Multi-Language Support** - JavaScript, TypeScript, Python, Rust, Go, Java, C++, etc.
+3. **AST-Aware Merging** - Preserves syntax and structure
+4. **Fuzzy Matching** - Handles renamed variables, moved code blocks
+5. **Confidence Scoring** - Know when merge is uncertain
+6. **Syntax Validation** - Ensures output is valid code
+
+### Performance Optimizations
+1. **Native Rust Core** - Maximum performance for Node.js
+2. **WASM Support** - Run in browsers, edge workers
+3. **Incremental Parsing** - Tree-sitter's fast updates
+4. **Smart Caching** - Reuse embeddings when possible
+5. **Parallel Processing** - Multi-file edits in parallel
+6. **Memory Efficient** - No persistent database required
+
+### Integration Features
+1. **Environment Variable** - `AGENT_BOOSTER_ENABLED=true`
+2. **CLI Commands** - `npx agent-booster apply <file> <edit>`
+3. **Programmatic API** - Import and use in Node.js/TypeScript
+4. **Agentic-flow Plugin** - Seamless integration
+5. **Fallback Mode** - Auto-fallback to LLM if uncertain
+
+## 📊 Success Metrics
+
+### Performance Benchmarks
+- [ ] Measure baseline: Morph LLM with Claude Sonnet 4
+- [ ] Measure baseline: Morph LLM with Claude Opus 4
+- [ ] Measure baseline: Morph LLM with Claude Haiku 4
+- [ ] Measure Agent Booster: Native addon
+- [ ] Measure Agent Booster: WASM
+- [ ] Measure Agent Booster: TypeScript fallback
+- [ ] Compare accuracy across 100+ real-world edits
+- [ ] Document speedup factor (target: 100-200x)
+- [ ] Document cost savings (target: 100%)
+
+### Quality Metrics
+- [ ] Accuracy: 95%+ on function replacements
+- [ ] Accuracy: 90%+ on method insertions
+- [ ] Accuracy: 85%+ on complex refactorings
+- [ ] False positives: < 5%
+- [ ] Syntax errors: < 1%
+
+### Adoption Metrics
+- [ ] Documentation coverage: 100%
+- [ ] Example coverage: 5+ use cases
+- [ ] Integration guides: Agentic-flow, standalone
+- [ ] Community feedback: GitHub issues/discussions
+
+## 🔄 Development Phases
+
+### Phase 1: Foundation (Week 1-2)
+- [ ] Setup Rust workspace
+- [ ] Implement tree-sitter parsing
+- [ ] Implement basic AST chunking
+- [ ] Setup benchmark framework
+- [ ] Create Morph LLM baseline benchmarks
+
+### Phase 2: Core Engine (Week 3-4)
+- [ ] Implement embedding generation (ONNX Runtime)
+- [ ] Implement vector similarity search (HNSW)
+- [ ] Implement merge strategies (replace, insert, append)
+- [ ] Implement confidence scoring
+- [ ] Add syntax validation
+- [ ] Run accuracy tests vs Morph LLM
+
+### Phase 3: Native Integration (Week 5)
+- [ ] Build napi-rs native addon
+- [ ] Create NPM package with auto-detection
+- [ ] Write TypeScript definitions
+- [ ] Add comprehensive tests
+- [ ] Benchmark native performance
+
+### Phase 4: WASM Support (Week 6)
+- [ ] Build WASM bindings
+- [ ] Optimize WASM bundle size
+- [ ] Add browser compatibility
+- [ ] Benchmark WASM performance
+- [ ] Create web examples
+
+### Phase 5: Agentic-flow Integration (Week 7)
+- [ ] Design .env configuration
+- [ ] Create agent-booster tool
+- [ ] Add fallback to Morph LLM
+- [ ] Write integration tests
+- [ ] Update agentic-flow documentation
+
+### Phase 6: CLI & SDK (Week 8)
+- [ ] Build standalone CLI (npx agent-booster)
+- [ ] Add watch mode
+- [ ] Add batch processing
+- [ ] Create usage examples
+- [ ] Write CLI documentation
+
+### Phase 7: Documentation & Release (Week 9-10)
+- [ ] Complete API documentation
+- [ ] Write architecture guide
+- [ ] Create comparison benchmarks
+- [ ] Record demo videos
+- [ ] Publish to crates.io + npm
+- [ ] Announce on GitHub, Twitter, Reddit
+
+## 🎓 Technical Approach
+
+### Vector Embeddings Strategy
+```
+1. Pre-trained Model: jina-embeddings-v2-base-code (768 dim)
+   - Specialized for code
+   - Understands syntax + semantics
+   - ONNX format for fast local inference
+
+2. Fallback Model: all-MiniLM-L6-v2 (384 dim)
+   - Faster, smaller
+   - General purpose but works well
+   - Lower memory footprint
+
+3. Custom Fine-tuning (Future):
+   - Train on agentic-flow's specific patterns
+   - Improve accuracy for common edits
+   - Domain-specific optimizations
+```
+
+### AST Processing Strategy
+```
+1. Parse with tree-sitter
+   - Support 40+ languages
+   - Incremental parsing for speed
+   - Error recovery
+
+2. Extract semantic chunks
+   - Functions, methods, classes
+   - Variable declarations
+   - Import/export statements
+   - Comments (for context)
+
+3. Index chunks with metadata
+   - Line numbers
+   - Node types
+   - Parent context
+   - Complexity metrics
+```
+
+### Merge Strategy Decision Tree
+```
+1. Exact AST Match (40% of cases)
+   → Replace matched node
+   → Confidence: 0.95-1.0
+
+2. High Vector Similarity (30% of cases)
+   → Replace if similarity > 0.85
+   → Confidence: 0.85-0.95
+
+3. Medium Similarity (20% of cases)
+   → Insert near if similarity > 0.65
+   → Confidence: 0.65-0.85
+
+4. Fuzzy AST Match (8% of cases)
+   → Use GumTree algorithm
+   → Confidence: 0.50-0.65
+
+5. Low Confidence (2% of cases)
+   → Return error or fallback to LLM
+   → Confidence: < 0.50
+```
+
+## 🔌 Integration Points
+
+### Agentic-flow Integration
+```typescript
+// .env configuration
+AGENT_BOOSTER_ENABLED=true
+AGENT_BOOSTER_MODEL=jina-code-v2  # or all-MiniLM-L6-v2
+AGENT_BOOSTER_CONFIDENCE_THRESHOLD=0.65
+AGENT_BOOSTER_FALLBACK_TO_MORPH=true
+MORPH_API_KEY=sk-morph-xxx  # fallback when confidence low
+
+// Automatic usage in agents
+const agent = new AgenticFlow({
+  tools: ['edit_file'],  // Automatically uses agent-booster
+  model: 'claude-sonnet-4'
+});
+```
+
+### Standalone Usage
+```bash
+# NPX CLI
+npx agent-booster apply src/main.ts "add error handling to parseConfig"
+
+# Watch mode
+npx agent-booster watch src/ --model jina-code-v2
+
+# Batch processing
+npx agent-booster batch edits.json --output results/
+```
+
+### Programmatic API
+```typescript
+import { AgentBooster } from 'agent-booster';
+
+const booster = new AgentBooster({
+  model: 'jina-code-v2',
+  confidenceThreshold: 0.65
+});
+
+const result = await booster.apply({
+  original: readFileSync('src/main.ts', 'utf-8'),
+  edit: 'add error handling to parseConfig',
+  language: 'typescript'
+});
+
+console.log(result.code);        // Merged code
+console.log(result.confidence);  // 0.0-1.0
+console.log(result.strategy);    // 'exact_match' | 'vector_similarity' | 'fuzzy'
+```
+
+## 🧪 Benchmark Design
+
+### Test Datasets
+1. **Simple Edits** (40 samples)
+   - Add function
+   - Rename variable
+   - Update import
+   - Add comment
+
+2. **Medium Edits** (40 samples)
+   - Replace function body
+   - Add error handling
+   - Refactor method
+   - Update types
+
+3. **Complex Edits** (20 samples)
+   - Multi-function changes
+   - Cross-file refactoring
+   - Architectural changes
+   - Performance optimizations
+
+### Models to Benchmark
+1. **Morph LLM Baseline**
+   - Claude Sonnet 4 (current best)
+   - Claude Opus 4 (highest quality)
+   - Claude Haiku 4 (fastest)
+
+2. **Agent Booster Variants**
+   - Native addon (fastest)
+   - WASM (portable)
+   - TypeScript fallback (baseline)
+
+### Metrics to Collect
+- **Latency**: p50, p95, p99, max
+- **Accuracy**: exact match, semantic match, syntax valid
+- **Cost**: API calls, tokens used, dollar amount
+- **Memory**: Peak usage, average usage
+- **Throughput**: Edits per second
+- **Confidence**: Distribution of scores
+
+## 📈 Expected Results
+
+### Performance Comparison
+```
+Edit Type: Simple Function Addition
+
+Morph + Claude Sonnet 4:
+├─ Latency: 5,800ms (p50)
+├─ Cost: $0.008 per edit
+├─ Accuracy: 98.5%
+└─ Tokens: 4,200
+
+Agent Booster (Native):
+├─ Latency: 35ms (p50)        ⚡ 166x faster
+├─ Cost: $0.000 per edit      💰 100% savings
+├─ Accuracy: 97.2%            📊 -1.3%
+└─ Memory: 180MB
+
+Agent Booster (WASM):
+├─ Latency: 58ms (p50)        ⚡ 100x faster
+├─ Cost: $0.000 per edit      💰 100% savings
+├─ Accuracy: 97.2%            📊 -1.3%
+└─ Memory: 220MB
+```
+
+### Accuracy Trade-offs
+- **Agent Booster Wins**: Deterministic, fast, simple edits
+- **Morph LLM Wins**: Ambiguous instructions, complex reasoning
+- **Sweet Spot**: 80% of edits are simple/medium → huge savings
+
+## 🎯 Success Criteria
+
+### Must Have (MVP)
+- [ ] 100x+ speedup vs Morph LLM
+- [ ] 95%+ accuracy on simple edits
+- [ ] Works with JavaScript/TypeScript
+- [ ] Native Node.js addon
+- [ ] NPM package published
+- [ ] Agentic-flow integration
+
+### Should Have (v1.0)
+- [ ] WASM support
+- [ ] 5+ language support
+- [ ] Standalone CLI
+- [ ] Comprehensive benchmarks
+- [ ] Documentation site
+
+### Nice to Have (v2.0)
+- [ ] Fine-tuned custom models
+- [ ] Browser extension
+- [ ] VS Code extension
+- [ ] Real-time collaborative editing
+- [ ] Cloud-hosted version
+
+## 🤔 Open Questions
+
+1. **Embedding Model Selection**
+   - Should we ship with one model or support multiple?
+   - What's the right balance between size and accuracy?
+   - Can we quantize models for smaller downloads?
+
+2. **Fallback Strategy**
+   - When should we fallback to LLM?
+   - Should fallback be opt-in or opt-out?
+   - Can we learn from fallback cases to improve?
+
+3. **Language Support**
+   - Which languages to prioritize?
+   - Should we support LSP for better parsing?
+   - How to handle non-tree-sitter languages?
+
+4. **Deployment Options**
+   - Should we offer hosted version?
+   - Enterprise on-premise deployment?
+   - Edge/serverless support?
+
+5. **Business Model**
+   - Fully open source (MIT/Apache)?
+   - Dual license (open + commercial)?
+   - SaaS offering for convenience?
+
+## 📚 References
+
+- [Morph LLM Docs](https://docs.morphllm.com/introduction)
+- [Tree-sitter](https://tree-sitter.github.io/)
+- [ONNX Runtime](https://onnxruntime.ai/)
+- [napi-rs](https://napi.rs/)
+- [Jina Embeddings](https://huggingface.co/jinaai/jina-embeddings-v2-base-code)
+- [GumTree Algorithm](https://github.com/GumTreeDiff/gumtree)
+
+## 🚀 Next Steps
+
+1. Review this plan with team
+2. Get feedback on architecture
+3. Finalize scope for MVP
+4. Create GitHub issue with tasks
+5. Begin Phase 1 implementation