weevil/docs/ROADMAP.md

# Weevil Roadmap

This document outlines the planned feature development for Weevil across multiple versions. Features are subject to change based on user feedback, technical constraints, and market needs.

## Status Key

- ✅ **Complete** - Feature shipped in a release
- ⚠️ **In Progress** - Currently being developed
- 🔄 **Deferred** - Planned but postponed to a later version
- ❌ **Cancelled** - Feature dropped from roadmap

---

## Version 1.1.0 - Core Stability & Professional Templates ✅ COMPLETE

**Theme:** Making Weevil production-ready for FTC teams with essential operational features, reducing friction in existing workflows, and providing professional code templates for learning.

**Status:** Released as v1.1.0 (all features complete and tested)

### System Audit & Diagnostics ✅

**Feature:** `weevil doctor` command

**Description:** Provides a comprehensive audit of the development environment, showing what's installed and what versions are present. This displays:
- FTC SDK versions (current and available)
- Android SDK installation status and version
- Gradle version and location
- Java/JDK version and location
- ADB availability and version
- Any other critical dependencies Weevil manages

**Status:** ✅ Complete - Shipped in v1.1.0

**Rationale:** Teams need visibility into their environment to troubleshoot issues. Coaches working with multiple machines need to quickly verify setup consistency across laptops. This builds trust by making Weevil's actions transparent.

---

### Dependency Cleanup ✅

**Feature:** `weevil uninstall` command

**Description:** Removes dependencies that Weevil installed during setup. This includes:
- FTC SDK files
- Android SDK components (if Weevil installed them)
- Gradle distributions
- Configuration files Weevil created

Offers options for selective cleanup (e.g., keep SDK but remove Gradle) or complete removal.

**Status:** ✅ Complete - Shipped in v1.1.0

**Implementation:** `weevil uninstall`, `weevil uninstall --dry-run`, `weevil uninstall --only <N>`

---

### Corporate/School Proxy Support ✅

**Feature:** Transparent proxy configuration for all network operations

**Description:** Automatically detect and use system proxy settings (or allow manual configuration) for all network operations including:
- Gradle dependency downloads
- Android SDK downloads
- FTC SDK downloads
- Any HTTP/HTTPS requests Weevil makes

