DoGaMa-serv/AGENTS.md

Instructions for Codex and automated contributors

Read README.md and the relevant documents under docs/ before changing implementation or contracts.

Non-negotiable rules

1. Preserve the product invariants in README.md.
2. Do not give the main application direct Docker-socket access.
3. Do not implement integrations as native plugins, host executables, scripts, or sidecar containers. Integrations are WebAssembly adapters only.
4. Do not add arbitrary command execution, arbitrary Docker API proxying, arbitrary host paths, or unrestricted network access.
5. Treat templates and module manifests as untrusted input. Validate them against specs/*.schema.json before persistence or execution.
6. Keep secrets out of API responses, logs, audit payloads, exports, error messages, and test fixtures.
7. Preserve player data and backups by default in every deletion, update, restore, and migration workflow.
8. Keep compose.yaml minimal. Product settings belong in the database and web interface unless they are bootstrap secrets, bind roots, or network/listen settings required before startup.
9. SQLite is the V1 database. Do not introduce an external database, message broker, Kubernetes, or distributed-node design without an accepted architecture decision.
10. Palworld is the reference integration. Any contract change affecting templates, modules, backups, permissions, or instance lifecycles must be checked against both Palworld examples.

Change workflow

• Locate the normative document first.
• State assumptions when requirements are ambiguous; do not silently invent security-sensitive behavior.
• Update documentation, schema, example, implementation, and tests together when a contract changes.
• Prefer small Go packages with explicit interfaces and dependency direction.
• Add migrations for persisted data changes. Never edit an already released migration.
• Use deterministic serialization and stable identifiers.
• Validate JSON Schemas and YAML examples in automated checks.
• Add negative tests for authorization, path validation, module capabilities, archive extraction, and agent operation scope.
• Report what was validated and what still needs physical or integration testing.

Codex operating workflow

These rules are permanent repository policy. A codex exec prompt should name the objective and constraints specific to the task, then rely on this file instead of repeating the repository workflow.

Git, branches and releases

• Start by reading the current branch and working-tree state. Treat existing changes as user-owned and do not overwrite, discard, stage or reformat unrelated work.
• Git commands required by the current task are allowed on working branches. Before any Git write, verify the active branch. Never switch to, modify, commit on, merge into, rebase, reset, delete or push main; if work starts on main, stop before writing and use or request a working branch.
• Commits and pushes on non-main branches are allowed only when they are necessary for the stated task. Do not infer that implementation alone requires publication, and always report the operations performed.
• Codex may create merge/pull requests from working branches when delivery requires review. Codex must never approve or merge them; leave approval and fusion into main to an authorized user in Gitea.
• Do not alter remotes, credentials or repository-wide Git configuration unless the task explicitly requires it.
• Never use destructive recovery commands such as git reset --hard, git clean, or checkout-based file restoration without explicit approval and a verified target list.

Security and scope

• Work only inside this repository unless the task explicitly names another location. Do not expose credentials, tokens, cookies, database contents or private keys in commands, logs, fixtures or reports.
• Preserve every trust boundary and non-negotiable product rule above. Stop and report a conflict instead of weakening authentication, authorization, validation, isolation, redaction or data-preservation behavior.
• Inspect before editing, make the smallest coherent change, and preserve user-owned changes. Do not modify generated or synchronized files unless the repository documents that workflow.
• Do not install system packages, start persistent services, modify host configuration or use elevated privileges without explicit approval.

Network and dependencies

• Treat network access as opt-in. Use it only when the task requires current primary documentation or dependency retrieval.
• Prefer existing pinned dependencies and repository tools. Review changes to go.mod and go.sum; do not add an unrelated dependency or execute code fetched from an untrusted source.
• Never send repository contents, secrets or local data to external services. Record any validation skipped because the network was unavailable.

Caches and temporary files

• Keep Codex-created caches and temporary artifacts outside tracked source paths, preferably under .cache/codex/ or an OS temporary directory.
• Reuse caches when safe. Do not delete or purge shared Go, Python, linter, container or user caches unless explicitly requested.
• Do not leave binaries, databases, coverage files, logs or temporary patches in the repository. Before finishing, remove only artifacts created by the current task and confirmed safe to remove.

Required validation

For Go implementation changes, run the applicable complete validation set from the repository root:

gofmt -w <changed-go-files>
go mod tidy
go test ./...
CGO_ENABLED=0 go build ./...
go test -race ./...
go vet ./...
staticcheck ./...
golangci-lint run
python3 tools/validate_spec.py
git diff --check

Use already installed tools when possible. If a required tool or Python module is unavailable, do not silently install it or omit the check: report the exact blocker and request approval when installation or network access is needed. Run narrower tests during development, but run the full applicable set before declaring completion. A passing build does not replace tests, race detection, static analysis or specification validation.

Completion report

• Summarize behavior changed and list every modified, created or removed file.
• List each validation command with pass, fail or not-run status and the exact blocker for anything incomplete.
• Report the final branch and working-tree state, while distinguishing changes made by Codex from changes that were already present.
• State explicitly whether commits, tags, pushes, branch changes, external writes or persistent host changes occurred. Never claim success for a check that was not run to completion.

Definition of done for a change

• Relevant requirements and acceptance criteria are satisfied.
• Authorization is enforced in the backend, not only hidden in the UI.
• Audit and notification behavior is deliberate.
• Failure and rollback behavior is covered.
• Documentation and machine-readable examples agree.
• Tests cover success, denial, and interruption paths.