spawnpack 0.1.8 → 0.1.10

package/README.md

@@ -20,7 +20,7 @@ It generates BP/RP structure, optional Script API setup, optional rgl integratio
 - Optional AI setup:
   - `CLAUDE.md` for Claude
   - `AGENTS.md` for Other
-  - `.mcp.json`
+  - `.mcp.json` with keyless MCP servers
 
 ## Runtime Requirement
 
@@ -97,6 +97,18 @@ Depending on your choices, Spawnpack can generate:
 - `CLAUDE.md`
 - `AGENTS.md`
 - `.mcp.json`
+
+## AI MCP setup
+
+When AI setup is enabled, Spawnpack generates an `.mcp.json` that works out of the box without API keys.
+
+Generated MCP servers currently include:
+
+- Exa hosted MCP (`https://mcp.exa.ai/mcp`) for free, rate-limited web/documentation search
+- `grep_app` for code search
+- `context7` for library documentation context
+
+You can add your own Exa API key later if you need higher Exa limits, but it is not required for the generated scaffold.
 
 ## Marketplace structure mode
 
@@ -139,6 +151,7 @@ bun run build
 The npm package is configured to publish only:
 
 - `dist/spawnpack.js`
+- `bin/spawnpack.js`
 - `templates/CLAUDE.md`
 - `templates/AGENTS.md`
 - `README.md`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "spawnpack",
-    "version": "0.1.8",
+    "version": "0.1.10",
     "description": "Minecraft Bedrock addon project generator — scaffold your BP+RP in seconds",
     "author": "veedy-dev",
     "license": "MIT",

package/templates/AGENTS.md

@@ -160,6 +160,37 @@ For non-trivial changes: pause and ask "is there a more elegant way?" If a fix f
 Write code that reads like a human wrote it. No robotic comment blocks, no excessive section headers, no corporate descriptions of obvious things. If three experienced devs would all write it the same way, that's the way.
 </behavior>
 
+<code_style name="boring_durable_addon_code" priority="high">
+Prefer code that is easy for an add-on developer to read top-to-bottom. Use boring, linear code as the default; add durability machinery only at persistence, async timing, entity lifecycle, duplication, or data-loss boundaries.
+
+Style rules:
+- Write linear, imperative code by default: do A, then B, then C.
+- Prefer guard clauses and early returns over nested branching.
+- Keep behavior close to where it happens.
+- Avoid framework-like abstractions unless they clearly reduce repeated complexity.
+- Prefer explicit state names over clever generic names.
+- Make the happy path obvious.
+- Split code by real gameplay/lifecycle responsibility, not by abstract pattern.
+- Do not hide important game-state transitions behind vague helpers.
+- If durability/data-loss protection requires complexity, isolate it behind a small, boring API.
+- Keep normal gameplay code simple even when the persistence/lifecycle layer underneath is more defensive.
+- Do not copy another contributor's style blindly; use their readability as a reference while preserving correctness.
+- Prefer one obvious source of truth for each piece of state.
+- Before adding a new helper/class/system, ask: "Will this make the next maintainer understand the code faster?"
+</code_style>
+
+<implementation_preference name="minimal_safe_patch" priority="high">
+When fixing bugs:
+1. First find the smallest clear fix near the bug.
+2. Add stronger safety only where data loss, duplication, or invalid world state can happen.
+3. Avoid broad lifecycle rewrites unless the current lifecycle is the root cause.
+4. If a durable solution needs more machinery, keep the public flow simple and document the responsibility through naming, not comments.
+</implementation_preference>
+
+<behavior name="use_simplify_skill_for_maintainability" priority="high">
+Use the `simplify` skill for maintainability, not only cleanup. When the user asks to simplify, clean up, refactor for readability, reduce complexity, or make code easier to maintain, load `simplify` before planning or editing. For non-trivial implementation work, use `simplify` as a post-implementation review pass before final verification: check whether the new code can be made more obvious, boring, local, and behavior-preserving. In orchestrated workflows, explicitly include this maintainability review after implementation and before reporting completion. For broad codebase cleanup, audit first, propose small phases, and wait for approval before editing.
+</behavior>
+
 <behavior name="dead_code_hygiene" priority="medium">
 After refactoring or implementing changes:
 - Identify code that is now unreachable