Handle `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables and write appropriate configuration into Gradle properties, Android SDK manager config, etc.

**Status:** ✅ Complete - Shipped in v1.1.0

**Implementation:** 
- `--proxy <url>` global flag
- `--no-proxy` global flag (bypass)
- Automatic HTTPS_PROXY/HTTP_PROXY env var detection
- git2/libgit2 proxy support
- Gradle wrapper respects proxy settings

---

### Android Studio Integration ✅

**Feature:** Seamless integration with Android Studio IDE

**Description:** Generate Android Studio project files and configurations that:
- Hide Weevil's internal directory structure from the IDE view
- Present a clean, minimal file tree to students
- Hook Weevil's build and deploy scripts into Android Studio's "Run" button
- Properly configure the IDE's indexing and code completion

The goal: students work in Android Studio (the tool they know) but get Weevil's improved project structure and deployment workflow behind the scenes.

**Status:** ✅ Complete - Shipped in v1.1.0

**Implementation:** 
- Auto-generated `.idea/` run configurations
  - Build
  - Deploy (auto) - auto-detects USB/WiFi
  - Deploy (USB) - forces USB
  - Deploy (WiFi) - forces WiFi
  - Test - runs unit tests
- workspace.xml for clean file tree
- Cross-platform support (Unix `.sh` and Windows `.bat` variants)
- One-click deployment from IDE

**Note:** Requires Shell Script plugin installation in Android Studio (one-time setup, documented in README)

---

### Template System ✅ **THE GAME CHANGER**

**Feature:** Professional code templates for project creation

**Description:** Transform Weevil from "empty project generator" to "start with professional code." Includes:

**Templates:**
1. **`basic`** (default) - Minimal FTC project
   - Clean starting point
   - ~10 files, ~50 lines of code
   - Perfect for teams starting from scratch

2. **`testing`** - Professional testing showcase
   - **45 comprehensive tests** that pass in < 2 seconds
   - **3 complete subsystems** (MotorCycler, WallApproach, TurnController)
   - **Hardware abstraction layer** with interfaces and mocks
   - **Professional documentation** (6 markdown files, ~65 KB)
   - ~30 files, ~2,500 lines of code
   - Real patterns used in competition

**Commands:**
- `weevil new <name>` - Creates project with basic template
- `weevil new <name> --template testing` - Creates with testing showcase
- `weevil new --list-templates` - Shows available templates with details

**Status:** ✅ Complete - Shipped in v1.1.0

**Implementation:**
- Templates embedded in binary using `include_dir!` macro
- Variable substitution (`{{PROJECT_NAME}}`, `{{PACKAGE_NAME}}`, `{{CREATION_DATE}}`, `{{WEEVIL_VERSION}}`, `{{TEMPLATE_NAME}}`)
- Template validation with helpful error messages
- Templates overlay on ProjectBuilder infrastructure
- 62 comprehensive tests (all passing)

**Rationale:** **This is revolutionary for FTC.** Most teams start with empty projects and learn by trial-and-error on hardware. Now they can:
- Start with working, tested code
- Run 45 tests instantly on their PC
- Learn from professional patterns
- Modify working examples for their robot
- Understand test-driven development

This is the kind of code students would write if they had years of experience. Now they can START with it.

**Impact:**
- Teams learn professional software engineering patterns
- Testing without hardware (save hours of deploy time)
- Clean architecture examples (interfaces, mocks, state machines)
- Comprehensive documentation showing WHY and HOW
- Positions Nexus Workshops as FTC software authority

---

### Manual Installation Fallback Documentation 🔄

**Feature:** Comprehensive manual setup documentation

**Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails.

**Status:** 🔄 Deferred to v1.2.0 - Basic troubleshooting exists in README, comprehensive guide pending

---

### Package Distribution (Debian/Ubuntu) 🔄

**Feature:** `.deb` package for easy installation on Debian-based systems

**Status:** 🔄 Deferred - Not essential for initial adoption

---

## Version 1.2.0 - Package Ecosystem & Enhanced Templates 🔥

**Theme:** Transforming Weevil from project generator to ecosystem platform. Teams can extend projects with community-shared components and additional professional templates.

**Status:** Planning - Expected Q2 2026

### Template Metadata & Improved Display ⚠️

**Feature:** Template discovery with rich metadata and formatted display

**Description:** Enhance template system with metadata files for better discoverability:

**Template Metadata (`template.toml`):**
```toml
[template]
name = "localization"
description = "Grid-based robot localization with sensor fusion"
file_count = 21
test_count = 3
perfect_for = "Advanced autonomous navigation"

[includes]
items = [
    "12x12 field grid system",
    "Multi-sensor fusion (encoders + IMU + vision)",
    "Fault-tolerant positioning"
]
```

**Improved `--list-templates` Output:**
```
Available templates:

  basic (default)
    Minimal FTC project structure
    Files: ~10 | Tests: 1
    Perfect for: Teams starting from scratch

  testing
    Professional testing showcase with examples
    Files: ~30 | Tests: 45
    Perfect for: Learning best practices
    Includes:
      • 3 complete subsystems
      • Hardware abstraction layer
      • 45 passing tests

  localization
    Grid-based robot localization with sensor fusion
    Files: ~21 | Tests: 3
    Perfect for: Advanced autonomous navigation
    Includes:
      • 12x12 field grid system
      • Multi-sensor fusion
      • Fault-tolerant positioning

Usage:
  weevil new <project-name>                    # Uses basic
  weevil new <project-name> --template testing # Uses testing
