summer-engine 2.7.0 → 2.8.0

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

@@ -15,9 +15,9 @@ allowed-tools: Read Write Glob Grep
 
 Ask the user:
 - **Name** (kebab-case, ≤ 64 chars). Example: `state-machine-patterns`.
-- **Category** (one of the 20 in `SKILL_CATEGORIES` at `src/lib/skills-registry.ts`). Example: `scripting-patterns`.
+- **Category** (must be one of the values in the `SKILL_CATEGORIES` array at `src/lib/skills-registry.ts` — read it, do not guess). Example: `scripting-patterns`.
 - **One-sentence description** for the frontmatter.
-- **Template-id** (optional). Lookup against `references/template-registry.md`.
+- **Template-id** (optional). Lookup against `../../../references/template-registry.md`.
 
 ### 2. Create the folder
 
@@ -80,13 +80,13 @@ May I <action>?
 
 → **template-id**: `<template-id>`
 → **Repo**: <github URL from references/template-registry.md>
-→ **Bootstrap**: `summer template clone <template-id> my-game`
+→ **Bootstrap**: `summer create <template-id> my-game` (see `summer list templates` for the slugs)
 
 ## See also
 
-- `references/godot-version.md`
-- `references/mcp-tools-reference.md`
-- `references/gd-style.md`
+- `../../../references/godot-version.md`
+- `../../../references/mcp-tools-reference.md`
+- `../../../references/gd-style.md`
 - (other relevant skills)
 ```
 
@@ -149,5 +149,5 @@ This skill writes files (the new skill folder + plugin manifest update + TS regi
 
 ## See also
 
-- `references/collaborative-protocol.md`
+- `../../../references/collaborative-protocol.md`
 - `workflow/skill-test/SKILL.md`

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

@@ -21,7 +21,7 @@ For a single skill at `skills/<category>/<name>/`, run these checks:
    - 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 `references/template-registry.md`.
+5. **Template-id resolved.** If the skill's frontmatter declares `template-id: <id>`, that id must exist in `../../../references/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. **Relative links resolve.** Every `](../references/...)`, `](../../references/...)`, `](./references/...)`, and `](./examples/...)` link must point at an existing file (FAIL if broken). Forward references in `## See also` to other SKILL.md files (e.g., `[design-mechanic](../../gameplay-mechanics/design-mechanic/SKILL.md)`) are allowed to dangle and only WARN if the target is missing — the catalog evolves and skills should be free to point at planned skills.
 
@@ -80,7 +80,7 @@ This skill is **read-only**. It never writes. No "May I" needed.
 
 ## See also
 
-- `references/collaborative-protocol.md`
-- `references/template-registry.md`
+- `../../../references/collaborative-protocol.md`
+- `../../../references/template-registry.md`
 - `tests/runner.md`
 - `tests/specs/` — per-skill behavioral specs

package/skills/workflow/using-summer/SKILL.md

@@ -38,10 +38,20 @@ Two layers:
 - **Skills** — discipline guides that fire on specific situations: brainstorming a game, designing a mechanic, building an FPS controller, debugging a crash, shipping a build. Each one is a SKILL.md you load via the Skill tool.
 - **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), whole-project sync to Summer Cloud (`summer_cloud_push`, `summer_cloud_pull`; see `summer:summer-cloud`), and 30+ more.
 
-**Scripting language:** Summer Engine is compatible with Godot 4.5. You can write game code in either:
+**Scripting language:** The user is making a Summer game with the Summer SDK.
+GDScript is the default creator language. Summer currently uses the 4.6.1
+upstream technical base, plans to adopt 4.7.1 next, and follows upstream
+continuously. Confirm version-sensitive behavior from the engine's own version
+string rather than turning that base into the product identity. You can write
+game code in either:
 
 - **GDScript** (`.gd`) — the default. Best supported by Summer skills (see `summer:gdscript-patterns`). Use this unless the user has explicitly chosen C#.
-- **C#** (`.cs`) — fully supported by the engine. There is no `summer:csharp-patterns` skill yet — when writing C#, use the Godot 4.5 C# API from first principles. The patterns are different (different lifecycle method names, different signal API, different export attributes), so don't blindly translate GDScript idioms. Confirm with the user that they want C# before producing it; switching languages mid-project is painful.
+- **C#** (`.cs`) — supported by the shipped Mono build. There is no
+  `summer:csharp-patterns` skill yet. When writing C#, use the upstream C# API
+  reference matching the current Summer technical base. The lifecycle, signal
+  API, and export attributes differ, so do not blindly translate GDScript
+  idioms. Confirm that the user wants C# before producing it; switching
+  languages mid-project is painful.
 
 Scenes are always `.tscn`/`.scn`. Resources are always `.tres`/`.res`. Drive the engine through `summer_*` tools — do not hand-edit `.tscn` files; the editor holds in-memory state that diverges from disk.
 

package/skills/workflow/verification-before-completion/SKILL.md

