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 🔥

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

Status: Planning - Expected Q2 2026

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:

# 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