@@ -215,27 +246,37 @@ PLAN:
 ALWAYS use Exa to search the latest Minecraft Script API documentation before implementing. APIs change every major update — never trust memory.
 </guideline>
 
-<guideline name="no_try_catch" priority="critical">
-Do NOT use `try-catch` blocks (overhead concerns). Use **guard clauses** for error prevention instead.
-
-```typescript
-// ✅ CORRECT: Use guard clauses
-function processBlock(block: Block | undefined): void {
+<guideline name="guard_first_error_handling" priority="critical">
+Prefer **guard clauses** for predictable invalid state: missing values, unloaded or invalid entities, optional components, permissions, and known preconditions. `throw`, `try`, and `catch` are allowed when they are truly necessary: APIs can fail despite correct guards, you are crossing IO/persistence/parsing/async boundaries, or you need cleanup, recovery, or clearer error context.
+
+Keep `catch` blocks narrow and purposeful. Do not use `try-catch` as normal control flow, to hide mistakes, or where a simple guard makes the failure impossible.
+
+```typescript
+// ✅ CORRECT: Use guard clauses
+function processBlock(block: Block | undefined): void {
   if (!block) return;
   if (!block.isValid) return;
   const permutation = block.permutation;
-}
-
-// ❌ WRONG: Using try-catch
-function processBlockBad(block: Block): void {
-  try {
-    const permutation = block.permutation;
-  } catch (e) {
-    // Overhead!
-  }
-}
-```
-</guideline>
+}
+
+// ✅ CORRECT: Use try-catch only at a real failure boundary
+function loadSavedConfig(rawConfig: string): AddonConfig {
+  try {
+    return JSON.parse(rawConfig) as AddonConfig;
+  } catch (error) {
+    throw new Error("Saved addon config is not valid JSON", { cause: error });
+  }
+}
+
+// ❌ WRONG: Catching instead of checking known state
+function processBlockBad(block: Block | undefined): void {
+  try {
+    const permutation = block!.permutation;
+  } catch {
+  }
+}
+```
+</guideline>
 
 <guideline name="typescript_verification" priority="critical">
 ALWAYS run `tsc --noEmit` after implementing. Ensure **zero warnings, zero errors, and no unused variables/imports**.
@@ -364,7 +405,7 @@ ALWAYS use Minecraft Bedrock Edition JSON Schemas for validation of BP/RP JSON f
 - Use explicit return types on functions
 - Use `readonly` for immutable properties
 - Prefer interfaces over type aliases for object shapes
-- Use `undefined` checks instead of try-catch
+- Use `undefined` checks and guard clauses before reaching for try-catch
 </best_practices>
 
 <best_practices name="script_api">
@@ -567,7 +608,7 @@ POTENTIAL CONCERNS:
 13. Editing files from stale context without re-reading first
 14. Duplicating state instead of fixing the real problem
 15. Writing library/framework code from memory without searching Exa for current docs first
-16. Using try-catch in Minecraft Script API code
+16. Using broad try-catch in Minecraft Script API code where guard clauses would be clearer
 17. Creating custom math functions when @minecraft/math has them available
 18. Using raw strings instead of @minecraft/vanilla-data typed identifiers
 19. Writing BP/RP JSON files without schema validation
@@ -583,7 +624,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
 2. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
 3. **PLAN BEFORE BUILD** — Spec and approval before implementation
-4. **GUARD CLAUSES** — Never use try-catch in Minecraft code
+4. **GUARD CLAUSES FIRST** — Prefer guards; use throw/try-catch only at real failure boundaries
 5. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
 6. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
 7. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
