feat(codex): add user-global Codex CLI instructions

[kurone-kito]

Parent roadmap: #130 (<!-- dotfiles-roadmap-id: user-global-ai-symmetrization -->)

Background

home/dot_codex/ currently contains only config.toml. Codex CLI
reads user-global instructions from ~/.codex/AGENTS.md when it
starts a session in a repository that lacks a local AGENTS.md.
Today, when this dotfiles repository is applied, Codex sessions in
non-IDD repositories fall back to model defaults for conversation
language, commit-message style, and commit-signing recovery.

For comparison, Copilot CLI is already covered by
home/dot_copilot/copilot-instructions.md (deployed to
~/.copilot/copilot-instructions.md since commit 9ee65fa).

Proposed change

Before drafting, verify that Codex CLI's user-global instructions
loader filename is AGENTS.md (Codex CLI's documented convention
for project-level files; verify upstream docs / changelog for the
user-global equivalent). If a different filename is canonical, name
the new file accordingly and record the source in the PR.

Add home/dot_codex/AGENTS.md. Use
home/dot_copilot/copilot-instructions.md as the reference shape
and adapt it for Codex CLI's interaction model:

• Opening paragraph stating that repository-specific instructions
  (project-level AGENTS.md, .github/instructions/*.md, etc.)
  always take precedence over this file.
• Conversation language policy (match user's language; comments and
  docs in English).
• Conventional Commits guidance (lowercase, user-perspective,
  72-character subject, atomic commits, breaking-change marker).
• The full bounded signing fallback ladder (configured GPG attempt
  → classify failure → optional gpg-agent restart → SSH fallback
  with key discovery → unsigned), matching the same structure used
  in the canonical home/dot_copilot/copilot-instructions.md.
• Coding standards defaults (LF endings, no trailing whitespace,
  trailing newline, lowercase-hyphen filenames).
• Guardrails (do not modify community docs without approval; do
  not claim tests succeeded without running them).

Replace Copilot-specific wording like "Agent mode" / "Plan mode"
with Codex CLI's own pause/continue terminology so the same
behavioral intent translates without product confusion. Where the
Copilot file uses "GitHub Copilot CLI" as the surface name, prefer
"Codex CLI" or surface-agnostic "the agent". Aim for structural
parity rather than a byte-identical copy.

Acceptance criteria

• home/dot_codex/AGENTS.md exists as a plain .md source file
  (not a .tmpl).
• The file opens with a paragraph that explicitly defers to
  repository-specific instructions.
• It contains sections covering Conversation, Commit rules
  (including the signing fallback ladder), Coding standards, and
  Guardrails, in any order that reads naturally.
• The signing fallback ladder spells out: configured GPG attempt,
  failure classification by category (P / C / A / U), conditional
  gpg-agent restart with all three skip clauses (gpgconf not on
  PATH; $SSH_AUTH_SOCK resolves to gpg-agent's SSH socket;
  non-interactive CI), SSH fallback with the same three-step key
  discovery (gpg.format == ssh → gpg.ssh.defaultKeyCommand →
  first non-certificate ssh-add -L line passed as one quoted
  argument), and unsigned as the accepted final fallback. No fixed
  ~/.ssh/id_ed25519 path is named.
• The existing home/dot_codex/config.toml is untouched.
• npx markdownlint-cli2 "home/dot_codex/AGENTS.md" passes (the
  rules from .markdownlint.yml).
• A cspell run over the new file passes (the custom dictionary in
  .cspell.config.yml is sufficient).
• tests/bash/helpers/bats-core/bin/bats tests/bash/ still passes
  unchanged.

Candidate files

• home/dot_codex/AGENTS.md (created)

Notes

• Reference shape: home/dot_copilot/copilot-instructions.md.
• Specificity target: a mid-tier model implementing this issue
  should choose the exact wording per section; the issue requires
  structural parity rather than literal copy.
• If verification finds the canonical user-global filename for
  Codex CLI differs from AGENTS.md, prefer the canonical name
  and explain in the PR description.

[kurone-kito]

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

[kurone-kito]

Field	Value
Phase	D4 waiting for CI
Claim	claude-code-8e8ebc52 / 5a5bf0c7-ed73-44b2-b9ed-68de982899a4
Branch	issue/131-feat-codex-add-user-global-codex-cli
Last checked	2026-05-18T23:58:00Z
Open blockers	none — CI in progress
Next action	when CI completes green, proceed to E1 review snapshot
Authoritative by	PR #135 head 9b0ed84 + claimed-by 4483208294

Path notes (this run)

• Commit signing path: GPG attempt 1 failed with category (P) pinentry (PINENTRY_LAUNCHED then signing failed: タイムアウトです); category (P) prohibits the gpg-agent restart, so the SSH fallback ran on attempt 2 via the project-blessed git commit-ssh alias. GitHub may show the commit as Unverified if the SSH key is not registered as a signing key on the maintainer profile.
• Pre-push-validate: bats 212 / 212 ✓, Pester (Linux) 182 / 0 / 33 ✓.
• CI on PR head so far: lint SUCCESS, Lua syntax check SUCCESS; Bash tests (bats) and PowerShell tests (Pester) still in progress.

[kurone-kito]

Implementation plan (B2)

Loader filename verification

Codex CLI documentation (OpenAI's openai/codex repository) keeps
the AGENTS.md convention symmetric between project-level
(repository root AGENTS.md) and user-global
(~/.codex/AGENTS.md) loaders. The new chezmoi source file will
therefore be home/dot_codex/AGENTS.md, deployed to
~/.codex/AGENTS.md. The existing home/dot_codex/config.toml
stays untouched.

File structure (mirroring home/dot_copilot/copilot-instructions.md)

The new file will carry the same five-section shape used by the
canonical Copilot user-global file, with Codex-specific phrasing:

1. Title + opening paragraph — explicitly states that
   repository-specific instructions (project AGENTS.md,
   .github/instructions/*.md, etc.) always take precedence over
   this file. Says it is loaded automatically by Codex CLI from
   ~/.codex/AGENTS.md.
2. Conversation — match the user's language; comments and
   documentation in English; pause and ask when uncertainty or
   hidden risk makes the next step unsafe (intent-based wording,
   not the Copilot product names Agent mode / Plan mode).
3. Commit rules — Conventional Commits subject format,
   lowercase imperative, ≤ 72 characters, body for the why,
   atomic commits. Followed by the full bounded signing fallback
   ladder (configured GPG attempt → category-based classification
   P/C/A/U → optional gpg-agent restart with skip clauses → SSH
   fallback with three-step key discovery → unsigned). No fixed
   ~/.ssh/id_ed25519 path is named; reporting requirement at the
   end.
4. Coding standards — LF line endings, trim trailing
   whitespace except Markdown, final newline, lowercase-hyphen
   filenames unless platform-constrained.
5. Guardrails — do not modify CODE_OF_CONDUCT* /
   CONTRIBUTING* without explicit approval; do not claim
   commands or tests succeeded if they were not actually run.

Aim for structural parity with the Copilot file, not a
byte-identical copy. Where the Copilot file says "GitHub Copilot",
the new file will say "Codex CLI" or use surface-agnostic phrasing
("the agent").

Validation plan

Before committing:

1. npx markdownlint-cli2 "home/dot_codex/AGENTS.md" — must pass
   the project rules in .markdownlint.yml (default rules with
   the documented exceptions for line length in code blocks,
   headings, tables; duplicate headings allowed; details /
   summary allowed).
2. npx markdownlint-cli2 --fix "**/*.md" && npx markdownlint-cli2 "**/*.md"
   (the project's fix-validate command) — to catch any
   incidental formatting drift across the repository.
3. tests/bash/helpers/bats-core/bin/bats tests/bash/ — the bats
   suite should be unaffected because the new file lives under
   home/dot_codex/ and is not referenced by any test fixture.
4. chezmoi diff from a fresh checkout — sanity check that the
   new file maps to ~/.codex/AGENTS.md. (Skipped if chezmoi
   is not installed in the worktree environment; documented in
   the PR description instead.)

Commit plan

One atomic commit: feat(codex): add user-global Codex CLI instructions. Body explains parity goal and references the
Copilot canonical user-global file. Signing follows the configured
GPG path first; if GPG fails, follow the in-repo signing ladder
(GPG → optional gpg-agent restart → git commit-ssh alias →
unsigned) and report the path taken in the PR description.

Out-of-scope reminders

• Do not touch home/dot_codex/config.toml.
• Do not touch the existing project-level AGENTS.md at the repo
  root.
• Do not edit docs/ai-strategy.md (track D — sibling issue
  docs(ai-strategy): document the user-global instructions layer #134).

Self-critique pass (pre-commit)

After drafting, re-read the new file against the issue's
acceptance criteria one more time before staging. Confirm in
particular:

• The signing ladder spells out all four failure categories
  (P / C / A / U).
• All three gpg-agent restart skip clauses appear (gpgconf not
  on PATH; $SSH_AUTH_SOCK resolves to gpg-agent's SSH socket;
  non-interactive CI).
• The SSH key discovery cascade lists all three steps in order
  (gpg.format == ssh → gpg.ssh.defaultKeyCommand → first
  non-certificate ssh-add -L line).
• No ~/.ssh/id_ed25519 literal path is named.
• The opening paragraph defers to repository-specific instructions.

If any of these fails, revise before committing.