summer-engine 1.3.1 → 1.4.0

package/hooks/pre-commit-doctor.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Summer Engine — Pre-commit doctor hook (OPT-IN)
+#
+# Event:    PreToolUse (matcher: Bash, if: "Bash(git commit*)")
+# Purpose:  Run `summer doctor` before any git commit Claude is about to make.
+#           Block the commit on FAIL. Allow with warnings on WARN.
+#
+# Status:   OPT-IN. Not registered in the Summer plugin manifest by default.
+#
+# To enable, add to ~/.claude/settings.json (or .claude/settings.json):
+#
+#   {
+#     "hooks": {
+#       "PreToolUse": [
+#         {
+#           "matcher": "Bash",
+#           "hooks": [
+#             {
+#               "type": "command",
+#               "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-commit-doctor.sh",
+#               "if": "Bash(git commit*)",
+#               "timeout": 15
+#             }
+#           ]
+#         }
+#       ]
+#     }
+#   }
+#
+# Then: chmod +x ${CLAUDE_PLUGIN_ROOT}/hooks/pre-commit-doctor.sh
+#
+# Input:    JSON on stdin: { tool_name, tool_input: { command, ... }, ... }
+# Output:   On FAIL: stderr explanation, exit 2 (blocks commit).
+#           On WARN: stderr warnings, exit 0 (allows commit).
+#           On PASS or no `summer` CLI: silent, exit 0.
+#
+# Portability: bash 3.2+, POSIX-friendly. jq optional.
+
+set +e
+
+INPUT=$(cat)
+
+# ---------- Parse the command ----------
+COMMAND=""
+if command -v jq >/dev/null 2>&1; then
+    COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+fi
+if [ -z "$COMMAND" ]; then
+    COMMAND=$(printf '%s' "$INPUT" \
+        | grep -oE '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
+        | head -1 \
+        | sed 's/^"command"[[:space:]]*:[[:space:]]*"//;s/"$//')
+fi
+
+# ---------- Bail early if not a git commit ----------
+if ! printf '%s' "$COMMAND" | grep -qE '^[[:space:]]*git[[:space:]]+commit'; then
+    exit 0
+fi
+
+# ---------- Bail if `summer` CLI missing ----------
+if ! command -v summer >/dev/null 2>&1; then
+    # Don't block — user may have installed via plugin only.
+    exit 0
+fi
+
+# ---------- Run doctor ----------
+DOCTOR_OUT=$(summer doctor --json 2>/dev/null)
+if [ -z "$DOCTOR_OUT" ]; then
+    exit 0
+fi
+
+# ---------- Parse status ----------
+HAS_FAIL=0
+HAS_WARN=0
+FAIL_MSGS=""
+WARN_MSGS=""
+
+if command -v jq >/dev/null 2>&1; then
+    FAIL_MSGS=$(printf '%s' "$DOCTOR_OUT" \
+        | jq -r '.checks[]? | select(.status == "FAIL") | "  - " + (.name // "?") + ": " + (.message // "")' 2>/dev/null)
+    WARN_MSGS=$(printf '%s' "$DOCTOR_OUT" \
+        | jq -r '.checks[]? | select(.status == "WARN") | "  - " + (.name // "?") + ": " + (.message // "")' 2>/dev/null)
+    [ -n "$FAIL_MSGS" ] && HAS_FAIL=1
+    [ -n "$WARN_MSGS" ] && HAS_WARN=1
+else
+    # Fallback: substring sniffing
+    if printf '%s' "$DOCTOR_OUT" | grep -q '"status"[[:space:]]*:[[:space:]]*"FAIL"'; then
+        HAS_FAIL=1
+        FAIL_MSGS=$(printf '%s' "$DOCTOR_OUT" \
+            | grep -oE '"status"[[:space:]]*:[[:space:]]*"FAIL"[^}]*"message"[[:space:]]*:[[:space:]]*"[^"]*"' \
+            | sed -E 's/.*"message"[[:space:]]*:[[:space:]]*"([^"]*)"/  - \1/')
+    fi
+    if printf '%s' "$DOCTOR_OUT" | grep -q '"status"[[:space:]]*:[[:space:]]*"WARN"'; then
+        HAS_WARN=1
+        WARN_MSGS=$(printf '%s' "$DOCTOR_OUT" \
+            | grep -oE '"status"[[:space:]]*:[[:space:]]*"WARN"[^}]*"message"[[:space:]]*:[[:space:]]*"[^"]*"' \
+            | sed -E 's/.*"message"[[:space:]]*:[[:space:]]*"([^"]*)"/  - \1/')
+    fi
+fi
+
+# ---------- FAIL: block ----------
+if [ "$HAS_FAIL" -eq 1 ]; then
+    {
+        echo "=== Summer doctor: FAIL — commit blocked ==="
+        echo "$FAIL_MSGS"
+        echo ""
+        echo "Fix the failures above, or run: summer doctor"
+        echo "To bypass once: disable the pre-commit-doctor hook in settings.json."
+        echo "============================================"
+    } >&2
+    exit 2
+fi
+
+# ---------- WARN: allow with notice ----------
+if [ "$HAS_WARN" -eq 1 ]; then
+    {
+        echo "=== Summer doctor: WARN — commit allowed ==="
+        echo "$WARN_MSGS"
+        echo "============================================"
+    } >&2
+fi
+
+exit 0

