Skip to content

Adopt .chezmoiroot layout to split repo-level and global AGENTS.md #105

Description

@ahjota

Problem

This repo's root is the chezmoi source root, so every top-level entry maps 1:1 into ~. That forces AGENTS.md to serve two audiences with one file:

  • Repo-level agent instructions (read by Droid/Claude Code/OpenCode sessions working in this repo)
  • Global agent guidance (deployed to ~/AGENTS.md, read on every machine)

With the current layout there is no way to give the two audiences different content:

  • A second source entry for target ~/AGENTS.md (e.g. symlink_AGENTS.md) is a duplicate-target error.
  • .chezmoiignore patterns match target paths, so ignoring AGENTS.md kills every entry targeting ~/AGENTS.md, symlink included.

Related symptom: repo-only files leak into ~ unless explicitly ignored. UNLICENSE-AUDIT.md currently deploys to ~/UNLICENSE-AUDIT.md (only README.md and LICENSE are ignored today).

Goal

  • Repo-root AGENTS.md = repo-specific agent instructions only; not deployed.
  • home/AGENTS.md = global agent guidance; deployed to ~/AGENTS.md.
  • All other deployed targets unchanged.

Approach: .chezmoiroot

Add a repo-root .chezmoiroot file containing home, making home/ the chezmoi source directory. Repo-root files (README.md, LICENSE, AGENTS.md, .github/, etc.) then sit outside the source state entirely and chezmoi never sees them.

Plan

  1. Snapshot current state for later diffing:
    chezmoi managed | sort > /tmp/managed-before.txt
  2. Create home/ and move the source state into it (use git mv to preserve history):
    • dot_Rprofile.tmpl, dot_bash_profile.tmpl, dot_bashrc.tmpl, dot_claude/, dot_gitconfig.tmpl, dot_gitignore, dot_local/, dot_pip/, dot_profile.tmpl, dot_shellrc.d/, dot_vimrc, dot_zsh_plugins.txt, dot_zshrc.tmpl
    • private_Library/, private_dot_config/, private_dot_factory/, workspace/
    • AGENTS.mdhome/AGENTS.md (becomes the global file)
    • .chezmoiignore and .chezmoi.toml.tmpl (special files live in the source root; ignore patterns are target-relative, so their contents don't change)
  3. Create repo-root .chezmoiroot containing exactly home.
  4. Write the new repo-root AGENTS.md with chezmoi-repo-specific instructions only (Conventional Commits requirement, dot_/.tmpl naming, code review and testing conventions). Keep purely global guidance in home/AGENTS.md.
  5. Update .github/prompts/fix-issue.md to note that the chezmoi source state lives under home/.
  6. Verify:
    chezmoi source-path          # expect: ~/.local/share/chezmoi/home
    chezmoi managed | sort > /tmp/managed-after.txt
    diff /tmp/managed-before.txt /tmp/managed-after.txt
    chezmoi apply --dry-run --verbose
    Expected diff: ~/UNLICENSE-AUDIT.md is no longer managed (intentional); ~/AGENTS.md remains managed, now sourced from home/AGENTS.md. Nothing else changes.
  7. Apply with chezmoi apply, then commit per Conventional Commits.

Acceptance criteria

  • chezmoi source-path prints ~/.local/share/chezmoi/home
  • chezmoi managed diff vs. pre-migration shows only the UNLICENSE-AUDIT.md removal
  • chezmoi apply --dry-run --verbose reports no unexpected changes
  • Repo-root AGENTS.md holds repo-specific instructions and is not deployed
  • ~/AGENTS.md renders the global guidance from home/AGENTS.md
  • droid-issue-fixer workflow and prompt still reference valid paths

Alternatives considered

  • One shared file (status quo): works, but repo-specific notes deploy to every machine and the two audiences can't diverge.
  • run_after_ script copying a global file to ~/AGENTS.md: works around the 1:1 mapping, but the deployed file becomes invisible to chezmoi status/chezmoi managed, so drift goes undetected.

Notes

  • Other machines: chezmoi update picks up .chezmoiroot automatically; deployed targets don't move, so no re-init is needed. Fresh clones: chezmoi init reads .chezmoi.toml.tmpl from the new source root.
  • Path references: anything hardcoding ~/.local/share/chezmoi/<file> must now use ~/.local/share/chezmoi/home/<file>.
  • History: the move is one large rename commit; git rename detection keeps git log --follow working.

Out of scope

  • Changing deployed file contents (other than the AGENTS.md split)
  • Reorganizing within home/

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions