Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (54 loc) · 4.43 KB

AGENTS.md

File metadata and controls

73 lines (54 loc) · 4.43 KB

Dotfiles

Personal dotfiles managed with chezmoi. This repo is the chezmoi source directory - edit files here, not in ~.

Available Skills

Skill Use When
writing-go-code Writing/editing Go code, interfaces, dependency injection
writing-go-tests Writing test files, assertions, mock selection, test naming
developing-cli-apps CLI commands, flags, Cobra patterns, Huh interactive UI, signal handling
building-go-binaries Compiling the project, troubleshooting build failures
linting-go-code Running linters, fixing lint errors, formatting code
testing-go-code Running unit tests, coverage, benchmarks, regenerating mocks
managing-chezmoi Editing dot_*, private_dot_*, or .tmpl files; chezmoi commands
configuring-zsh .zshrc, .zshenv, plugins, PATH, completions
configuring-github-actions .github/workflows, CI/CD, matrix builds
testing-e2e-containers E2E testing installer in Docker containers (Ubuntu, Debian, Fedora)

Workflow

  1. Read files first - Understand the current state and what needs to change
  2. Load relevant skills - Before editing, load ALL matching skills from the table above (match on file patterns and task type)
  3. Plan the approach - Briefly reason about what changes are needed and how they fit with existing patterns
  4. Make targeted changes - Follow conventions from the loaded skill

Directory Structure

.
├── dot_claude/                 # ~/.claude (Claude global config)
├── .github/workflows/          # CI/CD pipelines
├── installer/                  # Go installer/bootstrapper (has own AGENTS.md)
├── dot_config/                 # ~/.config/* files (sheldon, etc.)
├── dot_zshrc, dot_zshenv, ...  # Shell config files
├── private_dot_ssh/            # ~/.ssh (private files)
└── .chezmoiignore              # Files to ignore during apply

Documentation

  • docs/domain.md — Project-specific terminology, the work environment model, chezmoi data schema, package resolution system, and other domain concepts
  • docs/architecture.md — Top-level project structure: installer, chezmoi templates, shell runtime, and how they connect through the data contract
  • docs/architecture-installer.md — Installer's internal layered architecture: cmd, lib, cli, utils, dependency injection, key design decisions
  • docs/processes/ — End-to-end flows: installation (with sub-processes for compatibility checking, prerequisite installation, shell setup, GPG setup, dotfiles setup), package resolution, shell startup, work environment loading

Key Conventions

  1. Zsh is the primary shell - Most shell config is Zsh-specific
  2. Sheldon for plugin management - Not oh-my-zsh at runtime (used only for vendored snippets)
  3. Templates for conditional config - {{ .chezmoi.os }} for OS-specific logic
  4. Separate work/personal dotfiles - Work configs loaded conditionally in work environments
  5. Global skills and agents live in dot_claude/ - Edit dot_claude/skills/ and dot_claude/agents/ here, never under ~/.claude/ directly

Project Motivation

The goal is an easy, portable setup process for any machine. The installer handles prerequisites (including optional homebrew), installs chezmoi, populates its data file with custom keys (e.g., work vs personal environment), and applies the dotfiles.

While all actions could be performed manually, automating the process saves time and reduces complexity across multiple machines.

Installer

The installer is a Go CLI application in the installer/ directory. It was rewritten from Bash for better maintainability and testability.

Tech stack: cobra (CLI), huh (interactive UI), goreleaser (releases)

For development details, see installer/AGENTS.md.