3.7 KiB
MotorSignal — Agent Development Rules
Project Identity
MotorSignal is a Flutter motorcycle telemetry and ride-analysis application.
Before modifying code, agents MUST inspect the relevant existing architecture and tests and understand the current implementation.
Required Development Workflow
Before making changes:
- Inspect the relevant source files.
- Identify existing services, providers, models, repositories, and tests.
- Do not duplicate existing functionality.
- Make the smallest safe change necessary.
- Preserve existing public interfaces unless the task explicitly requires change.
- Add or update tests for behavioral changes.
- Run static analysis.
- Run the relevant test suite.
- Run the complete test suite before declaring the task complete.
- Report exactly what changed and what verification passed.
Telemetry Freeze Boundary
The following subsystem is FROZEN unless the task explicitly requires modification and the user approves the architectural change:
- TelemetryService
- SensorFusionService
- RideStateMachine
TelemetryService
Authoritative telemetry acquisition runs at 20 Hz / 50 ms.
Do not:
- change acquisition cadence
- introduce competing telemetry clocks
- duplicate sensor acquisition
- bypass the authoritative telemetry pipeline
- introduce UI-driven polling of sensors
All consumers must use the existing telemetry architecture.
SensorFusionService
Sensor fusion is authoritative for derived orientation/lean data.
Do not introduce an independent lean-angle calculation without explicit architectural justification and regression tests.
RideStateMachine
Preserve existing movement/crash/recovery semantics.
The 3.0 MPH moving gate and kickstand isolation behavior are architectural contracts unless explicitly changed by the user.
Database Freeze Boundary
AppDatabase is currently Schema 5.
Do not modify database schema, migrations, event semantics, or persistence behavior casually.
Any schema change MUST include:
- migration
- migration tests
- backward compatibility consideration
- verification against existing ride datasets
Never delete or rewrite historical ride data during feature development.
Forensic / Export Freeze Boundary
FieldTestExportService is authoritative for forensic exports.
Preserve:
- CSV schema
- JSON session schema 1
- GPX export
- timestamp semantics
- event ordering
- sub-second telemetry fidelity
Feature/UI work must not silently alter exported historical data.
State Management
Follow the project's existing Riverpod architecture.
Do not introduce another state-management framework.
Prefer existing providers/services over creating parallel state containers.
UI Development
UI features must consume existing domain/application services.
Do not place telemetry acquisition, persistence, sensor fusion, or business logic directly inside widgets.
Support both portrait and landscape layouts where applicable.
Testing
Every behavioral change requires appropriate automated coverage.
Before completion:
dart analyze lib test
flutter test
A task is NOT considered complete if tests fail, analysis reports new issues, or existing regression datasets change unexpectedly.
Git Safety
Never reset, force-push, rebase, delete branches, delete tags, or rewrite history unless explicitly requested.
Create a checkpoint commit before significant architectural changes.
Do not modify unrelated files.
Agent Behavior
Investigate before modifying.
Prefer surgical patches over broad rewrites.
Do not "fix" unrelated problems discovered during a task.
If an architectural conflict is discovered, stop and report it rather than silently changing a frozen subsystem.