agentleFS
vraravamvraravam/dotfiles/.github/copilot-instructions.md

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
  1. Distinctive:

    Read these before any code change:

    line 18
  2. Distinctive:

    When reading a long file, read it in sections and make sure you reach the end.

    line 28
  3. Distinctive:

    Every task that modifies shell/Ruby code MUST include syntax validation before the task is considered complete.

    line 53
  4. Very specific:

    Follow comment philosophy in .ai/domains/comment-philosophy.md

    line 59
  5. Distinctive:

    Document tradeoffs and non-obvious decisions

    line 61
  6. Distinctive:

    Never add unnecessary comments to generated code

    line 62
  7. Distinctive:

    Never log, expose in responses, or store credentials, tokens, or PII in plain text

    line 68
  8. Distinctive:

    Never commit secrets, API keys, or tokens to git

    line 69
  9. Very specific:

    Use Keybase and/or the encrypted-backup mechanism (gpg + git bundle, see TechnicalDeepDive.md § 14) for sensitive file storage

    line 70
  10. Distinctive:

    Use environment variables, Keybase, or the macOS Keychain for secrets

    line 72
  11. Distinctive:

    Default workflow: User reviews and stages changes manually.

    line 80
  12. Distinctive:

    After completing all code changes:

    line 94
  13. Very specific:

    Run syntax checks: zsh -n <files>, ruby -c <files>

    line 95
  14. Very specific:

    COMPLETE INSTRUCTIONS: All detailed instructions are in the .ai/ folder.

    line 101
  15. Very specific:

    Read .ai/README.md for the complete file structure, domain-specific rules, and repository context.

    line 103

≈ “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.

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

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:

  1. AGENTS.md -- hard rules and the task-to-domain routing table
  2. .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 files shell-functions-autoload.md / shell-portability-cron.md as needed
    • **/*.rb -> ruby-scripting.md (core); topic files ruby-infrastructure.md / ruby-shell-git-io.md / ruby-performance-idioms.md as 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, see TechnicalDeepDive.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:

  1. ✅ Make the requested edits to files
  2. ✅ Show git status or git diff to display what changed
  3. ❌ STOP - Do NOT stage, commit, or modify git state
  4. ✅ 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:

  1. Run syntax checks: zsh -n <files>, ruby -c <files>
  2. Fix all syntax errors before presenting output
  3. 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.

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.