Dotfiles Repository Conventions

Overview

Repository: Git-controlled dotfiles at /Users/jefffarr/src/dotfiles Main focus: Emacs configuration using org-mode literate programming Multi-machine: Hostname-specific configurations

Core principle: Org source files → generated elisp → modular loading → machine overrides

When to Use

Use this skill when:

• •Working in the dotfiles repository
• •Understanding file naming patterns
• •Need to know directory structure
• •Understanding branch strategy
• •Setting up Claude Code hooks/skills

Directory Structure

dotfiles/
├── .claude/                    # Claude Code configuration
│   ├── hooks/                 # validate_elisp_syntax.py
│   ├── skills/                # This file and related skills
│   ├── instructions.md        # Main instructions (decomposed to skills)
│   └── settings.local.json    # Claude settings
├── bin/                       # Utility scripts (tangle-org.sh)
├── emacs/                     # Emacs configuration
│   ├── core/                 # Core functionality
│   ├── language-modes/       # Programming language configs
│   ├── major-modes/          # Major mode configs (org-roam, etc)
│   ├── look-and-feel/        # UI and themes
│   ├── local/                # Machine-specific ({hostname}.el)
│   └── init.org              # Main entry point
└── [other dotfiles...]

File Naming Conventions

Module Categories

• •core: Core functionality
• •language-modes: Programming languages
• •major-modes: Major mode configurations
• •look-and-feel: UI and themes
• •local: Machine-specific overrides

Branch Strategy

Usage:

• •Work-specific configs → work branch
• •General improvements → master
• •Machine-specific configs work across branches

Claude Code Integration

Hook System

• •File: .claude/hooks/validate_elisp_syntax.py
• •Purpose: Prevents invalid elisp in .el files
• •Scope: Only validates emacs/ directory

Skills System

• •Location: .claude/skills/
• •Purpose: Modular knowledge for specialized assistance
• •Files: See skills in this directory

Module File Template

#+title: Module Name
#+author: Jeff Farr
#+property: header-args:emacs-lisp :tangle module-name.el
#+auto_tangle: y

* Introduction
Description of module purpose.

* Configuration
#+begin_src emacs-lisp
;; -*- lexical-binding: t; -*-

;; Module implementation
#+end_src

Package Configuration Template

(use-package package-name
  :straight (package-name :type git :host github :repo "user/repo")
  :bind (("C-c k" . package-function))
  :hook (mode . package-mode)
  :config
  (setq package-setting value))

Development Workflow

1. •Edit source: Always edit .org files (see emacs-literate-programming)
2. •Follow structure: Use established naming/directory conventions
3. •Test incrementally: Use module reloading (see emacs-modular-config)
4. •Machine-specific: Use hostname configs when needed (see machine-specific-config)

Common Mistakes

Best Practices

File Management:

• •Commit both .org and .el files
• •Never manually edit .el files
• •Keep modules focused and independent

Security:

• •No secrets in repository
• •Use machine configs for private data
• •Assume repo might be public

Performance:

• •Monitor startup time impact
• •Use error handling for resilience
• •Consider lazy loading expensive operations

Cross-References

For detailed information:

• •Literate programming: See emacs-literate-programming skill
• •Module system: See emacs-modular-config skill
• •Org-roam setup: See org-roam-knowledge-mgmt skill
• •Machine overrides: See machine-specific-config skill