# Owlen Project Improvement Roadmap

Generated from codebase analysis on 2025-11-01

## Overall Assessment

**Grade:** A (90/100)
**Status:** Production-ready with minor enhancements needed
**Architecture:** Excellent domain-driven design with clean separation of concerns

---

## 🔴 Critical Issues (Do First)

- [x] **Fix Integration Test Failure** (`crates/app/cli/tests/chat_stream.rs`) ✅ **COMPLETED**
  - Fixed mock server to accept requests with tools parameter
  - Test now passes successfully
  - Location: `crates/app/cli/tests/chat_stream.rs`

- [x] **Remove Side Effects from Library Code** (`crates/core/agent/src/lib.rs:348-349`) ✅ **COMPLETED**
  - Replaced `println!` with `tracing` crate
  - Added `tracing = "0.1"` dependency to `agent-core`
  - Changed to structured logging: `tracing::debug!` for tool calls, `tracing::warn!` for errors
  - Users can now control verbosity and route logs appropriately
  - Location: `crates/core/agent/src/lib.rs:348, 352, 361`

---

## 🟡 High-Priority Improvements

### Permission System ✅

- [x] **Implement Proper Permission Selection in TUI** ✅ **COMPLETED**
  - Added interactive permission popup with keyboard navigation
  - Implemented "Allow once", "Always allow", "Deny", and "Explain" options
  - Integrated permission requests into agent loop with async channels
  - Added runtime permission rule updates for "Always allow"
  - Permission popups pause execution and wait for user input
  - Location: `crates/app/ui/src/app.rs`, `crates/app/ui/src/components/permission_popup.rs`

### Documentation

- [ ] **Add User-Facing README.md**
  - Quick start guide
  - Installation instructions
  - Usage examples
  - Feature overview
  - Links to detailed docs
  - Priority: HIGH

- [ ] **Add Architecture Documentation**
  - Crate dependency graph diagram
  - Agent loop flow diagram
  - Permission system flow diagram
  - Plugin/hook integration points diagram
  - Priority: MEDIUM

### Feature Integration

- [ ] **Integrate Plugin System**
  - Wire plugin loading into `crates/app/cli/src/main.rs`
  - Load plugins at startup
  - Test with example plugins
  - Priority: HIGH

- [ ] **Integrate MCP Client into Agent**
  - Add MCP tools to agent's tool registry
  - Enable external tool servers (databases, APIs, etc.)
  - Document MCP server setup
  - Priority: HIGH

- [ ] **Implement Real Web Search Provider**
  - Add provider for DuckDuckGo, Brave Search, or SearXNG
  - Make the web tool functional
  - Add configuration for provider selection
  - Priority: MEDIUM

### Error Handling & Reliability

- [ ] **Add Retry Logic for Transient Failures**
  - Exponential backoff for Ollama API calls
  - Configurable retry policies (max attempts, timeout)
  - Handle network failures gracefully
  - Priority: MEDIUM

- [ ] **Enhance Error Messages**
  - Add actionable suggestions for common errors
  - Example: "Ollama not running? Try: `ollama serve`"
  - Example: "Model not found? Try: `ollama pull qwen3:8b`"
  - Priority: MEDIUM

---

## 🟢 Medium-Priority Enhancements

### Testing

- [ ] **Add UI Component Testing**
  - Snapshot tests for TUI components
  - Integration tests for user interactions
  - Use `ratatui` testing utilities
  - Priority: MEDIUM

- [ ] **Add More Edge Case Tests**
  - Glob patterns with special characters
  - Edit operations with Unicode
  - Very large file handling
  - Concurrent tool execution
  - Priority: MEDIUM

- [ ] **Code Coverage Reporting**
  - Integrate `tarpaulin` or `cargo-llvm-cov`
  - Set minimum coverage thresholds (aim for 80%+)
  - Track coverage trends over time
  - Priority: LOW

### Documentation

- [ ] **Module-Level Documentation**
  - Add `//!` docs to key modules
  - Explain design decisions and patterns
  - Document internal APIs
  - Priority: MEDIUM

