Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (58 loc) · 4.27 KB

AGENTS.md

File metadata and controls

74 lines (58 loc) · 4.27 KB
Raw

AGENTS.md

Guidance for AI agents (and humans) working in this repository.

What this repository is

Personal dotfiles / development-environment preferences. There is no application code, no build step, and no test suite. Every file here is configuration that gets copied or symlinked into $HOME on a developer machine. Mistakes ship silently — a broken .zshrc means a broken shell on the next machine provisioned from this repo, so treat small edits with the same care as production code.

Layout

Path Maps to (typical) Notes
bash/.bash_profile ~/.bash_profile Login-shell setup, history, git-prompt wiring, starship
bash/.bash_aliases ~/.bash_aliases and $ZSH_CUSTOM/aliases.zsh Shared between bash and zsh — keep it polyglot (no bashisms/zshisms)
zsh/.zshrc ~/.zshrc Oh My Zsh, plugins, history options, starship
zsh/.zshenv ~/.zshenv Cargo env only
git/.gitconfig ~/.gitconfig Aliases + defaults; user section is a placeholder on purpose
git/.gitignore_global ~/.gitignore_global Referenced by core.excludesfile
starship/starship.toml ~/.config/starship.toml Prompt config (used by both shells)
terminator/config ~/.config/terminator/config Terminal emulator
lsd/*.yaml ~/.config/lsd/ ls replacement config
scripts/update-git-prompt.sh run, not installed Fetches latest upstream git-prompt.sh to ~/.git-prompt.sh
docs/plans/ — Improvement plans / decision records

Hard rules

  1. Do not vendor third-party scripts. git-prompt.sh was vendored once and went stale; it is now fetched by scripts/update-git-prompt.sh. If a new external script is needed, add a fetch/update script instead of committing the file.
  2. Never commit secrets or personal data. The user section of git/.gitconfig stays as a placeholder (me@example.com); real identity lives only on the machine.
  3. ShellCheck must pass. CI runs ShellCheck (bash dialect) on bash/ and scripts/. Prefer fixing findings; when a finding is a false positive (e.g. a variable consumed by a sourced script), add a targeted # shellcheck disable=SCxxxx directive with a comment explaining why.
  4. zsh files cannot be ShellChecked (unsupported dialect). Validate zsh changes with zsh -n zsh/.zshrc instead.
  5. Anything sourced at shell startup must be guarded. Pattern: [ -f file ] && source file. A missing optional file must never break the shell.
  6. bash/.bash_aliases is shared with zsh. Only use syntax valid in both shells.

Conventions

  • Commits: short imperative subject, optionally prefixed with a gitmoji + type, e.g. 🔧 chore: update command timeout for starship, 🩹 fix: pnpm path …. Match the existing git log style. Commits go directly to master (single-maintainer repo).
  • Comments: these files double as documentation; keep the explanatory comment style (what an option does and why it is set).
  • Indentation/whitespace: governed by .editorconfig.

Verifying changes

# Lint bash + scripts (what CI runs)
shellcheck -s bash bash/.bash_aliases bash/.bash_profile scripts/*.sh

# Syntax-check zsh
zsh -n zsh/.zshrc

# Validate gitconfig parses and keys resolve
git config -f git/.gitconfig --list

# Try the git-prompt updater against a temp path
GIT_PROMPT_DEST=$(mktemp) scripts/update-git-prompt.sh

Pointers

  • Current improvement plan: docs/plans/2026-06-10-improvement-plan.md
  • CI: .github/workflows/shellcheck.yml