flame-harness-research

flame-harness-research

Phase 1 of the flutter-flame-harness pipeline. Reads the user's raw idea from config.md, performs market research if needed, proposes 2-3 concrete game concepts, queries the user via AskUserQuestion to pick one, checks it for App Store guideline 4.3 clone risk, then writes the research spec and advances the pipeline state.

All file schemas (config.md, state.md, pipeline-log.md) are defined in docs/harness-protocol.md — refer to that document as the single source of truth. Do not redefine schemas here.

---

Input

Read docs/harness/config.md and extract:

• app_idea — the raw one-line game idea supplied by the user (may be blank if the user invoked the harness without an idea, in which case you will generate ideas from scratch in the Discovery step). When app_idea is blank, the Discovery and "Propose & query" steps run exactly as normal but driven purely by market research and creative reasoning with no seed concept; the resulting proposals are presented via AskUserQuestion for the user to pick — the AI does not select automatically unless auto_idea: true, in which case the "Propose & query" step auto-scores and selects the best concept with no user prompt (see that section).
• skip_research — boolean. If true, treat app_idea as the chosen concept verbatim and skip the Discovery and "Propose & query" steps entirely. Jump directly to Clone avoidance, then Output. Even when skipping discovery you must still write the research spec.
• auto_idea — boolean (default false). When true, the "Propose & query" and "Clone avoidance" steps auto-decide instead of calling AskUserQuestion: the skill scores its own generated concepts, selects the best, and auto-revises any clone — running fully hands-off with no user input. Has no effect when skip_research: true (the idea is already taken verbatim — nothing to select).

If config.md does not exist, abort with: flame-harness-research: docs/harness/config.md not found — run the orchestrator to bootstrap first.

---

Discovery

Skip this section when skip_research: true.

Goal: understand the current mobile game landscape so the proposals are grounded in real market data.

1. Top-charting games

Use WebSearch and/or WebFetch to fetch the current top-grossing and top-free charts for mobile games on Google Play and the App Store. Search queries to use:

• "Google Play" top grossing mobile games 2026 site:sensor tower OR site:appfigures OR site:apptopia
• "App Store" top free games 2026 site:sensor tower OR site:apptopia
• "Flutter Flame" game examples 2026

For each chart, extract at least 10 titles and their genre/mechanic (e.g. idle clicker, hyper-casual runner, match-3, tower defense, merge).

2. Competitor mapping

For the genre most aligned with app_idea (if provided), or the top 2 genres by chart frequency, fetch the store pages of 3-5 representative titles via WebFetch. Record for each:

• Title, genre, core mechanic
• Differentiating feature (what makes it stand out)
• Approximate rating and download tier (if visible on the page)

3. Trend signals

Use WebSearch to look for "hypercasual game trends 2026" and "mobile game genre growth 2026". Extract 2-3 specific trend signals (e.g. "merge mechanics growing 40% YoY", "offline-playable games rising") to inform your proposals.

---

Propose & query

Synthesise your Discovery findings (and app_idea if provided) into exactly 2-3 concrete game concept proposals. Each proposal must include:

Field	Description
Title	Working title
Tagline	One sentence (≤ 15 words) describing the core loop
Core mechanic	What the player does every 10–30 seconds
Differentiator	One thing that makes it distinct from existing top charts
Flame suitability	Why Flutter/Flame is a good fit (≤ 2 sentences)
Monetisation hook	How AdMob ads fit naturally (interstitial / rewarded / banner)

Present the proposals in a numbered list that is easy to read.

Then branch on auto_idea:

If auto_idea: false (default) — ask the user

Use AskUserQuestion to ask the user to pick one or refine:

Which concept would you like to build?
Reply with the number (1, 2, or 3), or describe a variation.
If you are happy with one as-is, just type its number.

Wait for the user's response. If the user types a number, set the chosen concept to that proposal. If the user describes a variation, merge their input with the closest base proposal and confirm the merged concept with a follow-up AskUserQuestion before proceeding:

Got it. I'll build: <merged concept summary>.
Is this correct? (yes / describe further)

Repeat until the user confirms.

If auto_idea: true — auto-score and select (no user input)

Do not call AskUserQuestion. Score each of the 2-3 proposals against these weighted criteria and present a short scoring table:

Criterion	Weight
Market fit	30%
Differentiation / clone-safety	25%
Flame suitability	20%
Monetisation fit	15%
MVP scope feasibility	10%