package/hooks/run-hook.cmd

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Cross-platform hook dispatcher.
+# Usage: run-hook.cmd <hook-name>
+# Reads stdin, forwards to <plugin-root>/hooks/<hook-name>.sh
+# On Windows, Claude Code / Cursor / Codex invoke this via Git-Bash.
+
+HOOK_NAME="$1"
+shift || true
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_SCRIPT="$HOOK_DIR/$HOOK_NAME.sh"
+
+if [ ! -f "$HOOK_SCRIPT" ]; then
+  # Missing hook = no-op (don't break the host).
+  exit 0
+fi
+
+if [ ! -x "$HOOK_SCRIPT" ]; then
+  # Not executable yet (likely fresh checkout). Fall back to bash invocation.
+  exec bash "$HOOK_SCRIPT" "$@"
+fi
+
+exec "$HOOK_SCRIPT" "$@"

package/hooks/session-start.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Summer Engine — SessionStart hook
+#
+# Event:    SessionStart (matcher: startup|clear|compact)
+# Purpose:  Orient Claude on every fresh Summer-enabled session.
+#           Detect Godot project + GameSoul + doctor health, surface a one-line
+#           Bob-style greeting as additional context.
+#
+# Input:    JSON on stdin with { session_id, source, model, cwd, ... }
+#           Common Claude Code env vars: $CLAUDE_PROJECT_DIR, $CLAUDE_PLUGIN_ROOT
+# Output:   JSON on stdout with hookSpecificOutput.additionalContext
+#           (also emits Cursor / Copilot CLI variants based on host env vars)
+# Exit:     Always 0 — never block session start.
+#
+# Portability: bash 3.2+ (macOS default), POSIX-friendly, works on Git Bash.
+#              Uses `grep -E` not `grep -P`. Falls back gracefully when jq
+#              and `summer` are missing.
+
+set +e  # Hooks must never kill the session.
+
+# ---------- Resolve project dir ----------
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ---------- Build the orientation lines (max 3) ----------
+LINES=()
+
+# Line 1: Summer ready + skill count
+SKILL_COUNT=""
+if command -v summer >/dev/null 2>&1; then
+    # `summer skills count` is best-effort; ignore failure
+    SKILL_COUNT=$(summer skills count 2>/dev/null | grep -oE '[0-9]+' | head -1)
+fi
+if [ -n "$SKILL_COUNT" ]; then
+    LINES+=("Summer ready. ${SKILL_COUNT} skills.")
+else
+    LINES+=("Summer ready.")
+fi
+
+# Line 2: Godot project + GameSoul one-liner (only if project.godot exists)
+if [ -f "${PROJECT_DIR}/project.godot" ]; then
+    PROJECT_NAME=$(grep -E '^config/name=' "${PROJECT_DIR}/project.godot" 2>/dev/null \
+        | head -1 | sed 's/^config\/name=//;s/^"//;s/"$//')
+    [ -z "$PROJECT_NAME" ] && PROJECT_NAME=$(basename "$PROJECT_DIR")
+
+    SOUL_FILE="${PROJECT_DIR}/.summer/GameSoul.md"
+    if [ -f "$SOUL_FILE" ]; then
+        # First non-empty, non-heading paragraph (one line)
+        SOUL_LINE=$(awk 'BEGIN{p=""} /^[^#[:space:]]/ && NF>0 {p=$0; exit} END{print p}' \
+            "$SOUL_FILE" 2>/dev/null | cut -c1-120)
+        if [ -n "$SOUL_LINE" ]; then
+            LINES+=("Godot project: ${PROJECT_NAME}. GameSoul: ${SOUL_LINE}")
+        else
+            LINES+=("Godot project: ${PROJECT_NAME}.")
+        fi
+    else
+        LINES+=("Godot project: ${PROJECT_NAME}.")
+    fi
+fi
+
+# Line 3: doctor FAIL one-liner (only on FAIL — silent on PASS/WARN)
+if command -v summer >/dev/null 2>&1; then
+    DOCTOR_OUT=$(summer doctor --json 2>/dev/null)
+    if [ -n "$DOCTOR_OUT" ]; then
+        FAIL_REASON=""
+        if command -v jq >/dev/null 2>&1; then
+            FAIL_REASON=$(printf '%s' "$DOCTOR_OUT" \
+                | jq -r 'first(.checks[]? | select(.status == "FAIL") | .message) // empty' 2>/dev/null)
+        else
+            # Crude fallback: first "message" near a "FAIL"
+            FAIL_REASON=$(printf '%s' "$DOCTOR_OUT" \
+                | grep -oE '"status"[[:space:]]*:[[:space:]]*"FAIL"[^}]*"message"[[:space:]]*:[[:space:]]*"[^"]*"' \
+                | head -1 \
+                | grep -oE '"message"[[:space:]]*:[[:space:]]*"[^"]*"' \
+                | sed 's/.*"message"[[:space:]]*:[[:space:]]*"//;s/"$//')
+        fi
+        if [ -n "$FAIL_REASON" ]; then
+            LINES+=("Summer setup needs attention: ${FAIL_REASON}. Run: summer doctor")
+        fi
+    fi
+fi
+
+# ---------- Compose context ----------
+CONTEXT=""
+for line in "${LINES[@]}"; do
+    if [ -z "$CONTEXT" ]; then CONTEXT="$line"
+    else CONTEXT="${CONTEXT}"$'\n'"$line"
+    fi
+done
+
+# Bail with empty JSON if we somehow have no lines
+if [ -z "$CONTEXT" ]; then
+    printf '{}\n'
+    exit 0
+fi
+
+# ---------- JSON-escape for embedding ----------
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+CONTEXT_ESC=$(escape_for_json "$CONTEXT")
+
+# ---------- Emit per-host shape ----------
+# Cursor: top-level additional_context (snake_case)
+# Claude Code: nested hookSpecificOutput.additionalContext
+# Copilot CLI / SDK standard: top-level additionalContext (camelCase)
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+    printf '{"additional_context":"%s"}\n' "$CONTEXT_ESC"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then
+    printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$CONTEXT_ESC"
+else
+    printf '{"additionalContext":"%s"}\n' "$CONTEXT_ESC"
+fi
+
+exit 0

