A free/open-source launcher and vehicle-data platform for aftermarket Android head units.
free-auto docs BACKLOG.md
17 kB · 325 lines
Markdown
at main

FreeAuto Backlog #

Status: draft v0.1 · Created 2026-11-01 The queue of work. Every packet here is sized for one agent session and ends in an observable acceptance test. Anything bigger gets split. Phases and exit criteria: ROADMAP.md. Interfaces: ARCHITECTURE.md.


How to read this #

Field Meaning
ID FA-<phase><seq>. Stable. Never renumber.
Size S ≈ half a session · M ≈ one session · L ≈ split it
HW none (unit tests) · emu (emulator) · bench (physical unit) · car (needs driving)
Dep Packets that must merge first

Status board: move a packet to In progress only when an agent has started, and to Done only when the DoD in AGENTS.md §4 is fully ticked.

Order within a phase is risk-first, not value-first (ROADMAP §4, Rule 1).


Phase 0 — Foundations (weeks 1–3) #

ID Packet Size HW Dep Status
FA-001 Repo skeleton, Gradle modules, CI on push M none — partial
FA-002 Design tokens + one reference screen M emu FA-001 todo
FA-003 Walking skeleton: HOME intent, clock, 12 shortcuts, boots M bench FA-001 todo
FA-004 Device bring-up dossier + tools/hal-capture M bench FA-001 todo
FA-005 Agent harness: CI guards, PR template, module READMEs S none FA-001 todo
FA-006 MockHeadUnitBus + trace replay harness M none FA-004, FA-003 todo
FA-007 Screenshot matrix at 4 head-unit viewports in CI M emu FA-002 todo

FA-001 — Repo skeleton and CI #

Intent. A clean clone builds, tests, and fails loudly, in under 10 minutes. Scope in. Gradle monorepo with the module map from ARCHITECTURE §2 (empty but compiling), version catalog, ktlint/detekt, a Tangled workflow in .tangled/workflows/ that calls ./scripts/check.sh, .gitignore covering *.apk, work/, *.keystore. Licence files (LICENSE = GPL-3.0-or-later, LICENSE-APACHE, plus per-module copies in hal/api and plugin/api) vendored verbatim from gnu.org and apache.org with recorded checksums, and an SPDX-header CI check. Scope out. Any feature code. Any dependency beyond Kotlin/Compose/coroutines/test. Acceptance.

  1. ./gradlew check passes from a clean clone on a machine with no Gradle cache.
  2. CI runs on push and PR; a failing test fails the build.
  3. git ls-files contains zero .apk, zero keystore, zero file from work/.
  4. Dependency graph matches ARCHITECTURE §2 (a script asserts no forbidden edges).
  5. All four licence files are byte-identical to the upstream texts (checksums committed).
  6. CI fails on a source file missing its SPDX header, and on a GPL-2.0-only dependency.
  7. scripts/check-docs.sh and scripts/hooks/commit-msg are installed and run in CI; a PR that exceeds a doc budget or commits an AI-attribution trailer fails the build.

Open, and why this is partial.

  • No Gradle wrapper is committed and the dev machine has no Android SDK, so ./gradlew check has never run. Wrapper + toolchain first (README §Toolchain).
  • CI runs the guards only (--no-build). Compiling needs JDK 21 and the Android SDK inside the spindle image; unsolved for the nixery engine.

FA-002 — Design tokens and one reference screen #

Intent. Agents have a visual target. One screen that looks deliberate, not twelve mediocre ones. Scope in. Semantic tokens in core/design (ADR-0005); one reference screen (the home shell) as a static composable; day and night palettes; three presets; the density/mode scale; contrast lint at 4.5:1 / 7:1 and a 64 dp target-size lint. Scope out. Real data, real app list, animation, the theming UI, and the speed-driven mode switch (FA-210). Mode is a rendering parameter here, not a behaviour.

FA-003 — Walking skeleton #

