@ericrisco/rsc 0.1.34 → 0.1.36

package/skills/course-storytelling/references/learner-grounding.md

@@ -81,9 +81,19 @@ If the user can't answer a question, that dimension stays incomplete — note th
 
 ### Profile wiki article template
 
-Each `02-DOCS/wiki/teaching/*.md` article follows the harness wiki format:
+Each `02-DOCS/wiki/teaching/*.md` article follows the harness wiki format. It is an OKF v0.1 article: open it with YAML frontmatter carrying a non-empty `type:` (`teaching-profile`), then the H1 and body:
 
 ```markdown
+---
+type: teaching-profile
+title: Teaching — Learner
+description: Who is learning, their level and prior knowledge, their pains and desires, and what they can DO after.
+tags: [teaching, learner, profile]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: teaching
+status: stable
+---
+
 # Teaching — Learner
 
 > Sources: {user interview, YYYY-MM-DD}
@@ -116,9 +126,19 @@ After this, the learner can: …
 
 ### False-beliefs article specifics
 
-`false-beliefs.md` must type every belief so `brunson-frameworks.md` can match it to a breaking story:
+`false-beliefs.md` must type every belief so `brunson-frameworks.md` can match it to a breaking story (same OKF frontmatter; `type: teaching-profile`):
 
 ```markdown
+---
+type: teaching-profile
+title: Teaching — False Beliefs
+description: The learner's blocking beliefs, typed vehicle / internal / external, each with a breaking story.
+tags: [teaching, false-beliefs, profile]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: teaching
+status: stable
+---
+
 # Teaching — False Beliefs
 
 > Sources: {user interview, YYYY-MM-DD}

package/skills/decision-records/SKILL.md

