summer-engine 1.2.1 → 1.3.1

package/dist/lib/skills-registry.js

@@ -5,26 +5,86 @@ export const AGENT_CLIENTS = [
     "cursor",
     "windsurf",
 ];
+export const SKILL_CATEGORIES = [
+    "_meta",
+    "character-controllers",
+    "gameplay-mechanics",
+    "scripting-patterns",
+    "scene-and-project",
+    "rendering-and-lighting",
+    "shaders",
+    "visual-effects",
+    "post-processing",
+    "animation",
+    "audio",
+    "physics",
+    "multiplayer-and-networking",
+    "ai-and-npcs",
+    "level-design",
+    "performance",
+    "ui-and-ux",
+    "asset-pipeline",
+    "input-and-controls",
+    "debugging",
+    "deployment",
+];
 const ALL_CLIENTS = AGENT_CLIENTS;
+/**
+ * Skills with `status: HAVE` in catalog.yaml. The catalog is the planning source
+ * of truth (~85 skills); this TS registry is the install-time list (only skills
+ * with shippable content). When a NEXT skill ships, mirror it here.
+ */
 export const SKILL_REGISTRY = [
+    {
+        name: "debug",
+        category: "debugging",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_console",
+            "summer_get_debugger_errors",
+            "summer_get_script_errors",
+            "summer_get_diagnostics",
+            "summer_clear_console",
+            "summer_play",
+            "summer_stop",
+            "summer_inspect_node",
+        ],
+        testScenario: "Triage a runtime crash end-to-end: read errors, locate code, propose fix, apply on approval, verify.",
+    },
+    {
+        name: "play",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_is_running",
+            "summer_play",
+            "summer_stop",
+            "summer_clear_console",
+            "summer_get_diagnostics",
+            "summer_get_debugger_errors",
+            "summer_get_script_errors",
+        ],
+        testScenario: "Run the game from a clean state, wait for first frame, report whether it runs cleanly or has errors.",
+    },
     {
         name: "gdscript-patterns",
+        category: "scripting-patterns",
         public: true,
-        category: "scripting",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
-            "summer_set_prop",
-            "summer_connect_signal",
-            "summer_input_map_bind",
             "summer_get_script_errors",
         ],
