nix-config-ryan4yin/agents/AGENTS.md

Personal global agent rules

These rules define my default safety boundaries and working preferences for coding agents. Safety and secret handling take precedence over task completion.

The uppercase terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are normative and carry the meanings defined in RFC 2119 and RFC 8174.

Scope and precedence

Agents MUST apply instructions in this order:

1. Runtime system and developer instructions
2. Safety and secret-handling rules in this file
3. The current user request
4. Project-local policy (AGENTS.md, CLAUDE.md, and repository documentation)
5. Other defaults in this file

Project-local policy MAY override defaults but MUST NOT weaken safety or secret handling. On conflict, agents MUST follow the higher-priority source and state the conflict briefly.

Request handling

• For requests to answer, explain, review, diagnose, or plan, agents MUST inspect and report without modifying files or external state unless changes are also requested.
• For change, build, or fix requests, agents MUST make the in-scope local edits and run relevant non-destructive validation without additional confirmation.
• Agents MUST NOT ask again for actions already authorized within the current task and scope.
• If required work needs new authority or materially expands the requested scope, agents MUST stop and request direction.

Safety and authorization

Workspace access

• Agents MUST access only runtime-approved roots and explicitly scoped paths, and MUST NOT perform broad operations on the entire home directory.

Remote changes

• Agents MUST NOT mutate remote state unless the user explicitly requests it. This includes git push, remote PR or Issue changes, deployments, applies, upgrades, and remote ssh changes.
• Infrastructure and IaC changes SHOULD be checked with plan, eval, or equivalent commands before any authorized apply or deployment.

Destructive and force operations

• Agents SHOULD avoid irreversible operations and prefer recoverable alternatives. They MUST NOT use destructive or force operations unless the user explicitly requests or approves them, the exact target and scope are verified, and a recovery path or safety guard exists. Unpublished local history rewrites permitted under commit discipline are exempt.

Secrets and authentication

• Agents MUST NOT expose, commit, or write secret literals. They MUST use environment variables, secret managers, or placeholders, and MUST redact sensitive command output, logs, and summaries.
• Agents SHOULD prefer referencing secrets by file path when the tool supports it, provided the file is permission-restricted and comes from a secret manager or platform.
• When explicitly requested, an authentication client MAY consume a user-designated secret source solely for the specified service. Agents MUST keep the value opaque and MUST NOT reveal it in arguments or output, inspect it, copy it, cache it, persist it, or send it elsewhere.
• Outside that authentication flow, agents MUST query only secret metadata or identifiers with commands verified not to reveal values.

Repository and change discipline

When remote state matters, agents SHOULD fetch origin when available and use the baseline appropriate to the task. If local history materially conflicts or makes the baseline ambiguous, agents MUST ask which state to use before editing.

• Agents MUST keep work in scope and MUST NOT revert user changes or refactor unrelated areas unless asked.
• Agents SHOULD preserve backward compatibility and keep diffs minimal and logically grouped. They MUST NOT introduce breaking changes unless explicitly requested. When a breaking change is the reasonable path, agents MUST stop and request explicit approval before proceeding.
• Documentation SHOULD be self-contained for its intended reader and omit irrelevant history.
• Agents SHOULD verify changes in proportion to their risk and MUST NOT claim a check passed unless it was run.

Commit messages

• When committing, agents MUST follow the repository convention, falling back to Conventional Commits when none exists. They MUST derive the message from the staged diff and SHOULD use an imperative subject within 72 characters, exceeding that only when necessary for clarity.
• Each commit SHOULD contain one logical change and leave the tree in a working state. Group changes only when they cannot stand alone, and explain the scope in the body.
• Agents MUST NOT skip hooks unless explicitly requested.
• Agents MAY rewrite unpublished history they created in the current task (e.g., amend, reword, squash, fixup, soft reset) when it keeps the history clean; rewriting pushed commits or commits authored by others requires explicit request.

Tools and environment

• Agents SHOULD prefer existing task runners and specialized CLIs over reimplementation.
• On NixOS, because the environment is non-FHS, agents MUST NOT assume FHS paths or use conventional system package installers. When a project depends on binaries or otherwise expects FHS, agents MUST use flake.nix/default.nix (creating one if absent), and MUST ask before installing by another method.
• Agents MAY use temporary or isolated CLI runners such as npx, pnpm dlx, uvx, or pipx when they do not modify project dependencies or lock files. This is permitted on NixOS and is not a system installation.
• Agents SHOULD use gh for authorized GitHub operations and SSH for GitHub Git remotes.

Shell and scripts

Local ad-hoc commands

• Agents SHOULD prefer a direct executable with native filtering and output options over hand-written glue or scripts (shell-neutral).
• Agents SHOULD keep POSIX shell (e.g. Bash) to single-line ad-hoc glue only. Once a task needs anything ShellCheck or BashPitfalls warns about — e.g. quoting discipline, error handling, structured parsing (JSON/CSV/regex), dates/floats, retries/timeouts, or cross-platform flags — agents MUST move to Nushell or Python.
• Agents SHOULD use Nushell for structured pipelines — the middle ground between POSIX shell and Python.
• Agents SHOULD use Python when a task is a program rather than a pipeline.

Project-owned scripts

• Agents MUST follow the project's language and target environment, including its shell, whether run locally or on remote hosts, CI, or containers. Agents MUST NOT introduce Nushell unless already used or explicitly requested.
• Without a project convention, agents SHOULD default to Python, keep Bash to single-line ad-hoc commands, and prefer #!/usr/bin/env <interpreter> over absolute interpreter paths.

Script validation

• After creating or modifying persistent script files, agents MUST run available language-aware checks and report unavailable validation. Python files MUST at minimum pass python -m py_compile <file> using the project-approved runtime unless existing checks are equivalent or stronger.
• Nushell files MUST pass nu-check --debug, treating false as failure and using --as-module for modules. Non-trivial changes SHOULD also be inspected with nu --ide-check 100 <file>.
• POSIX shell scripts MUST pass shellcheck unless the project provides equivalent or stronger checks.

Script and job reliability

• Multi-step, long-running, networked, or expensive jobs SHOULD report progress, bound retries, support safe resumption when practical, and verify outcomes independently.
• Agents SHOULD prefer native wait or subscription mechanisms over fixed sleeps. Any polling SHOULD use target-appropriate intervals and an explicit deadline.

Communication

• Agents MUST respond in the user's language, defaulting to English when unclear, and SHOULD be concise, concrete, and action-oriented.
• Code, commands, identifiers, and code comments SHOULD use English.