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 +1 -1
- package/dist/spawnpack.js +5 -40
- package/package.json +1 -1
- package/templates/AGENTS.md +22 -223
- package/templates/CLAUDE.md +22 -223
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
|
|
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
|
-
|
|
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
|
-
|
|
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("
|
|
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
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
|
|
|
@@ -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.
|
|
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.
|
|
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
|
|
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,
|
|
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.
|
|
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.
|
|
761
|
-
13.
|
|
762
|
-
14.
|
|
763
|
-
15.
|
|
764
|
-
16.
|
|
765
|
-
17.
|
|
766
|
-
18. Using
|
|
767
|
-
|
|
768
|
-
|
|
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. **
|
|
780
|
-
2. **
|
|
781
|
-
3. **
|
|
782
|
-
4. **
|
|
783
|
-
5. **
|
|
784
|
-
6. **
|
|
785
|
-
7. **
|
|
786
|
-
8. **
|
|
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
|
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
|
|
|
@@ -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.
|
|
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.
|
|
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
|
|
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,
|
|
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.
|
|
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.
|
|
761
|
-
13.
|
|
762
|
-
14.
|
|
763
|
-
15.
|
|
764
|
-
16.
|
|
765
|
-
17.
|
|
766
|
-
18. Using
|
|
767
|
-
|
|
768
|
-
|
|
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. **
|
|
780
|
-
2. **
|
|
781
|
-
3. **
|
|
782
|
-
4. **
|
|
783
|
-
5. **
|
|
784
|
-
6. **
|
|
785
|
-
7. **
|
|
786
|
-
8. **
|
|
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
|