Agent Instruction Workspace

This repo exists to update, iterate on, and maintain the instruction files that drive the user's agentic workflow across Codex and Claude.

The real global instruction files live outside the repo, where the tools read them directly. This repo keeps pointers to those locations plus tracked snapshots of the same files so changes can be reviewed, committed, and understood over time.

Setup

Use this to load the tracked instruction files onto a new machine or user account. The canonical locations are user-specific, so the pointer files must be updated to match wherever the tools actually read from.

1. Find the canonical locations. The tools read from a per-user path:

   • Codex: <home>\.codex\AGENTS.md
   • Claude: <home>\.claude\CLAUDE.md

   Resolve <home> from the environment rather than assuming — on Windows it is $env:USERPROFILE (PowerShell) or %USERPROFILE% (cmd); on macOS/Linux it is $HOME. The tracked content is written for a Windows machine (backslash paths, py for Python); on another OS, adapt the paths and any OS-specific lines after copying.

2. Update the pointer files so they name the real paths for this machine:

   • agents location.md → the Codex path from step 1.
   • claude location.md → the Claude path from step 1.

3. Back up any existing global instruction files before copying. If <home>\.codex\AGENTS.md or <home>\.claude\CLAUDE.md already exists, it holds the user's current global instructions — do not overwrite blindly. Copy the existing file to a .bak alongside it (or confirm with the user) first, since the copy in the next step replaces it wholesale.

4. Copy the tracked snapshots into the canonical locations:

   • tracked/agents tracked.md → <home>\.codex\AGENTS.md
   • tracked/claude tracked.md → <home>\.claude\CLAUDE.md

   Create the .codex and .claude directories first if they do not exist.

5. Restart the tools (or start a new session) so they reload the instruction files from disk. The session running the setup will not pick up the new files until it restarts.

After setup, keep the two copies in sync per the Workflow below: edits go to the canonical file first, then get reflected back into the matching tracked/ file.

Workflow

1. Edit the real global instruction file.
2. Reflect the same content into the matching tracked/ file.
3. Commit the tracked snapshot so the instruction history is preserved.

Do not treat the tracked files as optional backups. They are the versioned record of the global instructions.

Files

• AGENTS.md: local repo instructions for agents.
• CLAUDE.md: Claude bridge to local agent instructions.
• agents location.md: Codex global instruction location.
• claude location.md: Claude global instruction location.
• tracked/: versioned snapshots of global instruction files.
• design/active-design.md: current design state.
• design/active-checklist.md: deferred work and discoveries.
• design/handoffs/: implementation handoffs.
• design/thinking-space/: exploratory notes.
• src/: implementation code.
• tests/: tests.