```

**Status:** ⚠️ Planned for v1.2.0

**Priority:** MEDIUM-HIGH - Improves template discoverability

**Effort:** 1-2 days (metadata format + CLI formatting)

---

### Localization Template ⚠️

**Feature:** Grid-based localization template for advanced autonomous

**Description:** Professional robot localization system with sensor fusion and fault tolerance:

**What's Included:**
- **Grid System** - 12ft x 12ft field divided into 12x12 grid (12" cells)
- **Sensor Fusion** - Combine odometry (encoders), IMU (gyro), and vision (AprilTags)
- **Fault Tolerance** - Graceful degradation when sensors fail
- **Lookup Tables** - Pre-computed navigation strategies
- **21 Files** - 7 localization classes, 3 hardware interfaces, 3 mocks, 3 tests, 2 docs
- **3 Comprehensive Tests** - Grid math, sensor fusion, fault tolerance

**Core Components:**
- `GridCell.java` - Cell in 12x12 grid (0-11, 0-11)
- `Pose2D.java` - Position (x, y) + heading with angle normalization
- `FieldGrid.java` - Field coordinate system and conversions
- `RobotLocalizer.java` - Multi-sensor fusion engine
- `OdometryTracker.java` - Dead reckoning from wheel encoders
- `ImuLocalizer.java` - Heading tracking from gyroscope
- `VisionLocalizer.java` - Position from AprilTags

**Sensor Fusion Priority:**
1. Vision (AprilTags) → ±2" accuracy, 100% confidence
2. IMU + Odometry → ±4" accuracy, 70% confidence
3. Odometry only → ±12" accuracy, 40% confidence

**Rationale:** Teaches professional robotics concepts (Kalman-filter-style sensor fusion, fault tolerance, grid-based navigation). No other FTC tool has this. Positions Nexus Workshops as teaching advanced autonomous programming.

**Usage:**
```bash
weevil new my-robot --template localization
cd my-robot
./gradlew test  # 3 tests pass
# Modify for your robot's sensors and autonomous strategy
```

**Status:** ⚠️ Template complete, ready to integrate in v1.2.0

**Priority:** HIGH - Unique differentiator, advanced autonomous capability

**Effort:** Template already created, integration 1 day

---

### `weevil add` - Component Package Manager ⚠️ **THE NEXT BIG THING**

**Feature:** Package manager for sharing and reusing FTC robot code components

**Description:** Enable teams to add pre-built components to existing projects:

```bash
# Add a complete subsystem
weevil add nexus/subsystems/mecanum-drive/complete

# Add just the interface
weevil add nexus/hardware/dc-motor/core

# Add test mocks
weevil add nexus/hardware/dc-motor/mock --dev

# Search for packages
weevil search "mecanum"

# See what's installed
weevil list --installed

