Agent rules — all AI tools

Shared rules for every AI coding tool on this machine (Codex, Cursor, Copilot, Antigravity, Trae, opencode, zcode/GLM). Claude Code reads CLAUDE.md, which mirrors these. Keep the two in sync.

Chat vs build

• Detect intent before acting: a question, an opinion request, thinking out loud, or a stream of ideas is a conversation, not a work order. Answer, discuss, wait. No branching, editing, or scaffolding until the user asks for the change or the idea is fully shaped.
• Rushing to code mid-discussion buries the user's next thought under diffs. Stay in the conversation while ideas keep coming; build when direction is confirmed.

Hard rules

• Do not refactor code unrelated to the task. Do not modify unrelated files. Do not install new dependencies without explicit approval.
• No AI attribution, ever: no Co-Authored-By, no "Generated with …" in commits, PRs, or release notes.
• Always create a working branch before starting work. Never commit directly to main/master. Branches land via PR + squash merge (gh pr merge --squash --delete-branch) — never leave any branch but main in local or remote after merging.
• If the working directory has no git repository or no associated remote: stop and ask the user before making changes.
• Never release, tag, push, or publish without an explicit user request in the current session.
• Releases publish via GitHub Actions on tag push ONLY — never locally (no local cargo publish, npm publish, twine upload, no hand-run gh release create). Tag + changelog + README consistent and tests passing before the release push.
• GitHub Actions cost money on private repos: never add or enable a workflow unless explicitly asked. When one exists, it triggers on merge to main or on release tags only — never on every push or PR update. Quality gates run locally (tests, lint, review) before merge instead. When CI exists or is requested, enforce the cost rules in rules/github-actions.md: lint/unit on Linux only, Windows gated to PRs + main, macOS UI/AppKit gated to approved PRs / main / nightly / releases, cancel superseded PR runs, path filters, dependency caches, expensive jobs needs: cheap Linux gates.

Language rules

• Rust: do not combine sources with tests — never put #[cfg(test)] mod tests blocks inside a source file. Go-style siblings: module.rs + module_test.rs, wired from the parent (lib.rs/mod.rs) with #[cfg(test)] mod module_test;.

Memento — learn from mistakes (all tools)

• Repeated-mistake ledger + enforcement. CLI: python3 ~/.agents/memento/memento.py (uv run memento inside this repo). Full protocol: skills/memento/SKILL.md.
• Task start: run memento check and respect its output. On any user correction, hard-won fix, or ignored quality gate: memento hit <slug> --rule "..." --fix "...". On a PROMOTE alert or user "always/never": memento promote <slug>.

Workspace

• Purpose: agent documentation, helpers, and small tools. Each project in its own subdirectory.
• Git workflow detail: rules/git-workflow.md. Release process: rules/releases.md. CI cost rules: rules/github-actions.md. Machine-local (gitignored): rules/local/ — tool fleet, inventories, review bridges.
• Posture: quality first — save tokens by avoiding waste, not by downgrading model quality on work that matters.
• When hard rules change: re-run uv run rulesync, and keep the pointer BLOCK in src/rulesync/core.py in step — it is the condensed "hard minimum" copy of these rules.

Memento-enforced

Rules promoted from the memento ledger. Details/fix: memento show <slug>.

• In uv-managed projects use uv run / uv add only — never bare python or pip; stdlib-only scripts (e.g. memento.py) run with plain python3 (memento: uv-not-python)
• Never ignore SonarQube gate findings — coverage, cognitive complexity, and code smells must be fixed before calling work done (memento: quality-gates-ignored)
• Visual-design agent prompts must carry measurable acceptance criteria (e.g. 'diff obvious in 2s side-by-side', 'gradient sweep >=50 levels'), never soft adjectives like 'restrained' or 'subtle polish' — those produce invisible changes the owner rejects (memento: design-agent-needs-measurable-boldness)
• Unsigned macOS debug binaries re-prompt keychain ACLs on every rebuild and block callers inside SecKeychainFindGenericPassword (masquerades as daemon/IPC hang) — sign dev binaries with a stable codesigning identity (memento: macos-dev-keychain-prompt-loop)
• A Tauri app binary built with plain cargo build --release keeps the dev context (loads devUrl, white window offline) — production binaries must be built through 'tauri build', including --no-bundle (memento: tauri-release-needs-cli-build)
• A merge is not landed until the main-branch CI run is green — check gh run list / pr checks after every squash-merge instead of reporting success from local gates alone (memento: verify-ci-after-merge)
• Never keep a live continuously-written binary DB (e.g. .ptrack/ptrack.redb) tracked in git — it permanently dirties the tree, breaks gh pr merge checkouts, ff pulls, and stash pops; and when untracking it, back the file up first because the merge checkout can delete the on-disk copy (memento: git-tracked-live-db)
• macOS login keychain that cannot auto-unlock returns errSecAuthFailed (-25293) on every write with NO permission prompt — masquerades as app-level 'native credential store unavailable'; it is not a signing or app bug (memento: macos-login-keychain-auth-failed)
• First keychain access from a freshly-linked signed macOS binary can take 1-5s (security server evaluates the whole binary's code signature); keychain-touching requests need generous deadlines or a startup warm-up, and 2s test deadlines on such paths are flaky by design (memento: keychain-first-access-signature-eval)
• On this machine /.cargo/config.toml sets build.target-dir=/.cargo/shared-target for every project, so an agent worktree's cargo build relinks the SAME pam binary the main checkout is executing (AMFI stale-signature kills, 'daemon not ready' hangs, directory-lock stalls); every parallel worktree agent and every local test loop must set its own CARGO_TARGET_DIR (memento: shared-target-agent-worktree-relink)
• The first exec of a freshly linked large macOS binary (100 MB debug pam) stalls in _dyld_start for 5-30+ s (one-time per-inode executable assessment, worse under build load); every later launch is sub-second. Test harnesses that spawn a just-built binary must warm-exec it once (e.g. --version) OUTSIDE their readiness/deadline clocks instead of widening timeouts (memento: macos-first-exec-assessment-stall)