flutter-flame-harness

flutter-flame-harness

English | 한국어

An autonomous game launch harness for Claude Code, Google Antigravity, and OpenAI Codex that takes a Flutter/Flame game from raw idea all the way to the app stores. The harness orchestrates a structured pipeline of skills — research, planning, design, contract negotiation, and a generator–evaluator build loop — so every stage produces a verified, hand-off-ready artifact before the next one begins.

Supported Environments

Why

AI coding tools usually skip the boring parts — they code before pinning requirements, skip tests, and stop while it's half-done. This harness delegates the process, not just the code: guardrails → plan → a generator↔evaluator build loop with a skeptical QA that runs the game before judging → human review. And it isn't theory — the fixes earned shipping real Flame games (audio pooling, haptics, app-lifecycle, performance, store/build pitfalls) are baked in, so a generated game doesn't re-walk the same traps.

Games

A mix of games I've shipped and games built with this harness — Flutter + Flame.

Portrait

Landscape

Phases

Phase A (complete): research → plan → design → contract → generator ↔ evaluator → playable game

The generator and evaluator negotiate completion criteria before any code is written, then build the Flutter/Flame project in three sub-phases (scaffold → API wiring → UI polish), with the evaluator gating each hand-off.

See docs/SMOKE-TEST.md for the full manual smoke-test procedure.

Phase B (complete): admob, build, screenshot, submit, retro

Automates AdMob integration, release builds (Android + iOS), App Store / Play Store screenshots, submission, and a post-launch retrospective.

See docs/SMOKE-TEST-phaseB.md for the full manual deploy dry-run procedure.

Install

Claude Code

/plugin marketplace add tjdrhs90/flutter-flame-harness
/plugin install flutter-flame-harness@flutter-flame-harness

Google Antigravity & Other Agents

Link the skill into your workspace's .agents/skills/:

mkdir -p .agents/skills
ln -s /path/to/flutter-flame-harness/skills/flame-harness .agents/skills/flame-harness

See docs/agent-compatibility.md for full Antigravity, OpenAI Codex, and generic agent integration details.

Updating

The plugin is copied into a cache at install time, so editing the source doesn't take effect until you re-sync. After pulling new commits (the version bumps each release):

/plugin marketplace update flutter-flame-harness   # re-sync the latest version into the cache
/reload-plugins                                     # apply it in the current session

Confirm the new version in /plugin. If a change doesn't appear, reinstall:

/plugin uninstall flutter-flame-harness@flutter-flame-harness
/plugin install flutter-flame-harness@flutter-flame-harness

(Last resort if the cache is stuck: rm -rf ~/.claude/plugins/cache, then restart Claude Code.)

Usage

/flame-harness "<idea>"
/flame-harness

Run with a quoted idea to seed the pipeline directly. Run with no idea and the AI researches the market, recommends 2-3 game concepts, and waits for you to pick one before proceeding. Add --auto-idea to skip that prompt: no idea + --auto-idea → AI generates, scores, and auto-picks a concept with no prompts (fully hands-off).

Flags:

By default, after the build passes QA the harness pauses for you to play and approve the game (cd <slug> && flutter run) before any deploy work; /flame-harness --resume continues to admob→build→screenshot→submit. --auto-deploy skips this gate, and --auto-idea --auto-deploy together run fully hands-off from idea to deploy.

Phase A Skills

Phase B Skills

File Protocol

See docs/harness-protocol.md for the full inter-skill file handoff protocol.

Security

Credentials and secrets never enter this repository. The .gitignore permanently excludes credentials/, secrets/, *.jks, *.p8, play-store-key.json, and sheets-key.json. Never commit signing keys, API credentials, or service-account files — pass them via environment variables or a secrets manager at runtime.