- [ ] **Create Examples Directory**
  - Simple CLI usage examples
  - Custom plugin development guide
  - Hook script examples
  - MCP server integration examples
  - Configuration templates
  - Priority: MEDIUM

### Code Quality

- [ ] **Fix Dead Code Warning** (`ui/src/app.rs:38`)
  - Either use `settings` field or remove it
  - Remove `#[allow(dead_code)]`
  - Priority: LOW

- [ ] **Improve Error Recovery**
  - Checkpoint auto-save on crashes
  - Graceful degradation when tools fail
  - Better handling of partial tool results
  - Priority: MEDIUM

---

## 🔵 Low-Priority Nice-to-Haves

### Project Infrastructure

- [ ] **CI/CD Pipeline (GitHub Actions)**
  - Automated testing on push
  - Clippy linting
  - Format checking with `rustfmt`
  - Security audits with `cargo-audit`
  - Cross-platform builds (Linux, macOS, Windows)
  - Priority: LOW

- [ ] **Performance Benchmarking**
  - Add benchmark suite using `criterion` crate
  - Track performance for glob, grep, large file ops
  - Track agent loop iteration performance
  - Priority: LOW

### Code Organization

- [ ] **Extract Reusable Crates**
  - Publish `mcp-client` as standalone library
  - Publish `llm-ollama` as standalone library
  - Enable reuse by other projects
  - Consider publishing to crates.io
  - Priority: LOW

---

## 💡 Feature Enhancement Ideas

### Session Management

- [ ] **Session Persistence**
  - Auto-save sessions across restarts
  - Resume previous conversations
  - Session history browser in TUI
  - Export/import session transcripts

### Multi-Provider Support

- [ ] **Multi-Model Support**
  - Support Anthropic Claude API
  - Support OpenAI API
  - Provider abstraction layer
  - Fallback chains for reliability

### Enhanced Permissions

- [ ] **Advanced Permission System**
  - Time-based permissions (expire after N minutes)
  - Scope-based permissions (allow within specific directories)
  - Permission profiles (dev, prod, strict)
  - Team permission policies

### Collaboration

- [ ] **Collaborative Features**
  - Export sessions as shareable transcripts
  - Import/export checkpoints
  - Shared permission policies for teams
  - Session replay functionality

### Observability

- [ ] **Enhanced Observability**
  - Token usage tracking per tool call
  - Cost estimation dashboard
  - Performance metrics export (JSON/CSV)
  - OpenTelemetry integration
  - Real-time stats in TUI

---

## 🚀 Quick Wins (Can Be Done Today)

- [ ] Add `README.md` to repository root
- [ ] Fix dead code warning in `ui/src/app.rs:38`
- [ ] Add `tracing` crate and replace `println!` calls
- [ ] Create `.github/workflows/ci.yml` for basic CI
- [ ] Add module-level docs to `agent-core` and `config-agent`

---

## 🌟 Long-Term Vision

- **Plugin Marketplace:** Curated registry of community plugins
- **Interactive Tutorial:** Built-in tutorial mode for new users
- **VS Code Extension:** Editor integration for inline assistance
- **Collaborative Agents:** Multi-agent workflows with role assignment
- **Knowledge Base Integration:** RAG capabilities for project-specific knowledge
- **Web Dashboard:** Browser-based interface for session management
- **Cloud Sync:** Sync configs and sessions across devices

---

## Notes

- **Test Status:** 28+ tests, most passing. 1 integration test failure (mock server issue)
- **Test Coverage:** Strong coverage for core functionality (permissions, checkpoints, hooks)
- **Architecture:** Clean domain-driven workspace with 15 crates across 4 domains
- **Code Quality:** Excellent error handling, consistent patterns, minimal technical debt
- **Innovation Highlights:** Checkpoint/rewind system, three-tiered permissions, shell-based hooks

---

## Priority Legend

- **HIGH:** Should be done soon, blocks other features or affects quality
- **MEDIUM:** Important but not urgent, improves user experience
- **LOW:** Nice to have, can be deferred

---

Last Updated: 2025-11-01