weevil/docs/TEMPLATE-PACKAGE-SPEC.md

Weevil Template & Package System - Complete Specification

Version: 1.0
Date: February 2, 2026
Status: Ready for implementation

---

Executive Summary

This document specifies two complementary features for Weevil:

1. weevil create (v1.1.0) - Project scaffolding with templates
2. weevil add (v1.2.0) - Package management system

Together, these enable teams to start with professional code and extend projects with community-shared components.

---

Part 1: weevil create Command

Overview

Purpose: Generate complete FTC robot projects from templates

Version: v1.1.0-beta.3
Priority: HIGH

Command Syntax

weevil create <project-name> [OPTIONS]

OPTIONS:
  --template <name>    Template to use (default: "basic")
  --path <directory>   Where to create project (default: current dir)
  --force              Overwrite existing directory
  --no-init            Don't initialize git repository
  --dry-run            Show what would be created

Templates (v1.1.0)

Template 1: basic (Default)

Purpose: Minimal starting point

Structure:

my-robot/
├── src/
│   ├── main/java/robot/
│   │   └── opmodes/
│   │       └── BasicOpMode.java
│   └── test/java/robot/
│       └── .gitkeep
├── build.gradle
├── settings.gradle
├── .weevil.toml
├── .gitignore
├── README.md
└── build.bat / build.sh

Files: ~10
Code: ~50 lines

Template 2: testing (Showcase)

Purpose: Professional testing demonstration

Includes:

• 3 subsystems (MotorCycler, WallApproach, TurnController)
• 6 hardware interfaces + FTC implementations
• 6 test mocks
• 45 passing tests
• Complete documentation (6 files)

Files: ~30
Code: ~2,500 lines
Tests: 45 (< 2 sec runtime)

Documentation:

• README.md
• DESIGN_AND_TEST_PLAN.md
• TESTING_GUIDE.md
• TESTING_SHOWCASE.md
• SOLUTION.md
• ARCHITECTURE.md

Usage Examples

# Create minimal project
weevil create my-robot

# Create with testing template
weevil create my-robot --template testing

# Create in specific location
weevil create my-robot --template testing --path ~/ftc-projects

# Preview without creating
weevil create my-robot --template testing --dry-run

Variable Substitution

Templates support variables:

Variable	Description	Example
{{PROJECT_NAME}}	Project directory name	my-robot
{{PACKAGE_NAME}}	Java package name	myrobot
{{CREATION_DATE}}	ISO 8601 timestamp	2026-02-02T10:30:00Z
{{WEEVIL_VERSION}}	Weevil version	1.1.0
{{TEMPLATE_NAME}}	Template used	testing

Example:

// File: src/main/java/robot/subsystems/Example.java
// Generated by Weevil {{WEEVIL_VERSION}} on {{CREATION_DATE}}
package robot.{{PACKAGE_NAME}};

Becomes:

// Generated by Weevil 1.1.0 on 2026-02-02T10:30:00Z
package robot.myrobot;

Success Output

✓ Created FTC project 'my-robot' using template 'testing'

Next steps:
  cd my-robot
  weevil test        # Run 45 tests (< 2 seconds)
  weevil build       # Build APK
  weevil deploy      # Deploy to robot

Documentation:
  README.md                    - Project overview
  DESIGN_AND_TEST_PLAN.md     - System architecture
  TESTING_GUIDE.md            - Testing patterns

Implementation Notes

Storage Location:

~/.weevil/templates/
├── basic/
│   ├── template.toml
│   └── files/
└── testing/
    ├── template.toml
    └── files/

Effort Estimate: 2-3 days
Complexity: MEDIUM

---

Part 2: weevil add Command

Overview

Purpose: Add components to existing projects

Version: v1.2.0
Priority: MEDIUM-HIGH

Command Syntax

weevil add <package> [OPTIONS]

