nix-config/agents/AGENTS.md

# Personal global agent rules

These rules define my default safety boundaries and working preferences for coding agents.

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 global defaults but MUST NOT weaken safety or secret handling.
Agents MUST follow the higher-priority source when rules conflict and MUST state the conflict
briefly.

## Request handling

- For requests to answer, explain, review, diagnose, or plan, agents MUST inspect the relevant
  materials and report the result. They MUST NOT modify files or external state unless the request
  also asks for changes.
- For requests to change, build, or fix, agents MUST make the requested in-scope local edits and run
  relevant non-destructive validation without additional confirmation.
- 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 paths explicitly placed in scope.
- Agents MUST NOT perform broad operations on the entire home directory.

### Remote changes

- Agents MUST NOT mutate remote state unless the user explicitly requests it.
- Remote mutations include `git push`, creating or updating remote PRs and Issues via `gh`,
  `kubectl apply/delete`, `helm upgrade`, `terraform apply`, and remote `ssh` changes.
- For infrastructure and IaC changes, agents SHOULD use plan, eval, or check commands before
  applying or deploying.

### Destructive and force operations

- Agents SHOULD NOT perform irreversible operations.
- Agents MUST NOT use destructive or force options unless the user explicitly requests or approves
  them, the exact target and scope have been verified, and a recovery path or safety guard is
  available.
- Agents SHOULD use recoverable alternatives and safeguards such as `git branch -d` and
  `git push --force-with-lease`.

### Secrets and authentication

- Agents MUST NOT expose or commit tokens, keys, passwords, kubeconfig credentials, or other
  secrets.
- Agents MUST NOT write secret literals into tracked files. They MUST use environment variables,
  secret managers, or placeholders.
- Agents MUST redact sensitive values from command output, logs, and summaries.
- When explicitly requested, an authentication client MAY consume a user-designated secret source
  solely to authenticate to the specified service.
- Agents MUST keep secrets opaque. They MUST NOT expose them in arguments or output, copy them,
  cache them, persist them, or send them anywhere except the intended authentication target.
- Agents MUST NOT access secret values for any other purpose. They MUST query only metadata or
  identifiers, using commands verified not to reveal secret values.

## Repository state

When the task depends on current remote state, agents SHOULD fetch `origin` when it exists and
network access is available, then SHOULD use its latest default branch as the baseline. If local
history differs in a way that materially affects the requested work or makes the baseline ambiguous,
agents MUST ask which state to use before editing.

## Change discipline

- Agents MUST keep work within the requested scope and MUST NOT refactor unrelated areas unless
  asked.
- Agents SHOULD preserve backward compatibility. They MUST NOT introduce a breaking change unless
  the user explicitly requests it.
- Agents SHOULD keep diffs minimal, reviewable, and grouped by logical purpose.
- Agents MUST NOT revert user changes or unrelated changes unless explicitly asked.
- Agents SHOULD write for the intended reader and make documentation self-contained. Documentation
  SHOULD omit prior states, mistakes, and surrounding context unless they are relevant and necessary
  for the reader's task.
- Agents SHOULD verify changes in proportion to their risk and MUST NOT claim a check passed unless
  it was run.

### Commit messages

- Agents MUST follow the repository convention. Otherwise, they MUST use Conventional Commits.
- Agents MUST derive the message from the staged diff and MUST use an imperative subject no longer
  than 72 characters.
- Agents MUST keep one logical change per commit and MUST NOT amend commits or skip hooks unless
  explicitly requested.

## Tools and environment

- Primary platforms are NixOS and macOS.
- Agents SHOULD use existing task runners and specialized CLI tools instead of reimplementing their
  behavior.
- On NixOS, agents MUST NOT assume FHS paths or conventional system package installers. They MUST
  use `nix run`, the project flake or dev shell, or the project's existing `uv` or `pnpm` workflow,
  and MUST ask before using a different installation method.
- Agents MAY use `npx` for temporary or skill-provided CLIs when it does not modify project
  dependencies or lock files.
- Agents SHOULD use `gh` for authorized GitHub operations, especially code, PR, and Issue search or
  inspection.
- Agents SHOULD prefer SSH for GitHub Git remotes.

## Shell and scripts

### Local commands on personal machines

- Agents SHOULD choose tools in the following order:
  1. Direct executables with native filtering and output options (shell-neutral)
  2. Nushell for pipelines and lightweight orchestration
  3. Python for substantial logic
- Local orchestration MUST use Nushell or Python; local pipelines MUST use Nushell. Agents MUST NOT
  use Bash or another POSIX shell for local pipelines, such as
  `command | grep ... | sed ... | head ...` (fragile around whitespace, newlines, escaping, exit
  codes, binary data, and platform differences).

### Project and target-environment scripts

- Project scripts and commands evaluated on remote hosts, CI, or containers MUST follow the
  project's language and target environment, including its shell.
- Agents MUST NOT introduce Nushell unless the project already uses it or the user explicitly
  requests it.
- When no project convention exists, agents SHOULD use Python by default and Bash only for simple
  portable scripts.

### Script and job reliability

- Multi-step, long-running, networked, or expensive scripts and 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. Polling SHOULD use
  short, target-appropriate intervals and an explicit deadline.

## Communication

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