agentleFS
vraravamvraravam/dotfiles/AGENTS.md

dotfiles

AGENTS.md98 starsChanged 33 days agoMITView on GitHub

Entry point for any AI coding agent. This file is deliberately short: it holds the hard rules and a routing table. Detailed rules live in .ai/ and are loaded on demand -- read only the files that match the task. - Always read: this file, .ai/instructions.md, and .ai/domains/whitespace-rules.md / .ai/domains/edit-checklist.md before editing code or config. - Read on demand: the domain file(s) matching the files you are touching (table below). Each domain file starts with its scope and a list…

  • Reads credentials
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Maintenance: when adding or moving rules, or on the periodic cadence, follow .ai/README.md § Periodic Review (size thresholds, dedupe, …

    line 18
  2. Distinctive:

    STOP: Do not stage, commit, or otherwise change git state.

    line 52
  3. Distinctive:

    When choices conflict, this order wins:

    line 87
  4. Distinctive:

    Document the tradeoff in a comment when priorities conflict.

    line 94
  5. Very specific:

    Ask ONLY if the repo cannot answer: undocumented team conventions, branch/PR/release expectations, or missing setup prerequisites.

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent Quick Reference

Entry point for any AI coding agent. This file is deliberately short: it holds the hard rules and a routing table. Detailed rules live in .ai/ and are loaded on demand -- read only the files that match the task.

Instruction Architecture

  • Always read: this file, .ai/instructions.md, and .ai/domains/whitespace-rules.md / .ai/domains/edit-checklist.md before editing code or config.
  • Read on demand: the domain file(s) matching the files you are touching (table below). Each domain file starts with its scope and a list of related files; the big ones (Ruby, shell, git) have a core file plus topic files -- read the core first, then only the topic you need.
  • Reference: .ai/context.md (navigation, debugging, testing, related repos), .ai/README.md (layout and tool entry points).
  • Rules apply to code in ${DOTFILES_DIR}, ${PERSONAL_BIN_DIR}, and ${PERSONAL_CONFIGS_DIR}.
  • Maintenance: when adding or moving rules, or on the periodic cadence, follow .ai/README.md § Periodic Review (size thresholds, dedupe, cross-reference checks).

Routing Table

If the task touches...Read (under .ai/domains/)
Any Ruby scriptruby-scripting.md, then as needed ruby-infrastructure.md (Logging/CliParser/EnvVars/requires), ruby-shell-git-io.md (system/GitProcessor/UTF-8), ruby-performance-idioms.md (and ruby-performance-string-ops.md for string-method perf)
Any shell script, .shellrc, .aliases, .envrcshell-scripting.md, then as needed shell-functions-autoload.md, shell-portability-cron.md
Zsh startup files (.zshenv, .zshrc, .zlogin, autoload functions)zsh-startup.md (startup-impact check is mandatory)
Logging/color output, depth tracking, path constantslogging-conventions.md, script-depth-tracking.md, path-constants.md
.gitconfig, git aliases, scripts/git-*, .gitattributesgit-config.md
Per-repo overrides (upreb-<basename>.*), git hooksgit-overrides.md
Staging, committing, branching, rebasinggit-workflow.md, changelog.md (commit messages), ../REBASE-AND-REFACTORING-METHODOLOGY.md
fresh-install-of-osx.sh, install-dotfiles.rb, bootstrap scriptsfresh-install.md
Adding/removing files under files/custom-gitignore-maintenance.md
SSH configssh-config.md
Markdown with copy-paste command blocksmarkdown-blocks.md
Comments, non-ASCII characterscomment-philosophy.md, character-encoding.md

CRITICAL -- apply fixes everywhere: any refactoring, formatting, or pattern fix identified in one location MUST be applied to all matching files across the three directories above. Search first (grep -r "pattern" ${DOTFILES_DIR} ${PERSONAL_BIN_DIR} ${PERSONAL_CONFIGS_DIR}), then edit.

Related repos: git-remote-gpg-encrypt carries its own trimmed copy of the Ruby rules, and homebrew-tap pins its release tag. When a Ruby rule or tool-release change is made here, check whether an adapted version belongs there -- see .ai/context.md § Related Repositories.

Git State Management -- NEVER Modify Without Permission

DEFAULT WORKFLOW: the user reviews and stages changes manually.

  1. Make the requested edits.
  2. Show git status / git diff.
  3. STOP. Do not stage, commit, or otherwise change git state.

Prohibited without explicit permission: git add, commit, reset, restore --staged, checkout, switch, push, rebase, merge, stash, rm, and similar state-changing commands. Permission is one-time, for that one instruction only -- never blanket, never carried into later requests or sessions. Details: domains/git-workflow.md.

Critical Commands (Run After Every Edit)

Shell scripts:

zsh -n file.sh                    # Syntax check
shfmt -w file.sh                  # Format (check .shfmtignore first)
rm -f file.sh.zwc                 # Delete bytecode cache
chmod +x file.sh                  # Ensure executable

Ruby scripts:

/usr/bin/ruby -c file.rb          # Syntax (Ruby 2.6 compat required)
rufo file.rb                      # Format

All files (except .md): ends with exactly one newline, no trailing blank lines, no trailing whitespace -- verification and fix commands in domains/whitespace-rules.md.

Startup-Time Check -- Mandatory for Zsh Startup Files

For any change to .shellrc, .aliases, .zshenv, .zshrc, .zlogin, autoload functions, or other code run during shell startup: verify there is no startup-time regression and report old-vs-new numbers. Starting Ruby on the startup path costs ~100ms -- guard it with a pure-shell freshness check. See domains/zsh-startup.md § Startup-Impact Verification (Mandatory).

Decision-Making Priority Order

When choices conflict, this order wins:

  1. Startup speed (for the zsh hot path)
  2. Maintainability (readability, DRY, clear intent)
  3. POSIX compatibility (when scripts run in bash/direnv)
  4. Zsh built-ins (when they don't conflict with #1-3)

Document the tradeoff in a comment when priorities conflict.

Common Agent Mistakes (one-liners; follow the link for the full rule)

  1. && under set -e -- a standalone A && B whose A is expected to be false triggers the ERR trap. Use if A; then B; fi. Safe exception: A && B || C where C returns 0. See shell-scripting.md § && as Conditional.
  2. Ruby scripts are dual-mode -- module X; extend self; def run(...) returning a boolean (never exit), plus an if __FILE__ == $PROGRAM_NAME CLI block. Call other scripts via require_relative + Mod.run, not a subprocess. See ruby-scripting.md § Dual-Mode.
  3. Never hardcode paths -- shell ${DOTFILES_DIR}, ${PERSONAL_BIN_DIR}, ${XDG_CONFIG_HOME}; Ruby EnvVars::XDG_CONFIG_HOME.join(...). Defined in files/--HOME--/.shellrc and scripts/utilities/env_vars.rb. See path-constants.md. Exception that OVERRIDES this and the defensive ${VAR:-default} / "variable might be unset" guards: SSH config files (files/--HOME--/.ssh/* incl. global_config, templates/ssh-config.template, ~/.ssh/config). ssh cannot expand ${VAR:-x} (it errors), so they use literal ~/.ssh/... paths and no shell-style expansion at all. ssh-config.md wins every conflict with the generic rules.
  4. No subshell forks on the startup hot path -- use ${PWD:t} not $(basename ...), the cached is_arm, the zsh/stat module. See zsh-startup.md § No Subshell Forks.
  5. Per-repo git overrides -- push/pull/cc/upreb dispatch to ${PERSONAL_BIN_DIR}/<command>-<basename>.rb (or .sh; .rb wins) via GitOverrides.script_for. Override scripts use Logging.run_script and GitCommands.<cmd>(args: ARGV, header: false). See git-overrides.md.
  6. Bootstrap functions live in .shellrc, not .aliases -- anything needed before Ruby or the dotfiles repo exists: clone_repo_into, suspend_cron/resume_cron, logging functions, is_file/is_directory/nil_or_empty. Ruby delegates to them via zsh -c "source ~/.shellrc && clone_repo_into ...".
  7. UTF-8 file reading in Ruby -- use Core.read_lines_utf8 / Core.each_line_utf8, never bare File.readlines / File.foreach (US-ASCII under cron breaks on em dashes). See ruby-shell-git-io.md § UTF-8 File Reading.
  8. Whitespace rules after every non-.md edit -- domains/whitespace-rules.md.
  9. Fresh install must be idempotent -- every section has a guard that skips finished work; supports vanilla-OS (FIRST_INSTALL=1) and pre-configured modes. See fresh-install.md.
  10. Logging auto-indents -- never add manual leading spaces to info/Logging.info output; indentation follows _DOTFILES_SCRIPT_DEPTH. See script-depth-tracking.md.

Repository Structure (Quick Map)

~/.config/dotfiles/
├── files/
│   ├── --HOME--/          # Symlinked to ~/ (Brewfile, .shellrc, .gitconfig)
│   ├── --ZDOTDIR--/       # Zsh config (.zshenv, .zshrc, .zlogin)
│   └── --XDG_CONFIG_HOME--/zsh/  # Autoload functions
├── scripts/
│   ├── utilities/         # Shared Ruby modules (logging*.rb, env_vars.rb, env_lite.rb, git_processor.rb, ...)
│   ├── fresh-install-of-osx.sh    # Bootstrap entry point
│   ├── install-dotfiles.rb        # Symlink/copy manager
│   └── capture-prefs.rb           # Preferences export/import
└── .ai/                   # AI instruction files (tool-agnostic)

Key paths:

  • ${DOTFILES_DIR} = ~/.config/dotfiles (this repo)
  • ${PERSONAL_BIN_DIR} = ~/personal/dev/bin (user scripts, not in repo)
  • ${PERSONAL_CONFIGS_DIR} = ~/personal/dev/configs (sensitive configs, not in repo)
  • ${XDG_CONFIG_HOME} = ~/.config
  • ${ZDOTDIR} = ~/.config/zsh

Testing patterns, debugging commands and performance numbers: .ai/context.md.

When to Ask Questions

Ask ONLY if the repo cannot answer: undocumented team conventions, branch/PR/release expectations, or missing setup prerequisites. Do NOT ask about anything covered in .ai/, standard shell/Ruby/git conventions, or the README/Adoption/TechnicalDeepDive docs.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.