summer-engine 2.2.0 → 2.5.0

package/skills/workflow/debugging-game-feel/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: debugging-game-feel
+description: Use when a gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts. Different from logical bug debugging; the bug is subjective and lives in tuning, timing, and feedback layers.
+---
+
+# Debugging Game Feel
+
+## Overview
+
+"Works but feels wrong" is its own debugging discipline. The code is correct. No diagnostic flags it. The unit tests pass. And yet the jump is floaty, the sword has no weight, the camera lags the player, the dash is unsatisfying.
+
+**Core principle:** Game-feel bugs are tuning bugs, not logic bugs. Treat them with discipline — isolate one variable, compare to a reference, measure what you can, feel what you can't.
+
+This skill is for the diagnostic phase. The polish-and-juice layer (screen shake, hit-stop, particles, sound design) is `summer:visual-effects/game-feel` — go there once you've identified WHICH variable is wrong.
+
+## When To Use
+
+- The user says: "feels floaty", "feels mushy", "feels off", "feels sluggish", "doesn't feel right", "lacks impact", "lacks weight", "doesn't feel satisfying".
+- The feature passes `summer:playtesting-a-feature` (no errors, golden path runs) but still doesn't feel right.
+- You're tuning movement, combat, camera, or any interaction with frame-level timing.
+
+## When NOT To Use
+
+- The feature has a **concrete reproducible bug** — go to `summer:investigating-bugs`.
+- The feature **crashes or throws** — go to `summer:debug`.
+- The feature **hasn't been built yet** — design it via `summer:brainstorming` first.
+
+## The Iron Law
+
+```
+ONE VARIABLE AT A TIME. ALWAYS.
+```
+
+Game-feel debugging is the place where engineers most often violate this rule, because each variable is a small tweak. "Let me bump acceleration AND friction AND max speed all together" produces a result you cannot reason about. You learn nothing. The bug returns.
+
+## The Loop
+
+```
+  Anchor → Isolate → Tweak one variable → Compare → Decide → Repeat
+```
+
+### 1. Anchor: name the reference
+
+Before touching any value, decide what "right" feels like. Game feel is subjective; without an anchor, you are debugging air.
+
+Two ways to anchor:
+
+| Anchor type | When to use | Example |
+|---|---|---|
+| **Reference game footage** | The user has a target in mind (Hollow Knight jumps, Dark Souls weight, Hades dashes) | "Match the Hollow Knight jump arc — peak in ~0.25s, fall ~0.35s, terminal velocity around frame 30" |
+| **Internal known-good** | An older build / a sibling feature in the same game already feels right | "The pistol fires snappy. Make the rifle feel as snappy as the pistol minus the recovery frames." |
+
+Write the anchor down in one sentence. If the user can't articulate it, ask. "What game does this remind you of when it's working?" is a fast way to extract the reference.
+
+### 2. Isolate: name the suspect variable
+
+Game-feel bugs almost always live in one of a small set of axes. Pick the most likely one first.
+
+| Domain | Common suspect variables |
+|---|---|
+| Jump | gravity, jump velocity, terminal velocity, coyote-time window, jump-buffer window, variable-jump cutoff, apex hang time |
+| Run | acceleration, max speed, friction (ground vs air), deceleration on input release, turn-around speed |
+| Combat hit | hit-stop duration (attacker), hit-stop duration (target), screen shake amplitude + duration, knockback velocity + decay, recovery frames |
+| Camera | follow lag (lerp factor or spring stiffness), lookahead distance, deadzone size, snap-vs-smooth on direction change |
+| Dash | distance, duration, ease curve, cooldown, i-frame window, end-lag |
+| UI feedback | input-to-response frame count, tween duration, easing function, sound onset delay |
+
+If you cannot pick one suspect: state the top two, pick the one you think is most likely (say which), tweak it, see if it moved the feel. Do not tweak both.
+
+### 3. Tweak one variable
+
+- Read the current value via `summer_inspect_node` or open the relevant `.tres` / `.gd` file.
+- Change ONE value. Save.
+- Trigger `summer_play` and walk the feature.
+- Ask: did the feel move toward or away from the anchor?
+
+### 4. Compare
+
+Two compare modes:
+
+**Feel:** subjective. The user (or you, if you have eyes on the screen) reports "warmer" or "colder." This is fine. Most game-feel work is felt, not measured.
+
+**Measure:** objective. When the feel is ambiguous, drop down to frame counts.
+
+| Question | Measurement |
+|---|---|
+| "Does the jump peak too fast?" | `print` the y-velocity in `_physics_process`, count frames from launch to peak |
+| "Is the camera too laggy?" | `print` `camera.global_position - target.global_position` per frame |
+| "Is the input dead?" | Log input event frame and resulting state-machine transition frame; subtract |
+| "Is the hit-stop too short?" | Log frame at hit + frame at unfreeze |
+
+The point of measurement is to ground the conversation in numbers when "feels off" stops being useful. You do not need to measure most tweaks — only the ambiguous ones.
+
+### 5. Decide
+
+After the tweak:
+
+- **Felt closer to the anchor** → commit the change, move to the next suspect variable if the feel still isn't right.
+- **Felt further** → revert the change, pick a different suspect variable.
+- **No change in feel** → revert the change, you tweaked the wrong variable.
+
+Never leave a tweak in the codebase that you couldn't tell did anything. It will compound with the next tweak and you will lose the thread.
+
+## The Compounding Tweaks Trap
+
+The most common failure mode in game-feel work:
+
+```
+  Jump feels floaty.
+  Bump gravity from 980 → 1200. Still floaty.
+  Bump it to 1500. A bit better.
+  Also reduce jump velocity from 500 → 450.
+  Also tweak terminal velocity 1500 → 2000.
+  Also add a 3-frame coyote window because why not.
+  Now it feels... different. But the dash that used to feel great no longer does.
+  Try to undo? You don't remember the starting point.
+```
+
+**Antidote:**
+
+1. Note the starting values before you begin.
+2. One variable at a time.
+3. After every tweak, ask: anchor closer or farther? If unsure, revert.
+4. Commit small revertible changes — one variable per commit during a feel-tuning session. Easy to bisect.
+
+## Feel Principles (Briefly)
+
+Game feel rests on three small ideas. Most "feels wrong" bugs trace to one of these being undertuned:
+
+| Principle | What it means | What it looks like when broken |
+|---|---|---|
+| **Anticipation** | A small wind-up before a big action | Sword swings feel like they "appear" instead of being thrown |
+| **Follow-through** | The action continues past the input | Player snaps to a stop on input release — feels robotic |
+| **Weight** | Visible cost to changing direction or stopping | Player turns on a dime at full speed — feels weightless |
+
+These are diagnostic tools, not lecture material. When the user says "feels weightless," your suspect-variable shortlist is: deceleration on input release, friction, turn-around speed, animation cross-fade time.
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| Tweaking 2+ variables in one play session without reverting between | You will lose the signal. |
+| "Let me just feel it out without an anchor" | You will tune in circles. Name the reference. |
+| "The user said floaty so I'm jacking gravity" | "Floaty" can also mean weak air control, slow terminal velocity, or too-long apex hang. Confirm before tweaking. |
+| Skipping the play step ("I'll just bump the number and trust the feel") | Game feel is felt, not predicted. Play every tweak. |
+| Adding "while I'm here" tweaks to unrelated features | Game feel debugging is a focused activity. Stay on the one feature. |
+| Going to `summer:visual-effects/game-feel` before identifying the broken variable | Juice on top of a broken tuning makes the bug louder. Fix tuning first. |
+| Spending >30 minutes on one variable without progress | The anchor is wrong, or the variable is wrong. Step back, re-anchor. |
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|---|---|
+| "It's subjective — I'll just iterate fast" | Fast iteration without isolation is thrashing, not iteration. |
+| "I know game feel, I don't need an anchor" | Even pros anchor. Especially pros anchor. |
+| "Two variables are coupled, I have to tune them together" | Then tune one, ship that delta, tune the other separately. |
+| "The user can't articulate the anchor" | "What game does this remind you of when it works?" — one question, anchor obtained. |
+| "Adding juice will hide the bad tuning" | It won't. It amplifies it. |
+
+## When To Escalate
+
+After diagnosis pins down which variable(s) are wrong, the tuning is done — but the feature may still want polish. Hand off to:
+
+- `summer:visual-effects/game-feel` — for the screen-shake, hit-stop, particle, sound layer once tuning is locked.
+- `summer:debug` — if mid-debug you discover an actual error (signal not firing, node freed) hiding under the feel issue.
+
+## The Bottom Line
+
+Feel bugs are tuning bugs. Tuning is a one-variable-at-a-time discipline. Anchor to a reference. Tweak one number. Play it. Decide. Repeat.
+
+**Related skills:**
+- `summer:investigating-bugs` — for logical bugs with concrete repros, not feel.
+- `summer:playtesting-a-feature` — the playtest discipline this skill plugs into.
+- `summer:debug` — when the feel investigation surfaces an actual error.

