/flame-harness-generator

name: flame-harness-generator
description: Phase 5 — build the Flame game in 3 gated sub-phases (core loop → systems+components → UI+content), then self-evaluate against the contract.
argument-hint: ""
allowed-tools: [Agent, Read, Write, Edit, Bash, Glob, Grep]

flame-harness-generator

Phase 5 of the flutter-flame-harness pipeline. Builds the Flame game in three gated sub-phases (5a → 5b → 5c). Each sub-phase ends with a HARD GATE (`flutter analyze` zero issues + `flutter test` all pass) before the next sub-phase begins. On round N > 1, reads the previous evaluator feedback and fixes only the listed failures.

All file schemas (`config.md`, `state.md`, `handoff/round-N-gen.md`, `feedback/round-N-qa.md`) and the phase transition table are defined in `docs/harness-protocol.md` — that document is the single source of truth (§2 for `state.md` schema; §4 for handoff layout; §5 for feedback layout; §7 for the `generator → evaluator` transition). Do not redefine schemas here.

---

Round Handling and Feedback Intake

Determine current round

Read `docs/harness/state.md`. Extract `current_round` (integer, ≥ 1).

Round 1 — build from scratch

When `current_round` is 1:

1. Read `docs/harness/config.md` (extract `app_slug`, `app_name`, `bundle_id`, `default_language`, `skip_admob`). 2. Read the latest PRD (`docs/harness/plans/*-prd.md`, sort descending, take first). 3. Read the latest design doc (`docs/harness/plans/*-design.md`, sort descending, take first). 4. Read `docs/harness/contract.md`. Confirm `## Status: AGREED` is present; abort with `flame-harness-generator: contract not AGREED — run flame-harness-contract first` if missing. 5. Read `checkpoint` from `state.md` (see `docs/harness-protocol.md` §2). **Re-entry:** if a prior run crashed/paused mid-phase, skip every sub-phase `≤ checkpoint` (its HARD GATE already passed and its output exists) and resume at the next one — e.g. `checkpoint: 5a` → start at 5b. If `checkpoint` is `""`, start at 5a. This makes the generator safe to re-run without redoing (or colliding with) completed work.

Round N > 1 — fix only listed failures (feedback intake)

When `current_round` is greater than 1:

1. Read `docs/harness/feedback/round-<N-1>-qa.md` (per `docs/harness-protocol.md` §5 layout). 2. Parse the `## Failed Criteria` section to extract each failing criterion and its prescribed fix. 3. Do NOT redesign or refactor areas that were not listed as failures. Make only the minimum changes required to satisfy the listed fixes. 4. If `docs/harness/feedback/round-<N-1>-qa.md` does not exist, abort with: `flame-harness-generator: feedback file for round <N-1> not found — cannot determine fixes`. 5. Apply each fix, then run the HARD GATE for the affected sub-phase before writing the handoff.

---

Sub-phase 5a — Scaffold + Core Loop

5a.1 Create the Flutter project (flutter create)

Run `flutter create`. The Dart **package name** must be snake_case (lowercase + underscores, no hyphens) — convert `app_slug` (e.g. `swing-line` → `swing_line`). This package name is separate from the bundle id:

GAME=<projects-dir>/<app_slug>
if [ -d "$GAME/lib" ]; then
  echo "project already exists — reusing (skipping flutter create)"
else
  flutter create --org com.<company> --project-name <app_slug_snake_case> "$GAME"
fi

**Idempotency:** `flutter create` fails if the target already exists, which would break a resume or a re-run of round 1. The guard above makes 5a.1 safe to re-enter — it reuses an existing scaffold instead of hard-failing. (If the user passed `--clean`, `rm -rf "$GAME"` first, then create fresh.)

**Bundle id — set it explicitly and IDENTICALLY on both platforms (do not trust the value `flutter create` derives from the project name).** `flutter create` builds the bundle id from `--org` + project-name, which can leave underscores / case differences and can diverge between iOS and Android. Force both to the canonical `config.bundle_id` (`com.<company>.<id>`, lowercase `[a-z0-9]` only — see `docs/harness-protocol.md`):

• iOS: set `PRODUCT_BUNDLE_IDENTIFIER` = `<bundle_id>` in **all three** build configs

(Debug/Release/Profile) in `ios/Runner.xcodeproj/project.pbxproj`.

• Android: set **both** `applicationId` and `namespace` = `<bundle_id>` in `android/app/build.gradle.kts`.
• Verify iOS `PRODUCT_BUNDLE_IDENTIFIER` == Android `applicationId` == `config.bundle_id`,

**byte-for-byte** (same case, no `_`, no `-`). The AdMob app and store records use this exact id.

**Important (per `docs/harness-protocol.md`):** After `flutter create` succeeds, move the `docs/harness/` directory into the game project so all artifacts share one repository:

mv <projects-dir>/flutter-flame-harness/docs/harness \
   <projects-dir>/<app_slug>/docs/harness

All subsequent reads/writes of harness files use the new path inside the game project.

5a.2 Remove default template files

Delete the generated counter demo to start from a clean slate:

rm <projects-dir>/<app_slug>/lib/main.dart
rm <projects-dir>/<app_slug>/test/widget_test.dart

These files will be replaced by the game implementation below.

5a.3 Configure pubspec.yaml

Set the following fields in `pubspec.yaml`:

• `name`: `<app_slug>` (from `config.md`)
• `description`: `<app_name>` (from `config.md`)
• `publish_to: none`
• `version: 1.0.0+1` — explicit semver `MAJOR.MINOR.PATCH+BUILD` (App Store marketing version =

`1.0.0`, not `1.0`; the build phase bumps the `+BUILD` on each upload).

Add to `dependencies` (use the latest compatible versions; minimum versions shown):

dependencies:
  flutter:
    sdk: flutter
  flame: ^1.37.0
  flame_audio: ^2.0.0
  google_mobile_ads: ^5.0.0
  shared_preferences: ^2.0.0
  flutter_secure_storage: ^9.0.0      # durable save: iOS Keychain (survives reinstall/device)
  play_services_block_store: ^0.8.0   # durable save: Android Block Store (survives reinstall/device)

Add to `dev_de