Roadmap: Symmetrize user-global AI agent instructions

[kurone-kito]

Goal

Bring Codex CLI, Claude Code, and Gemini CLI to parity with GitHub
Copilot CLI on the user-global instructions layer of this
chezmoi-managed dotfiles repository, so every supported AI agent
receives a stable repository-independent baseline (conversation
language policy, Conventional Commits, signing fallback ladder,
coding defaults, guardrails) without depending on a repository-local
entry file being present.

Background

This repository already maintains the project-level AI
instructions in a Copilot-first layout:

• .github/copilot-instructions.md — canonical, fully detailed
  (~380 lines)
• AGENTS.md, CLAUDE.md, GEMINI.md — compatibility shims that
  point at the canonical file
• docs/ai-strategy.md — human-facing strategy note that explains
  the canonical/shim split

The user-global layer is currently asymmetric. Only Copilot CLI
is fully wired:

Agent	Project shim	User-global instructions
GitHub Copilot CLI	.github/copilot-instructions.md	home/dot_copilot/copilot-instructions.md (~173 lines, deployed)
Codex CLI	AGENTS.md	home/dot_codex/config.toml only — no AGENTS.md
Claude Code	CLAUDE.md	none — no home/dot_claude/
Gemini CLI	GEMINI.md	none — no home/dot_gemini/

home/dot_copilot/copilot-instructions.md was introduced in commit
9ee65fa feat(copilot): add user-global copilot cli instructions
and refined through three signing-fallback ladder updates
(aff8888, 20fdfbf, 4cafe09). It acts as a
repository-independent baseline that defers to repository-specific
instructions when they exist.

The three remaining agents either ship no user-global instructions
file (Claude, Gemini) or carry only their tool config without
instructions (Codex). Outside this repository, agents reading those
locations fall back to model defaults — losing the cross-agent
conversation-language policy, the Conventional Commits convention,
and the bounded signing fallback ladder the maintainer relies on for
every repository.

Why this matters

• The maintainer drives multiple AI agents in parallel across many
  repositories. The user-global baseline is what keeps their
  behavior coherent before any repository-specific guidance loads.
• The signing fallback ladder (GPG → classify → optional gpg-agent
  restart → SSH → unsigned) is non-trivial. Without a user-global
  copy for the other agents, that hard-won knowledge is unavailable
  to them in repositories that do not supply project-level
  instructions.
• docs/ai-strategy.md currently documents only the project-level
  layer, so a future contributor cannot tell whether the user-global
  asymmetry is intentional or an oversight.

Tracks

• feat(codex): add user-global Codex CLI instructions #131 — feat(codex): add user-global Codex CLI instructions
• feat(claude): add user-global Claude Code memory file #132 — feat(claude): add user-global Claude Code memory file
• feat(gemini): add user-global Gemini CLI instructions #133 — feat(gemini): add user-global Gemini CLI instructions
• docs(ai-strategy): document the user-global instructions layer #134 — docs(ai-strategy): document the user-global instructions layer

Parallel notes:

• Tracks A, B, and C touch disjoint directories
  (home/dot_codex/, home/dot_claude/, home/dot_gemini/) and
  can be claimed in parallel without rebase risk. Track A adds a
  new file to the existing home/dot_codex/ (which currently only
  contains config.toml); B and C create the directory.
• Track D edits docs/ai-strategy.md only. It is independent of
  A/B/C because the new section describes the layer generically,
  not per-agent file presence. The doc text passes review even if
  A/B/C have not yet landed; once they land, no further doc edit
  is required.
• No Blocked by edges. The reviewer-preferred merge order is D
  first (so the policy lands with the implementations), then A/B/C
  in any order. The IDD discover loop does not enforce that order.

Success criteria

• home/dot_codex/AGENTS.md, home/dot_claude/CLAUDE.md, and
  home/dot_gemini/GEMINI.md all exist in the source tree and
  follow the same structural shape as
  home/dot_copilot/copilot-instructions.md (conversation policy,
  Conventional Commits, full signing fallback ladder, coding
  defaults, guardrails; repository-local precedence note in the
  opening paragraph).
• chezmoi diff against a fresh checkout reports the three new
  files as additions that map to ~/.codex/AGENTS.md,
  ~/.claude/CLAUDE.md, and ~/.gemini/GEMINI.md.
• docs/ai-strategy.md describes the two-layer (project +
  user-global) AI instructions structure and names the
  home/dot_<agent>/... source paths.
• tests/bash/helpers/bats-core/bin/bats tests/bash/ still passes
  unchanged.
• npx markdownlint-cli2 "**/*.md" and the cspell run both pass
  for the new files and the touched documentation.

Out-of-scope

• Reorganizing the existing project-level AI instructions
  (.github/copilot-instructions.md, AGENTS.md, CLAUDE.md,
  GEMINI.md). The doc-only edit in track D is limited to adding
  a user-global-layer section.
• Installing Gemini CLI through mise alongside Claude Code /
  Copilot CLI / Codex CLI in README.md. That is a separate
  availability decision; file it as its own issue if needed.
• Migrating canonical AI guidance away from Copilot-first.
  docs/ai-strategy.md's change policy explicitly defers that
  until benchmarks justify it.

[kurone-kito]

claude-code-c0715eea: issue claim — IDD automation marker. Do not edit.

[kurone-kito]

A1.5 roadmap completion audit — evidence summary

All four tracks under this roadmap are closed via merged PRs:

Track	Issue	PR	Merge commit	Closed at
A — Codex CLI instructions	#131	PR #135	cac548d	2026-05-19T00:09:30Z
B — Claude Code memory file	#132	PR #136	7b4292c	2026-05-19T02:00:05Z
C — Gemini CLI instructions	#133	PR #137	c2f1868	2026-05-19T02:08:37Z
D — docs/ai-strategy update	#134	PR #138	851e18b	2026-05-19T02:22:55Z

All four PRs passed required CI (lint, Lua syntax check, Bash tests (bats)) and all review threads are resolved. No open follow-up issues remain under this roadmap.

Success criteria met:

• home/dot_codex/AGENTS.md, home/dot_claude/CLAUDE.md, home/dot_gemini/GEMINI.md exist on master
• chezmoi diff will deploy these to ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md
• docs/ai-strategy.md now documents the user-global instructions layer with the precedence rule and all four source paths
• All three user-global files follow the same structural shape as the canonical home/dot_copilot/copilot-instructions.md

Closing roadmap.

[kurone-kito]

claude-code-c0715eea: issue claim released — IDD automation marker. Do not edit.