AGENT SAFEGUARDS (non-negotiable)
Operating principles
1. Prefer clear code over comments.
- Use comments only for: non-obvious reasoning, security invariants, protocol quirks, or “why” that code cannot express.
- Prefer descriptive names, small functions, and explicit types over commentary.
2. Solve root cause, not band-aids.
- Do not add retries/timeouts/logging to hide failures unless the root cause is addressed or explicitly impossible to fix.
- If a workaround is necessary, document the root cause and the exact reason it can’t be fixed now.
3. Use idioms of the language and ecosystem.
- Follow standard style guides, conventions, directory layout, and tooling.
- Avoid clever patterns that fight the ecosystem. Prefer boring, maintainable solutions.
Quality gates
4) Tests must run after each modification.
- After any functional change, run the relevant test suite locally (or in CI steps) and ensure it passes.
- If tests cannot run (missing dependency, environment), add or update a runnable test harness or clearly state what is required.
- Never leave the repo in a state where tests are known failing.
5. Documentation for all features.
- Every new feature must have usage docs + one runnable example.
- Docs must include intent, flags/config, and failure modes.
- Prefer docs that answer user questions (“How do I…”) and include copy/paste snippets.
6. Update CHANGELOG with all changes.
- Every user-visible change must be added to CHANGELOG.md under “Unreleased”.
- Use categories: Added / Changed / Fixed / Security / Deprecated / Removed / Chores.
- Mention migration steps if behavior changes.
Robustness & correctness
7) Include error handling everywhere it matters.
- Never ignore errors; propagate with context.
- Wrap/annotate errors so the caller has actionable info.
- Ensure exit codes/return values are correct and consistent.
8. Test edge cases and invariants.
- Add tests for: empty inputs, invalid inputs, boundary values, timeouts, large payloads (reasonable), and concurrency/ordering if relevant.
- Include at least one test for each bug fixed to prevent regressions.
Security & safety (important for agentic tooling)
9) No harmful actions by default.
- Do not delete data, rotate secrets, publish releases, or mutate external systems unless explicitly requested.
- Treat external calls (network, cloud APIs) as “dangerous”: require explicit opt-in via config/flags.
10. Least privilege and safe defaults.
- Minimize permissions, capabilities, scopes, and access tokens.
- For Kubernetes artifacts: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation=false, drop ALL capabilities unless justified.
11. No secret leakage.
- Never print tokens, passwords, or full credential material to logs.
- Redact known secret patterns; avoid echoing env vars that might contain secrets.
12. Deterministic builds and reproducibility.
- Prefer pinned versions, lockfiles, and deterministic packaging.
- Avoid “download latest at build time” unless necessary.
Change management rules
13) Small, reviewable diffs.
- Prefer incremental changes with clear commit boundaries.
- If a refactor is needed, do it in a separate commit/PR before feature changes.
14. Respect existing standards and tooling.
- Use the repo's existing lint/format/test tools (Makefile/package scripts/cargo test/etc.).
- If tooling is missing, add it in a minimal conventional way.
15. Provide a “How to verify” section in PR descriptions/output.
- Include exact commands: build, lint, unit tests, integration tests (if any).
Agent execution constraints (for local runners / GH actions)
16) Only modify files that are in-scope for the task.
- Do not reformat unrelated files.
- Do not introduce new dependencies unless justified.
17. When uncertain, choose the safer option and make it explicit.
- Prefer failing fast with actionable errors over silent fallback.
- If ambiguity remains, implement a guardrail and document the decision.
18. When really uncertain, ask for help.
- Avoid making assumptions without asking for confirmation.
19. When running locally, prefer the mcp edit tool to direct file edits.
- If issues arise where files seem unedited, alert the user before continuing.
20. Prefer bash commands/scripts to python3 when investigating.
Definition of implement issue
- Find the issue in github issues.
- If not found, inform the user.
- If found:
- Fetch from origin
- Create a branch with the issue number in the name from origin/main.
- Implement the issue.
- Run all e2e tests.
- If during implementation, obvious errors were found in the originating issue, also add a comment to the issue about the fix.
- If running from Claude Code or Claude Desktop:
- Do NOT create a PR automatically.
- Instead, present a summary of changes and let the user decide when to create the PR.
- Otherwise (e.g. GitHub Copilot, Junie, or other automated agents):
- Create a PR with the issue number in the title.
- Make sure the PR passes CI.
Definition of done
- Code compiles without warnings.
- Code is linted.
- Code is formatted.
- `dprint check` passes with no issues (Markdown, JSON, TOML, YAML, Dockerfile).
- Tests pass.
- Docs updated.
- CHANGELOG updated.
- Edge cases tested.
- Security posture maintained.
- Output includes a concise summary of changes + how to verify.
- For rust code:
- All unsafe code is annotated.
- Use explicit lifetimes where necessary.
- Use clippy lints.