@@ -56,9 +56,22 @@ Map every ADR to the **MADR 4.0.0 template** (released 2024-09-17 — the curren
 
 Required spine, in order: **Title → Status → Date → Context and Problem Statement → Decision Drivers → Considered Options → Decision Outcome → Consequences**. The MADR-optional sections (Confirmation, Pros and Cons of the Options, More Information) you add only when they pull weight.
 
-Minimal skeleton — this is enough for most decisions:
+Minimal skeleton — this is enough for most decisions. When the ADR lives in a harness
+workspace (`02-DOCS/wiki/decisions/`), it is part of an OKF v0.1 bundle, so it opens with YAML
+frontmatter carrying a non-empty `type: decision` (plus the OKF-recommended `title`/`tags`/
+`timestamp`). The body keeps the human-readable `- Status:`/`- Date:` lines verbatim — they are
+the decision's domain record and `scripts/verify.sh` reads them, so the frontmatter is purely
+additive. Cross-references use standard markdown links, never wikilinks. (In a plain code repo
+under `docs/adr/`, the frontmatter is optional — OKF conformance only governs the wiki bundle.)
 
 ```markdown
+---
+type: decision
+title: "Choose Postgres over DynamoDB for the primary store"
+tags: [adr, database, billing]
+timestamp: 2026-06-02T00:00:00Z
+---
+
 # 7. Choose Postgres over DynamoDB for the primary store
 
 - Status: accepted

package/skills/decision-records/references/templates.md

@@ -8,6 +8,17 @@ Filenames: `NNNN-title-with-dashes.md` where `NNNN` is a zero-padded sequential
 
 Store under one log only — `docs/adr/` (code repo) or `02-DOCS/wiki/decisions/` (harness workspace). Maintain an index as `docs/adr/README.md` or `0000-index.md`:
 
+When the log lives in `02-DOCS/wiki/decisions/`, each ADR is a document in an OKF v0.1 bundle, so it opens with YAML frontmatter carrying a non-empty `type: decision` (plus the OKF-recommended `title`/`tags`/`timestamp`). The MADR body — `- Status:`, `- Date:`, the sections — is kept exactly as below; the frontmatter is additive and `verify.sh` keeps reading the body lines. The index file (`0000-index.md` / `README.md`) is the OKF reserved directory listing and carries **no frontmatter**. All cross-references are standard markdown links, never wikilinks. In a plain `docs/adr/` code repo the frontmatter is optional — OKF conformance governs only the wiki bundle. The OKF frontmatter block to prepend (shown once; the templates below omit it for brevity):
+
+```yaml
+---
+type: decision
+title: "<short decision title>"
+tags: [adr]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+---
+```
+
 ```markdown
 # Decision Log
 
@@ -116,7 +127,16 @@ a test, an architecture-fitness check.>
 
 ## Worked example — `0007-choose-postgres.md`
 
+Shown with the OKF frontmatter it carries when stored in `02-DOCS/wiki/decisions/`:
+
 ```markdown
+---
+type: decision
+title: "Choose Postgres over DynamoDB for the primary store"
+tags: [adr, database, billing]
+timestamp: 2026-06-02T00:00:00Z
+---
+
 # 7. Choose Postgres over DynamoDB for the primary store
 
 - Status: accepted

package/skills/design/references/brand-grounding.md

@@ -102,9 +102,19 @@ If the user can't answer a question, that dimension stays incomplete — note th
 
 ### Visual-identity wiki article template
 
-Each `02-DOCS/wiki/brand/*.md` article follows the harness wiki format:
+Each `02-DOCS/wiki/brand/*.md` article follows the harness wiki format. It is an OKF v0.1 article: open it with YAML frontmatter carrying a non-empty `type:` (`brand-study`), then the H1 and body:
 
 ```markdown
+---
+type: brand-study
+title: Brand — Visual Identity
+description: The visual personality — OKLCH color system, type pairing & scale, and radius/shadow/motion personality.
+tags: [brand, visual-identity, design]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: brand
+status: stable
+---
+
 # Brand — Visual Identity
 
 > Sources: {user interview, YYYY-MM-DD}

package/skills/game-design/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: game-design
+description: "Use when designing or repairing the design of a game — inventing mechanics and systems, shaping the core loop, layering moment-to-moment / session / meta loops, planning progression, economy, currencies and sinks/faucets, tuning difficulty curves and balance, killing dominant strategies, adding 'juice'/game feel as design intent, prototyping and playtesting, or controlling scope, and especially when the ask is 'why isn't my game fun'. Triggers: 'design the core loop', 'my game isn't fun / doesn't hook', 'balance the economy', 'the difficulty curve feels off', 'players found a dominant strategy', 'how do I scope this', 'reward / progression loop', 'diseñar la mecánica', 'el juego no engancha', 'com equilibro l'economia'. NOT writing engine code, scripts or shaders (route to godot/unity/unreal), NOT narrative, dialogue or story beats (route to game-storytelling), NOT level layout or encounter placement (route to level-design)."
+tags: [game-design, mechanics, core-loop, balancing, progression, playtesting, scope, fun]
+recommends: [level-design, game-storytelling, godot, unity, unreal]
+profiles: [full]
+origin: risco
+---
+
+# 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`, `unity`, or `unreal`.
+
+## The one rule
+
+> 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. Every hour spent planning a mechanic you have not prototyped is an hour spent guessing. Prototype the riskiest assumption first, play it, then decide.
+
+> The design of a game is the set of **verbs** it gives the player plus the **loops** those verbs live in. Everything else — art, story, levels — dresses that skeleton. If the skeleton is not fun in greybox, nothing dresses it into fun.
+
+## When to use / When NOT
+
+**Use when:**
+- Inventing or reworking mechanics and systems, or defining the player's verb set.
+- Shaping the core loop, or layering moment-to-moment → session → meta.
+- Planning progression, unlocks, pacing, or an in-game economy.
+- Tuning a difficulty curve, hunting a dominant strategy, or setting up data-driven balance.
+- Adding "juice" / game feel **as a design concept** (what feedback, why).
+- Prototyping, planning a playtest, deciding what to measure, or cutting scope.
+- The vague-but-critical ask: "why isn't my game fun / why doesn't it hook?"
+
+**Do NOT use — route instead:**
+
+| The ask | Route to | Why not here |
+| --- | --- | --- |
+| Write the movement/AI/shader/save code | `godot` / `unity` / `unreal` | This skill decides *what* to build; the engine skill builds it. |
+| Author the story, dialogue, characters, lore | `game-storytelling` | Narrative design is its own craft; this skill owns systems and verbs. |
+| Lay out a level, encounter, or world map | `level-design` | Spatial/encounter design applies the mechanics this skill defines. |
+| Netcode, prediction, lag compensation | `gamedev-multiplayer` | A technical domain, not core design intent. |
+| Ship / store page / build pipeline | `gamedev-shipping` | Release logistics, not design. |
+
+(`godot`, `unity`, `unreal`, `game-storytelling`, `level-design` are linkable siblings; the rest are known ids you name but cannot link yet.)
+
+## 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.
+
+## Related skills
+
+- `../level-design/SKILL.md` — applies these mechanics in space: layout, pacing beats, encounter design.
+- `../game-storytelling/SKILL.md` — narrative, dialogue, and how story wraps the systems you define here.
+- `../godot/SKILL.md`, `../unity/SKILL.md`, `../unreal/SKILL.md` — implement the settled design; all engine APIs, feel/juice code, and data-driven tuning loaders live there.
+- Known siblings to name but not yet link: `gamedev-multiplayer`, `gamedev-physics`, `gamedev-pathing`, `gamedev-shaders`, `gamedev-shipping`.
+
+## 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/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/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 02-DOCS/wiki/design/ only if a harness exists"

package/skills/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/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/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.