package/skills/workflow/diagnosing-perf-regressions/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: diagnosing-perf-regressions
+description: Use when frame rate, frame time, or load time has gotten worse since a known-good state — "it used to run at 60, now it's at 30." Focused on finding the cause of a regression, not general performance tuning.
+---
+
+# Diagnosing Performance Regressions
+
+## Overview
+
+There is a difference between "this game is slow" and "this game got slow." This skill is for the second one.
+
+**Core principle:** A regression has a cause. The cause is a specific change. Bisect to find the change, then root-cause from there.
+
+This skill is **not** general performance tuning. If the game has always run at 30fps and you want to push it to 60, that is `summer:tune-performance` (the domain skill for budget-driven optimization). This skill is the diagnostic — what broke, where, when.
+
+## When To Use
+
+- "It used to run at 60fps, now it's at 30."
+- "Load time was 3s yesterday, now it's 15s."
+- "Frame stutters started after I added X."
+- "Build went from buttery to choppy and I don't know why."
+
+## When NOT To Use
+
+- "The game has always been slow, help me speed it up." → `summer:tune-performance`.
+- "I want to know if my game is fast enough to ship." → `summer:tune-performance`.
+- "The game crashes." → `summer:debug`.
+
+## The Iron Law
+
+```
+NO PERF FIX WITHOUT A KNOWN-GOOD vs KNOWN-BAD MEASUREMENT
+```
+
+You cannot fix a regression you have not measured. Eyeballing "feels laggy" is not a measurement. Get a number for the good state and a number for the bad state before touching code.
+
+## The Loop
+
+```
+  Measure now → Find last good → Bisect changes → Match to a cliff → A/B fix → Re-measure
+```
+
+### 1. Measure now
+
+```
+  summer_play  (on the scene that's slow)
+  ── wait 5-10 seconds of normal play ──
+  summer_get_diagnostics
+  summer_get_console
+  summer_stop
+```
+
+What to capture:
+
+| Metric | Source | Why |
+|---|---|---|
+| Avg FPS / frame time | `summer_get_diagnostics` or in-game perf monitor | Headline number |
+| Spike pattern | `summer_get_console` if user has frame-time prints, else in-game monitor | Steady 30 vs intermittent stutters → different causes |
+| Scene complexity | `summer_get_scene_tree` (root counts) | Establishes baseline for instance/body count cliffs |
+
+Write the bad-state number down. "Scene `Level3` runs at 31fps avg, drops to 12fps when 5+ enemies are on screen."
+
+### 2. Find the last known-good state
+
+Ask the user: when did it last run well? Then go to the VCS:
+
+```bash
+git log --oneline --since="<last good date>" --until="now"
+```
+
+If they can name a commit ("it was fine on Monday's build"), check that out and measure it the same way. You now have:
+
+- Known good: commit X, scene `Level3`, 60fps avg.
+- Known bad: HEAD, scene `Level3`, 31fps avg.
+
+If they can't name a date: ask for the rough window, list the commits, ask which ones are likely candidates. Do not bisect blind across 200 commits.
+
+### 3. Bisect the changes
+
+```bash
+git log --oneline <last-good>..HEAD
+```
+
+Read the list. Group commits into suspects:
+
+| Likely culprit | Why |
+|---|---|
+| Big asset imports (.glb, textures, audio) | GPU memory, draw-call count |
+| New shaders or material changes | Compilation stalls, overdraw, pipeline switches |
+| Scene additions (enemies, props, lights) | Physics-body count, instance count, light count |
+| `_process` / `_physics_process` additions | CPU per-frame cost |
+| Signal connections in tight loops | Hidden per-frame cost |
+| Particle systems | GPU + CPU |
+| `@tool` scripts running in editor | Misleading editor FPS |
+| Resource preload changes | First-use stalls |
+
+If a single commit is the obvious suspect (e.g. "Added 200 enemies to spawner"), test it first. Otherwise actually `git bisect` — check out the midpoint, measure FPS, repeat. Don't theorize through it; the bisect is fast and definitive.
+
+### 4. Match to one of the four Godot perf cliffs
+
+Godot 4.x regressions cluster heavily into four categories. Knowing them shortens diagnosis to minutes.
+
+| Cliff | Symptom | How to verify | Common cause |
+|---|---|---|---|
+| **Too many physics bodies** | FPS scales inversely with on-screen actor count, no GPU pressure | Count active `CharacterBody`/`RigidBody`/`Area` nodes; FPS doubles when half are queue_freed | Spawner with no upper cap; bullets/particles using physics bodies; collision layers too broad |
+| **Shader compilation stalls** | First-frame or first-effect-fire stutter, then smooth; only on shipped builds, not editor | Frame-time spike on first cast/shot; clean after; `OS.has_feature("editor")` differences | New shader added; `unique` material not pre-warmed; pipeline cache not built |
+| **GPU instance count / draw calls** | Steady low FPS, scales with what's on screen, no CPU pressure | RenderingServer perf monitors show high draw call count; FPS recovers when camera looks away | Forgot to enable MultiMeshInstance; unique materials per instance breaking instancing; too-detailed LOD0 |
+| **Transparent overdraw** | FPS tanks when looking at smoke, fire, foliage, glass — fine otherwise | Look at the offending region, FPS drops; look away, recovers | New particle effect with large quads; transparent UI over the viewport; fog/volumetrics |
+
+If the bad-state symptom matches one row, you have your hypothesis. Verify by reverting just the change you suspect and re-measuring.
+
+### 5. A/B with one variable
+
+This is the most violated step. Discipline:
+
+- **Revert one suspect commit** (or stub the suspect feature behind a flag).
+- Rebuild / reload the scene.
+- Measure FPS the same way you did in step 1.
+- Compare to known-bad. Did it recover?
+
+If yes → root cause confirmed. Now decide: fix the change, or accept the perf cost.
+If no → that wasn't it. Restore. Try the next suspect.
+
+**Never** revert multiple changes at once during diagnosis. You will not know which one was the cause, and the bug will return on the next merge.
+
+### 6. Re-measure after the fix
+
+The fix is not done until the same measurement that found the regression returns the good number. Same scene, same play duration, same warm-up.
+
+```
+  summer_clear_console
+  summer_play
+  ── 5-10 seconds of play ──
+  summer_get_diagnostics
+  summer_stop
+```
+
+State the result with the number: "Reverted the per-frame `get_tree().get_nodes_in_group()` call in `enemy_manager.gd`. Level3 back to 58fps avg." Not "should be faster now."
+
+## When To Escalate
+
+| Situation | Go to |
+|---|---|
+| Regression confirmed and root cause known, but the fix is "make the feature cheaper" rather than "undo the change" | `summer:tune-performance` for the optimization pass |
+| The regression turns out to be a crash or error in disguise (the slow path is throwing exceptions in a tight loop) | `summer:debug` |
+| The cause is a Godot version change or engine-side regression | Surface to the user; this is not a project-side fix |
+| Bisect lands on a commit that touches 40 files | Subdivide the commit: check out the commit, revert subsets, re-measure |
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| "Just optimize the whole scene" | That's tuning, not regression diagnosis. Find what changed first. |
+| Reverting 3 commits at once to "see if it helps" | You learn nothing. Revert one. |
+| Eyeballing "feels slow" without measuring | You will optimize the wrong thing. Get a number. |
+| Skipping the known-good measurement | Without a baseline, you don't know when you're done. |
+| Reading the slow scene's code top-to-bottom looking for inefficiency | The regression is in what changed, not in what was already there. |
+| Adding caching / pooling / LOD before identifying the cause | These are tuning moves. They can hide the regression instead of fixing it. |
+| Trusting editor FPS as ground truth | Editor runs `@tool` scripts, debug overlays, and a different render pipeline. Measure in a built or `--game` run when possible. |
+| "Maybe it's just a Tuesday thing" | Performance does not regress randomly. There is a cause. |
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|---|---|
+| "User wants it fixed now, no time to bisect" | Bisect is 5-15 minutes. Blind optimization can burn a day. |
+| "The slow commit is obvious, no need to A/B" | The "obvious" cause is wrong ~30% of the time. Verify before fixing. |
+| "I'll measure after I fix it" | If you don't have the bad number, you can't prove the fix worked. |
+| "It's probably just Godot" | Engine-side regressions exist but are rare. Suspect your project first. |
+| "Adding a pool / LOD / cache will help anyway" | Premature optimization on the wrong system is wasted work. |
+
+## When The Engine Isn't Running
+
+If `summer_play` is unavailable:
+
+1. Ask the user for an in-game perf overlay screenshot (FPS, frame time, draw call count).
+2. Walk the bisect logically with them: "Run on commit X, tell me the FPS. Run on commit Y, tell me the FPS."
+3. Do not claim a fix is verified from code reading alone.
+
+## The Bottom Line
+
+A regression is a delta. Diagnose the delta, not the codebase.
+
+Measure now. Measure last-good. Bisect what changed. Match to a Godot perf cliff. A/B one variable. Re-measure. Done.
+
+**Related skills:**
+- `summer:tune-performance` — for general optimization once the regression is fixed or when no regression exists.
+- `summer:investigating-bugs` — when the slow path turns out to be a logic bug (errors in a tight loop).
+- `summer:debug` — when the perf issue is actually a crash or freeze.
+- `summer:verification-before-completion` — to claim the fix worked, with numbers.