Score each criterion 0–10, multiply by its weight, and sum to a weighted total per proposal. Render the table (one row per proposal, one column per criterion, plus a Total column), then select the proposal with the highest total as the chosen concept. Print the choice and a one-line rationale, e.g. Auto-selected: <title> (total 8.4/10) — strongest market fit with a clone-safe twist. Then proceed to Clone avoidance. Do not query the user.

---

Clone avoidance

App Store guideline 4.3 prohibits apps that are copies of existing apps ("clone avoidance"). Before writing the spec, verify the chosen concept does not constitute a direct clone.

Check procedure

1. Extract the core mechanic from the chosen concept.

2. Use WebSearch to find the 3 most similar existing mobile games: "<core mechanic>" mobile game App Store 2025 OR 2026

3. For each similar game, note: title, mechanic, distinctive features.

4. Apply the clone test: a concept is a clone if it shares the same mechanic AND the same theme/setting AND offers no original feature. A concept is safe if it has at least one of:

   • A novel mechanic twist (e.g. gravity inversion in a runner)
   • A distinct setting/art direction not present in the top-3 matches
   • A gameplay mode absent from the top-3 matches (e.g. co-op, asynchronous multiplayer)

5. If the concept is a clone, do not proceed. Branch on auto_idea:

   If auto_idea: false (default) — use AskUserQuestion to ask:

   The chosen concept is too similar to <similar app> on the App Store, which may violate
   App Store guideline 4.3 (clone rule).
   Please describe how you want to differentiate it, or pick a different concept.
   

   Then re-run the clone check on the revised concept.

   If auto_idea: true — do not call AskUserQuestion. Auto-revise the concept by applying one differentiator from the "safe" list above (a novel mechanic twist, a distinct setting/art direction, or an absent gameplay mode), then re-run the clone check. Retry up to 2 attempts. If the concept is still a clone after 2 attempts, fall back to the next-highest-scored proposal from Propose & query and run the clone check on it. Record the outcome (which differentiator was applied, or that a fallback was used).

6. Record the clone-check result in the research spec (see Output).

---

Output

1. Write the research spec

Create docs/harness/specs/<YYYY-MM-DD>-research.md (use today's UTC date). Use the following structure:

# Research Spec — <app_name>

## Chosen Concept

**Title:** <working title>
**Tagline:** <one sentence>
**Core mechanic:** <what the player does>
**Differentiator:** <unique hook>
**Flame suitability:** <why Flutter/Flame fits>
**Monetisation hook:** <AdMob integration point>
**Selection:** <user-selected | auto-selected (auto_idea) — with the weighted total if auto-selected>

## Market Rationale

<2-4 sentences summarising the chart/trend data that supports this choice.
Reference the top competitors and the trend signals discovered.>

## Competitor Summary

| Title | Mechanic | Differentiator |
|---|---|---|
| <title> | <mechanic> | <differentiator> |

## Clone-Avoidance Check (App Store 4.3)

**Result:** SAFE / CLONE (resolved)
**Similar apps checked:** <title 1>, <title 2>, <title 3>
**Differentiating features:** <list the features that prevent a 4.3 rejection>

## Skip-Research Note

<!-- If skip_research was true, write: "Discovery skipped — app_idea accepted verbatim." -->
<!-- Otherwise delete this section. -->

2. Update config.md

Set app_idea to the final confirmed concept tagline (overwrite the original raw idea). This ensures downstream skills (plan, design, contract) read the refined concept, not the raw prompt.

Use Edit to make a targeted update — do not rewrite the entire file.

3. Update state.md

Update docs/harness/state.md per the schema in docs/harness-protocol.md §2:

status: running
current_phase: research
next_role: plan
updated_at: "<ISO-8601 UTC now>"

Leave all other keys unchanged. Use Edit for a targeted update.

4. Append to pipeline-log.md

Append one row to docs/harness/pipeline-log.md per the schema in docs/harness-protocol.md §6:

| <ISO-8601 UTC now> | complete | research | <N> competitors analysed; concept: <working title> |

If skip_research was true, use:

| <ISO-8601 UTC now> | complete | research | skip_research=true; concept accepted verbatim |

---

Error handling

• If WebSearch or WebFetch fails during Discovery, log a warning and proceed with whatever data was retrieved. Do not abort — partial market data is better than none.
• If the user declines all proposals and provides no viable alternative after 3 rounds of AskUserQuestion, set state.md to status: paused, pause_reason: manual_action, and write a note to pipeline-log.md explaining that the user could not settle on a concept.
• If docs/harness/specs/ does not exist, create it before writing the spec file.