mirror of
https://github.com/KAMKEEL/CustomNPC-Plus.git
synced 2026-11-22 10:49:47 +00:00
87 lines
5.0 KiB
Markdown
87 lines
5.0 KiB
Markdown
# Agent Guidelines
|
||
|
||
This repo keeps “fresh memory” notes under `.$state/`. These docs are the primary mental model for the script editor + interpreter stack.
|
||
|
||
Default todo list: `.$state/TODO.md`
|
||
|
||
## Compilation and Building
|
||
|
||
To compile the project, run the gradlew.bat compileJava task on ONLY the root project (CustomNPC-DBC-Addon). This applies for CustomNPC-Plus as well.
|
||
And WAIT!!! Waiting is essential, as the task can usually take up to 3 minutes. As long as the compileJava task is running, DO NOT close the terminal or interrupt the process.
|
||
|
||
## How to use state docs
|
||
|
||
Before exploring source code or making edits, scan the user prompt for subsystem keywords and open the relevant `.$state/*.md` doc(s) first. If multiple subsystems are involved, read all relevant docs (usually 1–3).
|
||
|
||
Recommended read order (when multiple apply):
|
||
1. `.$state/SYNTAX_HIGHLIGHTER.md`
|
||
2. `.$state/AUTOCOMPLETE.md`
|
||
3. `.$state/DTS_ECOSYSTEM.md`
|
||
4. `.$state/SCRIPT_EDITOR.md`
|
||
5. `.$state/SCRIPT_HANDLING.md`
|
||
|
||
The goal is not to treat the docs as perfectly authoritative; it’s to refresh terminology, invariants, and the intended architecture before verifying details in source.
|
||
|
||
## State docs (what to read when)
|
||
|
||
- `.$state/SYNTAX_HIGHLIGHTER.md`
|
||
- Read when the prompt involves: `ScriptDocument`, parsing/marking/token building, `TokenType` priority, `FieldChainMarker`, validation errors, hover/underlines, synthetic built-ins, JSDoc, or type-resolution questions involving `TypeResolver`, `resolveType` or `resolveExpressionType`.
|
||
|
||
- `.$state/AUTOCOMPLETE.md`
|
||
- Read when the prompt involves: autocomplete UI/behavior, prefix/receiver detection, insertion behavior, providers (`JavaAutocompleteProvider`, `JSAutocompleteProvider`), suggestion ranking, usage tracking, import insertion, or missing/wrong suggestions.
|
||
|
||
- `.$state/DTS_ECOSYSTEM.md`
|
||
- Read when the prompt involves: `.d.ts` generation (Gradle plugin in `gradle-plugins/`), `hooks.d.ts` / `index.d.ts`, runtime parsing (`TypeScriptDefinitionParser`), registry behavior (`JSTypeRegistry`), `JSTypeInfo`/`JSMethodInfo`/`JSFieldInfo`, or TypeScript generic bound handling.
|
||
|
||
- `.$state/SCRIPT_EDITOR.md`
|
||
- Read when the prompt involves: `GuiScriptTextArea`, editor UX (scroll/selection/search/go-to-line/rename), hover UI wiring, or the client editor model (`ScriptTextContainer`).
|
||
|
||
- `.$state/SCRIPT_HANDLING.md`
|
||
- Read when the prompt involves: (`JaninoScript`, `janino`, `GuiScriptInterface` ), runtime script storage/execution (`ScriptContainer`), script-related NBT serialization, hook dispatch, script engine selection, or script controller/handler wiring.
|
||
|
||
## Cross-subsystem quick picks
|
||
|
||
- Autocomplete issues that smell like “wrong receiver type / missing members / cannot resolve symbol”:
|
||
- Read `.$state/AUTOCOMPLETE.md` + `.$state/SYNTAX_HIGHLIGHTER.md` (+ `.$state/DTS_ECOSYSTEM.md` if JS/.d.ts types involved).
|
||
- JS autocomplete issues specifically:
|
||
- Read `.$state/AUTOCOMPLETE.md` + `.$state/DTS_ECOSYSTEM.md` + the relevant `.$state/SYNTAX_HIGHLIGHTER.md` sections.
|
||
- Hover tooltip / red underline / error text mismatches:
|
||
- Read `.$state/SYNTAX_HIGHLIGHTER.md`.
|
||
|
||
## Workflow expectation
|
||
|
||
1. Identify subsystem keywords in the user request.
|
||
2. Read the relevant `.$state/*.md` doc(s) first (before open-ended repo exploration).
|
||
3. Use the docs to decide which source files to inspect next.
|
||
4. Verify critical details against source before making edits (the docs can drift).
|
||
5. If edits change behavior/architecture described in a state doc, ask the user whether they want the doc updated as part of the change.
|
||
|
||
|
||
## Planning
|
||
|
||
When I prompt you to plan something, I want you to always follow these steps:
|
||
1. Analyze the user request carefully to understand their needs and objectives.
|
||
2. Break down the request into smaller, manageable tasks or components.
|
||
3. Prioritize the tasks based on their importance and dependencies.
|
||
4. Create a detailed plan or outline that addresses each task systematically.
|
||
5. Review the plan to ensure it aligns with the user's goals and is feasible to implement.
|
||
6. Present the plan to the user for feedback and approval before proceeding with implementation.
|
||
7. Once approved, execute the plan step by step, keeping the user informed of progress and any adjustments needed along the way.
|
||
8. After completing the tasks, review the outcomes with the user to ensure satisfaction and address any further needs.
|
||
9. Document the process and results for future reference and learning.
|
||
|
||
This plan must always be created and stored at .sisyphus/plans as a .md file with a unique name related to the task.
|
||
That document must be your main source of truth for the plan, you must always refer to it before and after taking any action.
|
||
|
||
## Expert-Scripter Conventions
|
||
|
||
For CustomNPC+ scripting conventions and quality standards, see `.github/agents/AGENTS.md`.
|
||
|
||
That file documents:
|
||
- Mandatory review gates and triggers
|
||
- API verification requirements (zero-tolerance policy)
|
||
- Storage decision tree (getNbt vs getStoredData vs getTempData)
|
||
- Subagent usage rules
|
||
- Production quality checklist
|
||
- Code-Review conventions
|
||
- Training scripts policy |