Instructions for Codex and automated contributors

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

Start every task

Run git status --short --branch and git log --oneline -5.
Read this file and docs/PROJECT-STATE.md.
Read only the current milestone/request and the domain documents it directly affects.
Use git show, git diff, rg and file-specific reads to locate the relevant implementation and tests.
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.
The public Compose deployment contains only dogama and agent. Do not add setup sidecars, init containers, user-managed internal secrets, host bootstrap scripts or host-system configuration unless the owner explicitly accepts that architectural change.
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.
Documentation is part of the product contract. When implementation, deployment behavior, configuration, environment variables, architecture, user-facing workflows or release behavior changes, update every affected canonical document and example in the same branch.
Before completing a contract change, search the repository for the superseded behavior and resolve stale or contradictory references. A task is not complete while documentation or examples contradict the implementation.
Do not duplicate canonical configuration files such as compose.yaml into README.md or other documentation when that copy can drift; reference the canonical file instead.
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

Git operations are explicitly authorized for this repository. Codex must use the normal feature-branch, commit, push and pull-request workflow below; never invent a no-Git constraint.
Fetch origin before branching and base each dedicated feature branch on the current origin/main, preserving any user-owned working-tree changes.
Git delivery is mandatory for every implementation or milestone: create a dedicated feature branch from an up-to-date main, make logical commits, push the branch with the codex Gitea account, and open a pull request to main.
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.
Develop each milestone on its own dedicated working branch.
After a milestone's validations and commits, always push its working branch to Gitea using the codex account. The milestone is not complete until the remote branch exists.
After pushing, open a pull request from the working branch to main. If automatic creation is technically unavailable, provide the exact creation URL and information immediately and report the blocker.
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

Read AGENTS.md and docs/PROJECT-STATE.md.
Read only the current milestone specification.
Inspect recent commits and the diff from the relevant baseline.
Locate affected files with targeted searches.
Implement the smallest complete change.
Run targeted tests first.
Run the applicable global validations.
Update docs/PROJECT-STATE.md with the new baseline, delivered behavior, durable decisions, limitations and next work.
Review the final diff and validation status, then commit the completed milestone.
Push the working branch to Gitea with the codex account and create, or provide the exact link to create, a pull request to main.

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.

For changes that affect the web interface, exercise the relevant screens and states in a real browser when the environment permits it. Capture screenshots and use them to check at least the overall rendering, alignment, overflow, labels, primary states, relevant responsive behavior and obvious visual regressions. Screenshots are local validation artifacts and must not be committed unless explicitly requested or another project rule requires it. If browser validation or screenshots are technically unavailable, state that explicitly in the completion report.

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.

7.8 KiB Raw Permalink Blame History