-        testScenario: "Create a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.",
+        testScenario: "Write a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.",
     },
     {
         name: "scene-composition",
+        category: "scene-and-project",
         public: true,
-        category: "scene",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -39,8 +99,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "fps-controller",
+        category: "character-controllers",
         public: true,
-        category: "gameplay",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -53,8 +113,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "3d-lighting",
+        category: "rendering-and-lighting",
         public: true,
-        category: "lighting",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -66,8 +126,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "ui-basics",
+        category: "ui-and-ux",
         public: true,
-        category: "ui",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -79,8 +139,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "asset-strategy",
+        category: "asset-pipeline",
         public: true,
-        category: "assets",
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
@@ -95,8 +155,8 @@ export const SKILL_REGISTRY = [
     },
     {
         name: "make-game",
+        category: "scene-and-project",
         public: true,
-        category: "workflow",
         clients: ALL_CLIENTS,
         recommended: false,
         requiresMcpTools: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",

package/skills/README.md

@@ -0,0 +1,96 @@
+# Summer Skill Library
+
+The canonical agent-readable game-dev knowledge source for Claude Code, Cursor, Codex, and Windsurf.
+
+When an agent is asked to make a game in Godot, this is what it reads to learn how.
+
+## Layout
+
+```
+skills/
+├── README.md                  # this file
+├── catalog.yaml               # canonical registry (name, category, status, template-id)
+├── _shared/                   # cross-skill references every skill can link
+│   ├── godot-version.md
+│   ├── mcp-tools-reference.md
+│   ├── collaborative-protocol.md
+│   ├── template-registry.md
+│   └── gd-style.md
+├── _meta/
+│   ├── skill-test/            # static + behavioral linter
+│   ├── skill-create/          # bootstrap a new skill
+│   └── skill-improve/         # eval-harness iteration
+├── _tests/
+│   ├── runner.md              # how /skill-test works
+│   └── specs/                 # behavioral specs per skill
+└── <category>/<skill>/
+    ├── SKILL.md               # < 500 lines, frontmatter + body
+    ├── references/            # loaded on demand
+    ├── examples/              # working snippets
+    └── tests/spec.md          # behavioral spec
+```
+
+## Categories (20)
+
+`character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+
+## Standard
+
+Adopts the **Anthropic Agent Skills open standard** (`agentskills.io`). Frontmatter:
+
+```yaml
+---
+name: <kebab-case>
+description: <when-to-use, key trigger phrases first>
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <one of the 20>
+template-id: <optional, resolved against _shared/template-registry.md>
+allowed-tools: Read Grep summer_add_node summer_set_prop ...
+paths: ["**/*.gd", "**/*.tscn"]
+---
+```
+
+Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
+
+## Authoring rules
+
+1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
+2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
+3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `_shared/collaborative-protocol.md`.
+4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
+5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.
+
+## Adding a new skill
+
+```
+/skill-create
+```
+
+(See `_meta/skill-create/SKILL.md`.)
+
+## Testing
+
+```
+/skill-test <name>           # static lint
+/skill-test <name> spec      # behavioral spec runner
+/skill-test audit            # whole-library audit
+/skill-improve <name>        # parallel-eval harness for iteration
+```
+
+(See `_meta/skill-test/SKILL.md` and `_tests/runner.md`.)
+
+## Roadmap
+
+Status legend in `catalog.yaml`:
+
+- **HAVE** — ships today.
+- **NEXT** — next wave, in active development.
+- **LATER** — on roadmap.
+
+Currently: **7 HAVE / ~50 NEXT / ~30 LATER ≈ 85 skills across 20 categories**. Subagents fill content category by category.
+
+## See also
+
+- [Architecture spec](../../../publicsummerengine/Docs/superpowers/specs/2026-05-05-skill-library-architecture.md) (lives in publicsummerengine for spec history)
+- [Research notes](../../../publicsummerengine/Docs/superpowers/research/2026-05-05-skill-library-research.md)

package/skills/_meta/skill-create/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: skill-create
+description: Bootstrap a new Summer skill with the canonical folder structure, frontmatter, and stub sections. Use when adding a new skill to the library. Trigger on "create skill", "add skill", "new skill".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Write Glob Grep
+---
+
+# /skill-create — Bootstrap a New Skill
+
+## Steps
+
+### 1. Get the basics
+
+Ask the user:
+- **Name** (kebab-case, ≤ 64 chars). Example: `state-machine-patterns`.
+- **Category** (one of the 20 in `catalog.yaml`). Example: `scripting-patterns`.
+- **One-sentence description** for the frontmatter.
+- **Template-id** (optional). Lookup against `_shared/template-registry.md`.
+
+### 2. Create the folder
+
+May I create `skills/<category>/<name>/` with this structure?
+
+```
+skills/<category>/<name>/
+├── SKILL.md
+├── references/        (empty, populate as needed)
+├── examples/          (empty, populate as needed)
+└── tests/spec.md
+```
+
+### 3. Write SKILL.md (template)
+
+```markdown
+---
+name: <name>
+description: <one-sentence what + when. Lead with key trigger phrases.>
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <category>
+template-id: <optional template-id from _shared/template-registry.md>
+allowed-tools: Read Grep <summer_* tools this skill uses>
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# <Title> for Summer Engine
+
+<One-paragraph context. Why this exists, who needs it.>
+
+## Steps
+
+### 1. <First step>
+
+**Preferred (Summer MCP):**
+
+\`\`\`
+summer_<tool>(...)
+\`\`\`
+
+**Fallback (no MCP — edit `<file>` directly):**
+
+\`\`\`
+<raw text/code>
+\`\`\`
+
+May I <action>?
+
+### 2. <Second step>
+
+...
+
+## Common mistakes
+
+- <mistake 1, with one-line fix>
+- <mistake 2, with one-line fix>
+
+## Want a working starter?
+
+→ **template-id**: `<template-id>`
+→ **Repo**: <github URL from _shared/template-registry.md>
+→ **Bootstrap**: `summer template clone <template-id> my-game`
+
+## See also
+
+- `_shared/godot-version.md`
+- `_shared/mcp-tools-reference.md`
+- `_shared/gd-style.md`
+- (other relevant skills)
+```
+
+### 4. Write tests/spec.md (template)
+
+```markdown
+# Skill Spec: /<name>
+
+## Fixture
+- <starting state of the project>
+- <which tools are available — Summer MCP yes/no>
+
+## Case 1: Happy Path
+**Input:** "<typical user prompt>"
+**Expected MCP tool sequence (in order):**
+1. <first tool call>
+2. <second>
+
+**Assertions:**
+- [ ] <observable outcome>
+- [ ] <skill asks "May I" before any write step>
+
+## Case 2: Failure / Edge
+**Fixture:** <something different>
+**Input:** "<edge prompt>"
+**Expected:** <how the skill should adapt>
+```
+
+### 5. Register in catalog.yaml
+
+Append:
+
+```yaml
+  - name: <name>
+    category: <category>
+    status: NEXT  # or HAVE if shipping immediately
+    template-id: <or omit>
+    public: true
+    recommended: false  # flip to true when status: HAVE and tested
+```
+
+### 6. Run /skill-test in static mode
+
+Confirm the new skill passes the 7 structural checks before commit.
+
+## Collaborative protocol
+
+This skill writes files (the new skill folder + catalog update). Always ask before each write step.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_meta/skill-test/SKILL.md`
+- `catalog.yaml`

package/skills/_meta/skill-improve/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: skill-improve
+description: Iterate on an existing Summer skill using a parallel-eval harness — run the skill against a behavioral spec with and without proposed changes, compare outputs, ship the version that wins. Use to upgrade a skill that's underperforming. Trigger on "improve skill", "iterate on skill", "make this skill better".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Write Edit Task
+---
+
+# /skill-improve — Iterate on a Skill With Eval Harness
+
+Inspired by `anthropics/skills` `skill-creator/`. Use when a skill's behavioral spec is failing assertions or producing low-quality output.
+
+## When to use this vs. `/skill-test`
+
+- `/skill-test spec` reasons over text. Cheap, fast, lossy.
+- `/skill-improve` actually runs the skill in parallel subagents with-vs-without proposed changes. Expensive, accurate.
+
+Run this when `/skill-test spec` flags issues you can't fix by reading the skill alone.
+
+## Steps
+
+### 1. Pick the skill + the spec
+
+Ask the user:
+- **Skill name.** Resolves to `skills/<category>/<name>/SKILL.md`.
+- **Test cases to focus on.** Default: all `## Case` blocks in `_tests/specs/<name>.md`.
+
+### 2. Establish a baseline
+
+For each Case:
+
+1. Spawn a subagent (`Task` tool, `general-purpose`) with the **current** skill body in context.
+2. Give it the Case's Input + Fixture.
+3. Capture the tool calls it makes and the diff it produces.
+4. Score against the Case's Assertions.
+
+Save outputs to `_tests/runs/<skill-name>/baseline/case-<N>/`.
+
+### 3. Propose changes
+
+Read the failing Cases. Identify the gap between what the skill says and what the agent did. Common gaps:
+
+- Skill names a tool but the agent picked a different one (clarify the trigger).
+- Skill assumes a fixture detail the agent missed (add explicit step to confirm).
+- Skill's "May I" wording is too generic for the agent to infer the right ask.
+
+Draft a revised SKILL.md. May I write it to `_tests/runs/<skill-name>/proposed/SKILL.md`?
+
+### 4. Run the proposed version
+
+Repeat step 2 with the proposed SKILL.md. Save to `_tests/runs/<skill-name>/proposed/case-<N>/`.
+
+### 5. Compare and decide
+
+For each Case, score:
+
+- Assertions passed (proposed vs. baseline).
+- Tool-call efficiency (fewer tools = better, all else equal).
+- Hallucination / unwanted ops (penalize).
+
+Output:
+
+```
+Case 1 (Happy):     baseline 4/6  proposed 6/6  ✓ ship proposed
+Case 2 (Failure):   baseline 3/4  proposed 4/4  ✓ ship proposed
+Case 3 (Edge):      baseline 3/3  proposed 3/3  = no change
+```
+
+If proposed wins on net, prompt the user:
+
+> Proposed version wins 2 cases, ties 1, loses 0. May I overwrite `skills/<category>/<name>/SKILL.md` with the proposed version and update `last-tested:` in `catalog.yaml`?
+
+### 6. Ship
+
+On user yes:
+- Overwrite `SKILL.md`.
+- Update `last-tested: <today>` in `catalog.yaml`.
+- Commit with message `feat(skill): improve <name> — <one-line summary of change>`.
+
+## Collaborative protocol
+
+This skill writes files at multiple steps. Always ask before each write.
+
+## See also
+
+- `_meta/skill-test/SKILL.md`
+- `_tests/runner.md`
+- `_tests/specs/`

package/skills/_meta/skill-test/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: skill-test
+description: Validate a Summer skill against static structural rules and per-skill behavioral specs. Use to lint a skill before commit, audit the whole library, or check a behavioral spec assertion. Trigger on "skill test", "lint skill", "validate skill".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Glob Grep
+---
+
+# /skill-test — Validate a Summer Skill
+
+Three modes. Pick by the user's intent.
+
+## Mode: `static` — Structural lint (default for "test this skill")
+
+For a single skill at `skills/<category>/<name>/`, run these checks:
+
+1. **Frontmatter completeness.** `name`, `description`, `license`, `compatibility`, `category` present. `name` matches the directory name.
+2. **SKILL.md length.** ≤ 500 lines. (Progressive disclosure rule from Anthropic spec.)
+3. **MCP-preferred + file-edit-fallback.** If the skill mutates scenes or resources, body must show both:
+   - At least one `summer_*` MCP tool example.
+   - At least one file-edit fallback block (e.g., raw `.tscn` snippet) OR an explicit "no fallback for this — Summer MCP required" note.
+4. **Collaborative protocol.** If the skill triggers user-visible writes, body must contain at least one of: `May I`, `I'm about to`, `Continue?`, `OK?`, `Proceed?`. Skills that only inspect/read are exempt.
+5. **Template-id resolved.** If the skill's frontmatter declares `template-id: <id>`, that id must exist in `_shared/template-registry.md`.
+6. **Tests/spec.md present.** Every skill in a non-`_meta` category must have `tests/spec.md` with at least one `## Case` heading.
+7. **No broken relative links.** Every `](../...)` and `](./...)` in the body must point at an existing file.
+
+Output:
+
+```
+skill: <category>/<name>
+  PASS  (1) frontmatter complete
+  PASS  (2) length 217 / 500 lines
+  FAIL  (3) no MCP-preferred example found in body
+  PASS  (4) collaborative protocol present
+  PASS  (5) template-id resolved
+  PASS  (6) tests/spec.md exists
+  PASS  (7) all relative links resolve
+
+6 PASS / 1 FAIL — fix item 3 before commit.
+```
+
+## Mode: `spec` — Behavioral spec runner
+
+For a single skill, read both `skills/<category>/<name>/SKILL.md` and `_tests/specs/<name>.md`. For each `## Case` in the spec:
+
+1. Lay out the **Fixture** (starting state, available tools).
+2. Read the **Input** (user prompt).
+3. Reason: given the skill's instructions and this fixture, would the agent follow the **Expected MCP tool sequence**?
+4. For each assertion under `**Assertions:**`, mark `[x]` if the skill's instructions would satisfy it, `[ ]` if not, with a one-line reason.
+
+Output: an annotated copy of the spec with assertions filled in, plus a pass-rate.
+
+No code execution. Pure reasoning over text.
+
+## Mode: `audit` — Whole library report
+
+Read `catalog.yaml`. For each skill with `status: HAVE`:
+
+1. Run `static` mode on the skill.
+2. Note the skill's `last-tested:` date.
+3. Flag skills where `last-tested:` is missing or older than 30 days.
+
+Output: a table with PASS / FAIL counts, last-tested ages, and a punch list of skills needing attention.
+
+## When to use which mode
+
+| User said | Mode |
+|---|---|
+| "test the fps-controller skill" | static |
+| "lint this skill" | static |
+| "does this skill actually do what it should?" | spec |
+| "run the behavioral check" | spec |
+| "audit the skill library" | audit |
+| "what skills need work" | audit |
+
+## Collaborative protocol
+
+This skill is **read-only**. It never writes. No "May I" needed.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/template-registry.md`
+- `_tests/runner.md`
+- `_tests/specs/` — per-skill behavioral specs

package/skills/_shared/collaborative-protocol.md

@@ -0,0 +1,50 @@
+# Collaborative Protocol — "May I write?"
+
+> Every Summer skill must follow this. The agent works *with* the user, not around them.
+
+## The rule
+
+**Before any user-visible write step, the agent must explicitly state what it is about to do and ask permission to proceed.**
+
+This applies to:
+- Creating files (`.gd`, `.tscn`, `.tres`, JSON, configs)
+- Modifying existing files (especially `.gd` and `.tscn`)
+- Running irreversible operations (deletion, reset, force-overwrite)
+- Setting up project-wide settings (`project.godot`)
+- Installing tools, libraries, or templates
+
+Reading is unconditional. Inspection, scene-tree walks, diagnostics — never need permission.
+
+## Phrasing
+
+Plain, short, action-first. Examples:
+
+> May I create `scenes/player.tscn` and add a CharacterBody3D + Camera3D?
+
+> I'm about to overwrite `levels/level_01.tscn`. The current version has 14 nodes — I'll preserve them and add the new lighting setup. Continue?
+
+> May I attach `scripts/player_controller.gd` to `./World/Player`?
+
+> I'm going to bind `move_forward`, `move_back`, `move_left`, `move_right`, `jump`. OK?
+
+## What this prevents
+
+1. **Silent overwrites.** The agent stomps the user's hand-edited script.
+2. **Cascading scope creep.** A "small fix" turns into a 30-file refactor.
+3. **Unclear state.** The user has no idea what changed when something breaks.
+4. **Trust loss.** One unauthorized edit and the user stops trusting the agent.
+
+## What this is NOT
+
+- Not a confirmation dialog for every property change in a single skill execution. Group related writes into one ask: "I'm about to add the player root, attach the controller script, and bind 5 input actions. OK?"
+- Not a request for design input. The skill should know what to do; the ask is for permission, not direction.
+- Not a stop on simple read-only ops or single-property tweaks the user clearly directed.
+
+## Linter check
+
+The `_meta/skill-test/SKILL.md` static linter looks for the phrases:
+- "May I" / "May I write" / "May I create" / "May I attach"
+- "I'm about to"
+- "Continue?" / "OK?" / "Proceed?"
+
+A skill that mutates files but never says any of these fails the linter.