package/skills/workflow/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

package/skills/workflow/gameskill/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: gameskill
+description: Use when finishing a game-development session and you want to capture what you just learned into Summer's canonical skill library so the next session and every Summer user start smarter. Trigger on "gameskill", "/gameskill", "capture learnings", "save to skills".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: workflow
+allowed-tools: Read Write Edit Glob Grep Bash
+---
+
+# /gameskill — Capture Session Learnings into the Skill Library
+
+You're being invoked at the end (or middle) of a game-development session. Your job is to turn what you just figured out into a durable skill update so future agents and Summer users get to start where you ended.
+
+This is the meta-skill: the loop that turns ad-hoc fixes into reusable expertise.
+
+## What "Summer Engine" is, so you're grounded
+
+Three repos, one ecosystem:
+
+1. **SummerEngine repo** — the desktop engine (Godot fork in C++) plus the canonical CLI. Engine source: `editor/`, `core/`, and the Summer-specific module at `modules/1summer_engine/`. CLI source: `tools/summer-cli/`. The CLI ships as `npm i -g summer-engine`. It does install/login/create/run for the engine, plus `summer skills install --agent claude-code` which writes a curated subset of skills into `~/.claude/skills/` for any agent to auto-discover.
+2. **PublicSummerEngine repo** — the web app at summerengine.com. Has its own AI skill stores at `src/lib/ai/skills/bundled/` and `public/knowledge/summer/skills/` for the in-browser chat agent. Also has its own consumers of the engine API in `src/lib/bridge/direct-executor.ts` and `src/lib/ai/tools/run-and-verify.ts` which call the same engine endpoints the CLI does.
+3. **The active game project** — usually `~/development/<game-name>` (Godot 4.6) or whatever game you were just working on. Real working code in this repo is the gold standard for examples.
+
+The skill system is the value flywheel. Every game shipped teaches lessons. Lessons become skills. Next user starts smarter. Your job here is to close that loop for what you just did.
+
+## Cross-repo change awareness — read before any non-trivial fix
+
+When the lesson is "the engine should expose more / behave differently," the change usually crosses repo boundaries. Map the layers before you edit:
+
+```
+[active game] -> calls MCP / web app
+                       v
+[summer-cli MCP server (TypeScript)] -> calls /api/ops + /api/state/* on the engine
+                       v
+[Summer Engine binary (C++ in SummerEngine repo)] - source of truth for what the API returns
+
+[PublicSummerEngine web app (TypeScript)] -> also calls the same engine endpoints via direct-executor or Redis bridge
+```
+
+Implications:
+
+- A C++ change in `SummerEngine/modules/1summer_engine/` or `SummerEngine/editor/` reaches everyone (CLI MCP, web app, future tools). Most powerful, also highest blast radius.
+- A TypeScript change in `tools/summer-cli/src/mcp/` only changes what the CLI exposes. The web app has its own TypeScript layer at `PublicSummerEngine/src/lib/bridge/`. Same engine endpoints, different glue. Don't assume your CLI tool change is web-app-aware.
+- A skill update in `tools/summer-cli/skills/` affects every agent that runs `summer skills install`. The web app's skill store is separate (`PublicSummerEngine/src/lib/ai/skills/bundled/`) and currently uses a different format (template wizards, not Markdown discipline guides). Don't try to mirror skills there blindly.
+
+When you change an engine endpoint's response shape:
+
+1. Grep both `tools/summer-cli/src/` and `PublicSummerEngine/src/lib/` for consumers of that endpoint.
+2. Confirm the change is additive (new fields, no removed/renamed) so existing consumers still work without modification.
+3. If the change is breaking, update both consumers in the same logical commit set.
+4. Note in `tools/summer-cli/TOOLING-TODO.md` what's now possible that wasn't before.
+
+Engine binary changes ship via a rebuild + new release. CLI/web TypeScript changes ship via npm publish or web deploy. State this delivery cost in your report so the user knows what they get today vs after a release.
+
+## The four skill stores (probe each before doing anything)
+
+1. **Canonical source** — `~/development/SummerEngine/tools/summer-cli/skills/`. Single source of truth. Domains: `ui-and-ux`, `gameplay-mechanics`, `character-controllers`, `scripting-patterns`, `visual-effects`, `debugging`, `rendering-and-lighting`, `scene-and-project`, `level-design`, `audio`, `ai-and-npcs`, `asset-pipeline`, `performance`, `deployment`, `multiplayer-and-networking`, plus `workflow` for process skills. The `skills:` array in `.claude-plugin/plugin.json` is the registry. Sibling references live at top-level `references/` and `tests/`.
+2. **Claude auto-discovery** — `~/.claude/skills/`. Where `summer skills install --agent claude-code` writes copies. Auto-discovered by Claude Code in any session.
+3. **Web-app stores** — `PublicSummerEngine/src/lib/ai/skills/bundled/` (template wizards, different format) and `PublicSummerEngine/public/knowledge/summer/skills/` (JSON knowledge files). Mirror only when the lesson genuinely fits their format. Most discipline-guide skills don't.
+4. **The active game** — read it as ground truth. Working code from the real project beats invented examples.
+
+## What to do, in order
+
+1. One short sentence to the user. "Capturing learnings from this session into the skill library." That's it. No plan dump.
+
+2. Probe the stores. Glob each path above. Note what exists and what's empty. Print a tight summary.
+
+3. Recap the session. Look back over the conversation. Pull out learnings that are non-obvious AND general — things a future agent or user would benefit from but couldn't derive from reading the codebase. Examples that count:
+   - A working shader (the actual code) -> `visual-effects`
+   - A GDScript idiom that beat the obvious approach -> `scripting-patterns`
+   - A UI layout that survived the design pass -> `ui-and-ux`
+   - A bug + root cause + fix that wasn't in any docs -> `debugging`
+   - A Godot 4.x quirk (type inference, signal gotchas, plugin layer config) -> `scripting-patterns`
+   - A spawning/AI/enemy pattern that worked -> `ai-and-npcs` or `gameplay-mechanics`
+   - A perf fix with measured before/after -> `performance`
+   - An asset workflow that beat alternatives -> `asset-pipeline`
+   - An MCP gap that needed an engine-side fix -> `tools/summer-cli/TOOLING-TODO.md` AND the relevant skill
+
+   Examples that DON'T count: one-off code with no general lesson, things already documented in CLAUDE.md or an existing skill, personal preferences without reasoning, anything you have to manufacture to fill space.
+
+4. Decide placement. For each learning:
+   - Update existing skill: name the file, quote the section, draft the addition.
+   - Create new skill: pick the domain, name the file, draft the full skill markdown.
+   Match the format of existing skills in the same domain exactly. Read one if you're unsure.
+
+5. One tight pause for the user. Five-to-ten lines max: what files you'll touch, what each one captures, what gets left out. Wait for OK or redirect. Don't ask multiple questions.
+
+6. Apply.
+   - Write/edit `.md` files under `tools/summer-cli/skills/<domain>/`.
+   - Register a new skill in `.claude-plugin/plugin.json` (and sibling `.codex-plugin/`, `.cursor-plugin/` manifests) AND in `src/lib/skills-registry.ts` `SKILL_REGISTRY` array. Both are required — `plugin-manifests.test.ts` fails the build if either is missing.
+   - If the skill belongs in the curated Claude set, also write it to `~/.claude/skills/<name>/` so it's live in the current session. Tell the user to consider adding it to the CLI's default install set.
+   - If the learning applies to the web chat agent, mirror to `PublicSummerEngine` skill stores too.
+   - Run `git status` in the SummerEngine repo (and `PublicSummerEngine` if touched) so the diff is visible.
+
+7. Report. One short message. Files changed, the future-agent payoff in one sentence per skill, and what (if anything) is still uncaptured.
+
+## Style rules
+
+- Tight. No slop. No glazing.
+- Capture the why, not just the what. "Use X" rots. "Use X because Y breaks under Z" survives. Always lead skill updates with the reason.
+- Real working code from the active project beats invented examples. Lift from the active codebase.
+- VFX is code. Shaders + GDScript + node setup. Never image-generation pipelines or Meshy prompts.
+- No em dashes (—) in any user-facing copy you write into skills. Use periods or restructure.
+- No date references inside skill bodies. Skills are timeless guidance. Dates belong in commit messages and changelogs, not in `.md` skill content.
+- No specific game / project names inside skill bodies. Skills are universal. The same skill might be installed by a future user who never heard of your current project.
+- `[SUMMER]` markers on core Godot engine file edits in C++ changes. Skill `.md` files don't need them.
+- Verify before claiming. If a skill says "Summer Engine does X," verify in the actual code before writing it down.
+
+## When there's nothing worth capturing
+
+It's totally fine to come back with "session was tactical, no durable learnings worth a skill update." Don't manufacture skills from thin air. Better to ship nothing than ship noise.