Intent. Prove a sideloaded third-party app can be HOME on a real unit and stay HOME. This is the project's killing risk #1; it gets done in week 2. Scope in. CATEGORY_HOME intent filter, clock, static 12-app grid read from PackageManager (launch only, no grid editing), single Activity, no permissions beyond QUERY_ALL_PACKAGES-avoiding package visibility queries. Scope out. Widgets, media, vehicle data, settings. Acceptance.

  1. Installs via adb install on a real head unit.
  2. Appears in the HOME chooser and can be set as default.
  3. After adb reboot, it is still the default HOME and shows first frame < 1.5 s.
  4. Tapping an app launches it; back returns to FreeAuto.
  5. adb shell dumpsys activity activities shows FreeAuto as the resolved HOME.

FA-004 — Device bring-up dossier and capture tool #

Intent. Everything an agent needs to know about hardware, written down and replayable. Scope in. Fill in docs/device/nakamichi-nam5260.md §3 (SoC, board, DPI, serial nodes, MCU version, OEM radio package). Identify the CarPlay/AA bridge package and whether it claims CATEGORY_HOME / BOOT_COMPLETED (ADR-0003). tools/hal-capture: on-device recorder writing the JSONL trace format from ARCHITECTURE §4, with built-in VIN/GPS scrubbing. Scope out. Decoding any protocol. That's Phase 3. Acceptance.

  1. Dossier for the NAM5260 filled in and committed, with no TODOs left.
  2. The OEM radio app and projection app packages are recorded in the dossier.
  3. hal-capture records ≥ 60 s of MCU serial traffic and ≥ 60 s of OBD traffic.
  4. Recorded traces replay byte-identically through the replayer.
  5. The scrubbing step is unit-tested against a synthetic VIN and GPS string.

FA-005 — Agent harness #

Intent. Make the rules in AGENTS.md mechanical instead of aspirational. Scope in. CI guards: no android.* import in core/model or hal/api; no APK/keystore in git; no work/ path referenced from code; PR template; module README template. Acceptance.

  1. A PR adding import android.os.Build to hal/api fails CI with a clear message.
  2. A PR adding a .apk fails CI.
  3. PR template renders with the four required sections.

FA-006 — Digital twin #

Intent. Let agents develop hardware code with no hardware. Scope in. MockHeadUnitBus and MockVehicleBus driven by the trace files from FA-004; instant-speed and wall-clock-speed replay modes; a Probe API to assert on the parsed signal stream. Acceptance.

  1. A test replays a recorded ignition event and asserts UnitEvent.IgnitionOn is emitted.
  2. Replay is deterministic: two runs produce identical event sequences.
  3. Instant replay of a 60 s trace completes in < 100 ms.

FA-007 — Screenshot matrix #

Intent. Visual regressions caught without a human looking at a phone. Scope in. Roborazzi (or Paparazzi) setup; four viewport configs (800×480, 1024×600, 1280×720, 1920×720); golden images; diff threshold; artefact upload on failure. Acceptance.

  1. Nudging a margin by 2 dp fails the build with a diff image.
  2. All four viewports render for the reference screen.
  3. CI uploads screenshots/diff/ on failure.

Phase 1 — The shell (weeks 4–10) #

Scope discipline for this phase: it is deliberately commodity-grade. femto-car-launcher already ships maps, voice, GPX export and a screenshot-tested dashboard better than this will (PRIOR-ART §2). No packet here should try to beat it. The exit gate is "you'd daily-drive it", not "it matches the competition". Reject any packet that adds maps, voice, video, or a theme gallery.

ID Packet Size HW Dep
FA-101 Constraint-driven layout system (aspect-aware) M emu FA-002, FA-007
FA-102 App grid, dock, favourites, folders, search L→split emu FA-101
FA-103 Media card via NotificationListenerService M emu FA-101
FA-104 Clock + weather widget (Open-Meteo, no key) S emu FA-101
FA-105 Theme engine + day/night by civil twilight M emu FA-002
FA-106 Quick controls: brightness, volume, radios S bench FA-101
FA-107 Settings app + preference backend M emu FA-105
FA-108 Service survival on aggressive vendor ROMs M bench FA-103
FA-109 Projection-bridge coexistence (AA/CarPlay must not be fought) S bench FA-003