package/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "summer",
+  "description": "Summer Engine plugins for Claude Code",
+  "owner": { "name": "Summer Engine", "email": "founders@summerengine.com" },
+  "plugins": [
+    {
+      "name": "summer",
+      "source": "./",
+      "version": "1.4.0",
+      "description": "AI game-dev studio: 19 skills under summer: namespace, MCP bridge, session-start + pre-commit hooks.",
+      "author": { "name": "Summer Engine", "email": "founders@summerengine.com" },
+      "category": "game-development",
+      "tags": ["game-dev", "godot", "ai-game-engine"],
+      "keywords": ["game-dev", "godot", "ai-game-engine", "skills"],
+      "brandColor": "#FF8F17",
+      "capabilities": ["Interactive", "Read", "Write"],
+      "defaultPrompt": [
+        "I want to make a game.",
+        "/summer:brainstorm-game"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",
@@ -25,7 +25,17 @@
   "files": [
     "dist/",
     "skills/",
-    "README.md"
+    "hooks/",
+    ".claude-plugin/",
+    ".cursor-plugin/",
+    ".codex-plugin/",
+    ".opencode/",
+    "gemini-extension.json",
+    "marketplace.json",
+    ".mcp.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -33,7 +43,7 @@
     "summer": "node dist/bin/summer.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm test"
   },
   "engines": {
     "node": ">=18"

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

@@ -23,7 +23,7 @@ For a single skill at `skills/<category>/<name>/`, run these checks:
 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.
+7. **Relative links resolve.** Every `](../_shared/...)`, `](../../_shared/...)`, `](./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.
 
 Output:
 

package/skills/_shared/summer-folder.md

@@ -0,0 +1,44 @@
+# `.summer/` Folder Convention
+
+> The canonical layout for project-scoped Summer state. Read this if you're authoring a skill that writes durable design output (briefs, art bible, level docs).
+
+## Files at the root of `.summer/`
+
+- `GameSoul.md` — the project brief. Created by `/summer:brainstorm-game`. Contains: name, one-sentence pitch, core loop, 3 mechanics max, art direction summary, scope. Updated whenever the game's high-level direction changes.
+- `art-bible.md` — visual style reference. Created by `/summer:art-direction`. Contains: palette (6–15 hex codes), mood adjectives, lighting plan, post-processing notes, do/don't list, references.
+- `audio-bible.md` — sonic identity. Created by `/summer:audio-direction`. Contains: music style + tempo range, SFX vocabulary (8 classes), dynamic music FSM, bus layout reference.
+
+## Subdirectories
+
+- `mechanics/<mechanic-name>.md` — one file per designed mechanic (e.g., `double-jump.md`, `parry.md`). Created by `/summer:design-mechanic`. Contains: input → response → feedback → failure modes → tunable parameters.
+- `levels/<level-name>.md` — one file per designed level. Created by `/summer:design-level`. Contains: teaching goal, pacing curve (5 beats), encounters, secrets, reward gating.
+- `npcs/<npc-name>.md` — one file per designed NPC. Created by `/summer:design-npc`. Contains: archetype, perception model, decision tree, escalation, defeat sequence.
+
+## Conventions
+
+- All filenames are lowercase, hyphens not underscores.
+- Skills MUST ask "May I write/update `.summer/<file>`?" before any write to this folder.
+- Skills MAY read existing files in `.summer/` without permission to ground their output in prior decisions.
+- The folder lives in the project root (sibling to `project.godot`).
+- Add `.summer/` to `.gitignore` if the user prefers it private; default is to commit it (game design lives with the game).
+
+## Skills that write here
+
+| Skill | Writes |
+|---|---|
+| `/summer:brainstorm-game` | `.summer/GameSoul.md` |
+| `/summer:art-direction` | `.summer/art-bible.md` |
+| `/summer:audio-direction` | `.summer/audio-bible.md` |
+| `/summer:design-mechanic` | `.summer/mechanics/<name>.md` |
+| `/summer:design-level` | `.summer/levels/<name>.md` |
+| `/summer:design-npc` | `.summer/npcs/<name>.md` |
+| `/summer:debug` | does NOT write here |
+| `/summer:play` | does NOT write here |
+| `/summer:vfx` | does NOT write here (VFX edits scenes/scripts) |
+| `/summer:tune-performance` | optionally writes `.summer/perf-notes.md` if user requests |
+| `/summer:setup-multiplayer` | optionally writes `.summer/multiplayer-architecture.md` |
+| `/summer:export-and-ship` | does NOT write here (writes export configs in `project.godot`) |
+
+## Linter check (future)
+
+Once `_meta/skill-test` gains an executable mode, it should validate that any skill writing to `.summer/` is documented in the table above.

package/skills/_tests/specs/art-direction.md

@@ -0,0 +1,115 @@
+# Skill Spec: /art-direction
+
+## Fixture
+
+- Godot 4.5 / Summer Engine project, main scene with `World/WorldEnvironment` and `World/Sun` (DirectionalLight3D) present.
+- `.summer/GameSoul.md` exists; brief: "Cozy farming sim, vertical slice scope."
+- No `.summer/art-bible.md` yet.
+- Summer MCP available.
+
+## Case 1: Happy Path — define art direction for cozy farming sim
+
+**Input:** "Help me define the art direction. References: Stardew Valley and Sable."
+
+**Expected MCP tool sequence (in order):**
+
+1. `Read .summer/GameSoul.md` — anchor
+2. (Skill notes: brief says "cozy", which forbids harsh contrast / saturated reds)
+3. (Skill walks: technique pick → palette (6-15 hex codes) → mood adjectives → lighting plan → post-processing rules → do/don't list)
+4. (Skill shows the bible inline)
+5. (Skill asks: "May I update `project.godot`'s default clear color to the palette primary, and enable MSAA 2x?")
+6. `summer_project_setting(key="rendering/environment/defaults/default_clear_color", value="Color(...)")`
+7. `summer_project_setting(key="rendering/anti_aliasing/quality/msaa_3d", value="2")`
+8. (Skill asks: "May I dial in the WorldEnvironment + Sun to the lighting plan?")
+9. `summer_inspect_node(path="./World/WorldEnvironment")`
+10. `summer_set_prop(...)` — adjustments + tonemap per the plan
+11. `summer_set_prop(path="./World/Sun", key="light_color", value="Color(...)")`
+12. (Skill asks: "May I create `.summer/art-bible.md` with this bible?")
+13. `Write .summer/art-bible.md`
+
+**Assertions:**
+
+- [ ] Skill reads `.summer/GameSoul.md` to anchor.
+- [ ] Skill enforces 2+ references — does not proceed with single reference.
+- [ ] Skill picks ONE rendering technique (does not allow blending without naming the conflict).
+- [ ] Palette has 6-15 hex codes; uses off-white (e.g., #f4ecdf) and off-black (e.g., #1f1a16) — flags pure #ffffff or #000000 if user pitches them.
+- [ ] Mood adjectives are concrete (e.g., "soft, hand-warmed, golden-hour"), not vague ("cool, atmospheric").
+- [ ] Lighting plan names DirectionalLight3D color, energy, angle; sky colors; ambient; never-rules.
+- [ ] Post-processing has explicit ON/OFF/value calls per item (Glow, SDFGI, SSAO, SSR, Tonemap, Vignette, Chromatic aberration, Film grain) — NOT a list of options.
+- [ ] DO and DON'T lists each have at least 5 specific, enforceable rules.
+- [ ] DON'T list explicitly forbids chromatic aberration, motion blur, lens flare unless mood justifies them.
+- [ ] Skill asks "May I ..." before any `summer_project_setting` or `summer_set_prop` call.
+- [ ] Skill writes `.summer/art-bible.md` only after asking.
+- [ ] Skill never calls `summer_set_resource_property` on an inline sub_resource (silent-fail trap).
+- [ ] Skill ends with routing to `/summer:audio-direction` or similar.
+
+## Case 2: Failure Path — mixed-technique pitch
+
+**Fixture:** Same as Case 1.
+
+**Input:** "I want PBR realistic characters in a toon-shaded world."
+
+**Expected behavior:**
+
+- Skill identifies the conflict explicitly: "Toon characters in a PBR world fight. The lighting that makes PBR read realistic crushes toon shading; the flat shading that makes toon read clean strips PBR's value."
+- Skill offers a hierarchy: "(a) PBR with toon outlines (one technique), (b) full-toon with PBR-feeling fabric (one technique), (c) accept the conflict and pick which side wins on which assets."
+- Skill does NOT silently pick or design two parallel pipelines.
+
+**Assertions:**
+
+- [ ] Skill names the technique conflict out loud.
+- [ ] Skill explains *why* the techniques fight (lighting interaction).
+- [ ] Skill forces the user to pick one primary technique.
+- [ ] No bible written until the technique is locked.
+
+## Case 3: Edge Case — user pitches pure white + pure black palette
+
+**Fixture:** Same as Case 1.
+
+**Input:** "Black-and-white only, super high contrast. Like Limbo."
+
+**Expected behavior:**
+
+- Skill recognizes the intent (high-contrast monochrome) but flags pure values: "Limbo isn't actually pure black — it's #0a0a0a to #f0f0f0 with subtle warm tint. Pure #000 + #fff makes UI text vibrate and reads as unintentional."
+- Skill offers a near-monochrome palette: e.g., #0a0a0a, #2a2a2a, #6e6e6e, #c0c0c0, #f0f0f0 with one accent color (often warm) reserved for a single mechanic-tied use.
+- Skill writes the bible with off-pure values and documents the single-accent rule in the DO list.
+
+**Assertions:**
+
+- [ ] Skill flags pure #000 / #fff as a red flag and corrects to off-pure values.
+- [ ] Bible includes at least one accent color reserved for mechanic-tied use.
+- [ ] Skill explains *why* (UI vibration, "looks unintentional") not just "use these values".
+
+## Case 4: No Summer MCP — file-edit fallback
+
+**Fixture:** Same as Case 1, but Summer MCP is unavailable.
+
+**Input:** "Define the art direction for my farming sim."
+
+**Expected behavior:**
+
+- Skill detects no MCP.
+- Walks the design beats normally.
+- Instead of `summer_project_setting`, prints the `project.godot` snippet for the user to paste:
+
+  ```
+  [rendering]
+  environment/defaults/default_clear_color=Color(0.227, 0.290, 0.227, 1)
+  anti_aliasing/quality/msaa_3d=2
+  ```
+
+- Instead of `summer_set_prop` on WorldEnvironment, prints the `.tscn` snippet for the user to paste into the main scene.
+- Still writes `.summer/art-bible.md` via host `Write`.
+- Asks "May I write ..." before each file write.
+
+**Assertions:**
+
+- [ ] Skill identifies that MCP is unavailable; does not blindly call `summer_*`.
+- [ ] Generated `project.godot` snippet uses correct INI section format.
+- [ ] Generated `.tscn` snippet for WorldEnvironment is parseable Godot 4.
+- [ ] Skill still writes `.summer/art-bible.md`.
+- [ ] Skill still asks "May I write ..." before each write.
+
+---
+
+This spec runs via `/skill-test art-direction spec` (see `_meta/skill-test/SKILL.md`).

package/skills/_tests/specs/audio-direction.md

@@ -0,0 +1,123 @@
+# Skill Spec: /audio-direction
+
+## Fixture
+
+- Godot 4.5 / Summer Engine project, default audio bus layout (Master only).
+- `.summer/GameSoul.md` exists; brief: "Cozy farming sim, vertical slice scope."
+- `.summer/art-bible.md` exists; mood: "soft, hand-warmed, golden-hour, painterly".
+- No `.summer/audio-bible.md` yet.
+- No `audio/` folder yet.
+- Summer MCP available.
+
+## Case 1: Happy Path — define audio direction for cozy farming sim
+
+**Input:** "Define the audio direction. References: Stardew Valley OST, Studio Ghibli scores, and Outer Wilds. Acoustic, organic SFX."
+
+**Expected MCP tool sequence (in order):**
+
+1. `Read .summer/GameSoul.md` — anchor to brief
+2. `Read .summer/art-bible.md` — anchor to visual mood
+3. (Skill notes the rhyme: "soft, hand-warmed, golden-hour" + acoustic references = acoustic / folk style as primary)
+4. (Skill walks: music style → tempo + key → SFX vocabulary (8 classes) → dynamic music plan with state machine → spatial + mix rules)
+5. (Skill shows the bible inline)
+6. (Skill asks: "May I create `audio/default_bus_layout.tres` with these buses: Master / Music / SFX / UI / Voice / Ambient / Reverb_Small / Reverb_Large / Reverb_Outdoor?")
+7. `Write audio/default_bus_layout.tres`
+8. `summer_project_setting(key="audio/buses/default_bus_layout", value="res://audio/default_bus_layout.tres")`
+9. (Skill asks: "May I create `.summer/audio-bible.md` with this bible?")
+10. `Write .summer/audio-bible.md`
+11. (Skill optionally asks: "May I generate first-pass SFX seeds for UI, pickup, damage?")
+12. (On yes) `summer_generate_audio(prompt="soft woody UI click, 80ms, no reverb", duration=0.1)` etc.
+
+**Assertions:**
+
+- [ ] Skill reads BOTH `.summer/GameSoul.md` AND `.summer/art-bible.md` to anchor.
+- [ ] Skill enforces 3+ references — does not proceed with one or two.
+- [ ] Skill picks ONE primary music style; if user pitches multiple, names the conflict.
+- [ ] Music section has explicit tempo range (BPM), key center, time signature — not "varies".
+- [ ] SFX vocabulary has 8 classes, each with character + examples + a DON'T rule.
+- [ ] DON'T rules include things like "no pure sine ding for pickup" and "no same footstep for all surfaces".
+- [ ] Dynamic music plan picks ONE model (layered / vertical / horizontal / procedural) — not a list.
+- [ ] Dynamic music plan defines a state machine with named states + transitions + crossfade times.
+- [ ] Spatial + mix section has concrete dB values, attenuation curve, max distance, master ceiling -1 dBTP.
+- [ ] Mix defaults to SFX 0 dB / Music -8 dB / UI -3 dB (SFX loudest).
+- [ ] Bus layout has at least Music, SFX, UI, Voice, Ambient + 1+ Reverb send buses.
+- [ ] Skill asks "May I ..." before any `Write`, `summer_project_setting`, or `summer_generate_audio` call.
+- [ ] Skill writes `.summer/audio-bible.md` only after asking.
+- [ ] Skill never calls `summer_set_resource_property` on an inline sub_resource (silent-fail trap).
+- [ ] Skill ends with routing to `/summer:design-mechanic` or implementation skill.
+
+## Case 2: Failure Path — references contradict the brief
+
+**Fixture:** Same as Case 1, but brief says "horror walking sim".
+
+**Input:** "References: Mario 64 OST, A Hat in Time, Banjo-Kazooie. Bouncy chiptune."
+
+**Expected behavior:**
+
+- Skill identifies the conflict: "Brief says horror; references are bright N64 platformer scores. Those want opposite shapes — horror wants ambient drone or industrial; bouncy chiptune undercuts dread."
+- Skill asks the user to resolve: "(a) keep horror brief, change references to ambient/industrial, (b) keep bouncy references, change brief away from horror, or (c) intentional juxtaposition (rare; works in 1 in 50 games — Undertale, Buckshot Roulette)."
+- Skill does NOT silently pick or design a "horror chiptune" hybrid without flagging the friction.
+
+**Assertions:**
+
+- [ ] Skill names the brief vs. references conflict explicitly.
+- [ ] Skill explains *why* the shapes oppose.
+- [ ] Skill offers (c) intentional juxtaposition as a valid but rare path.
+- [ ] No bible written until the user resolves.
+
+## Case 3: Edge Case — user wants no music
+
+**Fixture:** Same as Case 1.
+
+**Input:** "Reference: Inside, Limbo. No music — just diegetic sound and ambience."
+
+**Expected behavior:**
+
+- Skill accepts "no music" as a valid direction (those references genuinely use it).
+- Skill replaces the dynamic music plan section with a "Diegetic-only ambience plan":
+  - Named ambience layers (room tone / wind / distant water / heart-rate-tied sub-bass when tense)
+  - Rules for when sub-bass enters (proximity to threat) and exits
+  - SFX still gets all 8 vocabulary classes (with extra weight on the "Ambient layer" class)
+- Skill keeps the bus layout but removes the Music bus or marks it "reserved (unused in v1)".
+- Skill notes the trade-off: "Diegetic-only is harder to make feel paced — every level needs an ambient arc that does what music would normally do."
+
+**Assertions:**
+
+- [ ] Skill does NOT force a music style on a no-music game.
+- [ ] Bible has a Diegetic / ambience plan section instead of (or supplementing) Dynamic music plan.
+- [ ] Bus layout reflects the choice (no Music bus or marked reserved).
+- [ ] Skill flags the trade-off: pacing is now ambience's job.
+
+## Case 4: No Summer MCP — file-edit fallback
+
+**Fixture:** Same as Case 1, but Summer MCP is unavailable.
+
+**Input:** "Define the audio direction for my cozy farming sim."
+
+**Expected behavior:**
+
+- Skill detects no MCP.
+- Walks the design beats normally.
+- Instead of `summer_project_setting`, prints the `project.godot` snippet for the user to paste:
+
+  ```
+  [audio]
+  buses/default_bus_layout="res://audio/default_bus_layout.tres"
+  ```
+
+- Generates `audio/default_bus_layout.tres` content as plain text for the user to save (Godot's `.tres` resource format with bus entries).
+- Writes `.summer/audio-bible.md` via host `Write`.
+- Does NOT call `summer_generate_audio` — instead suggests external SFX library searches or asks the user to handle generation later.
+- Asks "May I write ..." before each file write.
+
+**Assertions:**
+
+- [ ] Skill identifies that MCP is unavailable; does not blindly call `summer_*`.
+- [ ] Generated `project.godot` snippet uses correct INI section format.
+- [ ] Generated `default_bus_layout.tres` is valid Godot 4 resource format.
+- [ ] Skill still writes `.summer/audio-bible.md`.
+- [ ] Skill does not attempt audio generation when generation tools are unavailable.
+
+---
+
+This spec runs via `/skill-test audio-direction spec` (see `_meta/skill-test/SKILL.md`).