@@ -594,7 +635,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 - ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
 - ❌ Edited a file from memory after 10+ messages without re-reading? → Violated context decay rule
 - ❌ Started building without plan approval on a non-trivial task? → Violated plan-build separation
-- ❌ Used try-catch in Minecraft code? → Violated no-try-catch rule
+- ❌ Used broad try-catch where guards would work? → Violated guard-first error handling
 - ❌ Made changes without running `tsc --noEmit`? → Violated TypeScript verification
 - ❌ Created custom math function without checking @minecraft/math? → Violated library-first rule
 - ❌ Used raw string like `"inventory"` or `"minecraft:wolf"`? → Violated vanilla-data rule

package/templates/CLAUDE.md

@@ -160,6 +160,37 @@ For non-trivial changes: pause and ask "is there a more elegant way?" If a fix f
 Write code that reads like a human wrote it. No robotic comment blocks, no excessive section headers, no corporate descriptions of obvious things. If three experienced devs would all write it the same way, that's the way.
 </behavior>
 
+<code_style name="boring_durable_addon_code" priority="high">
+Prefer code that is easy for an add-on developer to read top-to-bottom. Use boring, linear code as the default; add durability machinery only at persistence, async timing, entity lifecycle, duplication, or data-loss boundaries.
+
+Style rules:
+- Write linear, imperative code by default: do A, then B, then C.
+- Prefer guard clauses and early returns over nested branching.
+- Keep behavior close to where it happens.
+- Avoid framework-like abstractions unless they clearly reduce repeated complexity.
+- Prefer explicit state names over clever generic names.
+- Make the happy path obvious.
+- Split code by real gameplay/lifecycle responsibility, not by abstract pattern.
+- Do not hide important game-state transitions behind vague helpers.
+- If durability/data-loss protection requires complexity, isolate it behind a small, boring API.
+- Keep normal gameplay code simple even when the persistence/lifecycle layer underneath is more defensive.
+- Do not copy another contributor's style blindly; use their readability as a reference while preserving correctness.
+- Prefer one obvious source of truth for each piece of state.
+- Before adding a new helper/class/system, ask: "Will this make the next maintainer understand the code faster?"
+</code_style>
+
+<implementation_preference name="minimal_safe_patch" priority="high">
+When fixing bugs:
+1. First find the smallest clear fix near the bug.
+2. Add stronger safety only where data loss, duplication, or invalid world state can happen.
+3. Avoid broad lifecycle rewrites unless the current lifecycle is the root cause.
+4. If a durable solution needs more machinery, keep the public flow simple and document the responsibility through naming, not comments.
+</implementation_preference>
+
+<behavior name="use_simplify_skill_for_maintainability" priority="high">
+Use the `simplify` skill for maintainability, not only cleanup. When the user asks to simplify, clean up, refactor for readability, reduce complexity, or make code easier to maintain, load `simplify` before planning or editing. For non-trivial implementation work, use `simplify` as a post-implementation review pass before final verification: check whether the new code can be made more obvious, boring, local, and behavior-preserving. In orchestrated workflows, explicitly include this maintainability review after implementation and before reporting completion. For broad codebase cleanup, audit first, propose small phases, and wait for approval before editing.
+</behavior>
+
 <behavior name="dead_code_hygiene" priority="medium">
 After refactoring or implementing changes:
 - Identify code that is now unreachable
@@ -215,27 +246,37 @@ PLAN:
 ALWAYS use Exa to search the latest Minecraft Script API documentation before implementing. APIs change every major update — never trust memory.
 </guideline>
 
