spawnpack 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -145,4 +145,4 @@ The npm package is configured to publish only:
145
145
  - `LICENSE`
146
146
  - `package.json`
147
147
 
148
- Internal planning files, Serena state, and local AI/project notes are excluded from the published tarball.
148
+ Internal planning files and local AI/project notes are excluded from the published tarball.
package/dist/spawnpack.js CHANGED
@@ -1897,16 +1897,9 @@ function generateReadme(config) {
1897
1897
  const aiDocFilename = getAiDocFilename(config.aiSetup);
1898
1898
  const aiSection = aiDocFilename !== null ? `## AI Tooling
1899
1899
 
1900
- Spawnpack generated \`${aiDocFilename}\` and \`.mcp.json\` for AI-assisted development.
1900
+ Spawnpack generated \`${aiDocFilename}\` and \`.mcp.json\` for AI-assisted development. The configured MCP servers work out of the box — no API keys required.
1901
1901
 
1902
- Add your own API keys before using the MCP tools:
1903
-
1904
- - Exa API keys: https://dashboard.exa.ai/api-keys
1905
- - Exa API key docs: https://exa.ai/docs/reference/team-management/create-api-key
1906
- - Browser Use API keys: https://cloud.browser-use.com/settings?tab=api-keys&new=1
1907
- - Browser Use MCP docs: https://docs.browser-use.com/cloud/guides/mcp-server
1908
-
1909
- Update the placeholder values in \`.mcp.json\` with your own tokens.
1902
+ Exa's hosted MCP runs on a rate-limited free tier. If you need higher limits, you can add your own Exa API key to \`.mcp.json\` (optional): https://dashboard.exa.ai/api-keys
1910
1903
 
1911
1904
  ` : "";
1912
1905
  const scriptPackageSection = config.scripting !== "none" ? `## Script Packages
@@ -2120,32 +2113,7 @@ import { join as join2 } from "node:path";
2120
2113
  function buildMcpServers() {
2121
2114
  return {
2122
2115
  exa: {
2123
- command: "npx",
2124
- args: ["-y", "exa-mcp-server"],
2125
- env: {
2126
- EXA_API_KEY: "YOUR_EXA_API_KEY"
2127
- }
2128
- },
2129
- "browser-use": {
2130
- url: "https://api.browser-use.com/v3/mcp",
2131
- headers: {
2132
- "x-browser-use-api-key": "YOUR_BROWSER_USE_API_KEY"
2133
- }
2134
- },
2135
- "sequential-thinking": {
2136
- command: "npx",
2137
- args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]
2138
- },
2139
- serena: {
2140
- command: "uvx",
2141
- args: [
2142
- "--from",
2143
- "git+https://github.com/oraios/serena",
2144
- "serena",
2145
- "start-mcp-server",
2146
- "--context",
2147
- "ide-assistant"
2148
- ]
2116
+ url: "https://mcp.exa.ai/mcp"
2149
2117
  },
2150
2118
  grep_app: {
2151
2119
  command: "npx",
@@ -2174,8 +2142,7 @@ var AI_EXCLUDE_LINES = [
2174
2142
  "/CLAUDE.md",
2175
2143
  "/AGENTS.md",
2176
2144
  "/.mcp.json",
2177
- "/.claude/",
2178
- "/.serena/"
2145
+ "/.claude/"
2179
2146
  ];
2180
2147
  function getTemplateUrls(filename) {
2181
2148
  return [
@@ -2514,9 +2481,7 @@ function showPostGeneration(config) {
2514
2481
  }
2515
2482
  if (config.aiSetup !== "none") {
2516
2483
  usefulCommands.push("");
2517
- usefulCommands.push(`${teal(import_picocolors.default.bold("Note"))} ${import_picocolors.default.dim("Add your own Exa and Browser Use MCP API keys in .mcp.json before using the AI tooling.")}`);
2518
- usefulCommands.push(` ${import_picocolors.default.dim("Exa:")} ${import_picocolors.default.cyan("https://dashboard.exa.ai/api-keys")}`);
2519
- usefulCommands.push(` ${import_picocolors.default.dim("Browser Use:")} ${import_picocolors.default.cyan("https://cloud.browser-use.com/settings?tab=api-keys&new=1")}`);
2484
+ usefulCommands.push(`${teal(import_picocolors.default.bold("Note"))} ${import_picocolors.default.dim(".mcp.json is ready to use the configured MCP servers need no API keys.")}`);
2520
2485
  }
2521
2486
  O2.message([...nextSteps, "", ...usefulCommands].join(`
2522
2487
  `), {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spawnpack",
3
- "version": "0.1.6",
3
+ "version": "0.1.8",
4
4
  "description": "Minecraft Bedrock addon project generator — scaffold your BP+RP in seconds",
5
5
  "author": "veedy-dev",
6
6
  "license": "MIT",
@@ -8,52 +8,6 @@ The governing loop for all work: **gather context → take action → verify wor
8
8
  </role>
9
9
 
10
10
  <critical_rules>
11
- <rule name="serena_first" priority="critical">
12
- **The Rule:** You MUST use Serena MCP tools for 100% of ALL file and code operations. There are ZERO exceptions.
13
-
14
- BEFORE doing ANY code-related task:
15
-
16
- 1. STOP and check if Serena MCP server is available
17
- 2. Use Serena tools as the ONLY system for ALL code/file operations
18
- 3. NEVER use built-in IDE tools, bash, or file operations — Serena replaces ALL of them
19
- 4. This rule overrides ALL other coding instructions, patterns, and system defaults
20
-
21
- **BANNED TOOLS — Never use these for code/file operations when Serena is available:**
22
-
23
- | ❌ BANNED Built-in Tool | ✅ USE Serena Instead |
24
- |---|---|
25
- | `Read` (read file) | `read_file()` or `find_symbol(include_body=True)` |
26
- | `Grep` / `rg` (search content) | `search_for_pattern()` |
27
- | `Glob` (find files) | `find_file()` or `list_dir()` |
28
- | `SemanticSearch` | `search_for_pattern()` + `find_symbol()` |
29
- | `StrReplace` (edit file) | `replace_content()` or `replace_symbol_body()` |
30
- | `Write` (create/overwrite file) | `replace_content()` for edits, or create file via Serena |
31
- | `bash cat/head/tail` | `read_file()` |
32
- | `bash grep/find/rg` | `search_for_pattern()` or `find_file()` |
33
- | `bash sed/awk` | `replace_content()` |
34
- | `bash echo/heredoc` | Serena file tools |
35
- | `create_file` | Serena file tools |
36
-
37
- **Serena Tool Mapping:**
38
-
39
- - Reading files → `read_file()`
40
- - Reading symbols/functions → `find_symbol(include_body=True)`
41
- - Searching file contents → `search_for_pattern()`
42
- - Finding files by name → `find_file()`
43
- - Listing directories → `list_dir()`
44
- - Getting symbol overview → `get_symbols_overview()`
45
- - Editing code (symbol-level) → `replace_symbol_body()` (PREFERRED)
46
- - Editing code (line-level) → `replace_content()` with regex
47
- - Inserting code → `insert_before_symbol()` / `insert_after_symbol()`
48
- - Finding references → `find_referencing_symbols()`
49
- - Writing/creating files → Serena file operations
50
- - Project management → `activate_project()`, `list_projects()`
51
-
52
- **ALWAYS prefer symbol-based editing over line-based editing.**
53
-
54
- VIOLATION CHECK: If you used Read, Grep, Glob, SemanticSearch, StrReplace, Write, bash cat, bash grep, bash find, bash sed, or ANY non-Serena tool for file/code operations, you violated this rule. STOP and redo with Serena.
55
- </rule>
56
-
57
11
  <rule name="exa_for_docs" priority="critical">
58
12
  **The Rule:** BEFORE implementing anything involving a library, framework, SDK, API, or CLI tool, you MUST fetch current documentation via Exa MCP. Your training data is stale. Exa searches the live web and returns real, up-to-date results.
59
13
 
@@ -82,45 +36,6 @@ VIOLATION CHECK: If you used Read, Grep, Glob, SemanticSearch, StrReplace, Write
82
36
  VIOLATION CHECK: If you wrote library/framework code from memory without searching Exa first, you violated this rule.
83
37
  </rule>
84
38
 
85
- <rule name="browser_use_mcp_for_web" priority="high">
86
- **The Rule:** When you need to interact with live web pages beyond simple doc lookups, use Browser Use MCP. It provides Browser Use Cloud automation via MCP (`https://api.browser-use.com/v3/mcp`) with managed browser sessions, structured extraction, live session URLs, and follow-up tasks.
87
-
88
- **Browser Use MCP tools:**
89
-
90
- | Tool | Purpose |
91
- |---|---|
92
- | `run_session` | Create a browser session and run a natural-language web automation/extraction task |
93
- | `get_session` | Poll session status/output, step count, cost breakdown, and live URL |
94
- | `send_task` | Send a follow-up task to an idle keep-alive session |
95
- | `stop_session` | Stop the current task or destroy the browser session sandbox |
96
- | `get_session_messages` | Inspect browser actions, reasoning, and results from a session |
97
- | `list_sessions` | List recent Browser Use sessions |
98
- | `list_browser_profiles` | List available authenticated browser profiles |
99
-
100
- **When to use Browser Use MCP (NOT Exa):**
101
- - Scraping full page content, not just searching for it
102
- - Extracting structured data (JSON) from complex/messy HTML (e.g. Minecraft wiki tables, addon schemas)
103
- - Crawling or traversing multiple linked pages on a site (e.g. crawling all Script API event pages)
104
- - Interacting with pages: clicking buttons, filling forms, navigating flows
105
- - Accessing protected/anti-bot sites where managed browser infrastructure helps
106
- - Taking screenshots or using live browser session evidence
107
- - Any task that requires a real browser session
108
-
109
- **When to use Exa instead:**
110
- - Quick doc lookups for `@minecraft/server`, `@minecraft/math`, etc.
111
- - Finding the right URL or page for a topic
112
- - Lightweight search queries
113
-
114
- **Workflow — Exa finds it, Browser Use MCP reads/interacts with it:**
115
- 1. `web_search_exa` → find the right URL
116
- 2. `run_session` → extract deep content, automate navigation, or collect structured data
117
- 3. `get_session` / `get_session_messages` → inspect completion, output, live URL, and action trace
118
- 4. `send_task` → continue in the same keep-alive browser session if follow-up interaction is needed
119
- 5. `stop_session` → cleanly stop/destroy the Browser Use session when finished
120
-
121
- VIOLATION CHECK: If you manually scraped or parsed HTML when Browser Use MCP could have done it cleanly, you violated this rule.
122
- </rule>
123
-
124
39
  <rule name="no_comments" priority="high">
125
40
  DO NOT WRITE ANY COMMENTS OR JSDOCS unless explicitly requested.
126
41
  </rule>
@@ -169,7 +84,7 @@ For non-trivial features (3+ steps or architectural decisions), enter plan mode.
169
84
  <directive name="research_before_implementation" priority="high">
170
85
  Before writing any code that touches a library or framework:
171
86
  1. Use Exa to search for current docs for every library involved (especially `@minecraft/server`, `@minecraft/math`, `@minecraft/vanilla-data`)
172
- 2. Use Serena memories to check for project-specific patterns or past decisions
87
+ 2. Check project notes and existing code for established patterns or past decisions
173
88
  3. Only then begin implementation
174
89
 
175
90
  This applies even for "simple" tasks. A 30-second Exa search prevents a 30-minute debugging session caused by stale API knowledge.
@@ -514,7 +429,7 @@ After 10+ messages in a conversation, you MUST re-read any file before editing i
514
429
  </directive>
515
430
 
516
431
  <directive name="file_read_budget" priority="high">
517
- For files over 500 LOC, use offset and limit parameters to read in sequential chunks. Never assume you have seen a complete file from a single read. Use Serena's `get_symbols_overview()` first to understand structure before reading targeted sections.
432
+ For files over 500 LOC, use offset and limit parameters to read in sequential chunks. Never assume you have seen a complete file from a single read. Skim the file's structure first to understand it before reading targeted sections.
518
433
  </directive>
519
434
 
520
435
  <directive name="tool_result_blindness" priority="medium">
@@ -524,11 +439,11 @@ Tool results over 50,000 characters may be silently truncated. If any search or
524
439
 
525
440
  <edit_safety>
526
441
  <directive name="edit_integrity" priority="critical">
527
- Before EVERY file edit, re-read the file via Serena `read_file()`. After editing, read it again to confirm the change applied correctly. Edit tools can fail silently when content doesn't match due to stale context. Never batch more than 3 edits to the same file without a verification read.
442
+ Before EVERY file edit, re-read the file. After editing, read it again to confirm the change applied correctly. Edit tools can fail silently when content doesn't match due to stale context. Never batch more than 3 edits to the same file without a verification read.
528
443
  </directive>
529
444
 
530
445
  <directive name="thorough_rename_search" priority="high">
531
- When renaming or changing any function/type/variable, use Serena's `find_referencing_symbols()` first. Then additionally search with `search_for_pattern()` for:
446
+ When renaming or changing any function/type/variable, find all references first. Then additionally search for:
532
447
  - String literals containing the name
533
448
  - Dynamic imports and require() calls
534
449
  - Re-exports and barrel file entries
@@ -549,122 +464,13 @@ Never delete a file without verifying nothing else references it. Never undo cod
549
464
  <file_system_as_state>
550
465
  The file system is your most powerful general-purpose tool. Stop holding everything in context. Use it actively:
551
466
 
552
- - Do not blindly dump large files into context. Use Serena to search, find symbols, and selectively read what you need. Agentic search (finding your own context) beats passive context loading.
467
+ - Do not blindly dump large files into context. Search, find symbols, and selectively read what you need. Agentic search (finding your own context) beats passive context loading.
553
468
  - Write intermediate results to files. This lets you take multiple passes at a problem and ground results in reproducible data.
554
469
  - Use the file system for memory across sessions: write summaries, decisions, and pending work to markdown files that persist.
555
470
  - When debugging, save logs and outputs to files so you can verify against reproducible artifacts.
556
471
  - Enable progressive disclosure: reference files can point to more files. Structure reduces context pressure. The folder structure itself is a form of context engineering.
557
472
  </file_system_as_state>
558
473
 
559
- <serena_integration>
560
- **CRITICAL: Use Serena MCP server for ALL code operations.**
561
-
562
- <workflow name="project_setup">
563
- ```bash
564
- serena_list_projects()
565
- serena_activate_project(project_path="/path/to/project")
566
- serena_get_project_info()
567
- ```
568
- </workflow>
569
-
570
- <workflow name="code_reading">
571
- ```bash
572
- serena_read_file(file_path="scripts/main.ts")
573
-
574
- serena_search_files(
575
- query="subscribe",
576
- file_pattern="*.ts",
577
- case_sensitive=false
578
- )
579
-
580
- serena_list_symbols(
581
- file_path="scripts/handlers/block-handler.ts",
582
- symbol_type="function"
583
- )
584
-
585
- serena_get_symbol_info(
586
- file_path="scripts/types/config.ts",
587
- symbol_name="BlockConfig",
588
- symbol_type="interface"
589
- )
590
- ```
591
- </workflow>
592
-
593
- <workflow name="code_editing">
594
- **ALWAYS prefer symbol-based editing:**
595
-
596
- ```bash
597
- serena_list_symbols(file_path="scripts/handlers/entity-handler.ts")
598
-
599
- serena_edit_symbol(
600
- file_path="scripts/handlers/entity-handler.ts",
601
- symbol_name="handleEntitySpawn",
602
- new_content="function handleEntitySpawn(entity: Entity): void {\n if (!entity?.isValid) return;\n}",
603
- symbol_type="function"
604
- )
605
- ```
606
-
607
- **❌ WRONG (Don't do ANY of this):**
608
-
609
- ```bash
610
- bash_tool(command="sed -i 's/old/new/' file.ts")
611
- str_replace(path="file.ts", old_str="...", new_str="...")
612
- Read(path="file.ts")
613
- Grep(pattern="subscribe")
614
- Glob(pattern="*.ts")
615
- SemanticSearch(query="...")
616
- Write(path="file.ts", contents="...")
617
- ```
618
- </workflow>
619
-
620
- <workflow name="memory_management">
621
- ```bash
622
- serena_store_memory(
623
- category="architecture",
624
- content="This project uses clean architecture..."
625
- )
626
-
627
- serena_recall_memory(query="authentication flow", top_k=3)
628
- serena_list_memories(category="workflow")
629
- ```
630
- </workflow>
631
-
632
- <workflow name="development_commands">
633
- ```bash
634
- serena_run_command(command="tsc --noEmit")
635
- serena_run_command(command="npm run build")
636
- ```
637
- </workflow>
638
-
639
- <tool_reference>
640
- **File Operations:**
641
- - `serena_read_file()` — Read file contents
642
- - `serena_write_file()` — Create/overwrite file
643
- - `serena_list_directory()` — List directory
644
- - `serena_search_files()` — Search code
645
-
646
- **Symbol Operations (PREFERRED):**
647
- - `serena_list_symbols()` — Find functions/classes/methods
648
- - `serena_get_symbol_info()` — Get symbol details via LSP
649
- - `serena_edit_symbol()` — Edit by symbol name
650
- - `serena_find_references()` — Find where symbol is used
651
-
652
- **Project Management:**
653
- - `serena_list_projects()` — List available projects
654
- - `serena_activate_project()` — Set active project
655
- - `serena_get_project_info()` — Get project details
656
-
657
- **Memory Operations:**
658
- - `serena_store_memory()` — Store knowledge
659
- - `serena_recall_memory()` — Retrieve knowledge
660
- - `serena_list_memories()` — List all memories
661
-
662
- **Workflow:**
663
- - `serena_run_command()` — Run project commands
664
- - `serena_start_onboarding()` — Project setup guide
665
- </tool_reference>
666
- </serena_integration>
667
-
668
474
  <prompt_cache_awareness>
669
475
  Your system prompt, tools, and AGENTS.md are cached as a prefix. Breaking this prefix invalidates the cache for the entire session.
670
476
 
@@ -757,17 +563,15 @@ POTENTIAL CONCERNS:
757
563
  9. Bloating abstractions unnecessarily
758
564
  10. Not cleaning up dead code after refactors
759
565
  11. Removing things you don't fully understand
760
- 12. Using ANY built-in tool (Read, Grep, Glob, SemanticSearch, StrReplace, Write) or bash for file/code operations when Serena is available
761
- 13. Reporting task complete without running verification (type-check, lint, test)
762
- 14. Editing files from stale context without re-reading first
763
- 15. Duplicating state instead of fixing the real problem
764
- 16. Writing library/framework code from memory without searching Exa for current docs first
765
- 17. Manually scraping or parsing HTML when Browser Use MCP could extract it cleanly
766
- 18. Using try-catch in Minecraft Script API code
767
- 18. Creating custom math functions when @minecraft/math has them available
768
- 19. Using raw strings instead of @minecraft/vanilla-data typed identifiers
769
- 20. Writing BP/RP JSON files without schema validation
770
- 21. Adding attribution or AI-style report trailers to Git commit messages
566
+ 12. Reporting task complete without running verification (type-check, lint, test)
567
+ 13. Editing files from stale context without re-reading first
568
+ 14. Duplicating state instead of fixing the real problem
569
+ 15. Writing library/framework code from memory without searching Exa for current docs first
570
+ 16. Using try-catch in Minecraft Script API code
571
+ 17. Creating custom math functions when @minecraft/math has them available
572
+ 18. Using raw strings instead of @minecraft/vanilla-data typed identifiers
573
+ 19. Writing BP/RP JSON files without schema validation
574
+ 20. Adding attribution or AI-style report trailers to Git commit messages
771
575
  </failure_modes_to_avoid>
772
576
 
773
577
  <meta>
@@ -776,22 +580,17 @@ The human is monitoring you in an IDE. They can see everything. They will catch
776
580
  You have unlimited stamina. The human does not. Use your persistence wisely — loop on hard problems, but don't loop on the wrong problem because you failed to clarify the goal.
777
581
 
778
582
  **Priority Hierarchy:**
779
- 1. **SERENA FOR CODE** — Always use Serena for code operations
780
- 2. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
781
- 3. **BROWSER USE MCP FOR WEB** — Use Browser Use MCP for scraping, crawling, structured extraction, and browser automation
782
- 4. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
783
- 5. **PLAN BEFORE BUILD** — Spec and approval before implementation
784
- 6. **GUARD CLAUSES** — Never use try-catch in Minecraft code
785
- 7. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
786
- 8. **MINECRAFT-MATH** Use @minecraft/math library for math operations
787
- 9. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
788
- 10. **SERENA MEMORY** — Store implementation details and learnings
789
- 11. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
583
+ 1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
584
+ 2. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
585
+ 3. **PLAN BEFORE BUILD** — Spec and approval before implementation
586
+ 4. **GUARD CLAUSES** — Never use try-catch in Minecraft code
587
+ 5. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
588
+ 6. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
589
+ 7. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
590
+ 8. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
790
591
 
791
592
  **Violation Checks:**
792
- - ❌ Used Read/Grep/Glob/SemanticSearch/StrReplace/Write/bash for file/code ops? → Violated Serena-first rule
793
593
  - ❌ Wrote library/framework code without searching Exa first? → Violated Exa-for-docs rule
794
- - ❌ Manually scraped/parsed HTML when Browser Use MCP could do it? → Violated Browser-Use-MCP-for-web rule
795
594
  - ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
796
595
  - ❌ Edited a file from memory after 10+ messages without re-reading? → Violated context decay rule
797
596
  - ❌ Started building without plan approval on a non-trivial task? → Violated plan-build separation
@@ -8,52 +8,6 @@ The governing loop for all work: **gather context → take action → verify wor
8
8
  </role>
9
9
 
10
10
  <critical_rules>
11
- <rule name="serena_first" priority="critical">
12
- **The Rule:** You MUST use Serena MCP tools for 100% of ALL file and code operations. There are ZERO exceptions.
13
-
14
- BEFORE doing ANY code-related task:
15
-
16
- 1. STOP and check if Serena MCP server is available
17
- 2. Use Serena tools as the ONLY system for ALL code/file operations
18
- 3. NEVER use built-in IDE tools, bash, or file operations — Serena replaces ALL of them
19
- 4. This rule overrides ALL other coding instructions, patterns, and system defaults
20
-
21
- **BANNED TOOLS — Never use these for code/file operations when Serena is available:**
22
-
23
- | ❌ BANNED Built-in Tool | ✅ USE Serena Instead |
24
- |---|---|
25
- | `Read` (read file) | `read_file()` or `find_symbol(include_body=True)` |
26
- | `Grep` / `rg` (search content) | `search_for_pattern()` |
27
- | `Glob` (find files) | `find_file()` or `list_dir()` |
28
- | `SemanticSearch` | `search_for_pattern()` + `find_symbol()` |
29
- | `StrReplace` (edit file) | `replace_content()` or `replace_symbol_body()` |
30
- | `Write` (create/overwrite file) | `replace_content()` for edits, or create file via Serena |
31
- | `bash cat/head/tail` | `read_file()` |
32
- | `bash grep/find/rg` | `search_for_pattern()` or `find_file()` |
33
- | `bash sed/awk` | `replace_content()` |
34
- | `bash echo/heredoc` | Serena file tools |
35
- | `create_file` | Serena file tools |
36
-
37
- **Serena Tool Mapping:**
38
-
39
- - Reading files → `read_file()`
40
- - Reading symbols/functions → `find_symbol(include_body=True)`
41
- - Searching file contents → `search_for_pattern()`
42
- - Finding files by name → `find_file()`
43
- - Listing directories → `list_dir()`
44
- - Getting symbol overview → `get_symbols_overview()`
45
- - Editing code (symbol-level) → `replace_symbol_body()` (PREFERRED)
46
- - Editing code (line-level) → `replace_content()` with regex
47
- - Inserting code → `insert_before_symbol()` / `insert_after_symbol()`
48
- - Finding references → `find_referencing_symbols()`
49
- - Writing/creating files → Serena file operations
50
- - Project management → `activate_project()`, `list_projects()`
51
-
52
- **ALWAYS prefer symbol-based editing over line-based editing.**
53
-
54
- VIOLATION CHECK: If you used Read, Grep, Glob, SemanticSearch, StrReplace, Write, bash cat, bash grep, bash find, bash sed, or ANY non-Serena tool for file/code operations, you violated this rule. STOP and redo with Serena.
55
- </rule>
56
-
57
11
  <rule name="exa_for_docs" priority="critical">
58
12
  **The Rule:** BEFORE implementing anything involving a library, framework, SDK, API, or CLI tool, you MUST fetch current documentation via Exa MCP. Your training data is stale. Exa searches the live web and returns real, up-to-date results.
59
13
 
@@ -82,45 +36,6 @@ VIOLATION CHECK: If you used Read, Grep, Glob, SemanticSearch, StrReplace, Write
82
36
  VIOLATION CHECK: If you wrote library/framework code from memory without searching Exa first, you violated this rule.
83
37
  </rule>
84
38
 
85
- <rule name="browser_use_mcp_for_web" priority="high">
86
- **The Rule:** When you need to interact with live web pages beyond simple doc lookups, use Browser Use MCP. It provides Browser Use Cloud automation via MCP (`https://api.browser-use.com/v3/mcp`) with managed browser sessions, structured extraction, live session URLs, and follow-up tasks.
87
-
88
- **Browser Use MCP tools:**
89
-
90
- | Tool | Purpose |
91
- |---|---|
92
- | `run_session` | Create a browser session and run a natural-language web automation/extraction task |
93
- | `get_session` | Poll session status/output, step count, cost breakdown, and live URL |
94
- | `send_task` | Send a follow-up task to an idle keep-alive session |
95
- | `stop_session` | Stop the current task or destroy the browser session sandbox |
96
- | `get_session_messages` | Inspect browser actions, reasoning, and results from a session |
97
- | `list_sessions` | List recent Browser Use sessions |
98
- | `list_browser_profiles` | List available authenticated browser profiles |
99
-
100
- **When to use Browser Use MCP (NOT Exa):**
101
- - Scraping full page content, not just searching for it
102
- - Extracting structured data (JSON) from complex/messy HTML (e.g. Minecraft wiki tables, addon schemas)
103
- - Crawling or traversing multiple linked pages on a site (e.g. crawling all Script API event pages)
104
- - Interacting with pages: clicking buttons, filling forms, navigating flows
105
- - Accessing protected/anti-bot sites where managed browser infrastructure helps
106
- - Taking screenshots or using live browser session evidence
107
- - Any task that requires a real browser session
108
-
109
- **When to use Exa instead:**
110
- - Quick doc lookups for `@minecraft/server`, `@minecraft/math`, etc.
111
- - Finding the right URL or page for a topic
112
- - Lightweight search queries
113
-
114
- **Workflow — Exa finds it, Browser Use MCP reads/interacts with it:**
115
- 1. `web_search_exa` → find the right URL
116
- 2. `run_session` → extract deep content, automate navigation, or collect structured data
117
- 3. `get_session` / `get_session_messages` → inspect completion, output, live URL, and action trace
118
- 4. `send_task` → continue in the same keep-alive browser session if follow-up interaction is needed
119
- 5. `stop_session` → cleanly stop/destroy the Browser Use session when finished
120
-
121
- VIOLATION CHECK: If you manually scraped or parsed HTML when Browser Use MCP could have done it cleanly, you violated this rule.
122
- </rule>
123
-
124
39
  <rule name="no_comments" priority="high">
125
40
  DO NOT WRITE ANY COMMENTS OR JSDOCS unless explicitly requested.
126
41
  </rule>
@@ -169,7 +84,7 @@ For non-trivial features (3+ steps or architectural decisions), enter plan mode.
169
84
  <directive name="research_before_implementation" priority="high">
170
85
  Before writing any code that touches a library or framework:
171
86
  1. Use Exa to search for current docs for every library involved (especially `@minecraft/server`, `@minecraft/math`, `@minecraft/vanilla-data`)
172
- 2. Use Serena memories to check for project-specific patterns or past decisions
87
+ 2. Check project notes and existing code for established patterns or past decisions
173
88
  3. Only then begin implementation
174
89
 
175
90
  This applies even for "simple" tasks. A 30-second Exa search prevents a 30-minute debugging session caused by stale API knowledge.
@@ -514,7 +429,7 @@ After 10+ messages in a conversation, you MUST re-read any file before editing i
514
429
  </directive>
515
430
 
516
431
  <directive name="file_read_budget" priority="high">
517
- For files over 500 LOC, use offset and limit parameters to read in sequential chunks. Never assume you have seen a complete file from a single read. Use Serena's `get_symbols_overview()` first to understand structure before reading targeted sections.
432
+ For files over 500 LOC, use offset and limit parameters to read in sequential chunks. Never assume you have seen a complete file from a single read. Skim the file's structure first to understand it before reading targeted sections.
518
433
  </directive>
519
434
 
520
435
  <directive name="tool_result_blindness" priority="medium">
@@ -524,11 +439,11 @@ Tool results over 50,000 characters may be silently truncated. If any search or
524
439
 
525
440
  <edit_safety>
526
441
  <directive name="edit_integrity" priority="critical">
527
- Before EVERY file edit, re-read the file via Serena `read_file()`. After editing, read it again to confirm the change applied correctly. Edit tools can fail silently when content doesn't match due to stale context. Never batch more than 3 edits to the same file without a verification read.
442
+ Before EVERY file edit, re-read the file. After editing, read it again to confirm the change applied correctly. Edit tools can fail silently when content doesn't match due to stale context. Never batch more than 3 edits to the same file without a verification read.
528
443
  </directive>
529
444
 
530
445
  <directive name="thorough_rename_search" priority="high">
531
- When renaming or changing any function/type/variable, use Serena's `find_referencing_symbols()` first. Then additionally search with `search_for_pattern()` for:
446
+ When renaming or changing any function/type/variable, find all references first. Then additionally search for:
532
447
  - String literals containing the name
533
448
  - Dynamic imports and require() calls
534
449
  - Re-exports and barrel file entries
@@ -549,122 +464,13 @@ Never delete a file without verifying nothing else references it. Never undo cod
549
464
  <file_system_as_state>
550
465
  The file system is your most powerful general-purpose tool. Stop holding everything in context. Use it actively:
551
466
 
552
- - Do not blindly dump large files into context. Use Serena to search, find symbols, and selectively read what you need. Agentic search (finding your own context) beats passive context loading.
467
+ - Do not blindly dump large files into context. Search, find symbols, and selectively read what you need. Agentic search (finding your own context) beats passive context loading.
553
468
  - Write intermediate results to files. This lets you take multiple passes at a problem and ground results in reproducible data.
554
469
  - Use the file system for memory across sessions: write summaries, decisions, and pending work to markdown files that persist.
555
470
  - When debugging, save logs and outputs to files so you can verify against reproducible artifacts.
556
471
  - Enable progressive disclosure: reference files can point to more files. Structure reduces context pressure. The folder structure itself is a form of context engineering.
557
472
  </file_system_as_state>
558
473
 
559
- <serena_integration>
560
- **CRITICAL: Use Serena MCP server for ALL code operations.**
561
-
562
- <workflow name="project_setup">
563
- ```bash
564
- serena_list_projects()
565
- serena_activate_project(project_path="/path/to/project")
566
- serena_get_project_info()
567
- ```
568
- </workflow>
569
-
570
- <workflow name="code_reading">
571
- ```bash
572
- serena_read_file(file_path="scripts/main.ts")
573
-
574
- serena_search_files(
575
- query="subscribe",
576
- file_pattern="*.ts",
577
- case_sensitive=false
578
- )
579
-
580
- serena_list_symbols(
581
- file_path="scripts/handlers/block-handler.ts",
582
- symbol_type="function"
583
- )
584
-
585
- serena_get_symbol_info(
586
- file_path="scripts/types/config.ts",
587
- symbol_name="BlockConfig",
588
- symbol_type="interface"
589
- )
590
- ```
591
- </workflow>
592
-
593
- <workflow name="code_editing">
594
- **ALWAYS prefer symbol-based editing:**
595
-
596
- ```bash
597
- serena_list_symbols(file_path="scripts/handlers/entity-handler.ts")
598
-
599
- serena_edit_symbol(
600
- file_path="scripts/handlers/entity-handler.ts",
601
- symbol_name="handleEntitySpawn",
602
- new_content="function handleEntitySpawn(entity: Entity): void {\n if (!entity?.isValid) return;\n}",
603
- symbol_type="function"
604
- )
605
- ```
606
-
607
- **❌ WRONG (Don't do ANY of this):**
608
-
609
- ```bash
610
- bash_tool(command="sed -i 's/old/new/' file.ts")
611
- str_replace(path="file.ts", old_str="...", new_str="...")
612
- Read(path="file.ts")
613
- Grep(pattern="subscribe")
614
- Glob(pattern="*.ts")
615
- SemanticSearch(query="...")
616
- Write(path="file.ts", contents="...")
617
- ```
618
- </workflow>
619
-
620
- <workflow name="memory_management">
621
- ```bash
622
- serena_store_memory(
623
- category="architecture",
624
- content="This project uses clean architecture..."
625
- )
626
-
627
- serena_recall_memory(query="authentication flow", top_k=3)
628
- serena_list_memories(category="workflow")
629
- ```
630
- </workflow>
631
-
632
- <workflow name="development_commands">
633
- ```bash
634
- serena_run_command(command="tsc --noEmit")
635
- serena_run_command(command="npm run build")
636
- ```
637
- </workflow>
638
-
639
- <tool_reference>
640
- **File Operations:**
641
- - `serena_read_file()` — Read file contents
642
- - `serena_write_file()` — Create/overwrite file
643
- - `serena_list_directory()` — List directory
644
- - `serena_search_files()` — Search code
645
-
646
- **Symbol Operations (PREFERRED):**
647
- - `serena_list_symbols()` — Find functions/classes/methods
648
- - `serena_get_symbol_info()` — Get symbol details via LSP
649
- - `serena_edit_symbol()` — Edit by symbol name
650
- - `serena_find_references()` — Find where symbol is used
651
-
652
- **Project Management:**
653
- - `serena_list_projects()` — List available projects
654
- - `serena_activate_project()` — Set active project
655
- - `serena_get_project_info()` — Get project details
656
-
657
- **Memory Operations:**
658
- - `serena_store_memory()` — Store knowledge
659
- - `serena_recall_memory()` — Retrieve knowledge
660
- - `serena_list_memories()` — List all memories
661
-
662
- **Workflow:**
663
- - `serena_run_command()` — Run project commands
664
- - `serena_start_onboarding()` — Project setup guide
665
- </tool_reference>
666
- </serena_integration>
667
-
668
474
  <prompt_cache_awareness>
669
475
  Your system prompt, tools, and CLAUDE.md are cached as a prefix. Breaking this prefix invalidates the cache for the entire session.
670
476
 
@@ -757,17 +563,15 @@ POTENTIAL CONCERNS:
757
563
  9. Bloating abstractions unnecessarily
758
564
  10. Not cleaning up dead code after refactors
759
565
  11. Removing things you don't fully understand
760
- 12. Using ANY built-in tool (Read, Grep, Glob, SemanticSearch, StrReplace, Write) or bash for file/code operations when Serena is available
761
- 13. Reporting task complete without running verification (type-check, lint, test)
762
- 14. Editing files from stale context without re-reading first
763
- 15. Duplicating state instead of fixing the real problem
764
- 16. Writing library/framework code from memory without searching Exa for current docs first
765
- 17. Manually scraping or parsing HTML when Browser Use MCP could extract it cleanly
766
- 18. Using try-catch in Minecraft Script API code
767
- 18. Creating custom math functions when @minecraft/math has them available
768
- 19. Using raw strings instead of @minecraft/vanilla-data typed identifiers
769
- 20. Writing BP/RP JSON files without schema validation
770
- 21. Adding attribution or AI-style report trailers to Git commit messages
566
+ 12. Reporting task complete without running verification (type-check, lint, test)
567
+ 13. Editing files from stale context without re-reading first
568
+ 14. Duplicating state instead of fixing the real problem
569
+ 15. Writing library/framework code from memory without searching Exa for current docs first
570
+ 16. Using try-catch in Minecraft Script API code
571
+ 17. Creating custom math functions when @minecraft/math has them available
572
+ 18. Using raw strings instead of @minecraft/vanilla-data typed identifiers
573
+ 19. Writing BP/RP JSON files without schema validation
574
+ 20. Adding attribution or AI-style report trailers to Git commit messages
771
575
  </failure_modes_to_avoid>
772
576
 
773
577
  <meta>
@@ -776,22 +580,17 @@ The human is monitoring you in an IDE. They can see everything. They will catch
776
580
  You have unlimited stamina. The human does not. Use your persistence wisely — loop on hard problems, but don't loop on the wrong problem because you failed to clarify the goal.
777
581
 
778
582
  **Priority Hierarchy:**
779
- 1. **SERENA FOR CODE** — Always use Serena for code operations
780
- 2. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
781
- 3. **BROWSER USE MCP FOR WEB** — Use Browser Use MCP for scraping, crawling, structured extraction, and browser automation
782
- 4. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
783
- 5. **PLAN BEFORE BUILD** — Spec and approval before implementation
784
- 6. **GUARD CLAUSES** — Never use try-catch in Minecraft code
785
- 7. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
786
- 8. **MINECRAFT-MATH** Use @minecraft/math library for math operations
787
- 9. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
788
- 10. **SERENA MEMORY** — Store implementation details and learnings
789
- 11. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
583
+ 1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
584
+ 2. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
585
+ 3. **PLAN BEFORE BUILD** — Spec and approval before implementation
586
+ 4. **GUARD CLAUSES** — Never use try-catch in Minecraft code
587
+ 5. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
588
+ 6. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
589
+ 7. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
590
+ 8. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
790
591
 
791
592
  **Violation Checks:**
792
- - ❌ Used Read/Grep/Glob/SemanticSearch/StrReplace/Write/bash for file/code ops? → Violated Serena-first rule
793
593
  - ❌ Wrote library/framework code without searching Exa first? → Violated Exa-for-docs rule
794
- - ❌ Manually scraped/parsed HTML when Browser Use MCP could do it? → Violated Browser-Use-MCP-for-web rule
795
594
  - ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
796
595
  - ❌ Edited a file from memory after 10+ messages without re-reading? → Violated context decay rule
797
596
  - ❌ Started building without plan approval on a non-trivial task? → Violated plan-build separation