diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7f597ae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,164 @@ +# AGENTS.md + +Agent guidance for this repository (`Soul Droid Chat`). + +## Quick Start for New Agents + +1. Read `game/script.rpy`, `game/screens.rpy`, and `game/llm_ren.py` to understand flow and LLM integration. +2. Run `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" lint` before making changes. +3. Make small, focused edits that preserve Ren'Py ids and the `EMOTION:` response contract. +4. Validate with `compile` and `test` (`test ` for a single case while iterating). +5. Avoid committing generated artifacts/logs (`*.rpyc`, `game/cache/`, `log.txt`, `errors.txt`, `traceback.txt`) or secrets. +6. In your handoff, include what changed, why, and exact validation commands run. + +## Project Snapshot + +- Engine: Ren'Py 8.5.x project with script files in `game/*.rpy`. +- Python support code is embedded in Ren'Py files and `game/*_ren.py`. +- Runtime dependency: LM Studio server (default `http://localhost:1234`). +- No dedicated `tests/` directory was found; use Ren'Py `lint` and `test`. + +## Repository Layout + +- `game/script.rpy`: main dialogue/game flow loop. +- `game/screens.rpy`: UI screens, preferences, and menus. +- `game/options.rpy`: Ren'Py/build/runtime config and defaults. +- `game/llm_ren.py`: LLM call logic, parsing, and sanitizing. +- `game/constants_ren.py`: emotion synonym table. +- `project.json`, `android.json`: distribution/build settings. + +## Tooling and Environment + +- Expected Ren'Py launcher script: `/home/micost/renpy-8.5.2-sdk/renpy.sh`. +- CLI usage pattern: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "" [args]` +- Python in environment is available (`python3`), but gameplay validation should use Ren'Py commands. + +## Build, Lint, and Test Commands + +Run all commands from repository root: +`/home/micost/Documentos/Renpy Projects/Soul Droid Chat` + +### Quick checks (most common) + +- Lint project: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" lint` +- Run game locally: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" run` +- Compile scripts/python cache: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" compile` + +### Test execution (Ren'Py test runner) + +- Run default/global test suite: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test` +- Run a single test suite or testcase (important): + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test ` +- Show detailed test report: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test --report-detailed` +- Run all testcases even if disabled: + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" test --enable-all` + +### Distribution/build packaging + +- Create distributions (launcher command): + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" distribute` +- Android build exists as a Ren'Py command (if SDK/keystore configured): + - `"/home/micost/renpy-8.5.2-sdk/renpy.sh" "/home/micost/Documentos/Renpy Projects/Soul Droid Chat" android_build` + +## Suggested Validation Sequence for Agents + +1. `lint` +2. `compile` +3. `test` (or `test ` when iterating) +4. `run` for a manual smoke check on the edited flow/screen + +If a command fails, include the failing command and key error excerpt in your report. + +## Code Style Guidelines + +### General principles + +- Match existing Ren'Py and Python style in nearby files. +- Prefer small, focused changes; avoid unrelated refactors. +- Keep user-facing narrative tone and Anita persona constraints intact. +- Preserve ASCII-oriented output behavior where current code expects it. + +### Ren'Py script/style conventions (`.rpy`) + +- Use 4-space indentation; never tabs. +- Keep labels/screen names `snake_case` (`label start`, `screen quick_menu`). +- Keep style declarations grouped and readable (existing file order is a good template). +- For dialogue flow, keep Python blocks short; move reusable logic to `*_ren.py`. +- Use explicit keyword args when clarity helps (`prompt =`, `fadeout`, `fadein`). +- Do not rename core ids required by Ren'Py (`"window"`, `"what"`, `"who"`, `"input"`). + +### Python conventions (`*_ren.py` and embedded `init python`) + +- Imports: + - Standard library first (`re`). + - Ren'Py modules (`renpy`, `persistent`). + - Local imports last (`from .constants_ren import SYNONYMS`). +- Naming: + - Functions/variables: `snake_case`. + - Constants: `UPPER_SNAKE_CASE` (`EMOTIONS`, `SYSTEM_PROMPT`). + - Keep names descriptive (`parse_emotion`, `sanitize_speech`, `fetch_llm`). +- Types: + - Add type hints on new/edited Python functions when practical. + - Keep return types accurate (for list-returning functions, annotate accordingly). +- Formatting: + - Follow PEP 8 basics for spacing, line breaks, and readability. + - Keep multiline literals and dicts formatted consistently with existing file style. + +### Error handling and resilience + +- Wrap external boundary calls (network/LM Studio) with `try/except`. +- Return safe fallback values that keep game loop stable. +- Error messages should be concise and actionable for debugging. +- Avoid swallowing exceptions silently; at minimum return or log context. +- Preserve conversation continuity fields when present (`last_response_id`). + +### LLM integration constraints + +- Keep `SYSTEM_PROMPT` format guarantees consistent unless intentionally changing behavior. +- Maintain `EMOTION:` parsing contract used by dialogue rendering. +- If you add emotions, update both: + - `EMOTIONS` in `game/llm_ren.py` + - `SYNONYMS` in `game/constants_ren.py` +- Keep speech sanitization aligned with UI/rendering constraints. + +### UI/screens changes + +- Reuse existing `gui.*` variables and style helpers where possible. +- Keep mobile/small variant handling (`renpy.variant("small")`) intact. +- Prefer extending existing screens over introducing parallel duplicate screens. +- For settings UI, follow patterns already used in `preferences` screen. + +## Agent Working Rules + +- Before edits: + - Read related files fully (at least the touched blocks and nearby context). + - Check for existing patterns and follow them. +- During edits: + - Do not include secrets or API keys in committed files. + - Do not commit generated caches/logs (`*.rpyc`, `log.txt`, `errors.txt`, `traceback.txt`). +- After edits: + - Run relevant validation commands from the section above. + - Summarize what changed, why, and what was validated. + +## Git and Change Scope + +- Keep commits scoped to the requested task. +- Avoid touching binary assets unless the task explicitly requires it. +- If a keystore or credential-like file is changed, call it out explicitly. +- Do not rewrite history unless explicitly requested. + +## Cursor/Copilot Rules Status + +- No repository-specific Cursor rules were found: + - `.cursor/rules/` not present. + - `.cursorrules` not present. +- No repository-specific Copilot instruction file found: + - `.github/copilot-instructions.md` not present. + +If any of the above files are added later, treat them as higher-priority constraints and update this document.