# Update packages
weevil update
```

**Package Naming:** `scope/category/name/variant`

**Examples:**
- `nexus/hardware/dc-motor/complete` - Motor controller (interface + FTC impl + mocks + examples)
- `nexus/subsystems/wall-approach/complete` - Complete wall approach subsystem
- `nexus/examples/autonomous/simple-auto` - Example autonomous routine
- `team1234/sensors/custom-lidar/core` - Community package from Team 1234

**Standard Variants:**
- `core` - Interface + FTC implementation
- `mock` - Test doubles for unit testing
- `example` - Example OpMode showing usage
- `complete` - All of the above

**Key Features:**
- **Dependency resolution** - Auto-install dependencies (e.g., subsystem → hardware interfaces)
- **Conflict handling** - Interactive, force, or skip modes
- **Version management** - Semantic versioning, upgrade tracking
- **License compliance** - Track and display licenses
- **Quality tiers:**
  - **Community** - Open submissions
  - **Nexus Verified** - Reviewed, tested, maintained by Nexus Workshops

**Rationale:** This is the network effect feature that creates a moat:
- **For Teams:** Stop reinventing wheels, use proven solutions
- **For Nexus Workshops:** Becomes central hub for FTC software knowledge
- **For Community:** Share solutions, build on each other's work
- **For FTC:** Raises software quality across all teams

**Initial Package Set (v1.2.0 Launch):**

Must Have (10 packages):
1. `nexus/hardware/dc-motor/complete`
2. `nexus/hardware/servo/complete`
3. `nexus/hardware/distance/complete`
4. `nexus/hardware/imu/complete`
5. `nexus/hardware/color-sensor/complete`
6. `nexus/subsystems/wall-approach/complete`
7. `nexus/subsystems/turn-controller/complete`
8. `nexus/testing/mock-hardware`
9. `nexus/examples/autonomous/simple-auto`
10. `nexus/examples/teleop/basic-drive`

Nice to Have (+5):
11. `nexus/hardware/mecanum-drive/complete`
12. `nexus/subsystems/april-tag/complete`
13. `nexus/examples/autonomous/complex-auto`
14. `nexus/utilities/telemetry/dashboard`
15. `nexus/testing/test-patterns`

**Supporting Commands:**
- `weevil remove <package>` - Remove installed package
- `weevil search <query>` - Search package registry
- `weevil list [--installed|--available]` - List packages
- `weevil info <package>` - Show package details
- `weevil update [package]` - Update packages

**Package Repository:** https://packages.nxgit.dev (to be created)

**Status:** ⚠️ In Planning - Design complete, implementation starting

**Priority:** **CRITICAL** - This is the strategic differentiator for v1.2.0

**Estimated Effort:** 2-3 weeks development + 1 week for initial package set

**Success Metrics:**
- 20+ quality packages at launch
- 100+ package downloads in first month
- 5+ community-contributed packages within 3 months
- Active package ecosystem by end of 2026

---

### Windows Testing & Stabilization ✅

**Feature:** Complete Windows support verification

**Status:** ✅ Complete - All 62 tests passing on Windows, proxy support working, Android Studio integration verified

---

### Android Studio Debugging Support

**Feature:** Full debugging integration for Android Studio

**Description:** Extend the Android Studio integration to support breakpoint debugging directly from the IDE:
- Generate debug run configurations that attach to the robot
- Configure remote debugging for Android/FTC apps
- Map source files correctly for breakpoint support
- Handle ADB debugging bridge setup automatically
- Support both USB and WiFi debugging

**Status:** 🔄 Deferred to v1.3.0 - Advanced feature, build basic package system first

**Priority:** MEDIUM-HIGH - Natural extension after package system

---

### Windows Installer (MSI)

**Feature:** Professional Windows installer package

**Description:** Create an MSI installer using WiX Toolset or `cargo-wix` that:
- Installs weevil.exe to Program Files
- Adds weevil to system PATH automatically
- Creates Start Menu entries
- Appears in "Programs and Features" for clean uninstall
- Optionally creates desktop shortcut

**Status:** 🔄 Deferred to v1.2.0

**Priority:** MEDIUM - Polish feature for Windows adoption

---

### Linux Program Launcher Integration

**Feature:** Desktop file and menu integration for Linux

**Status:** 🔄 Deferred to v1.2.0

**Priority:** MEDIUM - Pairs well with GUI development (v1.3.0+)

---

### Non-Debian Linux Distribution Support

**Feature:** Support for Arch, Fedora, Slackware, and other distributions

**Status:** 🔄 Deferred - Low priority, most teams use Ubuntu/Debian or Windows

**Priority:** LOW-MEDIUM

---

## Version 1.3.0 - Developer Experience

**Theme:** Making Weevil an all-in-one development environment with advanced debugging and UX polish

**Status:** Planning - Expected Q3 2026

### Android Studio Debugging Support

**Feature:** Full debugging integration for Android Studio

**Description:** Students should be able to:
1. Set breakpoints in their OpMode code
2. Select "Debug" configuration from Android Studio
3. Click the debug button (🐛)
4. Have the debugger attach to the running robot
5. Step through code, inspect variables, etc.

**Status:** Planned for v1.3.0

**Priority:** HIGH - Natural next step after package ecosystem

---

### Graphical User Interface (GUI)

**Feature:** GUI application for teams uncomfortable with terminals

**Description:** A graphical interface that wraps Weevil's functionality:
- Create projects through forms/wizards
- Visual project configuration
- Button-based builds and deployments
- Visual package browser and installer
- Status and logs in a window

**Technical Approach:** Tauri (Rust + web frontend) for native performance and small binary

**Status:** Planned for v1.3.0

**Priority:** MEDIUM-HIGH - Lowers barrier to entry significantly

---

### REST API Layer

**Feature:** Internal API that both CLI and GUI can consume

**Description:** Refactor Weevil's core functionality behind a REST API:
- CLI becomes thin client
- GUI uses same API endpoints
- Enables future integrations (VS Code extension, web dashboard)

**Status:** 🔄 Deferred - Only if building GUI

**Priority:** MEDIUM - Clean architecture, but not essential unless building GUI

---

## Version 1.4.0 - Advanced Tooling

**Theme:** Making Weevil an intelligent development assistant

**Status:** Planning - Expected Q4 2026

### Troubleshooting Suite

**Feature:** Comprehensive diagnostic and debugging tools

**Potential Components:**
1. **Connectivity Diagnostics** - `weevil diagnose adb`
2. **Build Analysis** - Parse build errors and suggest fixes
3. **Log Analysis** - `weevil logs analyze`
4. **Performance Profiling** - Measure loop times, identify bottlenecks
5. **Code Quality Checks** - Static analysis, anti-pattern detection
6. **Interactive Troubleshooter** - Wizard-style troubleshooting

**Status:** Planned for v1.4.0

**Priority:** MEDIUM-HIGH - High value but complex

---

## Version 1.5.0 - Language Expansion

**Theme:** Future-proofing Weevil for FTC's evolution

### C++ Language Support

**Feature:** Support for C++ FTC projects alongside Java

**Status:** Research - Contingent on FTC officially supporting C++

**Priority:** LOW - Wait for FTC announcement

**Trigger:** FTC officially announces C++ support

---

### Multi-Language Architecture

**Feature:** Plugin-based language support architecture

**Status:** Research - Only if supporting 3+ languages

**Priority:** LOW-MEDIUM

---

## Version 2.0.0 - Major Architectural Changes

**Theme:** Breaking changes that significantly improve Weevil but may require migration

**Potential Features:**
- Complete rewrite of core systems if architecture needs major overhaul
- Breaking changes to project structure
- New configuration format
- Major changes to CLI interface
- Integration with cloud services (build servers, team collaboration)

**Note:** Given the `weevil upgrade` command's ability to migrate projects, moving to 2.0.0 may not be necessary unless there are fundamental architecture changes that can't be backward compatible.

---

## Unscheduled / Research Needed

### SOCKS Proxy Support

**Feature:** Support for SOCKS4/SOCKS5 proxies in addition to HTTP proxies

**Status:** Research - needs market validation

**Priority:** LOW - HTTP proxy covers most use cases

**Decision Point:** Wait for user requests

---

### Cloud Build Services

**Description:** Remote build servers for teams with slow computers

**Status:** Research - needs cost/benefit analysis, infrastructure planning

---

### VS Code Extension

**Description:** Extension for VS Code to provide similar integration as Android Studio

**Status:** Research - depends on VS Code adoption in FTC community

---

### Team Collaboration Features

**Description:** Features for teams to coordinate across multiple developers

**Status:** Research - needs market validation

---

### Custom Hardware Support

**Description:** Templates and tools for teams using custom sensors or actuators

**Status:** Research - depends on community need

---

## Versioning Philosophy

- **1.x.0 releases:** New features, backward compatible
- **1.x.y releases:** Bug fixes, patches, documentation
- **2.0.0:** Breaking changes requiring migration (avoid if possible)

The `weevil upgrade` command is designed to migrate projects forward across versions, making major version bumps less necessary.

---

## Success Metrics

How we'll measure if Weevil is succeeding:

### v1.1.0 Metrics (Achieved)
- ✅ 62 comprehensive tests, all passing
- ✅ Zero compiler warnings
- ✅ Cross-platform support (Windows, Linux, macOS)
- ✅ Professional documentation (README, DESIGN_AND_TEST_PLAN, etc.)
- ✅ Testing template with 45 passing tests

### v1.2.0 Target Metrics
- 20+ quality packages at launch
- 100+ package downloads in first month
- 5+ community-contributed packages within 3 months
- 50+ teams using Weevil

### Long-term Metrics
- **Adoption:** Number of teams using Weevil (tracked via downloads, GitHub stars)
- **Retention:** Teams continuing to use across seasons
- **Nexus Workshops impact:** Weevil drives workshop signups or consulting engagement
- **Community:** Package contributions, GitHub issues/PRs, community discussions
- **Competitive outcomes:** Nexus Workshops teams using Weevil perform better

---

## Recent Accomplishments (v1.1.0)

**What We Shipped:**

1. **Template System** - Start with professional code, not empty files
   - 45-test testing showcase
   - 3 complete subsystems
   - Hardware abstraction patterns
   - Professional documentation

2. **Android Studio Integration** - One-click deployment from IDE
   - Auto-generated run configurations
   - Clean file tree
   - Cross-platform support

3. **Proxy Support** - Works in corporate/school environments
   - HTTP/HTTPS proxy support
   - Environment variable detection
   - Bypass capability

4. **System Diagnostics** - `weevil doctor` and `weevil uninstall`
   - Comprehensive environment audit
   - Selective component removal
   - Troubleshooting support

**Impact:**
- Teams can now learn from professional code instead of starting from scratch
- Testing without hardware saves hours of development time
- Corporate/school adoption enabled
- Professional-grade tooling for FTC

---

## Contributing to the Roadmap

This roadmap is subject to change based on:
- User feedback from FTC teams
- Technical feasibility discoveries
- Market competition
- Strategic priorities for Nexus Workshops LLC

Features may be accelerated, deferred, or cancelled as the project evolves.

**Want to influence the roadmap?** 
- Submit GitHub issues with feature requests
- Share your team's pain points
- Contribute to package ecosystem (v1.2.0+)
- Provide feedback on template quality

---

*Last Updated: February 2026*
*Current Release: v1.1.0*
*Next Release: v1.2.0 (Package Ecosystem) - Q2 2026*