@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/game-design/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: game-design
+description: "Use when designing or repairing what makes a game fun — verbs and mechanics, moment-to-moment/session/meta loops, progression, economy faucets and sinks, difficulty curves, dominant strategies, juice, prototyping and scope. NOT engine code (that is `godot`), NOT story (that is `game-storytelling`), NOT level layout (that is `level-design`)."
+tags: [game-design, mechanics, core-loop, balancing, progression, playtesting, scope, fun]
+recommends: [level-design, game-storytelling, godot, unity, unreal]
+profiles: [full]
+origin: ai-hub
+---
+
+# Design games that are fun on purpose
+
+Engine-agnostic game design: mechanics, loops, progression, economy, balance, feel, and the discipline of prototyping and scope. No engine APIs live here — when the design is settled, the implementation belongs to [`godot`](../godot/SKILL.md), [`unity`](../unity/SKILL.md), or [`unreal`](../unreal/SKILL.md).
+
+Two premises govern everything below. **Fun is discovered, not designed** — you cannot reason your way to a fun game on paper, you find it by building the smallest playable version and playing it, so every hour spent planning a mechanic you have not prototyped is an hour spent guessing. And **a game is the set of verbs it gives the player plus the loops those verbs live in** — art, story, and levels dress that skeleton; if the skeleton is not fun in greybox, nothing dresses it into fun.
+
+Route elsewhere when the ask is not design:
+
+| The ask | Route to | Why not here |
+| --- | --- | --- |
+| Write the movement/AI/shader/save code | [`godot`](../godot/SKILL.md) / [`unity`](../unity/SKILL.md) / [`unreal`](../unreal/SKILL.md) | This skill decides *what* to build; the engine skill builds it. |
+| Author the story, dialogue, characters, lore | [`game-storytelling`](../game-storytelling/SKILL.md) | Narrative design is its own craft; this skill owns systems and verbs. |
+| Lay out a level, encounter, or world map | [`level-design`](../level-design/SKILL.md) | Spatial/encounter design applies the mechanics this skill defines. |
+| Netcode, prediction, lag compensation | [`gamedev-multiplayer`](../gamedev-multiplayer/SKILL.md) | A technical domain, not core design intent. |
+| Ship / store page / build pipeline | [`gamedev-shipping`](../gamedev-shipping/SKILL.md) | Release logistics, not design. |
+
+## Loops: moment-to-moment → session → meta
+
+A game is loops nested inside loops. Each layer must reward on its own **and** feed motivation to the layer above it.
+
+```text
+moment-to-moment  (seconds)   the primary verb: aim+fire, jump, place, click, parry
+        │  feeds
+session loop      (minutes)   a run / match / mission: setup → tension → resolution
+        │  feeds
+meta loop         (sessions)  mastery, unlocks, collection, rank — why you return tomorrow
+```
+
+- **Moment-to-moment first.** The thing the player does constantly must feel good with *no* goal attached — jumping in Mario is fun in an empty room. If this layer is flat, no progression system rescues it. (Bungie's "30 seconds of fun" rule: perfect the small loop, then repeat it.)
+- **Session loop** gives a run shape — a beginning, a rising middle, a payoff. It should end on a hook (almost-had-it, one-more-run).
+- **Meta loop** is the reason-to-return: it spends the currency and mastery earned in sessions on lasting change (new verbs, new options, status).
+- **Reward funding.** A reward at one layer should fund desire at the next. Misfunded loops fail predictably: fun moment-to-moment + empty meta = "great but I bounced"; rich meta + flat moment-to-moment = "I grind and I don't know why."
+
+Depth vs breadth of loops, feedback-loop math, and worked loop teardowns: **[references/mechanics-and-loops.md](references/mechanics-and-loops.md)**.
+
+## MDA: the working lens
+
+Mechanics → Dynamics → Aesthetics. The designer authors **Mechanics** (rules, entities, numbers). At runtime those produce **Dynamics** (emergent behavior as players interact). Players only ever feel the **Aesthetics** (the emotional response). You design left-to-right; the player experiences right-to-left — so you must reason backward from the feeling you want to the rule that causes it.
+
+- **"Fun" is not a design target — name the aesthetic.** MDA's vocabulary: sensation, fantasy, narrative, challenge, fellowship, discovery, expression, submission (relaxation). "Make it more fun" is unactionable; "raise the *challenge* and *discovery*, drop the *submission*" is a to-do list.
+- **Design the verbs, not the features.** The verb set *is* the game. A tight set of verbs with deep interaction (chess, Tetris) beats a wide set of shallow ones. Before adding a feature, ask: does it add a verb, deepen an existing verb, or just add a number?
+- **Second-order design.** Ask what the rule makes players *do*, not what it literally says. Every incentive is also a de-incentive for everything else — rewarding kills steals attention from exploring.
+
+The eight aesthetics with examples, emergence vs scripted content, and interaction-depth heuristics: **[references/mechanics-and-loops.md](references/mechanics-and-loops.md)**.
+
+## Progression & economy
+
+Progression controls the rate at which the game reveals its depth; economy is the currency plumbing underneath it.
+
+- **Pacing.** Interleave tension and release; teach → test → twist. Run difficulty and novelty as two curves so a lull in one is covered by the other.
+- **Unlocks earn their keep.** Each unlock should add a verb or a *meaningful choice*, not just +10%. Gate content to pace the complexity the player must hold at once.
+- **Currencies need distinct jobs.** Soft (earned, spent freely) vs hard/premium (scarce). Never add a currency without a distinct **sink** it exists to feed — currencies without sinks are clutter.
+- **Sinks and faucets.** Faucets create currency; sinks destroy it. Balance the two or the economy drifts.
+
+Model the drift with the core identity — no engine needed, a spreadsheet does it:
+
+```text
+net_income_rate = faucet_rate − sink_rate
+time_to_afford  = cost / net_income_rate          # tune this against desired pacing
+cost(n)         = base × growth^n                 # escalating sink; growth ≈ 1.07–1.15
+```
+
+- **Avoiding runaway.** If `net_income_rate` rises over time, costs must rise at least as fast or currency becomes meaningless (hyperinflation, trivialized late game). Fixes: escalating/exponential sinks, consumable sinks, caps, prestige resets.
+- **Kill snowballs.** Positive feedback loops (rich-get-richer) let a leader accelerate out of reach and end matches early. Counter with negative feedback / catch-up (rubber-banding, comeback mechanics, escalating cost of dominance) — tuned so it aids without feeling like punishment for winning.
+
+Currency taxonomies, inflation math, prestige/reset design, and a balancing-spreadsheet layout: **[references/progression-and-economy.md](references/progression-and-economy.md)**.
+
+## Difficulty & balancing
+
+- **The curve is a sawtooth, not a ramp.** Rising baseline with peaks (bosses, gauntlets) and valleys (recovery, reward). Aim for the *flow channel*: challenge tracking skill, between boredom (too easy) and anxiety (too hard).
+- **Few high-leverage knobs.** Most balance lives in a handful of variables (damage, health, spawn rate, cost, cooldown). Identify them, tune **one at a time**, and never chase a symptom by touching five knobs at once.
+- **Data-driven balance.** Externalize tunables into data (tables/config), not hard-coded constants, so designers iterate without a rebuild and you can diff and A/B numbers. (The engine skill wires the loader; this skill decides *which* numbers are tunable.)
+- **Dominant strategies kill choice.** When one option strictly beats the rest, all other choices die. Hunt them in playtest data and telemetry; fix by nerfing the outlier or buffing counters toward **intransitive** balance (rock-paper-scissors: every option beaten by another).
+- **Perceived ≠ actual difficulty**, and difficulty options/accessibility widen the audience — decouple challenge from exclusion.
+
+Flow-channel tuning, dominant-strategy detection, symmetry vs asymmetry, and difficulty-option patterns: **[references/progression-and-economy.md](references/progression-and-economy.md)**.
+
+## Feel / "juice" (as design intent)
+
+Game feel is the tactile sensation of control — the moment-to-moment made physical. It is a **design** concern here; the engine skills implement the effects.
+
+- **Every input needs an immediate, legible reaction** — visual, audio, and/or haptic. Perceived latency is the enemy; responsiveness beats fidelity.
+- **Juice vocabulary** (specify the intent, let the engine do it): hit-stop / hit-pause (freeze a few frames on impact to sell weight), screenshake (scaled to significance, never gratuitous), anticipation & follow-through and squash-and-stretch (animation principles that read intent), particles, easing/tweening curves, and layered sound.
+- **Feel is often hidden generosity.** Coyote time, input buffering, and forgiveness windows make a game feel *fair* and responsive without the player ever knowing why.
+- **Design-level, not code-level here.** Decide *what* should feel weighty and *why*; specify the effect and its trigger. The keyframes, curves, and shaders belong to `godot` / `unity` / `unreal`.
+
+## Prototyping & playtesting
+
+- **Prototype the riskiest assumption first.** Whatever most determines whether the game works — prove or kill it before building anything else.
+- **Paper → greybox → vertical slice.** Test rules and economies on paper/cards; test mechanics in an untextured blockout; only then build a polished slice. Find the fun before you buy the art.
+- **Watch, don't coach.** In a playtest, shut up and observe. Note confusion, boredom, and quit points. The first-time experience is gold and you get it exactly once per tester.
+- **Behavior over opinion.** Players are unreliable at saying *what* is wrong but reliable at signaling *that* something is. Weight what they do over what they say. Measure both: qualitative (struggle/quit points, think-aloud) and quantitative (completion rate, time-per-section, death heatmaps, D1/D7 retention).
+- **Kill your darlings.** Cut any mechanic that does not serve the core loop, however clever. A pile of clever unrelated mechanics is not a game.
+- **Scope is the #1 reason indie games die** — not talent, not tools. Cut *features*, not *quality*. A finished small game beats an unfinished ambitious one. Define the "one thing" the game is about and protect it ruthlessly; build a vertical slice, not a broad shallow map of half-features.
+
+Playtest protocols, metrics/retention definitions, the prototyping ladder, and concrete scope-cutting tactics: **[references/playtesting-and-scope.md](references/playtesting-and-scope.md)**.
+
+## Documenting design
+
+- **One page that lives beats a 100-page bible that dies.** Nobody reads the bible; it is stale the day after it is written. Write a living one-pager and let it grow only where a real decision needs recording.
+- **The one-pager holds:** the hook / fantasy, the core loop, the verb set, the target aesthetic (named MDA emotion), the MVP scope, and — explicitly — what is *out*.
+- **Design pillars** (2–4 words each, e.g. "tense stealth", "readable chaos") are decision filters: every feature must serve a pillar or it is cut. Pillars end arguments faster than any spec.
+- **Keep it a communication tool, not an archive.** A wiki page beats a locked document; version it, link it, prune it.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Designing on paper for months before building | Fun is only found by playing | Prototype the riskiest assumption first |
+| "Make it more fun" as a task | Unactionable | Name the target MDA aesthetic and the mechanic behind it |
+| Adding features instead of deepening verbs | Wide-and-shallow, no mastery | Deepen verb interaction before adding verbs |
+| Currency with no sink | Meaningless clutter, inflation | Give every currency a distinct sink or cut it |
+| Faucets outpacing sinks | Hyperinflation, trivial late game | Escalating/consumable sinks, caps, prestige |
+| Unchecked positive feedback loop | Leader snowballs, match ends early | Add negative feedback / catch-up, tuned gently |
+| One dominant strategy left standing | Choice dies, meta collapses | Nerf outlier / buff counters toward intransitive balance |
+| Tuning five knobs at once | Can't attribute cause | Change one high-leverage variable at a time |
+| Hard-coded balance constants | No iteration, no A/B, needs rebuild | Externalize tunables into data |
+| Guiding testers during playtests | Contaminates the first-time signal | Watch silently; weight behavior over opinion |
+| Scope creep / feature list as ambition | #1 indie killer | Cut features not quality; ship a vertical slice |
+| 100-page design bible | Nobody reads it; goes stale | Living one-pager + pillars |
+
+## Project grounding
+
+If the workspace has a `02-DOCS/` harness, record the design in `02-DOCS/wiki/design/` — a `game-design.md` one-pager (hook, core loop, verbs, pillars, MVP scope, what's out) plus an `economy.md` if there is a currency system. Write each as an OKF v0.1 wiki article per the harness [`wiki-article-template.md`](../harness/references/wiki-article-template.md): YAML frontmatter with a non-empty `type:` (use `type: design`), a `timestamp` in ISO 8601, and standard markdown links — never wikilinks. Index it in `02-DOCS/wiki/index.md`. This is **recorded, not gated** — skip silently if there is no harness.
+
+## Checklist
+
+- [ ] The **core verb** is named and is fun in greybox with no goal attached.
+- [ ] The three loops (moment-to-moment / session / meta) are identified and each is reward-funded by the layer below.
+- [ ] The target **aesthetic** is named (MDA vocabulary), not "fun".
+- [ ] Every currency has a distinct sink; faucets vs sinks are modeled and do not run away.
+- [ ] Difficulty follows a sawtooth in the flow channel; high-leverage knobs are identified and data-driven.
+- [ ] No dominant strategy survives; options are intransitively balanced.
+- [ ] Feel/juice intent is specified (what + why), deferred to the engine skill for how.
+- [ ] The riskiest assumption was prototyped and playtested; behavior (not just opinion) was observed.
+- [ ] Scope is cut to a vertical slice; a one-page living doc + pillars exist, not a bible.
+- [ ] Engine specifics were deferred to `godot`/`unity`/`unreal`; narrative to `game-storytelling`; layout to `level-design`.

package/skills/shared/game-design/evals/README.md

@@ -0,0 +1,13 @@
+# Evals for game-design
+
+`cases.yaml` is the trigger and capability spec for this skill, read by the catalog's
+skill-eval harness. `should_trigger` asserts the skill fires on design-intent asks — core
+loops, economy/inflation, balance, difficulty curves, feel, scope, and the vague "why isn't my
+game fun" — including a Spanish phrasing. `should_not_trigger` asserts near-misses route to the
+right sibling: engine code to `unity`/`godot`/`unreal`, story to `game-storytelling`, layout to
+`level-design`, netcode to `gamedev-multiplayer`, release to `gamedev-shipping`.
+
+The `capability` case checks that an economy/loop-repair answer stays engine-agnostic: it
+diagnoses loop funding, models faucets vs sinks with the pseudo-formula, stops runaway inflation
+with escalating sinks/prestige, names the MDA aesthetic, and defers implementation to the engine
+skills.

package/skills/shared/game-design/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: game-design
+
+should_trigger:
+  - prompt: "I've been building my game for months and it just isn't fun to play. What's wrong?"
+    why: "The signature 'why isn't my game fun' trigger; answer diagnoses which loop is starved and pushes prototype-the-core-verb-in-greybox."
+  - prompt: "Help me design the core gameplay loop for a roguelike deckbuilder."
+    why: "Core-loop design plus moment-to-moment → session → meta layering is the central job."
+  - prompt: "My in-game gold keeps inflating so late-game upgrades feel free. How do I fix the economy?"
+    why: "Economy/faucets-vs-sinks and runaway-inflation fixes (escalating sinks, caps, prestige); the pseudo-formula applies."
+  - prompt: "Everyone in my card game just plays the same one deck because it beats everything. How do I rebalance?"
+    why: "Dominant-strategy detection and pushing toward intransitive (rock-paper-scissors) balance."
+  - prompt: "The difficulty in my platformer spikes weirdly — some levels are trivial, then a wall. How should the curve work?"
+    why: "Difficulty curve as a sawtooth in the flow channel, high-leverage knobs, one-at-a-time tuning."
+  - prompt: "I keep adding features and never finishing. How do I decide what to cut?"
+    why: "Scope control (the #1 indie killer): cut features not quality, define the one thing, vertical slice, cut list, kill your darlings."
+  - prompt: "El juego no engancha después de la primera partida, ¿cómo lo arreglo?"
+    why: "Spanish — starved meta loop / return-reason; diagnoses reward funding across loop layers."
+  - prompt: "How do I make combat feel punchier and more satisfying without touching the story or the netcode?"
+    why: "Game feel / juice as design intent (hit-stop, screenshake, feedback); explicitly excludes story and netcode."
+
+should_not_trigger:
+  - prompt: "Write the C# script that moves my player character and handles jumping in Unity."
+    route_to: unity
+    why: "Engine implementation code; this skill decides what to build, the engine skill writes it."
+  - prompt: "Write the dialogue tree and backstory for my game's main antagonist."
+    route_to: game-storytelling
+    why: "Narrative and character writing, not systems/mechanics design."
+  - prompt: "Lay out the rooms and enemy placement for level 3 of my metroidvania."
+    route_to: level-design
+    why: "Spatial and encounter layout applies mechanics; it is not core mechanic/economy design."
+  - prompt: "Implement client-side prediction and lag compensation for my multiplayer shooter."
+    route_to: gamedev-multiplayer
+    why: "Netcode is a technical domain, not moment-to-moment or economy design intent."
+  - prompt: "Set up my Steam store page and build the release pipeline for launch."
+    route_to: gamedev-shipping
+    why: "Release logistics, not design."
+
+capability:
+  - scenario: "A solo dev's incremental/idle game feels grindy and the currency inflates until upgrades are free; they ask how to fix the design."
+    must_include:
+      - "Diagnoses which loop is starved (moment-to-moment / session / meta) and checks that each layer's reward funds the next"
+      - "Models the economy with net_income_rate = faucet_rate − sink_rate and time_to_afford = cost / net_income_rate"
+      - "Prescribes escalating/exponential sinks (cost(n) = base × growth^n), consumable sinks, caps, or prestige resets to stop runaway inflation"
+      - "Requires each currency to have a distinct sink, and tunables to be data-driven rather than hard-coded"
+      - "Names the target MDA aesthetic instead of 'more fun', and frames unlocks as new verbs/choices not just +N%"
+      - "Recommends prototyping the fix and playtesting for behavior (retention, time-per-tier), not just opinion"
+      - "Defers engine implementation to godot/unity/unreal and records the design in docs/design/ only if a harness exists"

package/skills/shared/game-design/references/mechanics-and-loops.md

@@ -0,0 +1,78 @@
+# Mechanics, verbs, loops, and feel — deep dive
+
+Engine-agnostic. This expands the SKILL.md sections on loops, MDA, verbs, and feel. No engine APIs — when a pattern needs code, it belongs to `godot` / `unity` / `unreal`.
+
+## MDA in practice
+
+Mechanics → Dynamics → Aesthetics is a lens, not a pipeline you fill in once.
+
+- **Mechanics** — the rules, entities, and numbers you literally author: gravity value, damage table, spawn rules, win condition.
+- **Dynamics** — the runtime behavior that emerges when players push on the mechanics: kiting, rushing, turtling, economy hoarding. You do not write dynamics; you *provoke* them with mechanics.
+- **Aesthetics** — the emotional response the player actually has. This is the only layer they experience directly.
+
+You author left-to-right but must **reason right-to-left**: start from the feeling you want, hypothesize a dynamic that would produce it, then author the mechanic that produces that dynamic. Playtest to see whether the real dynamic matches the intended one — it usually doesn't the first time.
+
+### The eight aesthetics (name the one you want)
+
+| Aesthetic | The feeling | Example games |
+| --- | --- | --- |
+| Sensation | Sense-pleasure, "game as toy" | *Tetris*, rhythm games, *Katamari* |
+| Fantasy | Make-believe, inhabiting a role | *Skyrim*, flight sims |
+| Narrative | Drama unfolding | *Disco Elysium*, *The Last of Us* |
+| Challenge | Obstacle course, mastery | *Celeste*, *Dark Souls*, *Trackmania* |
+| Fellowship | Social framework, cooperation | *It Takes Two*, MMOs, *Among Us* |
+| Discovery | Exploring the unknown | *Outer Wilds*, *Subnautica* |
+| Expression | Self-discovery, creation | *Minecraft*, *The Sims*, *Animal Crossing* |
+| Submission | Pastime, relaxation, "flow-off" | idle games, *Stardew Valley* farming |
+
+Most games target **two or three**, weighted. Writing them down settles arguments: a feature that serves none of your chosen aesthetics is a cut candidate, however cool.
+
+## Verbs are the game
+
+The player's verb set — the actions available — is the truest description of a design. "A game about jumping and stomping" (Mario) says more than any feature list.
+
+- **Depth over breadth.** A few verbs that interact combinatorially (chess: six piece-moves) yield more game than dozens of isolated ones. Interaction between verbs is where mastery and emergence live.
+- **Verb economy test.** Before adding anything, ask: does this add a *new verb*, *deepen an existing verb's interactions*, or merely *add a number*? Numbers rarely add game.
+- **Emergence vs progression** (Juul's distinction):
+  - *Emergent* games — simple rules, vast possibility space (chess, poker, *Spelunky*, roguelikes). Cheap to build, huge replay, hard to control the experience.
+  - *Progression* games — designer places a sequence of challenges (linear campaigns). Total authorial control, expensive per minute of play, low replay.
+  - Most games blend: an emergent core loop inside a progression frame.
+
+## Loop layering, in detail
+
+```text
+INPUT ─▶ [ moment-to-moment verb ] ─▶ immediate feedback ─▶ (repeat, seconds)
+                                            │ accrues into
+                          [ session goal / run ] ─▶ session payoff ─▶ (minutes–1h)
+                                            │ funds
+                          [ meta progression ] ─▶ lasting change ─▶ (across sessions)
+```
+
+- **Moment-to-moment must be intrinsically fun.** Test: strip every goal, reward, and score — is the raw act of doing the verb still satisfying? If not, fix this before anything else. This is Bungie's "30 seconds of fun" — perfect the small loop, and the game is that loop repeated in varied contexts.
+- **Session loop needs a shape.** Setup → rising tension → climax → resolution → hook. A run that just stops has no payoff; a run that ends on "so close" pulls the next one.
+- **Meta loop is the return reason.** It converts session output (currency, XP, mastery, unlocks) into durable change. If the meta gives only numeric inflation and no new *choices or verbs*, players feel the grind without the growth.
+- **Reward funding is the health check.** Each layer's reward should create desire for the next layer. Diagnose a "not fun" game by asking which loop is starved:
+  - Flat moment-to-moment → nothing above can save it.
+  - Empty meta → "great for an hour, then I bounced."
+  - Meta with no moment-to-moment joy → "I grind and don't know why."
+
+## Feedback loops (system dynamics)
+
+Distinct from "player feedback." These are the amplifying/damping loops in your systems.
+
+- **Positive feedback loop** — success makes further success easier (rich-get-richer). Accelerates games to a conclusion and rewards early leads. Good for *ending* a game; dangerous if unchecked mid-game (snowball, runaway leader, blowouts).
+- **Negative feedback loop** — success makes further success harder, or trailing players get help (catch-up, rubber-banding, escalating cost of dominance, *Mario Kart* items). Keeps games close and tense; overdone it punishes skill and feels unfair.
+- **Design move:** use negative feedback to keep the mid-game close and positive feedback to force a decisive end — so games stay tense but still *end*.
+
+## Game feel / juice as design intent
+
+Feel is the moment-to-moment made tactile. Decide it here; the engine implements it.
+
+- **Responsiveness first.** Immediate, legible reaction to every input beats visual fidelity. Perceived input latency destroys feel.
+- **Juice vocabulary** — specify the *intent* and *trigger*, not the code:
+  - *Hit-stop / hit-pause* — freeze a few frames on impact to sell weight.
+  - *Screenshake* — amplitude scaled to significance; gratuitous shake reads as noise.
+  - *Anticipation & follow-through*, *squash-and-stretch* — animation principles that telegraph intent and add weight.
+  - *Particles, easing/tweening curves, layered SFX* — reinforce the action's magnitude.
+- **Hidden generosity.** Coyote time (jump slightly after leaving a ledge), input buffering (queue an input landing a hair early), and forgiveness windows make a game feel *fair* and responsive without the player knowing why. These are design decisions with real numbers (frames/ms) — specify them; the engine skill wires them.
+- **Boundary:** keyframes, curves, shader passes, and timing code are engine work. Here you produce a table of "action → intended feel → effect → trigger."

package/skills/shared/game-design/references/playtesting-and-scope.md

@@ -0,0 +1,58 @@
+# Prototyping, playtesting, scope, and docs — deep dive
+
+Engine-agnostic. Expands the SKILL.md sections on prototyping, playtesting, scope, and documenting design.
+
+## The prototyping ladder
+
+Climb only as far as each rung earns. Each rung is cheaper to change than the next.
+
+1. **Riskiest-assumption first.** Name the single thing that, if it doesn't work, sinks the game (Is the core verb fun? Does the economy hold? Is the twist readable?). Prototype *that*, not the easy parts.
+2. **Paper / cards.** Best for rules, turn order, economies, and card/board interactions. Simulate the loop by hand; you can rebalance in seconds with a pencil.
+3. **Greybox / blockout.** Untextured, programmer-art mechanics running in the engine. Proves *feel* and moment-to-moment fun. If it isn't fun in greybox, art will not make it fun — this is the single most expensive lesson to learn late.
+4. **Vertical slice.** One polished, representative sliver — one level or one loop at final quality — proving the game is worth finishing and showing what "done" looks like. Prefer this over a broad, shallow map of half-built features.
+
+**Find the fun before you buy the art.** Art and audio are the most expensive assets and the hardest to change; commit them only after the mechanic underneath is proven.
+
+## Playtesting
+
+- **Watch, don't coach.** Say as little as possible. The instant you explain a control, you have destroyed the first-time-user signal you can never recapture from that tester.
+- **Behavior over opinion.** Players are unreliable at diagnosing *what* is wrong and reliable at signaling *that* something is. When a tester says "the jump is fine" but dies to the same gap ten times, believe the deaths. Weight actions over words.
+- **Protocols:**
+  - *Think-aloud* — tester narrates their thoughts live; surfaces confusion and mental model mismatches.
+  - *First-time-user (FTUE)* — a fresh tester with zero explanation; the harshest and most valuable test of onboarding.
+  - *Post-play interview* — ask open questions ("what would you tell a friend about this?"), never leading ones.
+- **What to measure:**
+  - *Qualitative* — struggle points, boredom points, quit points, "aha" moments, emotional reactions.
+  - *Quantitative* — completion rate per section, time-per-section, death heatmaps, failure counts, and retention: **D1 / D7 / D30** (fraction returning 1/7/30 days later). Retention is the honest verdict on whether the loops hook.
+- **Cadence:** test early, test ugly, test often. A rough test this week beats a polished one next month. Rotate testers — a tester can only be first-time once.
+
+## Killing your darlings
+
+- Cut any mechanic that does not serve the core loop or a design pillar — regardless of how clever it is or how long it took. A pile of unrelated clever mechanics is not a game.
+- Signs a darling must die: it needs its own tutorial, it only shines in one contrived spot, playtesters ignore it, or defending it starts with "but it was hard to build" (sunk cost is not a design argument).
+
+## Scope: the #1 indie killer
+
+More indie games die of scope than of bad ideas, weak talent, or poor tools. The failure mode is always the same: a feature list that outruns the finish line.
+
+- **Cut features, not quality.** A finished small game beats an unfinished ambitious one, every time. Shrinking scope preserves polish; cutting polish to keep scope produces a large mediocre thing nobody finishes.
+- **Define "the one thing."** State in one sentence what the game is *about* and protect it. Everything that doesn't serve it is a candidate for the cut list.
+- **Vertical slice over horizontal sprawl.** Build one loop end-to-end at quality before widening. A deep narrow slice ships; a wide shallow map of stubs does not.
+- **A public cut list.** Keep an explicit "not doing" list next to the feature list. Naming what's *out* is as important as naming what's in — it ends the "wouldn't it be cool if…" spiral.
+- **Budget by the finish, not the ambition.** Estimate remaining work against real available time; when they don't fit, the variable you move is scope, not the ship date and not sleep.
+
+## Documenting design: the living one-pager
+
+A 100-page design bible is stale the day after it's written and read by no one. Replace it with a living one-pager that grows only where a real decision needs recording.
+
+One-page design doc contents:
+
+- **Hook / fantasy** — one sentence: what is the player's power fantasy or core experience?
+- **Pillars** — 2–4 short phrases (e.g. "tense stealth", "readable chaos", "no dead ends"). These are decision filters: every feature must serve a pillar or it is cut.
+- **Core loop** — the moment-to-moment → session → meta chain in a few lines.
+- **Verbs** — the actions the player has.
+- **Target aesthetic** — the named MDA emotion(s), weighted.
+- **MVP / vertical-slice scope** — the smallest thing worth building and playing.
+- **Out of scope** — the explicit cut list.
+
+Keep it a communication tool, not an archive: a versioned wiki page beats a locked document. Prune it as decisions settle; link deeper notes only where they earn their space.

package/skills/shared/game-design/references/progression-and-economy.md

@@ -0,0 +1,70 @@
+# Progression, economy, and balance — deep dive
+
+Engine-agnostic. Expands the SKILL.md sections on progression, economy, difficulty, and balancing. All math here fits in a spreadsheet; no engine APIs.
+
+## Progression pacing
+
+- **Two parallel curves: difficulty and novelty.** Boredom comes from either flatlining. When difficulty must plateau (a rest area), spike novelty (a new mechanic, a set-piece); when novelty must pause, nudge difficulty. Never let both go flat at once.
+- **Teach → test → twist.** Introduce a mechanic safely, test it under mild pressure, then combine it with an earlier mechanic. This is how you build *layered* mastery instead of a pile of unrelated tutorials.
+- **Gate to control cognitive load.** Unlocks pace how many systems the player juggles at once. Front-loading every verb overwhelms; drip-feeding lets each verb be learned before the next.
+- **Unlock quality bar.** Each unlock should add a **verb** or a **meaningful choice**, not just +N%. A stat bump is progression felt as grind; a new option is progression felt as growth.
+
+## Economy: currencies, faucets, sinks
+
+- **Currency taxonomy:**
+  - *Soft currency* — earned through play, spent freely (gold, scrap). Drives the core economy loop.
+  - *Hard / premium currency* — scarce or bought, gates high-value or aspirational items.
+  - *Time / energy* — a pacing gate (stamina systems); a sink on session length.
+  - *Prestige* — meta-currency earned by resetting progress; funds the long meta.
+- **One currency, one job.** Every currency must have a distinct **sink** it exists to feed. If two currencies buy the same things, merge them. Currency without a sink is clutter and inflates.
+
+### Faucets and sinks
+
+- **Faucet** = anything that *creates* currency (quest rewards, drops, passive income).
+- **Sink** = anything that *destroys* it (shop costs, upgrades, repairs, consumables, taxes/fees).
+- The economy is healthy when total faucet output and total sink demand track each other over the play arc.
+
+Core identity to model in a sheet:
+
+```text
+net_income_rate = faucet_rate − sink_rate
+time_to_afford  = cost / net_income_rate
+
+# escalating sink — the standard way to keep pace with rising income:
+cost(n) = base × growth^n
+#   growth ≈ 1.07–1.15 for idle/incremental; higher = steeper wall
+#   solve for growth by pinning two target prices, or for base by pinning the first cost
+```
+
+Tune `time_to_afford` against desired pacing (e.g. "a new tier every ~2 sessions"). Sweep the parameters in a spreadsheet before touching the engine.
+
+### Runaway and inflation
+
+- **Symptom:** `net_income_rate` grows faster than `cost(n)` → currency piles up, prices feel free, the late game trivializes. Or the reverse: sinks outpace faucets → progress stalls, players feel taxed.
+- **Fixes for over-supply:** escalating/exponential sinks (`growth` above), consumable sinks (currency spent every session, not banked), soft/hard caps, and **prestige resets** that trade accumulated progress for a permanent multiplier and re-open the curve.
+- **Multiplayer economies** add faucet leaks (duping, botting, gold farming) and player-to-player trade that can concentrate wealth — audit total money supply over time, not just per-player rates.
+
+## Difficulty and balancing
+
+### The curve
+
+- **Sawtooth, not a straight ramp.** A rising baseline with peaks (bosses, gauntlets) and valleys (recovery, reward rooms). The valleys make the peaks legible and let the player breathe.
+- **Flow channel** (Csikszentmihalyi via game design): keep perceived challenge tracking the player's rising skill, in the band between boredom (too easy for current skill) and anxiety (too hard). As skill grows, challenge must grow with it.
+- **Perceived ≠ actual.** Telegraphing, readability, and generosity (see feel) change *perceived* difficulty without changing the numbers. A fair-feeling hard game keeps players; an unfair-feeling easy one loses them.
+
+### Tuning knobs
+
+- **Find the few high-leverage variables** — usually damage, health, spawn rate/density, resource cost, cooldown/duration. Most balance lives in a handful of them.
+- **Change one at a time.** Chasing a symptom by moving five knobs makes cause un-attributable. Move one, retest, record.
+- **Data-driven.** Put tunables in data (tables/config/spreadsheets), never hard-coded constants, so designers iterate without a rebuild and numbers are diffable and A/B-able. This skill decides *which* values are tunable and their ranges; the engine skill (`godot`/`unity`/`unreal`) builds the loader.
+
+### Dominant strategies and intransitive balance
+
+- **Dominant strategy** = an option that strictly beats the alternatives in most situations. It collapses the meta: every rational player converges on it and all other choices die.
+- **Detect it:** watch playtests and telemetry for pick-rate/win-rate outliers, and for "solved" openings. High pick + high win = nerf target.
+- **Fix toward intransitivity:** aim for rock-paper-scissors — every option is beaten by *some* other option, none beats all. Nerf the outlier or buff its counters; prefer many small changes over one sweeping one.
+- **Symmetry vs asymmetry:** symmetric balance (mirror factions) is easy to make fair but flat; asymmetric balance (distinct factions/classes) is rich but must be balanced by *outcome parity* (equal win-rates), not by identical stats.
+
+### Difficulty options & accessibility
+
+- Decouple **challenge** from **exclusion**. Difficulty modes, assist toggles (aim assist, slow-mo, invulnerability), and separate sliders for enemy damage vs enemy health widen the audience without diluting the intended experience for those who want it. Accessibility is design, not charity — it grows the reachable player base.

package/skills/shared/game-storytelling/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: game-storytelling
+description: "Use when a game's story is the work: premise and pillars, branching topology, meaningful choice, dialogue state, quests, environmental storytelling, ludonarrative harmony. Author portable — engine wiring is `godot`/`unity`/`unreal`. NOT the mechanics and economy the story serves (that is `game-design`), NOT level layout (that is `level-design`)."
+tags: [game, narrative, story, dialogue, quest, branching, worldbuilding]
+recommends: [game-design, level-design]
+profiles: [full]
+origin: ai-hub
+---
+
+# Game Storytelling — Narrative Design (engine-agnostic)
+
+*Design the story as a system the player operates, not a script they watch. This skill owns the narrative graph — premise, pillars, branches, choices, dialogue state, quests, and the storytelling embedded in the world.*
+
+You produce **design artifacts**: a premise/theme/pillars doc, a branch topology, a state/flag table, dialogue in a portable format (Ink/Yarn/Twee/articy), quest specs, and environmental beats. Story is a **system in service of play**; when you catch yourself designing a great scene the mechanics can't honor, reconcile it (see Ludonarrative harmony) rather than ship the dissonance.
+
+Boundaries: **game-design** owns what the player *does* — core loop, verbs, systems, progression, economy, difficulty, balance — and the story serves those verbs; call it when resolving dissonance needs a *mechanic* change, or when designing the conditions for systemic/emergent story. **level-design** owns spatial layout, encounter placement, sightlines, blockout and the pacing *of a space* — the space environmental storytelling lives inside; co-own the set-dressing. **godot / unity / unreal** implement the dialogue runner, quest state, save-serialization of story state, and the Ink/Yarn/articy plugin glue — author portable, they wire it. **marketing** owns the store page, premise pitch and trailer copy (external-facing, not in-game narrative). Prose fiction, a screenplay, or a novel with no interactive/branching structure is general writing, not this skill.
+
+## Premise, theme, and pillars (do this first)
+
+Nail these before a single branch or line of dialogue. They are the constraint that keeps a branching story from sprawling into incoherence.
+
+1. **Premise** — one sentence: *who*, in *what world*, wants *what*, against *what*. If it doesn't fit in a sentence, the story isn't decided yet.
+2. **Theme** — the question the game argues about (loyalty vs. survival, cost of power). Theme is the filter for every choice; a choice that doesn't press on it is decoration.
+3. **Narrative pillars** — 3–5 non-negotiables the story must always deliver (e.g. "every companion can die," "the player is never the chosen one"). Pillars kill scope arguments later.
+4. **Tone & POV** — register (grim, wry, mythic), narrative distance (silent, voiced, ensemble), tense/person for text.
+5. **Story-in-service-of-play** — write pillars so they are *expressed through the verbs the player already has*. If the theme is "trust is earned," the game needs a trust mechanic, not a paragraph asserting it.
+
+### Ludonarrative harmony (avoid dissonance)
+
+Dissonance is when the story says one thing and the mechanics say the opposite (the "caring family man" who murders a thousand henchmen). Diagnose and fix, in order:
+
+- **Verb audit.** List what the player *does* most. Does the dominant verb match the theme and the protagonist's values? If the loop is "kill," a pacifist narrative is dissonant.
+- **Reward audit.** What does the game *reward*? Rewards are the loudest narrative voice — if you reward hoarding but preach generosity, players believe the reward.
+- **Fix by moving the cheaper piece.** Usually re-frame the narrative to match the mechanic rather than re-engineering the mechanic — but flag to **game-design** when only a mechanic change resolves it.
+- **Failure & death.** Reconcile the fiction of losing (respawn, checkpoint, permadeath) with the story; unexplained respawns are the most common silent dissonance.
+
+## Narrative structures for interactivity
+
+Pick a topology deliberately; most games mix them. Full trade-offs, diagrams, and containment math → `references/branching-and-state.md`.
+
+| Structure | Shape | Player agency | Author cost | Use when |
+| --- | --- | --- | --- | --- |
+| **Linear** | one path, story beats gated by progress | low (pacing only) | low | story-driven, cinematic, tight authorship |
+| **Branching (tree)** | choices split, rarely rejoin | high, expensive | explodes fast | short, choice-showcase, replay-driven |
+| **Hub-and-spoke** | central hub, self-contained spokes, return | medium (order + selection) | moderate, scales | quests/missions, RPGs, episodic |
+| **Foldback / string-of-pearls** | branches diverge then **reconverge** at beats | feels high, stays bounded | moderate | the workhorse for long branching stories |
+| **Environmental** | story embedded in space & objects, player-assembled | interpretive | front-loaded | immersive sims, exploration, "show don't tell" |
+| **Systemic / emergent** | story generated by rules + player, not scripted | very high, uncurated | design not writing | sims, roguelikes, sandbox; the "anecdote factory" |
+
+The pragmatic default for a story-heavy game is **foldback**: let choices matter locally, then reconverge on load-bearing beats so you author a bounded number of scenes. Pure trees are a trap (see below).
+
+## Branching & choice
+
+A choice is **meaningful** only if the player can (a) form an intent, (b) foresee a plausible consequence, and (c) later *see the consequence land*. Missing any leg makes it noise. Meaningful choice vs. the deliberate, defensible **illusion of choice**, plus state modeling and the combinatorial-explosion fix → `references/branching-and-state.md`.
+
+- **Meaningful choice** changes state that the game later reads back to the player (a door, a death, a line, an ending). Track it with a **flag/variable**, not a duplicated scene.
+- **Illusion of choice** (options that reconverge to the same outcome) is a legitimate tool for *expression and tone* — but never sell a fake choice as consequential; players feel the betrayal and stop trusting every future choice.
+- **State & flags** are the spine. Model story state as named variables (`met_the_witch`, `reputation >= 3`, `betrayed_ally`). Gate content on state; don't copy-paste branches.
+- **The combinatorial-explosion trap.** N independent binary choices imply 2^N futures — unauthorable past a handful. Contain it with:
+  - **Reconvergence (bottlenecks)** — funnel branches back to shared beats; the space between bottlenecks stays small.
+  - **Gates** — require a flag/level/item to open content, pruning the live branch set.
+  - **State over structure** — one scene that reads flags and swaps lines beats ten near-duplicate scenes.
+  - **Locality** — most choices affect only the current scene ("weave"); reserve the few loud choices for global state.
+
+## Dialogue systems
+
+Every dialogue tool reduces to the same four primitives — design against these, then let the engine skill wire the chosen tool. Deep tool comparison, a "pick one" guide, and the same conversation shown in Ink / Yarn / Twee → `references/dialogue-tools.md`.
+
+- **Node** — a unit of content (a line, a passage, a knot) with an id you can jump to.
+- **Condition** — boolean over story state that gates a node, option, or line (`if hasKey`, `if trust > 2`).
+- **Variable** — the story state read/written by nodes (flags, counters, enums, inventory).
+- **Effect** — a side effect a node fires (set a flag, give an item, start a quest, emit an engine event).
+
+Tools (pointers — do not author engine glue here):
+
+- **Ink** (inkle) — writer-first scripting language: knots/stitches, diverts `->`, once-only `*` / sticky `+` choices, gathers, weave, `VAR`, `LIST`, tunnels, threads, tags. Great for prose-heavy branching; runs via `inkjs` or engine integrations.
+- **Yarn Spinner** (v3.x, current) — node-based, Twine-friendly: `<<set $var to x>>`, `<<if>>`, `<<jump>>`, commands, functions, markup. First-class Unity; Godot (C# beta, GDScript alpha); Unreal in progress.
+- **Twine** — visual node editor, publishes standalone HTML; scripting depends on the **story format** (Harlowe, SugarCube, Snowman, Chapbook). Twee is its text form — a good neutral interchange.
+- **articy:draft X** — heavyweight visual narrative DB (flow/dialogue fragments, hubs, conditions, instructions, entities); free Unity/Unreal importers and a **Generic Engine Export** (JSON) for anything else.
+
+Author in one of these formats and keep dialogue **portable**; engine binding is a separate step owned by the engine skill.
+
+## Quests & objectives
+
+A quest is a small state machine plus presentation. Spec each quest with:
+
+- **Trigger** — what activates it (talk to X, enter zone, flag set).
+- **Objective(s)** — ordered or parallel steps; each a condition over world/story state.
+- **States** — `unavailable → available → active → (step states) → complete / failed`, modeled explicitly. Ambiguous quest state is the #1 quest bug.
+- **Tracking & presentation** — what the player sees (journal, marker, count). Design the *reveal*: don't show a marker for a step the player shouldn't know yet.
+- **Rewards & consequences** — the flags/items/state the quest writes on completion *and* on failure.
+- **Fail states** — decide per quest: can it fail, and is failure a dead-end, a branch, or lost content? **Failing forward** (failure opens a different path) beats a hard fail; **soft-locking the game** is a defect — always leave an escape.
+- **Nesting & dependencies** — main/side/hidden; prerequisite flags; mutual exclusivity (faction A locks B). Track dependencies as gates, per the branching rules above.
+
+## Environmental & systemic storytelling (show, don't tell)
+
+Deliver story *through the world* so the player assembles it and feels ownership. Technique catalog, diegetic-vs-non-diegetic delivery, and the "anecdote factory" → `references/environmental-storytelling.md`.
+
+- **Show, don't tell.** Prefer a scene the player reads (a skeleton clutching a locked door) over a paragraph narrating it. Text-dumps are the fallback, not the default.
+- **Environmental storytelling** — set dressing, aftermath/traces, spatial sequencing, object placement, and readable item descriptions that imply events without narrating them. Coordinate with **level-design** for the space itself.
+- **Systemic / emergent storytelling** — let rules + player generate stories you didn't script ("that time my colonist starved defending the fridge"). You design the *conditions and vocabulary* for stories, not the stories — a **game-design** collaboration.
+- **Diegetic first.** Prefer in-world delivery (signage, barks, world change) over HUD/narrator; reserve non-diegetic (menus, codex, narrator) for what the world genuinely can't carry.
+
+## Delivery: pacing, VO, localization-readiness
+
+- **Pace the text.** Match line length to the moment; long paragraphs in combat go unread. Chunk to the display (one box-screen), respect reading speed, never block play with unskippable text.
+- **VO considerations** *(design-side, not recording — that's audio/engine)* — write for the ear (contractions, short clauses); budget line counts early (VO is expensive and near-frozen once recorded); keep a **stable line ID** on every spoken line; don't splice recorded fragments across variables (gender/number/name concatenation breaks in most languages).
+- **Localization-readiness** *(so the loc pipeline can do its job)* — externalize all player-facing text to string tables keyed by stable id; **never concatenate** sentences or embed grammar in code (gender/plural/word-order differ per language — use full templated strings with ICU-style placeholders); allow +30–40% text expansion; keep variables as named tokens (`{playerName}`), not positional; leave translator notes per line.
+
+## Anti-patterns
+
+| Anti-pattern | Do instead |
+| --- | --- |
+| Branching everything because "players love choices" | Pure trees explode (2^N). Use foldback + gates; reconverge on beats. |
+| A choice that feels huge but no later node reads it back | If no later node reads the flag, the choice is noise. Show the consequence or cut it. |
+| Both options lead to the same scene, and it's sold as a big decision | Fine as expression, not as stakes. Never sell a fake choice as consequential. |
+| Explaining in the story why he's a mass murderer | Words don't beat verbs. Fix the ludonarrative dissonance, don't narrate around it. |
+| Adding an audio log to explain the backstory | Text-dump is the fallback. Try to *show* it environmentally first. |
+| Hardcoding strings, "we'll localize later" | Concatenation and hardcoded text break loc. Externalize to keyed string tables now. |
+| A quest that can't be failed because it's simpler that way | Sometimes right; but soft-locking the game on a missed step is a defect — leave an escape. |
+| Wiring the Ink file into Unity here | Not this skill. Author portable narrative; hand wiring to the engine skill. |
+
+## Checklist
+
+- [ ] Premise (one sentence), theme, and 3–5 narrative pillars are written and agreed; every pillar is expressible through an existing player verb (no assert-only themes).
+- [ ] Verb + reward audit done; any ludonarrative dissonance is fixed or escalated to game-design.
+- [ ] A topology is chosen deliberately (default: foldback), not accidental tree sprawl; combinatorial explosion is contained (reconvergence + gates + locality) so the branch count is authorable.
+- [ ] Story state is modeled as named variables/flags; content gates on state, not duplicated scenes.
+- [ ] Every "meaningful" choice writes a flag some later node reads back to the player; no fake choice is sold as consequential.
+- [ ] Dialogue authored in a portable format (Ink/Yarn/Twee/articy); engine wiring left to the engine skill.
+- [ ] Each quest has explicit states, tracking, rewards/consequences, and a defined fail behavior (no silent soft-locks).
+- [ ] Environmental/diegetic delivery preferred over text-dumps and non-diegetic narration where the world can carry it.
+- [ ] All player-facing text externalized to keyed string tables; no concatenation; variables are named tokens; +30–40% expansion allowed.
+- [ ] VO lines have stable IDs, are written for the ear, and the script is locked before recording is proposed.

package/skills/shared/game-storytelling/evals/README.md

@@ -0,0 +1,28 @@
+# Eval harness — `game-storytelling`
+
+Agent-run eval, not a shell script. A human or judge-agent drives a Claude Code
+agent and scores its behaviour against `cases.yaml`. There is no automated grader.
+
+`cases.yaml` has three blocks: `should_trigger` (7), `should_not_trigger` (5),
+and `capability` (2 scenarios with `must_include` rubrics).
+
+## A. Triggering accuracy
+
+Assert the skill fires on real narrative-design work (premise/pillars, branching
+and choice, dialogue-tool authoring, quests, environmental storytelling,
+ludonarrative harmony) and stays quiet on near-misses that belong to `game-design`
+(mechanics/balance), `level-design` (spatial layout), the engine skill (dialogue
+runner + save wiring), `marketing` (store/trailer copy), or plain prose fiction.
+Load only this skill, run each prompt in a fresh session for 3–5 trials, and score
+`should_trigger` as fire / `should_not_trigger` as don't-fire (bonus: routes to the
+named `route_to`). Pass bar: ≥90% correct decisions across all trials.
+
+## B. Capability uplift
+
+Run each `capability` scenario WITH vs WITHOUT the skill and score against its
+`must_include` rubric. The branching scenario checks the containment kit (2^N
+framing, foldback/reconvergence, gates, state-over-structure, real-vs-illusory
+choice) and engine-agnostic hand-off; the dissonance scenario checks the verb/
+reward audit and cheaper-piece fix. Pass bar: WITH the skill covers ≥80% of rubric
+points and clearly beats the baseline (which typically skips the explosion math,
+conflates fake stakes with real choice, and writes engine code instead of a graph).