oraclemcp AGENTS.md

AGENTS.md - oraclemcp

Operating rules for agents working in this repository.

oraclemcp is an unofficial, engine-free, safe-by-default Oracle Database MCP server in pure Rust: a small Cargo workspace of 9 oraclemcp-* library crates plus the oraclemcp binary. Its optional plsql-intelligence feature embeds the PL/SQL engine for offline tools; the separate plsql-mcp server is deprecated. Independent open-source project; not affiliated with Oracle.

RULE 1 - ABSOLUTE

Do not delete any file or directory unless the operator gives the exact command in-session. This includes files you just created. If something should go, stop and ask first.

Irreversible / outward-facing actions

Never run git reset --hard, git clean -fd, git push --force, branch deletion, or rm -rf on tracked paths without explicit in-session approval. Never force-push main. Do not commit on the operator's behalf without a clear in-session go-ahead. crates.io publishes and registry listings are permanent (versions immutable, names claimed forever); treat publishing as a gated, deliberate step.

Swarm operating constitution

Eighteen rules. Rules 1-12 were mined from the 2026-07 multi-repo swarm retrospective (docs/plan/RETRO_SWARM_CAMPAIGN_2026-07.md §3G, docs/plan/PLAN_ENGINEERING_PROGRAM.md §27.3); rules 13-17 were mined from the 2026-07-21 five-agent session, one per incident it produced (rule 18 from an incident during the session that encoded the others). Binding on every agent in this repo, solo or swarmed — most are new; a few name-and-link existing rules above so the constitution stays the one place to check:

1. Never defer planned work on your own initiative — deferral is the operator's call, not an agent's judgment call.
2. Green means honestly green; surface red before the operator finds it.
3. Claims must be evidence-backed — never assert what you haven't just run and checked.
4. Reread this file (and README.md) until understood, every session, before acting.
5. Think before acting ("ultrathink"): verify, then execute — don't patch on a hunch.
6. Be resource-disciplined: don't trash the host, the disk, or the token/session budget (CARGO_BUILD_JOBS caps, scoped -p builds over full-workspace ones, no unbounded concurrent compiles).
7. Keep driving autonomously, but follow explicit operator choices — model, agent freshness, scope — exactly; deviation is the fastest path to anger.
8. The fail-closed guard is sacred and tighten-only — see "The safety invariant" below; this rule doesn't restate it, it just makes the constitution complete.
9. Confidentiality is absolute: field-test/live-customer identifiers never leave quarantine (todelete/, gitignored) or enter a committed artifact.
10. No surprise costs — cloud resources (OCI, etc.) stay free-tier; a hard rule, not a target.
11. Land complete, not sliced across version bumps or half-shipped across sessions.
12. Escalate blockers to the operator; delegate unforeseen work to the tracker (br create), don't quietly derail the authoritative prompt's scope.
13. A modified file that is not yours is another agent mid-edit, not a defect. Check git status on a file before declaring it broken, and judge the committed truth (git show HEAD:<path>) before filing a build blocker or going idle on one.
14. Close evidence comes from a tree verified clean of other agents' work. Derive the evidence source block from git rather than asserting it; commit your in-scope work first, and generate a whole-tree reproducibility proof from a dedicated clean worktree at HEAD.
15. Read the gate verdict yourself; never infer a pass from a successful push. git push reports what the remote accepted, not what the gate decided. A gate that printed a failure is a failure no matter how the push went.
16. Never block a turn on an unbounded wait. Check once, report, move on. Every wait carries a deadline, and reaching the deadline is a result to report — not a reason to wait again. A blocked turn queues every dispatch behind it.
17. A struct field and its initializers are ONE logical change, landed in ONE commit by ONE agent. The same holds for any edit whose halves do not compile apart: a git mv and its references, a trait method and its impls, an enum variant and its exhaustive matches. Split it across panes and you break the build for everyone in the shared checkout.
18. Commit explicit paths, then verify what landed. git commit -- <path>... and git show --stat HEAD; never -a/git add -A in a shared checkout. A deletion of a path that still exists in the worktree is a stale index snapshot committed over someone else's landed work, not a delete.