Read the detailed guide · 中文 README
An AI-native engineering harness for production Flutter and hybrid mobile application repositories.
Flutter AI Harness helps coding agents work inside explicit, testable engineering boundaries. It combines repository-owned project contracts, focused agent roles, task artifacts, review loops, and executable quality gates. It is an engineering system for building applications with AI agents, not an SDK for adding AI features to a Flutter app.
This README is the primary adoption entry and project preview. The detailed guide covers the system model, delivery workflow, security review, reference implementation, adoption paths, and future extensions.
AI Harness is a repository-level engineering system for governing and executing AI-assisted software delivery. The Flutter Demo is its first governed reference implementation, not the Harness itself.
AI Harness
├── Project contract: architecture boundaries, coding rules, security policy
├── Workflows: planning, execution, review, fixes, archival, release checks
├── Task system: task cards, dependencies, executors, acceptance criteria
├── Agent system: architect, executors, routed reviewers, security reviewer
├── Quality gates: static checks, tests, builds, evidence, CI
├── AI tool adapters: Claude Code and Codex
└── Reference technology stacks and adapters
├── Flutter / Dart
├── Android / Kotlin
└── iOS / Swift
The reusable product is the project contract, delivery workflow, agent collaboration model, and executable quality loop. Flutter, Android, and iOS provide the current reference environment used to exercise and verify that system.
Start a coding agent in the project you want to build or improve. Do not clone the Flutter Demo into that project. The Agent uses this repository as reference input, first produces an adoption plan, and changes the target only after you approve the plan.
This repository currently ships native project entries for Claude Code and Codex. Another coding agent can follow the same tool-neutral protocol when it has equivalent filesystem, shell, and instruction-control capabilities.
cd path/to/your-project
# Start Claude Code, Codex, or an equivalent coding agent here.Adapt the AI Harness engineering model from
https://github.com/bladeofgod/flutter-ai-harness.git
to the current directory.
The current directory is the target project. The Harness repository is reference
input only. Keep the target read-only during phase one: do not edit its files,
install dependencies, initialize a project, commit, or push. The only permitted
write is cloning the Harness outside the target into a temporary directory. Do not
execute source-repository scripts. Record the exact source commit and follow
docs/adoption/AGENT_BOOTSTRAP.md.
If this is an existing project, audit its stack, architecture, instructions, tests,
CI, and current changes before proposing an adaptation plan. If the directory is
empty, first discuss the product requirements, targets, constraints, deployment,
team capabilities, and quality expectations with me. Do not select a stack or
initialize the project until I approve those decisions. If the directory is
ambiguous, ask me how it should be treated.
Do not copy the Flutter Demo, business code, archived tasks, reviews, or evidence.
Present the adoption plan, proposed files, verification commands, conflicts, and
unresolved decisions, then stop and wait for my approval.
Review the proposed stack and adaptation plan. When it is correct, continue with:
Implement the approved adoption plan. Keep the target project's confirmed stack
and contract authoritative, adopt only capabilities with real consumers, preserve
existing work, and run the target-specific checks. Report every unverified platform
or unavailable environment. Do not commit or push unless I explicitly ask.
Target directory
├── Existing project -> read-only audit -> adaptation plan -> approval -> implementation
├── Empty directory -> requirements and stack discussion -> initialization plan -> approval -> implementation
└── Ambiguous files -> ask the user and stop
Read the complete Agent adoption protocol, existing-project path, and new-project path. The adopted result belongs to the target repository; this repository does not become its runtime dependency.
- One authoritative project contract with generated Codex-native Skill and Agent adapters.
- Focused workflows for planning, Figma decomposition, implementation, work-routed review, risk-triggered security review, and release checks.
- Repository-owned architecture gates, Git hooks, evidence capture, and CI checks.
- A layered Flutter workspace with explicit package, data, routing, and dependency-injection boundaries.
- First-class Android and iOS host guidance, including contract-first platform channels.
- Optional Figma and Marionette integrations for design context and explicitly scheduled UI verification.
Product input or Figma
-> task cards
-> implementation and focused tests
-> workKinds-routed independent review
-> explicit fixes and re-review
-> archived evidence
Ordinary review follows the task instead of using one general-purpose role:
| Task work | Independent review profile |
|---|---|
| Flutter, Dart Client, Native, Bridge Adapter, integration, quality gates | Code Reviewer |
| Harness commands, agents, validators, fixtures, evidence, adapters | Harness Reviewer |
| Capability/Wire contracts, or standalone documentation and planning | Contract Reviewer |
One task can select multiple profiles in a fixed order. Their findings stay in one aggregated task report, while Security Review remains a separate, conditional dimension. After a repair, only checks and review profiles whose inputs or conclusions changed are rerun.
Running the Demo is optional. Use it to inspect a complete working example of task cards, reviews, evidence, architecture gates, and Flutter/Android/iOS integration. It is not a prerequisite for adopting the Harness.
Prerequisites: Claude Code 2.1.198 or later for the repository's Claude workflows, ripgrep, and either FVM or Flutter 3.41.9.
git clone https://github.com/bladeofgod/flutter-ai-harness.git
cd flutter-ai-harness
make setup
make checkRun the local-fixture Demo:
TOOL_WORKDIR=app/apps/demo bash scripts/flutter-tool.sh runSee the complete reference evaluation path.
Automated development record: The Demo was completed in one overnight run, with no human intervention in implementation during execution. Human input covered design selection, scope decisions, and environment operations.
 |
 |
 |
 |
Android Debug · deterministic local fixtures · four sequential previews · source recording duration: 1m 13s
The Shoppe-inspired Demo includes Welcome, Auth, Shop, Categories, Product Detail, Wishlist, Cart, Checkout, Profile, Settings, Orders, Search, Promotions, Rewards, and Support flows. Its task cards, reviews, implementation evidence, and project documentation were produced through the Harness workflow rather than written as placeholder history.
Design source: Shoppe Community design. Source and license notes are recorded in docs/figma-links.md.
flutter-ai-harness/
├── CLAUDE.md Authoritative project contract
├── .claude/ Commands, agents, skills, and memories
├── .agents/ Generated Codex Skill adapters
├── .codex/ Generated Codex project Agents
├── docs/ Detailed guide, architecture, tasks, and reviews
├── scripts/ Hooks and executable quality gates
└── app/ Flutter workspace and reference Demo
- Agent adoption protocol
- Adopt in an existing project
- Start a new project
- Detailed design and adoption guide
- Authoritative project contract
- Application architecture
- Background article: AI 编程的工程化实践 (Chinese)
The Harness baseline, Demo UI, shared media resources, and Android/iOS Media Capture integration are implemented. The app uses deterministic local business data rather than production services. Android Debug and iOS no-codesign builds are verified; Android emulator/device capture flows and iOS camera, microphone, interruption, and performance acceptance remain manual device checks.
Flutter AI Harness is available under the MIT License.