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
- Snapshot current state for later diffing:
chezmoi managed | sort > /tmp/managed-before.txt
- 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.md → home/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)
- Create repo-root
.chezmoiroot containing exactly home.
- 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.
- Update
.github/prompts/fix-issue.md to note that the chezmoi source state lives under home/.
- 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.
- Apply with
chezmoi apply, then commit per Conventional Commits.
Acceptance criteria
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/
Problem
This repo's root is the chezmoi source root, so every top-level entry maps 1:1 into
~. That forcesAGENTS.mdto serve two audiences with one file:~/AGENTS.md, read on every machine)With the current layout there is no way to give the two audiences different content:
~/AGENTS.md(e.g.symlink_AGENTS.md) is a duplicate-target error..chezmoiignorepatterns match target paths, so ignoringAGENTS.mdkills every entry targeting~/AGENTS.md, symlink included.Related symptom: repo-only files leak into
~unless explicitly ignored.UNLICENSE-AUDIT.mdcurrently deploys to~/UNLICENSE-AUDIT.md(onlyREADME.mdandLICENSEare ignored today).Goal
AGENTS.md= repo-specific agent instructions only; not deployed.home/AGENTS.md= global agent guidance; deployed to~/AGENTS.md.Approach:
.chezmoirootAdd a repo-root
.chezmoirootfile containinghome, makinghome/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
home/and move the source state into it (usegit mvto 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.tmplprivate_Library/,private_dot_config/,private_dot_factory/,workspace/AGENTS.md→home/AGENTS.md(becomes the global file).chezmoiignoreand.chezmoi.toml.tmpl(special files live in the source root; ignore patterns are target-relative, so their contents don't change).chezmoirootcontaining exactlyhome.AGENTS.mdwith chezmoi-repo-specific instructions only (Conventional Commits requirement,dot_/.tmplnaming, code review and testing conventions). Keep purely global guidance inhome/AGENTS.md..github/prompts/fix-issue.mdto note that the chezmoi source state lives underhome/.~/UNLICENSE-AUDIT.mdis no longer managed (intentional);~/AGENTS.mdremains managed, now sourced fromhome/AGENTS.md. Nothing else changes.chezmoi apply, then commit per Conventional Commits.Acceptance criteria
chezmoi source-pathprints~/.local/share/chezmoi/homechezmoi manageddiff vs. pre-migration shows only theUNLICENSE-AUDIT.mdremovalchezmoi apply --dry-run --verbosereports no unexpected changesAGENTS.mdholds repo-specific instructions and is not deployed~/AGENTS.mdrenders the global guidance fromhome/AGENTS.mddroid-issue-fixerworkflow and prompt still reference valid pathsAlternatives considered
run_after_script copying a global file to~/AGENTS.md: works around the 1:1 mapping, but the deployed file becomes invisible tochezmoi status/chezmoi managed, so drift goes undetected.Notes
chezmoi updatepicks up.chezmoirootautomatically; deployed targets don't move, so no re-init is needed. Fresh clones:chezmoi initreads.chezmoi.toml.tmplfrom the new source root.~/.local/share/chezmoi/<file>must now use~/.local/share/chezmoi/home/<file>.git log --followworking.Out of scope
home/