Phase exit: daily-driver test — 7 consecutive days, no ANR, no crash-to-home, you don't want to switch back.

Notes that matter:

  • FA-102 must be split into grid+launch, then dock/folders, then search. L is a smell.
  • FA-108 is the sneaky one. Vendor ROMs kill background services and revoke NotificationListenerService silently. Test on the real unit, not the emulator.
  • FA-109 implements ADR-0003. FreeAuto must not auto-relaunch over a projection session, must not steal audio focus, and must offer "launch projection on boot" respecting the OEM's existing behaviour. Acceptance is behavioural: start AA, exit AA, land back in FreeAuto within one tap, with no double-launch race at boot.

Phase 2 — Vehicle data (weeks 8–16) #

ID Packet Size HW Dep
FA-201 VehicleBus API + MockVehicleBus from traces M none FA-006
FA-202 ELM327 transport: Bluetooth SPP M bench FA-201
FA-203 ELM327 transport: USB serial (CDC-ACM) M bench FA-202
FA-204 PID codec + per-vehicle profile discovery L→split bench FA-202
FA-205 Live gauge screen with Quality degradation M emu FA-201
FA-206 Trip computer + Room persistence M emu FA-205
FA-207 DTC read/clear with the caution flow M bench FA-204
FA-208 Export/import CSV+JSON, lossless round-trip M none FA-206
FA-209 GPS/OBD speed fusion + speed-limit alert M car FA-205
FA-210 Speed-driven Parked/Driving mode switch S car FA-209

Phase exit: a real 1-hour drive logs with no gap > 2 s, exports, and re-imports losslessly.

Notes:

  • Phase 2 has a human prerequisite, do it in week 1. Confirm the Viva's OBD protocol and PID bitmask, and whether the Ferio needs a 3-pin adapter (docs/device/perodua-viva-elite-2011.md, R12). If your own cars are the worst case, the quality = Unsupported path stops being an edge case and becomes acceptance criterion #1 for FA-205.
  • FA-202 before FA-203: Bluetooth adapters are what people own.
  • FA-207 needs the confirmation copy reviewed by a human — it's a safety surface, and clearing DTCs resets readiness monitors.
  • FA-209 is the only car packet in the whole backlog so far. It needs you, not an agent.

Phase 3 — Head-unit integration (weeks 14–24) #

ID Packet Size HW Dep
FA-301 HeadUnitBus API, adapter probe/selection, NoHeadUnitBus M none FA-006
FA-302 MTCD/Rockchip adapter (read-only: ignition, illumination, reverse) L→split bench FA-301, FA-004
FA-303 KSW/Qualcomm adapter (read-only) L→split bench FA-301
FA-304 Radio delegation via intent + fallback M bench FA-301
FA-305 Climate read-only display M bench FA-302
FA-306 Steering-wheel key events M bench FA-302
FA-307 Audio focus + ducking M emu FA-103

Phase exit: two MCU families report ignition/reverse/illumination correctly within 500 ms, radio delegation works on both, and units with no MCU access aren't regressed.

Notes:

  • FA-302 and FA-303 are the highest-risk packets in the project. Each needs a community member with that unit to contribute a trace. Design the packets so a trace is all that's required.
  • Split each adapter into: protocol codec (pure, testable, trace-driven) → probe/lifecycle → signal mapping. Three small packets, not one big one.

Phase 4 — Platform (weeks 20–30) #

ID Packet Size HW Dep
FA-401 plugin/api v1 contract + published artifact L→split none FA-301
FA-402 Plugin runtime: discovery, binding, timeout, quarantine L→split emu FA-401
FA-403 Plugin manager UI + permission grants M emu FA-402
FA-404 sample-widget plugin, built and tested in CI M emu FA-402
FA-405 Theme packs as a plugin type M emu FA-402
FA-406 Vehicle profiles: per-car config, shareable file M emu FA-206

Phase exit: an external contributor ships a working widget plugin without asking you how. A crashing plugin is quarantined and the shell survives.


