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.
./gradlew checkpasses from a clean clone on a machine with no Gradle cache.- CI runs on push and PR; a failing test fails the build.
git ls-filescontains zero.apk, zero keystore, zero file fromwork/.- Dependency graph matches ARCHITECTURE §2 (a script asserts no forbidden edges).
- All four licence files are byte-identical to the upstream texts (checksums committed).
- CI fails on a source file missing its SPDX header, and on a GPL-2.0-only dependency.
scripts/check-docs.shandscripts/hooks/commit-msgare 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 checkhas 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 thenixeryengine.
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.
- Installs via
adb installon a real head unit. - Appears in the HOME chooser and can be set as default.
- After
adb reboot, it is still the default HOME and shows first frame < 1.5 s. - Tapping an app launches it; back returns to FreeAuto.
adb shell dumpsys activity activitiesshows 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.
- Dossier for the NAM5260 filled in and committed, with no TODOs left.
- The OEM radio app and projection app packages are recorded in the dossier.
hal-capturerecords ≥ 60 s of MCU serial traffic and ≥ 60 s of OBD traffic.- Recorded traces replay byte-identically through the replayer.
- 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.
- A PR adding
import android.os.Buildtohal/apifails CI with a clear message. - A PR adding a
.apkfails CI. - 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.
- A test replays a recorded ignition event and asserts
UnitEvent.IgnitionOnis emitted. - Replay is deterministic: two runs produce identical event sequences.
- 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.
- Nudging a margin by 2 dp fails the build with a diff image.
- All four viewports render for the reference screen.
- 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-launcheralready 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.
Lis a smell. - FA-108 is the sneaky one. Vendor ROMs kill background services and revoke
NotificationListenerServicesilently. 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, thequality = Unsupportedpath 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
carpacket 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.