@@ -45,6 +45,7 @@ Skip any step = lying, not verifying
 | Linter clean | Linter output: 0 errors | Partial check, extrapolation |
 | Build succeeds | Build command: exit 0 | Linter passing, logs look good |
 | Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Gameplay behaviour works | `RunVerification` probe: pressed the input, read the state back | Script compiles, game boots, diagnostics clean |
 | Regression test works | Red-green cycle verified | Test passes once |
 | Agent completed | VCS diff shows changes | Agent reports "success" |
 | Requirements met | Line-by-line checklist | Tests passing |
@@ -72,6 +73,7 @@ Skip any step = lying, not verifying
 | "I'm tired" | Exhaustion ≠ excuse |
 | "Partial check is enough" | Partial proves nothing |
 | "Different words so rule doesn't apply" | Spirit over letter |
+| "There's no way to test gameplay, I'll ask the user" | There is. A `RunVerification` probe presses input and reads state back. Ask the user only for what a probe cannot judge. |
 
 ## Key Patterns
 

package/skills/workflow/writing-plans/SKILL.md

@@ -13,7 +13,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
-**Context:** If working in an isolated worktree, it should have been created via the `summer:using-git-worktrees` skill at execution time.
+**Context:** If the work needs isolation from the current checkout, create a git worktree for it before execution starts.
 
 **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
 - (User preferences for plan location override this default)
@@ -49,7 +49,7 @@ This structure informs the task decomposition. Each task should produce self-con
 ```markdown
 # [Feature Name] Implementation Plan
 
-> **For agentic workers:** REQUIRED SUB-SKILL: Use summer:subagent-driven-development (recommended) or summer:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+> **For agentic workers:** implement this plan task-by-task, in order, checking off each step as it lands. Steps use checkbox (`- [ ]`) syntax for tracking. Dispatch a fresh subagent per task where the tasks are independent (see summer:dispatching-parallel-agents), otherwise execute inline with a review checkpoint after each task.
 
 **Goal:** [One sentence describing what this builds]
 
@@ -139,14 +139,14 @@ After saving the plan, offer execution choice:
 
 **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
 
-**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+**2. Inline Execution** - Execute tasks in this session, batched with checkpoints
 
 **Which approach?"**
 
 **If Subagent-Driven chosen:**
-- **REQUIRED SUB-SKILL:** Use summer:subagent-driven-development
-- Fresh subagent per task + two-stage review
+- One fresh subagent per task, each given the task's full text and nothing else from this session's history. See `summer:dispatching-parallel-agents` for prompt structure and when parallelism is safe.
+- Two-stage review: read the subagent's summary, then verify the diff yourself before starting the next task.
 
 **If Inline Execution chosen:**
-- **REQUIRED SUB-SKILL:** Use summer:executing-plans
-- Batch execution with checkpoints for review
+- Execute tasks in order in this session, stopping at a checkpoint after each task for review.
+- Never batch past a failing step. Fix it, verify it, then continue.

package/skills/workflow/writing-skills/SKILL.md

@@ -15,7 +15,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel
 
 **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
 
-**REQUIRED BACKGROUND:** You MUST understand summer:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
+**REQUIRED BACKGROUND:** This skill adapts the RED-GREEN-REFACTOR cycle to documentation. The cycle: write the test first and watch it FAIL for the reason you expect (red), make the smallest change that passes it (green), then clean up without changing behaviour (refactor). A test you never saw fail proves nothing.
 
 **Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
 
@@ -280,10 +280,12 @@ wc -w skills/path/SKILL.md
 **When writing documentation that references other skills:**
 
 Use skill name only, with explicit requirement markers:
-- ✅ Good: `**REQUIRED SUB-SKILL:** Use summer:test-driven-development`
+- ✅ Good: `**REQUIRED SUB-SKILL:** Use summer:verification-before-completion`
 - ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand summer:investigating-bugs`
-- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
-- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
+- ❌ Bad: `See skills/debugging/debug` (unclear if required)
+- ❌ Bad: `@skills/debugging/debug/SKILL.md` (force-loads, burns context)
+
+**Check the skill exists before you point at it.** The registry of shipped skills is the `SKILL_REGISTRY` array in `src/lib/skills-registry.ts` and the `skills:` array in `.claude-plugin/plugin.json`. A `REQUIRED SUB-SKILL` pointing at a skill that was never shipped is worse than no cross-reference: the reader stops and looks for something that does not exist.
 
 **Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
 
@@ -390,7 +392,7 @@ Edit skill without testing? Same violation.
 - Don't "adapt" while running tests
 - Delete means delete
 
-**REQUIRED BACKGROUND:** The summer:test-driven-development skill explains why this matters. Same principles apply to documentation.
+**Why this matters:** an untested change is an assertion, not a result. Same principle in documentation as in code.
 
 ## Testing All Skill Types
 

package/skills/workflow/writing-skills/testing-skills-with-subagents.md

@@ -10,7 +10,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres
 
 **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
 
-**REQUIRED BACKGROUND:** You MUST understand summer:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
+**REQUIRED BACKGROUND:** the RED-GREEN-REFACTOR cycle as stated just above. This reference supplies the skill-specific test formats on top of it (pressure scenarios, rationalization tables).
 
 **Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.