OPTIONS:
  --force          Overwrite conflicting files
  --merge          Attempt to merge conflicts (experimental)
  --interactive    Prompt for each conflict
  --dry-run        Preview without adding
  --no-deps        Don't install dependencies
  --dev            Add as dev dependency

Package Naming

Hierarchical structure: scope/category/name/variant

Examples:

nexus/hardware/dc-motor/core
nexus/hardware/dc-motor/mock
nexus/hardware/dc-motor/example
nexus/hardware/dc-motor/complete

nexus/subsystems/wall-approach/complete
nexus/examples/autonomous/simple-auto

team1234/sensors/custom-lidar/core

Components:

• scope: Publisher (nexus, team1234, etc.)
• category: Type (hardware, subsystems, examples, testing)
• name: Component name (dc-motor, wall-approach)
• variant: Implementation (core, mock, example, complete)

Standard Variants

Variant	Contents	Dependencies
core	Interface + FTC wrapper	None
mock	Test double	Requires core
example	Example OpMode	Requires core
complete	All of above	Includes all variants

Usage Examples

# Add complete package
weevil add nexus/hardware/dc-motor

# Add specific variant
weevil add nexus/hardware/dc-motor/core
weevil add nexus/hardware/dc-motor/mock

# Add subsystem (auto-installs dependencies)
weevil add nexus/subsystems/wall-approach/complete

# Preview
weevil add nexus/hardware/servo/core --dry-run

# Force overwrite
weevil add nexus/hardware/gyro/complete --force

# Interactive resolution
weevil add nexus/subsystems/turn-controller/core --interactive

Dependency Resolution

Packages declare dependencies in manifest:

[dependencies]
"nexus/hardware/distance/core" = "^2.0.0"
"nexus/hardware/dc-motor/core" = "^1.0.0"

[dev-dependencies]
"nexus/testing/mock-base" = "^1.0.0"

Automatic Resolution:

weevil add nexus/subsystems/wall-approach/complete

Installing:
  1. nexus/hardware/distance/core (v2.1.0) - dependency
  2. nexus/hardware/dc-motor/core (v1.2.0) - dependency
  3. nexus/subsystems/wall-approach/complete (v1.0.0)

✓ Added 3 packages (15 files)

Conflict Handling

Default (Skip)

⚠ File conflicts detected:
  src/main/java/robot/hardware/MotorController.java (exists)

Resolution: Skipping conflicting files

Added:
  ✓ src/main/java/robot/hardware/FtcMotorController.java

Skipped:
  ⊗ MotorController.java (already exists)

Force Mode

weevil add nexus/hardware/dc-motor/core --force

⚠ Warning: --force will overwrite 2 files
Continue? [y/N]: y

✓ Overwrote 2 files, added 3 files

Interactive Mode

weevil add nexus/hardware/dc-motor/core --interactive

Conflict: MotorController.java

Options:
  [s] Skip (keep your file)
  [o] Overwrite (use package file)
  [d] Show diff
  [a] Abort

Choice [s]: d

Diff:
  --- Existing
  +++ Package
  @@ -5,3 +5,5 @@
   public interface MotorController {
       void setPower(double power);
       double getPower();
  +    void setMode(RunMode mode);
  +    RunMode getMode();
   }

Choice [s]:

Package Categories

