--- name: flame-harness description: Orchestrator — bootstrap a Flutter/Flame game pipeline (idea→playable game) and dispatch each phase skill. Use when starting or continuing a flame-harness run. argument-hint: "[game idea] [--strict] [--rounds N] [--skip-research] [--skip-admob] [--auto-idea] [--auto-deploy] [--resume]" allowed-tools: [Agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill] --- # flame-harness Orchestrator This skill bootstraps and drives the full Flutter/Flame game pipeline from idea to playable game. All file schemas (`config.md`, `state.md`, `contract.md`, log tables) and the phase transition table are defined in `docs/harness-protocol.md` — refer to that document as the single source of truth. Do not redefine schemas here. --- ## Argument Parsing Parse the invocation arguments before doing anything else. | Argument | Config key (in `config.md`) | Default | |---|---|---| | `[game idea]` | `app_idea` | optional — if omitted, research generates & recommends ideas from scratch | | `--strict` | `strict_mode: true` | `false` | | `--rounds N` | `max_rounds: N` | `3` | | `--skip-research` | `skip_research: true` | `false` | | `--skip-admob` | `skip_admob: true` | `false` | | `--auto-idea` | `auto_idea: true` | `false` | | `--auto-deploy` | `auto_deploy: true` | `false` | | `--resume` | (delegates to resume handler; see Resume section) | — | **Guard:** if `--skip-research` is set AND no idea is given, abort immediately with: `flame-harness: --skip-research needs a game idea (nothing to build without research or an idea).` Key-to-file mapping follows the `config.md` schema in `docs/harness-protocol.md` Section 1. - `--strict` → set `strict_mode: true` in `config.md` - `--rounds N` → set `max_rounds: N` in `config.md` - `--skip-research` → set `skip_research: true` in `config.md`. On first run `next_role` is still `research` (NOT `plan`): the research skill honors `skip_research` by skipping market discovery and idea generation, but it still runs the App Store 4.3 clone-avoidance check on the provided idea and writes the research spec — so the clone check is never silently skipped. - `--skip-admob` → set `skip_admob: true` in `config.md` - `--auto-idea` → set `auto_idea: true` in `config.md`. The research skill then auto-scores its generated concepts and selects the best WITHOUT asking the user. No effect with `--skip-research` (which already takes the idea verbatim — nothing to select). - `--auto-deploy` → set `auto_deploy: true` in `config.md`. Skips the post-QA human-review pause: on QA PASS the pipeline continues straight to deploy (admob→build→screenshot→submit) without stopping for the user to play/approve the game. Default `false` — by default the harness PAUSES after QA so the user can check the built game before deploy. (`--auto-idea --auto-deploy` together = fully hands-off idea→deploy.) - `--resume` → skip bootstrap entirely, delegate straight to `flame-harness-resume` (see Resume) --- ## Bootstrap (First Run) Bootstrap runs only when `docs/harness/state.md` does not yet exist. ### 1. Create directory tree ``` docs/harness/ docs/harness/handoff/ docs/harness/feedback/ docs/harness/specs/ docs/harness/plans/ ``` ### 2. Write `docs/harness/config.md` Determine `credentials_dir`: use the `--credentials-dir ` flag if given, else a `credentials/` directory beside the harness, else `~/AndroidStudioProjects/credentials`. **Never hard-code a company, developer name, contact, or signing identity into the schema or skills** — every such value is the *user's own* and must be sourced at runtime. Look for `/store-metadata.md` and read the `developer`, `ios`, and `android` blocks from it. **If that file does not exist** (e.g. a new user who just installed the plugin), do NOT fall back to any placeholder/sample identity — instead **ask the user** for their own values (company, first/last name, support email, contact phone, privacy-policy URL, support/marketing URL, copyright; and — only when a deploy is intended — Apple `team_id`/`asc_key_id`/`asc_issuer_id`/key path and the Android keystore path/alias). Offer to save them to `/store-metadata.md` for reuse. The signing/store-credential answers may be deferred (left blank) until the build/submit phase if the user only wants to generate and play the game now. Then write `docs/harness/config.md` with the full schema from `docs/harness-protocol.md` Section 1. Populate the game-specific keys from the parsed arguments: - `default_language` — the language the user is conversing in: detect it from the user's request/messages (Korean request → `ko`, English request → `en`). If there's no conversational signal yet (e.g. a bare `/flame-harness` with no idea), **fall back to the OS locale** — run `defaults read -g AppleLanguages 2>/dev/null || echo $LANG` and map the first locale (`ko*` → `ko`, otherwise `en`). Only default to `en` if even that is unavailable. The whole pipeline (PRD, copy, l10n primary) is authored in this language. Not fixed to `ko`. - `app_idea` — from the positional argument; if no positional argument was given, write `app_idea: ""` (blank is valid — research will generate and recommend concepts). Do NOT abort on an empty idea. - `app_name` — derive a short display name from the idea (ask the user if ambiguous); if NO idea was given, write `app_name: ""` — the plan phase sets the name after research confirms the concept. - `app_slug` — kebab-case of `app_name`; write `app_slug: ""` if `app_name` is blank. - `bundle_id` — `com..` where `` is `app_slug` with hyphens/underscores removed (bundle-id segments must be `[a-z0-9]+`; hyphens/underscores break signing). Blank if `app_slug` is blank. - `strict_mode`, `max_rounds`, `skip_research`, `skip_admob`, `auto_idea`, `auto_deploy` — from flags (defaults per table above) - `developer`, `ios`, `android` — from `credentials/store-metadata.md` - `credentials_dir` — `/credentials` Do NOT hard-code credential values; always read them from `credentials_dir`. ### 3. Write `docs/harness/state.md` Write `state.md` per the schema in `docs/harness-protocol.md` §2. Initial values: `status: running`, `current_phase: (init)`, `current_round: 1`, `next_role: research` (always `research` on first run — the research skill handles `skip_research` internally, still running the clone check and writing the spec), `pause_reason: ""`, `resume_attempts: 0`, and `created_at`/`updated_at` set to the current ISO-8601 UTC timestamp. ### 4. Append INIT row to `docs/harness/pipeline-log.md` Create `pipeline-log.md` if absent and append: ``` | | start | bootstrap | config.md written | ``` Follow the `pipeline-log.md` schema in `docs/harness-protocol.md` Section 6. --- ## Dispatch Loop After bootstrap (or when resuming without `--resume` flag), enter the dispatch loop. ### Reading `next_role` Read `docs/harness/state.md` and extract `next_role` and `status`. - If `status: completed` — print a completion summary and exit. - If `status: paused` — print the `pause_reason` and any pending manual steps, then instruct the user to run with `--resume`. Do not continue automatically. ### Dispatch For any `next_role` value in the known set, invoke the corresponding phase skill: ``` Skill("flame-harness-") ``` Valid `next_role` values and their skills (per transition table in `docs/harness-protocol.md` Section 7): | next_role | Skill invoked | |---|---| | `research` | `flame-harness-research` | | `plan` | `flame-harness-plan` | | `design` | `flame-harness-design` | | `contract` | `flame-harness-contract` | | `generator` | `flame-harness-generator` | | `evaluator` | `flame-harness-evaluator` | | `admob` | `flame-harness-admob` | | `build` | `flame-harness-build` | | `screenshot` | `flame-harness-screenshot` | | `submit` | `flame-harness-submit` | | `retro` | `flame-harness-retro` | Each phase skill is responsible for updating `state.md` (including setting `next_role` to the next phase) before returning, following the transition rules in `docs/harness-protocol.md` Section 7. After each skill returns, re-read `state.md` and verify that either `updated_at` changed or `next_role` advanced compared to the values before dispatch. If neither changed, abort immediately with: "orchestrator: phase skill `` returned without updating state.md — halting to avoid a redispatch loop." When `status: paused` (e.g. after `submit` sets `pause_reason: manual_action`), print the pending manual steps from `state.md` and instruct the user to complete them, then run with `--resume`. Do not continue automatically. Then repeat the dispatch check. Continue until: - `status: completed` (set by `retro` — print a completion summary and exit) - `status: paused` (print pause_reason and instruct user to run with `--resume`, then exit) --- ## Resume If `--resume` is passed as an argument, first verify that `docs/harness/state.md` exists. If it does not exist, abort with: "Nothing to resume — no state.md found. Run without --resume to start a new pipeline." Otherwise, skip all bootstrap and dispatch logic and delegate immediately to the resume skill: ``` Skill("flame-harness-resume") ``` `flame-harness-resume` is responsible for reading `state.md`, incrementing `resume_attempts`, restoring `status: running`, and re-entering the dispatch loop. Do not attempt to read or modify `state.md` before delegating to the resume skill. --- ## Error Handling - If `docs/harness/config.md` is missing on a non-first run, abort with a clear error message. - If an invoked phase skill exits with an error or sets `status: paused` with `pause_reason: error`, stop the loop and report the failure to the user. - If `next_role` contains a value not in the known set (research, plan, design, contract, generator, evaluator, admob, build, screenshot, submit, retro), abort with an "unknown next_role" error so the user can investigate `state.md`.