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.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
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
- Very specific: line 18
Maintenance: when adding or moving rules, or on the periodic cadence, follow .ai/README.md § Periodic Review (size thresholds, dedupe, …
- Distinctive: line 52
STOP: Do not stage, commit, or otherwise change git state.
- Distinctive: line 87
When choices conflict, this order wins:
- Distinctive: line 94
Document the tradeoff in a comment when priorities conflict.
- Very specific: line 157
Ask ONLY if the repo cannot answer: undocumented team conventions, branch/PR/release expectations, or missing setup prerequisites.
≈ “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.
Files
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.mdbefore 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 script | ruby-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, .envrc | shell-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 constants | logging-conventions.md, script-depth-tracking.md, path-constants.md |
.gitconfig, git aliases, scripts/git-*, .gitattributes | git-config.md |
Per-repo overrides (upreb-<basename>.*), git hooks | git-overrides.md |
| Staging, committing, branching, rebasing | git-workflow.md, changelog.md (commit messages), ../REBASE-AND-REFACTORING-METHODOLOGY.md |
fresh-install-of-osx.sh, install-dotfiles.rb, bootstrap scripts | fresh-install.md |
Adding/removing files under files/ | custom-gitignore-maintenance.md |
| SSH config | ssh-config.md |
| Markdown with copy-paste command blocks | markdown-blocks.md |
| Comments, non-ASCII characters | comment-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.
- Make the requested edits.
- Show
git status/git diff. - 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 executableRuby scripts:
/usr/bin/ruby -c file.rb # Syntax (Ruby 2.6 compat required)
rufo file.rb # FormatAll 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:
- Startup speed (for the zsh hot path)
- Maintainability (readability, DRY, clear intent)
- POSIX compatibility (when scripts run in bash/direnv)
- 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)
&&underset -e-- a standaloneA && BwhoseAis expected to be false triggers the ERR trap. Useif A; then B; fi. Safe exception:A && B || CwhereCreturns 0. Seeshell-scripting.md§&&as Conditional.- Ruby scripts are dual-mode --
module X; extend self; def run(...)returning a boolean (neverexit), plus anif __FILE__ == $PROGRAM_NAMECLI block. Call other scripts viarequire_relative+Mod.run, not a subprocess. Seeruby-scripting.md§ Dual-Mode. - Never hardcode paths -- shell
${DOTFILES_DIR},${PERSONAL_BIN_DIR},${XDG_CONFIG_HOME}; RubyEnvVars::XDG_CONFIG_HOME.join(...). Defined infiles/--HOME--/.shellrcandscripts/utilities/env_vars.rb. Seepath-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.mdwins every conflict with the generic rules. - No subshell forks on the startup hot path -- use
${PWD:t}not$(basename ...), the cachedis_arm, thezsh/statmodule. Seezsh-startup.md§ No Subshell Forks. - Per-repo git overrides --
push/pull/cc/uprebdispatch to${PERSONAL_BIN_DIR}/<command>-<basename>.rb(or.sh;.rbwins) viaGitOverrides.script_for. Override scripts useLogging.run_scriptandGitCommands.<cmd>(args: ARGV, header: false). Seegit-overrides.md. - 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 viazsh -c "source ~/.shellrc && clone_repo_into ...". - UTF-8 file reading in Ruby -- use
Core.read_lines_utf8/Core.each_line_utf8, never bareFile.readlines/File.foreach(US-ASCII under cron breaks on em dashes). Seeruby-shell-git-io.md§ UTF-8 File Reading. - Whitespace rules after every non-
.mdedit --domains/whitespace-rules.md. - Fresh install must be idempotent -- every section has a guard that skips finished work;
supports vanilla-OS (
FIRST_INSTALL=1) and pre-configured modes. Seefresh-install.md. - Logging auto-indents -- never add manual leading spaces to
info/Logging.infooutput; indentation follows_DOTFILES_SCRIPT_DEPTH. Seescript-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.
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
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.