Phase 5 — Distribution (from week 24) #

ID Packet Size HW Dep
FA-501 fdroid product flavour, FOSS-only deps M none FA-107
FA-502 Release automation + signing custody docs M none FA-001
FA-503 Device compatibility database (community-editable) M none FA-004
FA-504 Docs site: install, first-run, troubleshooting M none FA-503
FA-505 i18n via Weblate + lint in CI S none FA-107

Appendix A — Packet template #

Copy this for every new packet.

### FA-### — <title, imperative>
**Intent.** One paragraph. The user-visible outcome and why it matters. No implementation.
**Scope in.** Bullets. Concrete.
**Scope out.** Bullets. What a reasonable agent might wrongly include.
**Design.** Link to spec/ADR, or "none — follows <module> conventions".
**Acceptance.**
1. Observable statement. Maps to `<TestClass.method>`.
2. ...
**HW.** none | emu | bench | car
**Dep.** FA-###, ...
**Agent brief.** 2–4 sentences, prompt-ready, including the failure mode to avoid.

Why each field exists #

  • Intent stops the agent from implementing the literal words instead of the goal.
  • Scope out is the highest-value field. Most agent overreach is a missing "don't".
  • Acceptance must be a statement a test can encode. "Looks good" is not acceptance.
  • HW tells you what you must do yourself, and therefore what your week looks like.
  • Agent brief is what you actually paste into the agent, with context it can't infer.

Appendix B — A fully worked packet #

Real, copyable, and the first one you should hand to an agent after FA-001.

### FA-003 — Walking skeleton: HOME intent and boot survival
**Intent.** Prove that a sideloaded third-party APK can become the default HOME on an
aftermarket head unit and survive a reboot with a fast first frame. This retires the project's
largest feasibility risk before any real feature work begins.

**Scope in.**
- Single `MainActivity` with `CATEGORY_HOME` + `CATEGORY_DEFAULT` intent filter.
- A digital clock and date, updated once per minute.
- A static grid of the 12 most recently used launchable apps, from `PackageManager`.
- Tapping an app launches it; back returns here.
- First frame under 1.5 s cold, no splash, no blank frame.

**Scope out.**
- Grid editing, folders, dock, favourites, search.
- Widgets, media, weather, theming, settings.
- Any vehicle/MCU/OBD code.
- Any permission request.
- Any icon artwork — use the app's own icon via `LauncherApps`, never bundled art.

**Design.** Layout: 4 columns × 3 rows at 1024×600, 8 dp gutters, tokens from FA-002.
No ADR needed.

**Acceptance.**
1. `adb install` succeeds on the bench unit; the app appears in the HOME chooser.
2. After selection as default and `adb reboot`, `dumpsys activity activities` resolves
   `dev.freeauto/.MainActivity` as HOME.
3. Cold start to first frame < 1500 ms, measured by Macrobenchmark, reported in the PR.
4. Clock shows correct local time and updates within 1 s of the minute boundary.
5. Tapping each of the 12 shortcuts launches the target package; back returns to FreeAuto.
6. Screenshot golden at 1024×600 committed.

**HW.** bench
**Dep.** FA-001

**Agent brief.**
Build the HOME activity and app list only — nothing else. The trap here is scope: do not add
grid editing, folder support, or any settings screen. Use `LauncherApps` and
`queryIntentActivities` with `MATCH_ALL`; do not request `QUERY_ALL_PACKAGES` if package
visibility queries suffice. The clock must use `LocalTime` + a `Flow` ticker, not a
`Handler.postDelayed` loop. Attach the Macrobenchmark number and a 1024×600 screenshot to the
PR — without them the packet is not done.

Appendix C — WIP limits #

  • Max 3 packets in progress at once. More than that and review quality collapses.
  • Never two agents in the same module simultaneously.
  • A packet in progress for > 3 sessions is mis-specified. Stop, split it, and rewrite the scope.
  • Keep the backlog ≤ ~40 open packets. Beyond that it's a wish list, not a plan.