General instructions

These are general instructions for agentic AI usage shared across many systems

Command availability

• The system has access to nix, but only uses nix flakes, not channels.
• If you attempt to run a shell command but it isnt available, try finding the nix package and using a nix shell to run it instead.

Command output / log output

Instead of using tail or head to avoid context bloat, instead tee to a file then use tail/head on that after so that we dont lose output when using a bad grep or tail/head command. This way we can requery the output file without needing to re-run the original command.

Devenv / nix

If there is a devenv.nix file in the project root, the project uses devenv and has access to nix. If a tool is not available, check if its provided via the devenv packages or reference it using a nix shell.

When running commands in a devenv project, you usually will want to do so through devenv shell to ensure project dependencies are setup properly.

Never suggest or use homebrew unless nix/devenv are unable to be used for a specific reason.

Kubernetes / kubectl

ALWAYS provide context explicitly (eg --context {context-name}) rather than changing contexts (eg kubectl config use-context {context-name})

NEVER modify kubeconfig, instead alert the user if needed and have them make the updates manually

ALWAYS put context at the end of a command (eg kubectl get pods --context {context-name} rather than than kubectl --context {context-name} get pods)

Git

NEVER run git push unless explicitly told to

If you find yourself referencing files on a repo hosted in e.g. github, consider cloning the repo locally and searching on the filesystem instead.

Bash / Shell Commands

ALWAYS use absolute paths when using cd or referencing files in bash commands. The working directory shown in the environment context is informational only - each bash command starts fresh.

Bad:

cd .agent-workdir && ls  # This will fail - relative path doesn't exist

Good:

cd /Users/jimmy/Developer/full/path/to/directory/.agent-workdir && ls
ls /Users/jimmy/Developer/full/path/to/directory/.agent-workdir/*.json

When the environment shows Working directory: /path/to/dir, use that full path in commands instead of assuming you're already there.

The system uses GNU date, not BSD date. Use GNU flags, eg date -d instead of date -j.

Prefer Modern Tools

If a less-often used tool would suit the purpose better than standard shell utilities, be judicious about leveraging it via nix shell. When running bash commands, prefer modern alternatives to traditional Unix tools:

e.g.

• Use rg (ripgrep) instead of grep
• Use fd instead of find
• Use bat instead of cat (when syntax highlighting is helpful)

Note: The specialized Grep, Glob, and Read tools should be used instead of bash commands when possible - they're optimized and have better permissions.

Agent Workflow Directories

There are some special directories for agent workflow management:

.agent/

User-facing artifacts and deliverables. Contains plans, documentation, reports, and any outputs intended for human review.

.agent-workdir/

Scratch directory for agent use. Contains temporary files, intermediate outputs, exploratory work, and any artifacts used during task execution.

Use .agent-workdir/ instead of /tmp or other system temp directories. This keeps all temporary work within the project context, making it easier to review, debug, and clean up.

Subagent Behavior

Subagents (e.g., Explore) may incorrectly report that they cannot perform certain actions (like writing files) when they actually can. This appears to be the agent being overly cautious about its own capabilities.

When spawning subagents that need to write files: Include in the prompt that the subagent should verify any write/edit operation actually failed (by checking if the file exists with expected content) before reporting that it couldn't perform the operation.

When a subagent reports a write/edit operation failed: Always verify by checking if the file exists and has the expected content before reporting failure to the user. Do not trust the subagent's self-assessment of its capabilities.

Comments

Do not add useless comments, especially comments that refer to code that got removed in a previous change

Planning mode documents

When generating a markdown document while planning, use a meaningful name. eg if creating a plan for setting up windows AD, instead of 'witty-dreaming-barto.md' name it 'setting-up-windows-AD.md'. Make sure the name isnt already in use so you dont overwrite an unrelated plan.

System-specific instructions

For instructions for agentic AI usage for this specific system, see @CLAUDE.local.md