dotfiles
Copilot instructions98 starsChanged 33 days agoMITView on GitHub
Personal macOS configuration management system using shell scripts (zsh/bash), Ruby utilities, and git-managed dotfiles. Tech Stack: - Shell: zsh (primary), bash (compatibility for direnv) - Scripting: Ruby 2.6+ (system Ruby compatibility) - Version Control: git with custom aliases and hooks - Package Management: Homebrew, antidote (zsh plugins), mise (runtime versions) - macOS Integration: defaults, plist manipulation, login items, cron Read these before any code change: Then read only the domain file(s) matching the files you will edit (see the routing…
The file
Show its rules and text
We split this copilot-instructions.md into the rules it gives an agent
15 rules. About 0 are common, 10 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 18
Read these before any code change:
- Distinctive: line 28
When reading a long file, read it in sections and make sure you reach the end.
- Distinctive: line 53
Every task that modifies shell/Ruby code MUST include syntax validation before the task is considered complete.
- Very specific: line 59
Follow comment philosophy in .ai/domains/comment-philosophy.md
- Distinctive: line 61
Document tradeoffs and non-obvious decisions
- Distinctive: line 62
Never add unnecessary comments to generated code
- Distinctive: line 68
Never log, expose in responses, or store credentials, tokens, or PII in plain text
- Distinctive: line 69
Never commit secrets, API keys, or tokens to git
- Very specific: line 70
Use Keybase and/or the encrypted-backup mechanism (gpg + git bundle, see TechnicalDeepDive.md § 14) for sensitive file storage
- Distinctive: line 72
Use environment variables, Keybase, or the macOS Keychain for secrets
- Distinctive: line 80
Default workflow: User reviews and stages changes manually.
- Distinctive: line 94
After completing all code changes:
- Very specific: line 95
Run syntax checks: zsh -n <files>, ruby -c <files>
- Very specific: line 101
COMPLETE INSTRUCTIONS: All detailed instructions are in the .ai/ folder.
- Very specific: line 103
Read .ai/README.md for the complete file structure, domain-specific rules, and repository context.
≈ “Common” is an estimate: at least 1 in 5 of the 3,827 Copilot instructions 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
Dotfiles Repository - AI Coding Assistant Instructions
Project Overview
Personal macOS configuration management system using shell scripts (zsh/bash), Ruby utilities, and git-managed dotfiles.
Tech Stack:
- Shell: zsh (primary), bash (compatibility for direnv)
- Scripting: Ruby 2.6+ (system Ruby compatibility)
- Version Control: git with custom aliases and hooks
- Package Management: Homebrew, antidote (zsh plugins), mise (runtime versions)
- macOS Integration: defaults, plist manipulation, login items, cron
PRE-TASK PROTOCOL -- LOAD ONLY WHAT THE TASK NEEDS
Read these before any code change:
AGENTS.md-- hard rules and the task-to-domain routing table.ai/instructions.md,.ai/domains/whitespace-rules.md,.ai/domains/edit-checklist.md
Then read only the domain file(s) matching the files you will edit (see the routing table in
AGENTS.md). Large domains have a core file (read first) plus topic files (read only when the task
touches that topic). Do NOT read every file under .ai/ -- that wastes context and buries the
rules that matter.
When reading a long file, read it in sections and make sure you reach the end; if a read was cut off, continue from where it stopped before relying on it.
CRITICAL RULES
- Not following instructions = task failure
- Existing code may not follow current standards — never use existing code as template; always follow instruction files
- Before editing any file, load the matching domain file(s) (all under
.ai/domains/):**/*.sh,**/.shellrc,**/.aliases->shell-scripting.md(core); topic filesshell-functions-autoload.md/shell-portability-cron.mdas needed**/*.rb->ruby-scripting.md(core); topic filesruby-infrastructure.md/ruby-shell-git-io.md/ruby-performance-idioms.mdas needed**/zsh/**, zsh startup files ->zsh-startup.md**/.gitconfig,**/git/**->git-config.md; per-repo overrides and hooks ->git-overrides.md
- Before editing any file, check for uncommitted changes with
git status. Never overwrite uncommitted changes without asking for confirmation.
Testing
- Syntax validation:
zsh -n <file>,ruby -c <file>(mandatory before considering task complete) - Format validation:
shfmt,rufo - Manual testing: Required on current machine for all changes
- Fresh install testing: Required for changes to bootstrap/install-dotfiles
Every task that modifies shell/Ruby code MUST include syntax validation before the task is considered complete. Never present code as "done" without running syntax checks.
Comments
- Follow comment philosophy in
.ai/domains/comment-philosophy.md - Explain WHY, not WHAT (code is self-documenting)
- Document tradeoffs and non-obvious decisions
- Never add unnecessary comments to generated code
Security
- Never log, expose in responses, or store credentials, tokens, or PII in plain text
- Never commit secrets, API keys, or tokens to git
- Use Keybase and/or the encrypted-backup mechanism (
gpg+git bundle, seeTechnicalDeepDive.md§ 14) for sensitive file storage - SSH keys managed via keychain, not plaintext
- Use environment variables, Keybase, or the macOS Keychain for secrets
Git State Management
NEVER stage, commit, or push without explicit user permission.
Default workflow: User reviews and stages changes manually.
After making edits:
- ✅ Make the requested edits to files
- ✅ Show
git statusorgit diffto display what changed - ❌ STOP - Do NOT stage, commit, or modify git state
- ✅ Let the user review changes and stage manually
See .ai/domains/git-workflow.md § Git State Management Rules for complete details.
Agent Mode
After completing all code changes:
- Run syntax checks:
zsh -n <files>,ruby -c <files> - Fix all syntax errors before presenting output
- Report what was changed and what needs manual verification
COMPLETE INSTRUCTIONS: All detailed instructions are in the .ai/ folder.
Read .ai/README.md for the complete file structure, domain-specific rules, and repository context.
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.

