Feature Development Workflow

This document outlines the standard operating procedure for adding new features to the project. AI agents must follow this pipeline sequentially.

1. Requirement & Planning Phase

• Understand the Goal: Cross-reference requests against the strategic roadmap (research/Expected_features_speed_Assist_Product_Roadmap.md). If a feature violates the core pivot (e.g., adding a heavy map module), flag it.
• Create an Implementation Plan: For any non-trivial change, AI must output an implementation_plan.md detailing:
  • Which layers (data, domain, presentation) will change.
  • What new classes or tests will be created.
• Wait for Approval: Do not write code until the user approves the plan.

2. Execution Phase (AI & Developer Workflow)

When executing a new feature, strict adherence to the following sequence is mandatory. Do not make any assumptions, fail out loud, and ask for clarity.

1. Information Gathering: Clarify requirements and gather any necessary mockups or existing references.
2. Analysis: Analyze the codebase to find where the feature fits cleanly without breaking existing logic.
3. Preview (Diff Style): Propose the exact code changes to the user using a diff style format. Clearly state the class names and functions being modified or created.
4. Approval & Execution: Stop and wait. Do not apply corrections or write the code until explicit approval is given by the user. Once approved, apply the exact changes.
5. Post-Correction Review: After applying the feature, show the resulting code changes using a diff style summary to confirm the exact modifications made.
6. Module Separation (SDK Architecture): Write logic in the appropriate module (:speed-core, :speed-ui, :speed-overlay, :speed-autostart, :speed-bom). Keep :speed-core headless with zero Compose dependencies.

3. Testing Phase (Mandatory)

Every new feature or bug fix MUST be accompanied by unit and/or UI tests.

• Unit Tests: Use JUnit4 / Robolectric, MockK, and kotlinx-coroutines-test.
  • Domain telematics algorithms (TelematicsEngine, SpeedWatcher, SpeedUnit) and repository implementations must have high branch and line coverage (target > 90%).
  • Verification: Run ./gradlew testDebugUnitTest locally to ensure all test suites pass before committing.
• UI Tests: Use Compose Testing rules (createComposeRule) to verify that UI elements render correctly based on specific SpeedData and UiState inputs.
• CI/CD Quality Gates: All commits and Pull Requests are automatically validated by GitHub Actions (.github/workflows/quality-gates.yml).

4. Verification & Documentation

• Run Quality Gates: Before concluding any task or pushing code, run the strict static analysis gates:
  • Run ./gradlew detekt lintDebug
  • Fix any code smells or formatting issues reported by these tools.
• Run the Build: Always verify that the project compiles via ./gradlew assembleDebug.
• Update Docs: If you added or modified public APIs, update the web documentation in docs/ and verify the build with npm run docs:build --prefix docs.
• Walkthrough: Generate a walkthrough.md summarizing what was built, how it was tested, and how to verify the feature.

5. API Stability & Deprecation Policy (B2B SDK Lifecycle)

To ensure long-term stability across dozens of versions and enterprise clients, we enforce a strict backwards-compatibility rule:

• Never abruptly delete public APIs.
• Deprecate First: Mark obsolete functions/classes with the Kotlin @Deprecated annotation. You must include a descriptive message explaining why it is deprecated and provide a replaceWith parameter so the client's IDE can automatically auto-correct their code.
• 2-Major-Version Rule: A deprecated API must be fully supported under the hood for exactly 2 major versions. (e.g., An API deprecated in v3.1.0 can only be deleted in v5.0.0).
• Update Migration Guides: Any breaking changes or deprecations MUST be documented in docs/guide/migration-guides.md.