ai-coding-fortress

AGENTS.md — ai-coding-fortress

Instructions for AI coding agents (Codex, Claude Code, Copilot, Cursor, Gemini CLI, opencode, local agents) working on this repo. AGENTS.md is the open standard most of them read (agents.md); CLAUDE.md and .gemini/settings.json point the other two here.

This file is the lab’s policy layer: the guards and gates in the README control what the model says and ships, and these rules control what a coding agent is allowed to do. The project facts are in this top part. The shared rules at the bottom are one baseline kept in sync across all of the author’s repos, and each comes from a real incident.

Project

Project-specific rules

Shared rules (all agents, all projects)

These rules come from real incidents: an agent once took a one-word reply as approval, its backup attempt failed, and it wiped a secrets store anyway; a later sweep found live passwords in unit files, .env files, container config and process arguments.

Destructive actions — hard rules

  1. Explicit yes to the exact action. Before deleting, wiping, re-initialising, force-pushing, dropping or overwriting anything stateful, state the exact command and what will be lost, then wait for an unambiguous “yes” to that command. A vague, one-word or frustrated reply is not approval — ask again.
  2. Safety net first, or stop. Take a snapshot/backup before the destructive step. If it fails, stop and report — never proceed without it. Check that the snapshot actually covers the data (separate volumes are often not in a container snapshot).
  3. Move aside, don’t delete. Prefer mv x x.bak-<date> over rm -rf.
  4. Never wipe or re-initialise a secrets store or identity system. Lost access means asking the owner to unseal / recover — not starting over.
  5. “Blocked” is an answer. If you lack access or permission, say what is blocked and what the user can do. Don’t find a workaround that destroys state or bypasses a control.

Secrets

  1. Secrets live in the secret store (e.g. Vault) and services read them at start. Never put a secret in a repo file, .env, unit file, compose file, container config, chat, log or command-line argument.
  2. Never display secret values, even while debugging: print variable names only and compare secrets by hash or equality. Never ask the user to paste a secret into chat — have them run the command, or read it from a file inside the command.
  3. Pass secrets via stdin or files, never argv — argv is readable by every process (/proc/<pid>/cmdline, ps). With curl:
    • body: --data @<(printf '{"secret_id":"%s"}' "$SID") or --data @-
    • headers: -K <(printf 'header = "Authorization: Bearer %s"\n' "$TOKEN")
    • CI secret variables: map them through the step’s env:; never inline a secret variable macro (e.g. $(SECRET)) into script text.
  4. Rotating = change the store, restart the consumer. If a rotation needs editing files on the consumer, wire the consumer to the store first.

Git and publishing

Working style