Skip to content

AGENTS.md

Latest commit

 

History

History
189 lines (134 loc) · 7.4 KB

AGENTS.md

File metadata and controls

189 lines (134 loc) · 7.4 KB

Agent Guidelines for This Repository

This repository is a chezmoi-managed dotfiles repository. Chezmoi is a tool for managing dotfiles across multiple machines.

Chezmoi Workflow

This repository (~/.local/share/chezmoi) is the source directory. The user's home directory (~/) is the target directory.

The correct workflow is:

  1. Edit files in this repository (the source directory under managed/)
  2. Run chezmoi apply to deploy changes to the target (home directory)
  3. Run chezmoi diff to preview what would change before applying

For files already managed by chezmoi, agents MUST edit files directly in managed/ using the appropriate naming conventions (see below). Agents MUST NOT edit the target copy and then re-add it with chezmoi add.

Chezmoi Commands

Agents MUST NOT execute any chezmoi commands (e.g., chezmoi apply, chezmoi update, chezmoi diff, etc.) without explicit user instruction in the current session.

Chezmoi commands can modify the user's home directory and system configuration. These side effects MUST only occur when the user deliberately requests them.

Repository Structure

.
├── managed/          # Chezmoi source directory (set via .chezmoiroot)
│   ├── dot_*         # Files that become ~/.* (dot_ prefix → . prefix)
│   ├── private_*     # Files with restricted permissions
│   └── *.tmpl        # Template files processed by chezmoi
├── extra/            # Files NOT managed by chezmoi (auxiliary configs)
├── scripts/          # Scripts called by chezmoi itself
├── backup/           # Backup files
└── setup/            # Setup scripts

Chezmoi Naming Conventions

Source Name Target Name Description
dot_gitconfig .gitconfig dot_ prefix becomes .
private_Library/ Library/ Private directory (restricted perms)
*.tmpl * Template file (.tmpl suffix removed)
dot_config/fish/ .config/fish/ Nested directories work as expected

Template Files (*.tmpl)

Template files use Go's text/template syntax with chezmoi extensions. Common patterns in this repo:

  • Variables from config: {{ .email }}, {{ .workingContext }}
  • 1Password integration: {{ onepasswordItemFields "Item Name" ... }}
  • Conditional content: {{- if eq .workingContext "work" }}...{{- end }}

The chezmoi config template is at managed/.chezmoi.toml.tmpl and defines user-specific variables like email and workingContext.

Key Files

  • .chezmoiroot - Points chezmoi to managed/ as the source directory
  • managed/.chezmoi.toml.tmpl - Chezmoi configuration template
  • managed/.chezmoiignore - Files to ignore when applying
  • managed/.chezmoiexternal.toml.tmpl - External file sources

Adding New Files to Chezmoi Management

Agents MUST NOT simply create files in managed/ to start managing new paths. Chezmoi requires files to be added through its CLI before they can be managed.

The correct workflow is:

  1. Create the file in the target location first

    # Example: creating a new script
touch ~/.local/bin/my-script.py
chmod +x ~/.local/bin/my-script.py

  2. Run chezmoi add to start managing it

    chezmoi add ~/.local/bin/my-script.py

    This copies the file to the source directory with the correct naming conventions (e.g., managed/dot_local/bin/executable_my-script.py).

  3. Now edit the source file directly After chezmoi add, the file exists in managed/ and can be edited there.

Safe Operations for Agents

Agents MAY safely:

  • Read and analyze any files in this repository
  • Edit source files in managed/ that are already being managed

Agents MUST ask for permission before:

  • Running chezmoi add to start managing new files
  • Running chezmoi apply, chezmoi update, or similar commands
  • Running chezmoi init or chezmoi init --apply

Commit Message Format

All commits in this repository MUST use Conventional Commits format:

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Common types:

  • feat - A new feature
  • fix - A bug fix
  • docs - Documentation only changes
  • chore - Maintenance tasks
  • refactor - Code change that neither fixes a bug nor adds a feature

Example:

feat(fish): add environment selection for Atlas API

Agents MUST NOT include any agent/AI attribution in commits (e.g., "Generated with Claude Code", "Co-Authored-By: Claude", etc.).

Managing Global AI Agent Rules

This repository manages global rules for AI coding agents (Claude Code, Augment, etc.). These rules are shared across all projects.

Directory Structure

managed/
├── dot_ai-guidelines/rules/    # Shared rules (→ ~/.ai-guidelines/rules/)
│   ├── rfc2119.md              # RFC 2119 key word definitions
│   └── git.md                  # Git/commit rules
├── private_dot_claude/         # Claude-specific config (→ ~/.claude/)
│   ├── CLAUDE.md               # Claude entrypoint (references shared rules)
│   └── rules/                  # Claude-only rules (if any)
└── dot_augment/                # Augment-specific config (→ ~/.augment/)
    └── rules/
        ├── shared-rules.md     # References shared rules location
        └── prompting-workflow.md # Augment-specific workflow rules

How It Works

  1. Shared rules live in managed/dot_ai-guidelines/rules/ and are deployed to ~/.ai-guidelines/rules/
  2. Agent entrypoints reference the shared location:
    • Claude: ~/.claude/CLAUDE.md
    • Augment: ~/.augment/rules/shared-rules.md
  3. Agent-specific rules can still be placed in their native locations (~/.claude/rules/, ~/.augment/rules/)

Adding or Updating Global Rules

To add a new global rule that applies to all AI agents:

  1. Create or edit the rule file in managed/dot_ai-guidelines/rules/
  2. Run chezmoi apply to deploy (with user permission)

To add an agent-specific rule:

  1. Create the rule in the agent's native location:
    • Claude: managed/private_dot_claude/rules/
    • Augment: managed/dot_augment/rules/
  2. Run chezmoi apply to deploy (with user permission)

Removing Files from Target Directory

Chezmoi does not automatically remove files from the target (home) directory when they are deleted from the source. It only manages files that exist in the source state.

To remove files that were previously managed by chezmoi:

  1. Create managed/.chezmoiremove (if it doesn't exist)
  2. Add the target paths (relative to home directory) of files to remove: 
    # Example .chezmoiremove content
.config/old-app/config.toml
.some-deprecated-file
  3. Run chezmoi apply (with user permission) to remove the files
  4. After the removal has been applied, delete the entries from .chezmoiremove (they don't need to stay there permanently)

See chezmoi .chezmoiremove documentation for more details.

References