140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
1. Inspect the relevant source files.
|
|
2. Identify existing services, providers, models, repositories, and tests.
|
|
3. Do not duplicate existing functionality.
|
|
4. Make the smallest safe change necessary.
|
|
5. Preserve existing public interfaces unless the task explicitly requires change.
|
|
6. Add or update tests for behavioral changes.
|
|
7. Run static analysis.
|
|
8. Run the relevant test suite.
|
|
9. Run the complete test suite before declaring the task complete.
|
|
10. 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.
|