Skip to content

AGENTS.md

Note

This file is a high-level context map for AI coding agents. It provides an index to the detailed documentation located in docs/.

Context Map

Topic Description Documentation
Architecture System design, data flow, and core components. docs/architecture/ARCHITECTURE.md
Tools List of all tools, their purposes, and replacements. docs/reference/TOOLS.md
Mise Tasks Automation scripts for install, test, lint, etc. docs/reference/MISE_TASKS.md
Testing Test strategy, BATS suite, and CI pipeline. docs/guides/TESTING.md
Contributing Workflows, code style, and PR guidelines. docs/meta/CONTRIBUTING.md
Server Headless/Server deployment strategies. docs/architecture/SERVER-DEPLOYMENT.md
Work Environments Professional/corporate server deployment guide. docs/guides/WORK-ENVIRONMENTS.md
Shell Policy (ADR-013) Tiered shell strategy and guardrails. docs/adr/013-shell-support-tier-strategy.md
AI Agent Isolation (ADR-014) History isolation strategy for AI coding agent sessions. docs/adr/014-ai-agent-history-isolation.md

Core Concepts

1. Tool Management (Mise)

  • Concept: We do NOT use system package managers (apt, pacman) for tools.
  • Source: mise.toml defines all CLI tools.
  • Execution: Tools are installed to ~/.local/share/mise.

2. Dotfile Management (Chezmoi)

  • Concept: Idempotent, template-based dotfile management.
  • Source: dot_ files in the repo root (e.g., dot_zshrc).
  • Templating: Files ending in .tmpl are processed as Go templates.

3. Unified Command Interface

  • Command: dots is the entry point for all operations.
  • Key Aliases:
  • dots i (install)
  • dots up (update)
  • dots dr (doctor)
  • dots t (test)
  • dots cz (chezmoi wrapper)

4. Testing & Quality

  • Rule: All scripts must be idempotent.
  • Rule: Run mise run lint before committing.
  • Rule: Use command -v for existence checks.
  • Rule: All error messages must go to stderr (>&2).

Critical File Paths

  • Root: ~/repos/dotfiles (or $DOTFILES_DIR)
  • Mise Config: mise.toml
  • Mise Tasks: mise-tasks/*
  • Tests: tests/*.bats
  • Docs Config: config/mkdocs.yml

Capabilities & Limitations

Capabilities

  • State Management: Uses mise to manage tool versions deterministically.
  • Secrets Encryption: age encrypts secrets; chezmoi decrypts at runtime.
  • Multi-OS: Supports Linux (Debian/Arch) and WSL2.
  • Server Mode: Can deploy a minimal environment without GUI tools.

Limitations

  • No Rootless Package Management: Relies on apt/pacman for base system packages (requires sudo).
  • Windows Limitation: Must run inside WSL2; native Windows is not supported.
  • Tiered Shell UX: zsh provides full interactive UX; bash is a stable baseline by design.

Shell Guardrails

  • zsh is the primary interactive shell for workstation UX.
  • bash is a supported stable baseline, especially for servers/homelabs.
  • Keep shell-specific behavior in shell-specific files.
  • Do not bind Enter (Ctrl-M) via Bash bind -x.

Attribution & Identity Policy

  • Human attribution only: Commits, changelog entries, ADRs, and contributor references must list only real human contributors.
  • No AI co-author lines: Do not add Co-authored-by or similar attribution for AI tools/agents (Claude, Codex, Gemini, ChatGPT, etc.).
  • Agent file aliases: CLAUDE.md and GEMINI.md must remain symlinks to this file.