spawnpack 0.1.5 → 0.1.7
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 +6 -4
- package/dist/spawnpack.js +9 -22
- package/package.json +1 -1
- package/templates/AGENTS.md +20 -179
- package/templates/CLAUDE.md +20 -179
package/README.md
CHANGED
|
@@ -122,9 +122,11 @@ Spawnpack fetches the latest stable npm versions for:
|
|
|
122
122
|
- `@minecraft/vanilla-data`
|
|
123
123
|
- `@minecraft/math`
|
|
124
124
|
|
|
125
|
-
If version lookup fails, it falls back to baked stable defaults.
|
|
126
|
-
|
|
127
|
-
|
|
125
|
+
If version lookup fails, it falls back to baked stable defaults.
|
|
126
|
+
|
|
127
|
+
Only runtime Script API modules, currently `@minecraft/server` and `@minecraft/server-ui`, are written to the behavior pack manifest. npm-side libraries such as `@minecraft/vanilla-data` and `@minecraft/math` stay in the generated `package.json` for imports and bundling.
|
|
128
|
+
|
|
129
|
+
## Development
|
|
128
130
|
|
|
129
131
|
```bash
|
|
130
132
|
bun install
|
|
@@ -143,4 +145,4 @@ The npm package is configured to publish only:
|
|
|
143
145
|
- `LICENSE`
|
|
144
146
|
- `package.json`
|
|
145
147
|
|
|
146
|
-
Internal planning files
|
|
148
|
+
Internal planning files and local AI/project notes are excluded from the published tarball.
|
package/dist/spawnpack.js
CHANGED
|
@@ -1586,7 +1586,7 @@ var PACK_VERSION = [1, 0, 0];
|
|
|
1586
1586
|
function getAuthors(author) {
|
|
1587
1587
|
return author.trim() === "" ? [] : [author];
|
|
1588
1588
|
}
|
|
1589
|
-
function
|
|
1589
|
+
function getManifestScriptDependencies(config, versions) {
|
|
1590
1590
|
const dependencies = [];
|
|
1591
1591
|
if (config.scriptPackages.server) {
|
|
1592
1592
|
dependencies.push({ module_name: "@minecraft/server", version: versions.server });
|
|
@@ -1594,12 +1594,6 @@ function getScriptDependencies(config, versions) {
|
|
|
1594
1594
|
if (config.scriptPackages.serverUi) {
|
|
1595
1595
|
dependencies.push({ module_name: "@minecraft/server-ui", version: versions.serverUi });
|
|
1596
1596
|
}
|
|
1597
|
-
if (config.scriptPackages.vanillaData) {
|
|
1598
|
-
dependencies.push({ module_name: "@minecraft/vanilla-data", version: versions.vanillaData });
|
|
1599
|
-
}
|
|
1600
|
-
if (config.scriptPackages.math) {
|
|
1601
|
-
dependencies.push({ module_name: "@minecraft/math", version: versions.math });
|
|
1602
|
-
}
|
|
1603
1597
|
return dependencies;
|
|
1604
1598
|
}
|
|
1605
1599
|
function getBpModules(config) {
|
|
@@ -1618,7 +1612,7 @@ function getBpModules(config) {
|
|
|
1618
1612
|
function generateBpManifest(config, bpUuid, rpUuid, versions) {
|
|
1619
1613
|
const dependencies = [{ uuid: rpUuid, version: PACK_VERSION }];
|
|
1620
1614
|
if (config.scripting !== "none") {
|
|
1621
|
-
dependencies.push(...
|
|
1615
|
+
dependencies.push(...getManifestScriptDependencies(config, versions));
|
|
1622
1616
|
}
|
|
1623
1617
|
return {
|
|
1624
1618
|
format_version: VERSIONS.manifestFormat,
|
|
@@ -1914,6 +1908,11 @@ Add your own API keys before using the MCP tools:
|
|
|
1914
1908
|
|
|
1915
1909
|
Update the placeholder values in \`.mcp.json\` with your own tokens.
|
|
1916
1910
|
|
|
1911
|
+
` : "";
|
|
1912
|
+
const scriptPackageSection = config.scripting !== "none" ? `## Script Packages
|
|
1913
|
+
|
|
1914
|
+
Selected npm packages are installed through \`package.json\`. Only runtime Script API modules such as \`@minecraft/server\` and \`@minecraft/server-ui\` are written to \`packs/BP/manifest.json\`; npm-side libraries such as \`@minecraft/vanilla-data\` and \`@minecraft/math\` are imported and bundled from \`package.json\`.
|
|
1915
|
+
|
|
1917
1916
|
` : "";
|
|
1918
1917
|
return `# ${config.projectName}
|
|
1919
1918
|
|
|
@@ -1938,7 +1937,7 @@ ${config.scripting === "none" ? "This project was generated without Script API s
|
|
|
1938
1937
|
- Add additional JavaScript files beside \`main.js\` and import them from there.
|
|
1939
1938
|
- Minecraft copies the BP/RP content directly into \`com.mojang\`, so there is no TypeScript compile step.`}
|
|
1940
1939
|
|
|
1941
|
-
${config.useRgl ? `## rgl Workflow
|
|
1940
|
+
${scriptPackageSection}${config.useRgl ? `## rgl Workflow
|
|
1942
1941
|
|
|
1943
1942
|
- \`rgl watch\` rebuilds your scripts and exports your add-on while you work.
|
|
1944
1943
|
- \`rgl run\` builds a development export once.
|
|
@@ -2137,17 +2136,6 @@ function buildMcpServers() {
|
|
|
2137
2136
|
command: "npx",
|
|
2138
2137
|
args: ["-y", "@modelcontextprotocol/server-sequential-thinking"]
|
|
2139
2138
|
},
|
|
2140
|
-
serena: {
|
|
2141
|
-
command: "uvx",
|
|
2142
|
-
args: [
|
|
2143
|
-
"--from",
|
|
2144
|
-
"git+https://github.com/oraios/serena",
|
|
2145
|
-
"serena",
|
|
2146
|
-
"start-mcp-server",
|
|
2147
|
-
"--context",
|
|
2148
|
-
"ide-assistant"
|
|
2149
|
-
]
|
|
2150
|
-
},
|
|
2151
2139
|
grep_app: {
|
|
2152
2140
|
command: "npx",
|
|
2153
2141
|
args: ["-y", "grep-mcp"]
|
|
@@ -2175,8 +2163,7 @@ var AI_EXCLUDE_LINES = [
|
|
|
2175
2163
|
"/CLAUDE.md",
|
|
2176
2164
|
"/AGENTS.md",
|
|
2177
2165
|
"/.mcp.json",
|
|
2178
|
-
"/.claude/"
|
|
2179
|
-
"/.serena/"
|
|
2166
|
+
"/.claude/"
|
|
2180
2167
|
];
|
|
2181
2168
|
function getTemplateUrls(filename) {
|
|
2182
2169
|
return [
|
package/package.json
CHANGED
package/templates/AGENTS.md
CHANGED
|
@@ -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
|
|
|
@@ -169,7 +123,7 @@ For non-trivial features (3+ steps or architectural decisions), enter plan mode.
|
|
|
169
123
|
<directive name="research_before_implementation" priority="high">
|
|
170
124
|
Before writing any code that touches a library or framework:
|
|
171
125
|
1. Use Exa to search for current docs for every library involved (especially `@minecraft/server`, `@minecraft/math`, `@minecraft/vanilla-data`)
|
|
172
|
-
2.
|
|
126
|
+
2. Check project notes and existing code for established patterns or past decisions
|
|
173
127
|
3. Only then begin implementation
|
|
174
128
|
|
|
175
129
|
This applies even for "simple" tasks. A 30-second Exa search prevents a 30-minute debugging session caused by stale API knowledge.
|
|
@@ -514,7 +468,7 @@ After 10+ messages in a conversation, you MUST re-read any file before editing i
|
|
|
514
468
|
</directive>
|
|
515
469
|
|
|
516
470
|
<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.
|
|
471
|
+
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
472
|
</directive>
|
|
519
473
|
|
|
520
474
|
<directive name="tool_result_blindness" priority="medium">
|
|
@@ -524,11 +478,11 @@ Tool results over 50,000 characters may be silently truncated. If any search or
|
|
|
524
478
|
|
|
525
479
|
<edit_safety>
|
|
526
480
|
<directive name="edit_integrity" priority="critical">
|
|
527
|
-
Before EVERY file edit, re-read the file
|
|
481
|
+
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
482
|
</directive>
|
|
529
483
|
|
|
530
484
|
<directive name="thorough_rename_search" priority="high">
|
|
531
|
-
When renaming or changing any function/type/variable,
|
|
485
|
+
When renaming or changing any function/type/variable, find all references first. Then additionally search for:
|
|
532
486
|
- String literals containing the name
|
|
533
487
|
- Dynamic imports and require() calls
|
|
534
488
|
- Re-exports and barrel file entries
|
|
@@ -549,122 +503,13 @@ Never delete a file without verifying nothing else references it. Never undo cod
|
|
|
549
503
|
<file_system_as_state>
|
|
550
504
|
The file system is your most powerful general-purpose tool. Stop holding everything in context. Use it actively:
|
|
551
505
|
|
|
552
|
-
- Do not blindly dump large files into context.
|
|
506
|
+
- 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
507
|
- Write intermediate results to files. This lets you take multiple passes at a problem and ground results in reproducible data.
|
|
554
508
|
- Use the file system for memory across sessions: write summaries, decisions, and pending work to markdown files that persist.
|
|
555
509
|
- When debugging, save logs and outputs to files so you can verify against reproducible artifacts.
|
|
556
510
|
- 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
511
|
</file_system_as_state>
|
|
558
512
|
|
|
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
513
|
<prompt_cache_awareness>
|
|
669
514
|
Your system prompt, tools, and AGENTS.md are cached as a prefix. Breaking this prefix invalidates the cache for the entire session.
|
|
670
515
|
|
|
@@ -757,13 +602,12 @@ POTENTIAL CONCERNS:
|
|
|
757
602
|
9. Bloating abstractions unnecessarily
|
|
758
603
|
10. Not cleaning up dead code after refactors
|
|
759
604
|
11. Removing things you don't fully understand
|
|
760
|
-
12.
|
|
761
|
-
13.
|
|
762
|
-
14.
|
|
763
|
-
15.
|
|
764
|
-
16.
|
|
765
|
-
17.
|
|
766
|
-
18. Using try-catch in Minecraft Script API code
|
|
605
|
+
12. Reporting task complete without running verification (type-check, lint, test)
|
|
606
|
+
13. Editing files from stale context without re-reading first
|
|
607
|
+
14. Duplicating state instead of fixing the real problem
|
|
608
|
+
15. Writing library/framework code from memory without searching Exa for current docs first
|
|
609
|
+
16. Manually scraping or parsing HTML when Browser Use MCP could extract it cleanly
|
|
610
|
+
17. Using try-catch in Minecraft Script API code
|
|
767
611
|
18. Creating custom math functions when @minecraft/math has them available
|
|
768
612
|
19. Using raw strings instead of @minecraft/vanilla-data typed identifiers
|
|
769
613
|
20. Writing BP/RP JSON files without schema validation
|
|
@@ -776,20 +620,17 @@ The human is monitoring you in an IDE. They can see everything. They will catch
|
|
|
776
620
|
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
621
|
|
|
778
622
|
**Priority Hierarchy:**
|
|
779
|
-
1. **
|
|
780
|
-
2. **
|
|
781
|
-
3. **
|
|
782
|
-
4. **
|
|
783
|
-
5. **
|
|
784
|
-
6. **
|
|
785
|
-
7. **
|
|
786
|
-
8. **
|
|
787
|
-
9. **
|
|
788
|
-
10. **SERENA MEMORY** — Store implementation details and learnings
|
|
789
|
-
11. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
|
|
623
|
+
1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
|
|
624
|
+
2. **BROWSER USE MCP FOR WEB** — Use Browser Use MCP for scraping, crawling, structured extraction, and browser automation
|
|
625
|
+
3. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
|
|
626
|
+
4. **PLAN BEFORE BUILD** — Spec and approval before implementation
|
|
627
|
+
5. **GUARD CLAUSES** — Never use try-catch in Minecraft code
|
|
628
|
+
6. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
|
|
629
|
+
7. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
|
|
630
|
+
8. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
|
|
631
|
+
9. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
|
|
790
632
|
|
|
791
633
|
**Violation Checks:**
|
|
792
|
-
- ❌ Used Read/Grep/Glob/SemanticSearch/StrReplace/Write/bash for file/code ops? → Violated Serena-first rule
|
|
793
634
|
- ❌ Wrote library/framework code without searching Exa first? → Violated Exa-for-docs rule
|
|
794
635
|
- ❌ Manually scraped/parsed HTML when Browser Use MCP could do it? → Violated Browser-Use-MCP-for-web rule
|
|
795
636
|
- ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
|
package/templates/CLAUDE.md
CHANGED
|
@@ -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
|
|
|
@@ -169,7 +123,7 @@ For non-trivial features (3+ steps or architectural decisions), enter plan mode.
|
|
|
169
123
|
<directive name="research_before_implementation" priority="high">
|
|
170
124
|
Before writing any code that touches a library or framework:
|
|
171
125
|
1. Use Exa to search for current docs for every library involved (especially `@minecraft/server`, `@minecraft/math`, `@minecraft/vanilla-data`)
|
|
172
|
-
2.
|
|
126
|
+
2. Check project notes and existing code for established patterns or past decisions
|
|
173
127
|
3. Only then begin implementation
|
|
174
128
|
|
|
175
129
|
This applies even for "simple" tasks. A 30-second Exa search prevents a 30-minute debugging session caused by stale API knowledge.
|
|
@@ -514,7 +468,7 @@ After 10+ messages in a conversation, you MUST re-read any file before editing i
|
|
|
514
468
|
</directive>
|
|
515
469
|
|
|
516
470
|
<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.
|
|
471
|
+
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
472
|
</directive>
|
|
519
473
|
|
|
520
474
|
<directive name="tool_result_blindness" priority="medium">
|
|
@@ -524,11 +478,11 @@ Tool results over 50,000 characters may be silently truncated. If any search or
|
|
|
524
478
|
|
|
525
479
|
<edit_safety>
|
|
526
480
|
<directive name="edit_integrity" priority="critical">
|
|
527
|
-
Before EVERY file edit, re-read the file
|
|
481
|
+
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
482
|
</directive>
|
|
529
483
|
|
|
530
484
|
<directive name="thorough_rename_search" priority="high">
|
|
531
|
-
When renaming or changing any function/type/variable,
|
|
485
|
+
When renaming or changing any function/type/variable, find all references first. Then additionally search for:
|
|
532
486
|
- String literals containing the name
|
|
533
487
|
- Dynamic imports and require() calls
|
|
534
488
|
- Re-exports and barrel file entries
|
|
@@ -549,122 +503,13 @@ Never delete a file without verifying nothing else references it. Never undo cod
|
|
|
549
503
|
<file_system_as_state>
|
|
550
504
|
The file system is your most powerful general-purpose tool. Stop holding everything in context. Use it actively:
|
|
551
505
|
|
|
552
|
-
- Do not blindly dump large files into context.
|
|
506
|
+
- 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
507
|
- Write intermediate results to files. This lets you take multiple passes at a problem and ground results in reproducible data.
|
|
554
508
|
- Use the file system for memory across sessions: write summaries, decisions, and pending work to markdown files that persist.
|
|
555
509
|
- When debugging, save logs and outputs to files so you can verify against reproducible artifacts.
|
|
556
510
|
- 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
511
|
</file_system_as_state>
|
|
558
512
|
|
|
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
513
|
<prompt_cache_awareness>
|
|
669
514
|
Your system prompt, tools, and CLAUDE.md are cached as a prefix. Breaking this prefix invalidates the cache for the entire session.
|
|
670
515
|
|
|
@@ -757,13 +602,12 @@ POTENTIAL CONCERNS:
|
|
|
757
602
|
9. Bloating abstractions unnecessarily
|
|
758
603
|
10. Not cleaning up dead code after refactors
|
|
759
604
|
11. Removing things you don't fully understand
|
|
760
|
-
12.
|
|
761
|
-
13.
|
|
762
|
-
14.
|
|
763
|
-
15.
|
|
764
|
-
16.
|
|
765
|
-
17.
|
|
766
|
-
18. Using try-catch in Minecraft Script API code
|
|
605
|
+
12. Reporting task complete without running verification (type-check, lint, test)
|
|
606
|
+
13. Editing files from stale context without re-reading first
|
|
607
|
+
14. Duplicating state instead of fixing the real problem
|
|
608
|
+
15. Writing library/framework code from memory without searching Exa for current docs first
|
|
609
|
+
16. Manually scraping or parsing HTML when Browser Use MCP could extract it cleanly
|
|
610
|
+
17. Using try-catch in Minecraft Script API code
|
|
767
611
|
18. Creating custom math functions when @minecraft/math has them available
|
|
768
612
|
19. Using raw strings instead of @minecraft/vanilla-data typed identifiers
|
|
769
613
|
20. Writing BP/RP JSON files without schema validation
|
|
@@ -776,20 +620,17 @@ The human is monitoring you in an IDE. They can see everything. They will catch
|
|
|
776
620
|
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
621
|
|
|
778
622
|
**Priority Hierarchy:**
|
|
779
|
-
1. **
|
|
780
|
-
2. **
|
|
781
|
-
3. **
|
|
782
|
-
4. **
|
|
783
|
-
5. **
|
|
784
|
-
6. **
|
|
785
|
-
7. **
|
|
786
|
-
8. **
|
|
787
|
-
9. **
|
|
788
|
-
10. **SERENA MEMORY** — Store implementation details and learnings
|
|
789
|
-
11. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
|
|
623
|
+
1. **EXA FOR DOCS** — Always search library/framework docs via Exa before implementing
|
|
624
|
+
2. **BROWSER USE MCP FOR WEB** — Use Browser Use MCP for scraping, crawling, structured extraction, and browser automation
|
|
625
|
+
3. **VERIFY BEFORE DONE** — Type-check, lint, test before claiming success
|
|
626
|
+
4. **PLAN BEFORE BUILD** — Spec and approval before implementation
|
|
627
|
+
5. **GUARD CLAUSES** — Never use try-catch in Minecraft code
|
|
628
|
+
6. **VANILLA-DATA** — Use typed identifiers from @minecraft/vanilla-data
|
|
629
|
+
7. **MINECRAFT-MATH** — Use @minecraft/math library for math operations
|
|
630
|
+
8. **JSON SCHEMAS** — Validate BP/RP JSONs with Rockide/schemas
|
|
631
|
+
9. **NATURAL COMMITS** - Write human commit messages; no attribution or AI-style report trailers
|
|
790
632
|
|
|
791
633
|
**Violation Checks:**
|
|
792
|
-
- ❌ Used Read/Grep/Glob/SemanticSearch/StrReplace/Write/bash for file/code ops? → Violated Serena-first rule
|
|
793
634
|
- ❌ Wrote library/framework code without searching Exa first? → Violated Exa-for-docs rule
|
|
794
635
|
- ❌ Manually scraped/parsed HTML when Browser Use MCP could do it? → Violated Browser-Use-MCP-for-web rule
|
|
795
636
|
- ❌ Said "Done!" without running type-check/lint/tests? → Violated forced verification rule
|