-<guideline name="no_try_catch" priority="critical">
-Do NOT use `try-catch` blocks (overhead concerns). Use **guard clauses** for error prevention instead.
-
-```typescript
-// ✅ CORRECT: Use guard clauses
-function processBlock(block: Block | undefined): void {
+<guideline name="guard_first_error_handling" priority="critical">
+Prefer **guard clauses** for predictable invalid state: missing values, unloaded or invalid entities, optional components, permissions, and known preconditions. `throw`, `try`, and `catch` are allowed when they are truly necessary: APIs can fail despite correct guards, you are crossing IO/persistence/parsing/async boundaries, or you need cleanup, recovery, or clearer error context.
+
+Keep `catch` blocks narrow and purposeful. Do not use `try-catch` as normal control flow, to hide mistakes, or where a simple guard makes the failure impossible.
+
+```typescript
+// ✅ CORRECT: Use guard clauses
+function processBlock(block: Block | undefined): void {
   if (!block) return;
   if (!block.isValid) return;
   const permutation = block.permutation;
-}
-
-// ❌ WRONG: Using try-catch
-function processBlockBad(block: Block): void {
-  try {
-    const permutation = block.permutation;
-  } catch (e) {
-    // Overhead!
-  }
-}
-```
-</guideline>
+}
+
+// ✅ CORRECT: Use try-catch only at a real failure boundary
+function loadSavedConfig(rawConfig: string): AddonConfig {
+  try {
+    return JSON.parse(rawConfig) as AddonConfig;
+  } catch (error) {
+    throw new Error("Saved addon config is not valid JSON", { cause: error });
+  }
+}
+
+// ❌ WRONG: Catching instead of checking known state
+function processBlockBad(block: Block | undefined): void {
+  try {
+    const permutation = block!.permutation;
+  } catch {
+  }
+}
+```
+</guideline>
 
 <guideline name="typescript_verification" priority="critical">
 ALWAYS run `tsc --noEmit` after implementing. Ensure **zero warnings, zero errors, and no unused variables/imports**.
@@ -364,7 +405,7 @@ ALWAYS use Minecraft Bedrock Edition JSON Schemas for validation of BP/RP JSON f
 - Use explicit return types on functions
 - Use `readonly` for immutable properties
 - Prefer interfaces over type aliases for object shapes
-- Use `undefined` checks instead of try-catch
+- Use `undefined` checks and guard clauses before reaching for try-catch
 </best_practices>
 
 <best_practices name="script_api">
@@ -567,7 +608,7 @@ POTENTIAL CONCERNS:
 13. Editing files from stale context without re-reading first
 14. Duplicating state instead of fixing the real problem
 15. Writing library/framework code from memory without searching Exa for current docs first
-16. Using try-catch in Minecraft Script API code
+16. Using broad try-catch in Minecraft Script API code where guard clauses would be clearer
 17. Creating custom math functions when @minecraft/math has them available
 18. Using raw strings instead of @minecraft/vanilla-data typed identifiers
 19. Writing BP/RP JSON files without schema validation
@@ -583,7 +624,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
 2. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
 3. **PLAN BEFORE BUILD** — Spec and approval before implementation
-4. **GUARD CLAUSES** — Never use try-catch in Minecraft code
+4. **GUARD CLAUSES FIRST** — Prefer guards; use throw/try-catch only at real failure boundaries
 5. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
 6. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
 7. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
@@ -594,7 +635,7 @@ You have unlimited stamina. The human does not. Use your persistence wisely —
 - ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
 - ❌ Edited a file from memory after 10+ messages without re-reading? → Violated context decay rule
 - ❌ Started building without plan approval on a non-trivial task? → Violated plan-build separation
-- ❌ Used try-catch in Minecraft code? → Violated no-try-catch rule
+- ❌ Used broad try-catch where guards would work? → Violated guard-first error handling
 - ❌ Made changes without running `tsc --noEmit`? → Violated TypeScript verification
 - ❌ Created custom math function without checking @minecraft/math? → Violated library-first rule
 - ❌ Used raw string like `"inventory"` or `"minecraft:wolf"`? → Violated vanilla-data rule