Skip to content

AGENTS.md

Latest commit

 

History

History
106 lines (79 loc) · 3.92 KB

AGENTS.md

File metadata and controls

106 lines (79 loc) · 3.92 KB

Agent Instructions: Dotfiles Repository

This AGENTS.md defines rules and conventions for AI agents operating in this dotfiles repository. It is managed by chezmoi for cross-platform deployment (macOS, Arch Linux, CachyOS, Windows).

Note: The file at private_dot_config/private_opencode/GSD.md contains the core AI operating philosophy (Get Shit Done). This root-level file governs this repo specifically.

1. Project Architecture

This repository uses chezmoi for cross-platform dotfile management with Go templates for OS-specific configuration.

Core Structure

  • dot_*.tmpl - Templated dotfiles (Go templates with OS/arch conditionals)
  • dot_* - Plain dotfiles (copied as-is)
  • private_dot_* - Files deployed with restricted permissions
  • run_onchange_* - Scripts that run when their dependencies change
  • .chezmoi.toml.tmpl - Interactive user configuration (prompted on chezmoi init)
  • .chezmoiexternal.toml - External dependencies
  • .chezmoiignore - Platform-specific file exclusions
  • Brewfile - macOS Homebrew package manifest
  • private_dot_config/private_opencode/ - OpenCode AI agent config (our customizations)

Chezmoi Naming Conventions

  • dot_ prefix -> deploys as . (e.g., dot_zshrc.tmpl -> ~/.zshrc)
  • private_ prefix -> sets 0700/0600 permissions
  • .tmpl suffix -> processed as Go template before deployment
  • run_onchange_ prefix -> script runs when hash in comment changes

2. Commands

Chezmoi Lifecycle

  • Apply changes: chezmoi apply (renders templates and deploys)
  • Preview changes: chezmoi diff (show what would change)
  • Dry run: chezmoi apply --dry-run (simulate without applying)
  • Edit source: chezmoi edit ~/.zshrc (opens template in editor)
  • Re-add from live: chezmoi re-add (updates source from live files)
  • First-time setup: chezmoi init <repo-url> (clones + prompts for config)

Homebrew (macOS only)

  • Install dependencies: brew bundle install --file=Brewfile
  • Update manifest: brew bundle dump --file=Brewfile --force

3. Go Template Conventions

When modifying .tmpl files, use chezmoi's Go template syntax:

OS Conditionals

{{ "{{" }} if eq .chezmoi.os "darwin" {{ "}}" }}
# macOS-only content
{{ "{{" }} else if eq .chezmoi.os "linux" {{ "}}" }}
# Linux-only content
{{ "{{" }} end {{ "}}" }}

User Data Access

Data is defined in .chezmoi.toml.tmpl and accessed as .variable_name:

{{ "{{" }} .git_name {{ "}}" }}
{{ "{{" }} .git_email {{ "}}" }}
{{ "{{" }} .ssh_keys {{ "}}" }}

Whitespace Control

Use - to trim whitespace around template actions:

{{ "{{" }}- if eq .chezmoi.os "darwin" {{ "}}" }}

4. Zsh Configuration Conventions

Performance Principles (Crucial)

Do not degrade startup time (currently sub-50ms).

  • Use _cache_eval function for slow init commands (brew, fzf, zoxide)
  • Lazy load where possible (e.g., NVM is lazy-loaded)
  • Background slow operations with &! (e.g., loading SSH keys)

Organization

  • Keep the Powerlevel10k instant prompt block at the top of .zshrc.
  • Group aliases under # === banner comments.
  • Add new plugins to dot_zsh_plugins.txt, not the zshrc template.
  • Do not modify dot_p10k.zsh manually (generated by p10k configure).

5. File Modification Rules

  1. Never write secrets. Use chezmoi's data system or secret manager integration.
  2. Use templates for OS differences. Don't use runtime if [[ "$OSTYPE" ]] — use Go template {{ "{{" }} if eq .chezmoi.os {{ "}}" }} instead.
  3. Test templates: Run chezmoi execute-template < file.tmpl to verify output.
  4. Preview before apply: Always chezmoi diff before chezmoi apply.

6. Git & Commit Conventions

  • Use Conventional Commits format (feat:, fix:, chore:, docs:, refactor:).
  • Keep descriptions lowercase, no trailing period.
  • Example: feat: add windows powershell profile template