DoGaMa-serv/AGENTS.md

Instructions for Codex and automated contributors

Work incrementally. Do not perform a repository-wide audit unless the user explicitly requests one.

Start every task

1. Run git status --short --branch and git log --oneline -5.
2. Read this file and docs/PROJECT-STATE.md.
3. Read only the current milestone/request and the domain documents it directly affects.
4. Use git show, git diff, rg and file-specific reads to locate the relevant implementation and tests.
5. Treat existing working-tree changes as user-owned. Never overwrite, discard, stage or reformat unrelated work.

Do not reread all documentation, list every source file, concatenate large files, or emit thousands of log lines when a targeted query is sufficient. Start with targeted tests and concise output; expand diagnostics only after a failure.

Product invariants

• The main application never accesses the Docker socket. Only the private restricted agent does.
• Integrations are WebAssembly adapters only: no native plugins, host scripts, executables or sidecars.
• Never add arbitrary commands, Docker API proxying, host paths or unrestricted network access.
• Validate untrusted templates and manifests against specs/*.schema.json.
• Never expose secrets in APIs, logs, audit events, exports, errors or fixtures.
• Preserve player data and backups by default in deletion, update, restore and migration workflows.
• Keep compose.yaml minimal; ordinary product settings belong in SQLite and the web UI.
• SQLite is the V1 database. Keep the single-host architecture unless an accepted decision changes it.
• Palworld is the reference integration. Check both Palworld examples when a contract affects templates, modules, backups, permissions or instance lifecycle.

Stop and report any request that would weaken these boundaries.

Change rules

• Work only inside this repository unless the task explicitly names another location. Never send repository contents or local data to external services.
• Treat network access, dependency installation, host configuration and persistent services as opt-in; request approval when required.
• State assumptions instead of inventing security-sensitive behavior.
• Make the smallest coherent change; avoid unrelated redesigns.
• Enforce authorization and validation in the backend, not only the UI.
• Update documentation, schema, examples, implementation and tests together when a contract changes.
• Prefer small Go packages, explicit interfaces, deterministic serialization and stable identifiers.
• Add a new migration for persisted changes; never edit a released migration.
• Add negative tests for authorization, paths, archives, module capabilities and agent operation scope when relevant.
• Open detailed documents under docs/ only when their domain is affected. README.md is required only when product invariants, the documentation map or top-level status changes.

Git workflow

• Work only on a non-main feature branch. If the task starts on main, create or request a working branch before editing.
• Never modify, commit on, merge into, rebase, reset, delete or push main.
• Commit or push a working branch only when the task requests delivery. Never approve or merge a Gitea pull request.
• Do not alter remotes, credentials or repository-wide Git configuration unless explicitly requested.
• Never use destructive recovery commands such as git reset --hard, git clean, or checkout-based restoration without explicit approval and a verified target list.
• Before committing, review git status, git diff --stat, the complete relevant diff and git diff --check.

Standard milestone procedure

1. Read AGENTS.md and docs/PROJECT-STATE.md.
2. Read only the current milestone specification.
3. Inspect recent commits and the diff from the relevant baseline.
4. Locate affected files with targeted searches.
5. Implement the smallest complete change.
6. Run targeted tests first.
7. Run the applicable global validations.
8. Update docs/PROJECT-STATE.md with the new baseline, delivered behavior, durable decisions, limitations and next work.
9. Review and report the final diff and validation status.

Validation

For documentation-only changes:

python tools/validate_spec.py
git diff --check

For Go changes, run the applicable full set from the repository root after targeted tests:

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

Use installed tools and pinned dependencies. Do not silently install missing tools; report the exact blocker. Keep caches under .cache/codex/ or an OS temporary directory and remove only artifacts created by the current task.

Completion report

• Summarize behavior and contract changes.
• List modified, created and removed files.
• Report each validation as pass, fail or not run with the exact blocker.
• Report the final branch and working-tree state, distinguishing prior changes from yours.
• Report commits, pushes, branch changes, external writes and persistent host changes explicitly.

A change is complete only when success, denial and interruption behavior relevant to its scope are deliberate, documentation and machine-readable contracts agree, and unfinished integration or physical validation is reported.