hardware/*

Physical hardware abstractions

Subcategories:

• hardware/motors/* - Motor controllers
• hardware/sensors/* - Sensor interfaces
• hardware/servos/* - Servo controllers
• hardware/vision/* - Camera systems
• hardware/imu/* - Gyroscopes

Standard Variants: core, mock, example, complete

subsystems/*

Robot subsystems built on hardware

Examples:

• subsystems/drivetrain/*
• subsystems/arm/*
• subsystems/intake/*

Standard Variants: core, mock, example, complete

examples/*

Complete working examples

Subcategories:

• examples/autonomous/*
• examples/teleop/*
• examples/vision/*

Variants: Usually standalone (no variants)

testing/*

Testing utilities and patterns

Examples:

• testing/mock-hardware - Mock collection
• testing/test-patterns - Reusable patterns
• testing/assertions - Custom assertions

utilities/*

Helper utilities

Examples:

• utilities/math/*
• utilities/telemetry/*
• utilities/logging/*

Package Manifest

Example (package.toml):

[package]
name = "dc-motor"
scope = "nexus"
category = "hardware"
version = "1.2.0"
description = "DC motor controller interface and FTC implementation"
license = "MIT"
authors = ["Nexus Workshops <info@nxgit.dev>"]

[variants]
available = ["core", "mock", "example", "complete"]
default = "complete"

[dependencies]
# Empty for base hardware

[files.core]
include = [
    "src/main/java/robot/hardware/MotorController.java",
    "src/main/java/robot/hardware/FtcMotorController.java"
]

[files.mock]
include = ["src/test/java/robot/hardware/MockMotorController.java"]
dependencies = ["core"]

[files.example]
include = ["src/main/java/robot/opmodes/examples/MotorExample.java"]
dependencies = ["core"]

[files.complete]
dependencies = ["core", "mock", "example"]

Package Repository

Location: https://packages.nxgit.dev

Structure:

packages.nxgit.dev/
├── index.json
├── nexus/
│   ├── hardware/
│   │   ├── dc-motor/
│   │   │   ├── package.toml
│   │   │   ├── core.tar.gz
│   │   │   ├── mock.tar.gz
│   │   │   └── complete.tar.gz
│   │   └── distance/...
│   └── subsystems/...
└── team1234/...

Implementation Notes

Effort Estimate: 2-3 weeks
Complexity: HIGH

Key Components:

1. Package registry (hosted)
2. Dependency resolver
3. Conflict detector
4. File installer
5. Supporting commands (remove, search, list)

---

Supporting Commands

weevil remove

Remove installed package

weevil remove <package> [--prune] [--force]

weevil search

Search package registry

weevil search <query>

Output:
  nexus/hardware/mecanum-drive/complete
    Mecanum drive system with holonomic control
    ★★★★★ (342 downloads)

weevil list

List packages

weevil list --installed        # Show installed
weevil list --available        # Show all available

weevil info

Show package details

weevil info nexus/hardware/dc-motor/complete

Package: nexus/hardware/dc-motor/complete
Version: 1.2.0
Downloads: 1,523
License: MIT

Description:
  DC motor controller with interface, FTC implementation,
  test mocks, and examples.

weevil update

Update packages to latest versions

weevil update                  # Update all
weevil update <package>        # Update specific

---

Strategic Benefits

For Teams

• Faster start - Working code immediately
• Best practices - Learn from examples
• Code reuse - Don't reinvent wheels
• Community - Share solutions

For Nexus Workshops

• Authority - Set FTC code standards
• Network effects - More packages = more value
• Revenue - Workshops teach patterns
• Differentiation - Unique offering

For FTC Community

• Quality - Raised bar across teams
• Collaboration - Build on each other
• Education - Professional patterns
• Innovation - Focus on unique solutions

---

Success Metrics

v1.1.0 (create)

• 50+ teams use testing template in first month
• Positive feedback on quality
• Used in Nexus Workshops curriculum
• Documentation complete

v1.2.0 (add)

• 20+ quality packages at launch
• 100+ downloads first month
• 5+ community packages
• Active ecosystem

---

Implementation Roadmap

Phase 1: v1.1.0 (2-3 days)

weevil create command:

• Template storage system
• Variable substitution
• Basic template
• Testing template
• Git initialization
• Success/error messages
• Documentation
• Tests

Phase 2: v1.2.0 (2-3 weeks)

weevil add command:

• Package registry setup
• Package manifest format
• Dependency resolver
• Conflict detection
• File installation
• Remove command
• Search command
• List command
• 10+ launch packages
• Documentation
• Tests

---

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

---

Package Quality Standards

Required (All Packages):

• ✅ Valid package.toml
• ✅ License specified
• ✅ README included
• ✅ Compiles without errors

Recommended (Verified Badge):

• ✅ Tests included
• ✅ Comprehensive docs
• ✅ Interface-based design
• ✅ No hardcoded values
• ✅ Follows naming conventions

Nexus Verified:

• All required + recommended
• Professional code quality
• Full test coverage
• Maintained and supported

---

Future Enhancements

v1.3.0+

• Package signing (GPG)
• Private registries
• weevil publish command
• Package mirrors
• Offline mode

v2.0.0+

• Binary packages
• Pre-built libraries
• Cloud builds
• Team collaboration features

---

Open Questions

1. Versioning: How handle breaking changes?
2. Testing: Require tests in packages?
3. Licensing: Enforce compliance?
4. Moderation: Who approves packages?
5. Private packages: Support team-private?
6. Namespaces: Use team numbers?
7. Binary support: Allow compiled code?
8. Update notifications: Alert on updates?
9. Code signing: Security/trust model?
10. Monorepo: Where store templates/packages?

---

References

• npm - Node package manager (scopes, registry)
• Cargo - Rust package manager (semver, crates.io)
• FreeBSD Ports - Package system inspiration
• Maven Central - Java repository patterns
• Homebrew - macOS package management

---

Appendix: Complete Examples

Example 1: Creating Project

$ weevil create my-robot --template testing

Creating FTC project 'my-robot'...

✓ Created directory structure
✓ Generated source files (17 files)
✓ Generated test files (4 files)
✓ Created build configuration
✓ Generated documentation (6 files)
✓ Initialized Git repository

Project created successfully!

Next steps:
  cd my-robot
  weevil test              # 45 tests pass in < 2 sec
  weevil build             # Build APK
  weevil deploy --auto     # Deploy to robot

Documentation:
  README.md                     - Overview
  DESIGN_AND_TEST_PLAN.md       - Architecture
  TESTING_GUIDE.md              - How to test

Example 2: Adding Package

$ cd my-robot
$ weevil add nexus/subsystems/mecanum-drive/complete

Resolving dependencies...

Package nexus/subsystems/mecanum-drive/complete requires:
  - nexus/hardware/dc-motor/core (v1.2.0)
  - nexus/hardware/imu/core (v2.0.0)

Installing 3 packages:
  1. nexus/hardware/dc-motor/core (v1.2.0)
  2. nexus/hardware/imu/core (v2.0.0)
  3. nexus/subsystems/mecanum-drive/complete (v2.1.0)

✓ Added 12 source files
✓ Added 8 test files
✓ Updated build.gradle

Package installed successfully!

Next steps:
  See docs/subsystems/MECANUM_DRIVE.md for usage
  Run weevil test to verify integration

Example 3: Handling Conflicts

$ weevil add nexus/hardware/dc-motor/core

⚠ File conflict detected:
  src/main/java/robot/hardware/MotorController.java (exists)

Options:
  1. Skip conflicting files (safe, default)
  2. Overwrite conflicting files (--force)
  3. Interactive resolution (--interactive)
  4. Abort

Choice [1]: 1

Added:
  ✓ src/main/java/robot/hardware/FtcMotorController.java
  ✓ docs/hardware/DC_MOTOR.md

Skipped:
  ⊗ src/main/java/robot/hardware/MotorController.java

Package partially installed (1 file skipped)

Note: Package may not work correctly if required files skipped
Consider using --force or --interactive for complete installation

---

End of Specification

Status: Ready for Implementation
Next Steps:

1. Implement weevil create for v1.1.0-beta.3
2. Use testing showcase as testing template
3. Plan v1.2.0 package system

Contact: eric@intrepidfusion.com
Organization: Nexus Workshops LLC