summer-engine 2.3.0 → 2.6.0

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.

package/skills/workflow/investigating-bugs/CREATION-LOG.md

@@ -0,0 +1,119 @@
+# Creation Log: Systematic Debugging Skill
+
+Reference example of extracting, structuring, and bulletproofing a critical skill.
+
+## Source Material
+
+Extracted debugging framework from `~/.claude/CLAUDE.md`:
+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
+- Rules designed to resist time pressure and rationalization
+
+## Extraction Decisions
+
+**What to include:**
+- Complete 4-phase framework with all rules
+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
+- Concrete steps for each phase
+
+**What to leave out:**
+- Project-specific context
+- Repetitive variations of same rule
+- Narrative explanations (condensed to principles)
+
+## Structure Following skill-creation/SKILL.md
+
+1. **Rich when_to_use** - Included symptoms and anti-patterns
+2. **Type: technique** - Concrete process with steps
+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
+5. **Phase-by-phase breakdown** - Scannable checklist format
+6. **Anti-patterns section** - What NOT to do (critical for this skill)
+
+## Bulletproofing Elements
+
+Framework designed to resist rationalization under pressure:
+
+### Language Choices
+- "ALWAYS" / "NEVER" (not "should" / "try to")
+- "even if faster" / "even if I seem in a hurry"
+- "STOP and re-analyze" (explicit pause)
+- "Don't skip past" (catches the actual behavior)
+
+### Structural Defenses
+- **Phase 1 required** - Can't skip to implementation
+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
+- **Anti-patterns section** - Shows exactly what shortcuts look like
+
+### Redundancy
+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
+- "NEVER fix symptom" appears 4 times in different contexts
+- Each phase has explicit "don't skip" guidance
+
+## Testing Approach
+
+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
+
+### Test 1: Academic Context (No Pressure)
+- Simple bug, no time pressure
+- **Result:** Perfect compliance, complete investigation
+
+### Test 2: Time Pressure + Obvious Quick Fix
+- User "in a hurry", symptom fix looks easy
+- **Result:** Resisted shortcut, followed full process, found real root cause
+
+### Test 3: Complex System + Uncertainty
+- Multi-layer failure, unclear if can find root cause
+- **Result:** Systematic investigation, traced through all layers, found source
+
+### Test 4: Failed First Fix
+- Hypothesis doesn't work, temptation to add more fixes
+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
+
+**All tests passed.** No rationalizations found.
+
+## Iterations
+
+### Initial Version
+- Complete 4-phase framework
+- Anti-patterns section
+- Flowchart for "fix failed" decision
+
+### Enhancement 1: TDD Reference
+- Added link to skills/testing/test-driven-development
+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
+- Prevents confusion between methodologies
+
+## Final Outcome
+
+Bulletproof skill that:
+- ✅ Clearly mandates root cause investigation
+- ✅ Resists time pressure rationalization
+- ✅ Provides concrete steps for each phase
+- ✅ Shows anti-patterns explicitly
+- ✅ Tested under multiple pressure scenarios
+- ✅ Clarifies relationship to TDD
+- ✅ Ready for use
+
+## Key Insight
+
+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
+
+## Usage Example
+
+When encountering a bug:
+1. Load skill: skills/debugging/systematic-debugging
+2. Read overview (10 sec) - reminded of mandate
+3. Follow Phase 1 checklist - forced investigation
+4. If tempted to skip - see anti-pattern, stop
+5. Complete all phases - root cause found
+
+**Time investment:** 5-10 minutes
+**Time saved:** Hours of symptom-whack-a-mole
+
+---
+
+*Created: 2025-10-03*
+*Purpose: Reference example for skill extraction and bulletproofing*