Flutter AI Harness: A Repo Template That Gives AI Coding Tools a Readable Engineering Contract
Most AI coding workflows still rely on chat-window context that evaporates between sessions. This template turns architectural rules, task scope, and verification steps into committed files that multiple AI tools read from a single source of truth, cutting the re-explanation tax and making AI-generated changes auditable in CI.
AI coding tools generate code quickly but lose coherence when modifications span modules or require iteration. Flutter AI Harness addresses this by making engineering rules a first-class repository artifact: a project contract defines invariants, Commands and Agents describe workflows, and task cards scope each change. A four-layer structure separates stable rules from per-task knowledge, preventing context bloat and configuration drift when multiple AI tools share the same codebase.
The template includes a local e-commerce Demo built with Flutter Pub Workspace and Melos, enforcing strict dependency direction and data-type boundaries. Quality gates are not advisory; Git hooks, static analysis, dependency matrix checks, and CI stages execute them deterministically. UI automation via Marionette runs independently of ordinary tasks, so device-dependent checks never block daily development.
Adoption follows two paths: run the Demo to evaluate the full feedback loop, or let AI read the Harness design and adapt its principles to an existing project. The second path preserves the contract, closed-loop delivery, and verifiable evidence while allowing teams to swap out directories, state management, and platform integrations.
Separating task artifacts from long-term Memory prevents the knowledge base from bloating into a second project document that nobody maintains.
Making Reviews read-only and requiring explicit re-review after fixes creates an audit trail that distinguishes what was found from what was actually changed, a distinction most AI-coding workflows lack.
The template deliberately avoids pre-installing Dio, Proto, or Drift until a real consumer exists, treating the control of invalid abstractions as equally important as establishing layering.
Requiring positive and negative Fixtures for every quality gate before it is worth maintaining prevents the gate system from becoming process overhead that teams learn to bypass.