|
|
|
@@ -1,97 +1,75 @@
|
|
|
|
|
# Instructions for Codex and automated contributors
|
|
|
|
|
|
|
|
|
|
Read `README.md` and the relevant documents under `docs/` before changing implementation or contracts.
|
|
|
|
|
Work incrementally. Do not perform a repository-wide audit unless the user explicitly requests one.
|
|
|
|
|
|
|
|
|
|
## Non-negotiable rules
|
|
|
|
|
## Start every task
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Change workflow
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
## Product invariants
|
|
|
|
|
|
|
|
|
|
## Codex operating workflow
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
Stop and report any request that would weaken these boundaries.
|
|
|
|
|
|
|
|
|
|
### Git, branches and releases
|
|
|
|
|
## Change rules
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
### Security and scope
|
|
|
|
|
## Git workflow
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
- 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`.
|
|
|
|
|
|
|
|
|
|
### Network and dependencies
|
|
|
|
|
## Standard milestone procedure
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### Caches and temporary files
|
|
|
|
|
## Validation
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
For documentation-only changes:
|
|
|
|
|
|
|
|
|
|
### Required validation
|
|
|
|
|
```sh
|
|
|
|
|
python tools/validate_spec.py
|
|
|
|
|
git diff --check
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For Go implementation changes, run the applicable complete validation set from
|
|
|
|
|
the repository root:
|
|
|
|
|
For Go changes, run the applicable full set from the repository root after targeted tests:
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
gofmt -w <changed-go-files>
|
|
|
|
@@ -102,33 +80,18 @@ go test -race ./...
|
|
|
|
|
go vet ./...
|
|
|
|
|
staticcheck ./...
|
|
|
|
|
golangci-lint run
|
|
|
|
|
python3 tools/validate_spec.py
|
|
|
|
|
python 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.
|
|
|
|
|
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
|
|
|
|
|
## 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.
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
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.
|
|
|
|
|